Job Criteria

The criteria for a given Job by which to evaluate Candidates. Right now, only boolean (yes/no) criteria are supported; contact Endorsed to request additional types.

Create a Criterion

POST https://endorsed.ai/api/v1/jobs/{id}/criteria

Creates a new Job Criterion and returns the Criterion's UUID.

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
prompt_text*	string	The detailed criterion text by which to evaluate the candidate. See How to Write Good Evaluation Criteria for information on crafting good prompt_texts.
display_name	string	The text to display in place of the prompt_text when returning or displaying evaluations. If not set, prompt_text will be used.

201 Successfully created

{
  "is_error": false,
  "result": {
    "id": "4d3914bb-b31b-47ab-8976-afaa2d995503"
  }
}

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

409: Conflict A criterion for this Job with the same prompt_text already exists

{
  "is_error": true,
  "error": {
    "code": "CONFLICT",
    "issues": [
      {
        "message": "A criterion with the same prompt_text already exists for this job. Ensure that all criteria have unique prompt_texts."
      }
    ]
  }
}

Examples:

cURL

curl -X POST "${BASE_URL}/api/v1/jobs/3c2914bb-b31b-47ab-8976-afaa2d995503" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "prompt_text": "Has experience with digital marketing platforms like AdWords or equivalent",
  "display_name": "Digital marketing experience"
}'

Get all existing Criteria for the specified Job

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

Get all existing Criteria by a Job'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 Job

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,
  "results": [
    {
      "id": "61cd4e66-7b52-4558-84c5-5f5df667ba5b",
      "prompt_text": "Has experience in the technical recruiting industry",
      "display_name": null,
      "evaluation_result_type": "boolean",
      "created_at": "2024-02-05T18:15:50.887+00:00"
    },
    {
      "id": "45ce4e56-42bc-4205-98fc-dee36a5355f9",
      "prompt_text": "Has two or more years of experience with Python",
      "display_name": "Python experience",
      "evaluation_result_type": "boolean",
      "created_at": "2024-02-05T18:16:43.116+00:00"
    },
    {
      "id": "99c2eac3-9749-4dac-81a8-0393fb392130",
      "prompt_text": "Has experience with digital marketing platforms like AdWords or equivalent",
      "display_name": "Digital marketing experience",
      "evaluation_result_type": "boolean",
      "created_at": "2024-03-06T21:03:04.167+00:00"
    }
  ]
}

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/jobs/remote.remote-id_from-originating-system/criteria" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Endorsed Id

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

Get a single existing Job Criterion

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

Retrieve a single existing Job Criterion given its ID and associated Job's ID. Job ID may be either Endorsed's UUIDs or your system's IDs structured like remote.<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

200 Successful

{
  "is_error": false,
  "result": {
    "id": "60cd4e66-7b52-4558-84c5-5f5df667ba5b",
    "prompt_text": "Has experience with digital marketing platforms like AdWords or equivalent",
    "display_name": "Digital marketing experience",
    "evaluation_result_type": "boolean",
    "created_at": "2024-02-05T18:15:50.887+00:00"
  }
}

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 Endorsed Id

curl -X GET "${BASE_URL}/api/v1/jobs/4d3914bb-b31b-47ab-8976-afaa2d995503/criteria/71cd4e66-7b52-4558-84c5-5f5df667ba5b" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Remote Id

curl -X GET "${BASE_URL}/api/v1/jobs/remote.12345/criteria/remote.56789" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Delete a single existing Job Criterion

DELETE https://endorsed.ai/api/v1/jobs/{id}/criteria/{id}

Delete a single existing Job Criterion given its ID and associated Job's ID. IDs may be either Endorsed's UUIDs or your system's IDs structured like remote.<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

200 Successfully deleted

{
  "is_error": false,
  "result": {
    "id": "60cd4e66-7b52-4558-84c5-5f5df667ba5b"
  }
}

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