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

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

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

{
  "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 -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>

{
  "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"
  }
}

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

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

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

{
  "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 -X GET "${BASE_URL}/api/v1/nomination_stages/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

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

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

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

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

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

{
  "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 -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
}'

Last updated 9 months ago