Nominations

Nominations can represent either an application of a candidate who has actively applied for a job OR an active consideration of a candidate for a job by a recruiter, marketplace, etc. Generally, a nom

Relationships:

• Candidate to Nominations is 1-Many

• Nomination Stages to Nominations is 1-1. Each nomination can only be in one stage at a given time.

Create a Nomination

POST https://endorsed.ai/api/v1/nominations

Creates a new Nomination and returns the Nomination's UUID id.

Headers

Name	Type	Description
Authorization*	string	Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>
Content-Type	string	Must be application/json. If not set, defaults to application/json

Request Body

Name	Type	Description
job_id*	string	The Job UUID from the /jobs entity resource.
candidate_id*	string	The Candidate UUID from the /candidates entity resource
current_nomination_stage_id*	string	The Nomination Stage UUID from the /nomination_stages entity resource.
applied_at	string	The ISO 8601 formatted string representing the time when the candidate applied. Optional in the case that a candidate has not yet actively applied (i.e. shortlisting a candidate, internal consideration for a role)
remote_id*	string	The id of the nomination from the originating system

201 Successfully created

{
  "is_error": false,
  "result": {
    "id": "6427f970-70c0-4b42-8fae-5609cefbb1bc"
  }
}

401 Unauthorized

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}

500: Internal Server Error

{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

cURL

curl -X POST "${BASE_URL}/api/v1/nominations" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "job_id": "39cce06d-148f-44ba-ad63-3ddc825339b6",
  "candidate_id": "7240574b-9870-4293-a0d1-44fe77c59420",
  "current_nomination_stage_id": "602f023c-53a2-4886-9b36-6157e70b2c93",
  "applied_at": "2023-09-30T06:35:16.000Z",
  "remote_id": "remote-id_from-originating-system"
}'

Get an existing Nomination

GET https://endorsed.ai/api/v1/nominations/{id}

Get an existing Nomination by it's UUID id or by a remote id. Remote ids MUST be structured by remote.<id>

Path Parameters

Name	Type	Description
id*	string	UUID id of the Nomination

Headers

Name	Type	Description
Authorization*	string	Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>

200 Successfully fetched

{
  "is_error": false,
  "result": {
    "id": "6427f970-70c0-4b42-8fae-5609cefbb1bc",
    "job_id": "3c2914bb-b31b-47ab-8976-afaa2d995503",
    "candidate_id": "b8c76214-d518-4d69-9aab-77b0166696d2",
    "current_nomination_stage_id": "01d6e7e3-44fb-436b-b593-fa3e376caf08",
    "applied_at": "2023-09-25T22:06:01.000Z",
    "remote_id": "27bac5c5-7447-4714-8696-0aa2fbc78ffa",
    "created_at": "2023-09-25T22:06:01.000Z",
    "modified_at": "2023-09-25T22:06:01.000Z"
  }
}

401 Unauthorized

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}

403: Forbidden Permission denied

{
  "is_error": true,
  "error": {
    "code": "FORBIDDEN",
    "issues": [
      {
        "message": "Access to this resource is not authorized."
      }
    ]
  }
}

404: Not Found

{
  "is_error": true,
  "error": {
    "code": "NOT_FOUND",
    "issues": [
      {
        "message": "This resource entity does not exist."
      }
    ]
  }
}

500: Internal Server Error

{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

cURL with Remote Id

curl -X GET "${BASE_URL}/api/v1/nominations/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Endorsed Id

curl -X GET "${BASE_URL}/api/v1/nominations/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Update an existing Nomination

PUT https://endorsed.ai/api/v1/nominations/{id}

Updates an existing Nomination by it's UUID id.

Headers

Name	Type	Description
Authorization*	string	Authorization header containing the Bearer Access Token from the /auth/tokens endpoint. Example: Bearer <ACCESS_TOKEN>
Content-Type	string	Must be application/json. If not set, defaults to application/json

Request Body

Name	Type	Description
current_nomination_stage_id*	string	The Nomination Stage UUID from the /nomination_stages entity resource.
applied_at	string	The ISO 8601 formatted string representing the time when the candidate applied. Optional in the case that a candidate has not yet actively applied (i.e. shortlisting a candidate, internal consideration for a role)

200 Successfully updated

{
  "is_error": false,
  "result": {
    "id": "6427f970-70c0-4b42-8fae-5609cefbb1bc"
  }
}

401 Unauthorized

{
  "is_error": true,
  "error": {
    "code": "UNAUTHENTICATED",
    "issues": [
      {
        "message": "Resource requires authentication. Please provide a valid access token."
      }
    ]
  }
}

403: Forbidden Permission denied

{
  "is_error": true,
  "error": {
    "code": "FORBIDDEN",
    "issues": [
      {
        "message": "Access to this resource is not authorized."
      }
    ]
  }
}

404: Not Found

{
  "is_error": true,
  "error": {
    "code": "NOT_FOUND",
    "issues": [
      {
        "message": "This resource entity does not exist."
      }
    ]
  }
}

500: Internal Server Error

{
  "is_error": true,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "issues": [
      {
        "message": "An unexpected error occurred on our end. Please try again later, and if the problem persists, contact our support team"
      }
    ]
  }
}

Examples:

cURL

curl -X PUT "${BASE_URL}/api/v1/nominations/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "current_nomination_stage_id": "602f023c-53a2-4886-9b36-6157e70b2c93",
  "applied_at": "2023-12-30T06:35:16.000Z"
}'