Nomination Stages

Nomination Stages for a given job represent an ordered sequence of states that a candidate nominations can progress through.

Relationships:

The Nomination Stages relationships can be either of the following:

• Job to Nomination Stages can be 1-Many: Set job_id to the job UUID for this use case.

• Job to Nomination Stages can be independent: Don't set job_id to create stages that are global to your system. This would allow a single stage to be used by multiple nominations across multiple job.

Create a Nomination Stage

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

Creates a new Nomination Stage and returns the Nomination Stage'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. Can be optional in the case that a stage should be used / referenced for any nomination regardless of which job that nomination is associated with.
name*	string	The name of the Nomination Stage
stage_order_index*	integer	The order index of this stage amongst the stages under this job, which must be unique per job or unique among the global nomination stages. All of the stage order indices under a job or amongst the global nomination stages are considered sequenced in ascending numeric order.
remote_id*	string	The id of the Nomination Stage from the originating system

201 Successfully created

{
  "is_error": false,
  "result": {
    "id": "01d6e7e3-44fb-436b-b593-fa3e376caf08"
  }
}

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/nomination_stages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "job_id": "c10a54c5-7890-412d-98a7-6a87e9a45b9f",
  "name": "Initial Interview",
  "stage_order_index": 1000,
  "remote_id": "remote-id_from-originating-system"
}'

Get an existing Nomination Stage

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

Get an existing Nomination Stage 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 Stage

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": "01d6e7e3-44fb-436b-b593-fa3e376caf08",
    "job_id": "3c2914bb-b31b-47ab-8976-afaa2d995503",
    "name": "Application Review",
    "stage_order_index": 1000,
    "remote_id": "095e53a7-b990-4d32-8b32-754b7ed20fa8",
    "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/nomination_stages/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Endorsed Id

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

Update an existing Nomination Stage

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

Updates an existing Nomination Stage 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
name*	string	The name of the Nomination Stage
stage_order_index*	integer	The order index of this stage amongst the stages under this job, which must be unique per job or unique among the global nomination stages. All of the stage order indices under a job or amongst the global nomination stages are considered sequenced in ascending numeric order.

200 Successfully updated

{
  "is_error": false,
  "result": {
    "id": "01d6e7e3-44fb-436b-b593-fa3e376caf08"
  }
}

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/nomination_stages/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "name": "First Interview",
  "stage_order_index": 2000
}'