Jobs

A company's job to which candidates may apply.

Create a job

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

Creates a new job and returns the job'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
title*	string	The title of the job
description*	string	The description of the job
status*	string	The current status of the job: open, archived, or closed
job_posting_urls	string[]	List of publicly visible job posting urls
remote_id*	string	The id of the job from the originating system
auto_evaluation_behavior	string	The automatic evaluation behavior of the job (see Bring AI-powered evaluations to your users): auto_evaluate_nominations, auto_nominate_and_evaluate_candidates, or null
default_nomination_stage_id	string	The default nomination stage id (UUID) to be used for Endorsed to automatically generate nominations. Required if the auto_evaluation_behavior is auto_nominate_and_evaluate_candidates.

201 Successfully created

{
  "is_error": false,
  "result": {
    "id": "3c2914bb-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"
      }
    ]
  }
}

Examples:

cURL

curl -X POST "${BASE_URL}/api/v1/jobs" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "title": "Digital Marketing Specialist",
  "description": "Digital Marketing Specialist sought for fast-paced agency. Must have expertise in SEO, PPC, and content strategy. Google Analytics certification preferred.",
  "status": "open",
  "job_posting_urls": [
    "https://www.marketinghub.com/jobpost/digi-mark-special-1003"
  ],
  "remote_id": "remote-id_from-originating-system"
}'

Get an existing job

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

Get an existing job 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 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,
  "result": {
    "id": "3c2914bb-b31b-47ab-8976-afaa2d995503",
    "title": "Job Title",
    "description": "Job Description",
    "status": "open",
    "job_posting_urls": ["https://endorsed.ai/jobPosting/example"],
    "remote_id": "ef29a39b-b143-4491-9f84-038b8806f950",
    "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/jobs/remote.remote-id_from-originating-system" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Endorsed Id

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

Update or upserts an existing job

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

Updates an existing job by it's UUID id or upserts a job by a remote id. Remote ids MUST be structured by 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

Request Body

Name	Type	Description
title*	string	The title of the job
description*	string	The description of the job
status*	string	The current status of the job: open, archived, or closed
job_posting_urls	string[]	List of publicly visible job posting urls
auto_evaluation_behavior	string	The automatic evaluation behavior of the job (see Bring AI-powered evaluations to your users): auto_evaluate_nominations, auto_nominate_and_evaluate_candidates, or null
default_nomination_stage_id	string	The default nomination stage id (UUID) to be used for Endorsed to automatically generate nominations. Required if the auto_evaluation_behavior is auto_nominate_and_evaluate_candidates.

200 Successfully updated

{
  "is_error": false,
  "result": {
    "id": "3c2914bb-b31b-47ab-8976-afaa2d995503"
  }
}

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 PUT "${BASE_URL}/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "title": "Senior Web Engineer",
  "description": "Experienced Web Developer needed to join our dynamic tech team. Proficient in Javascript, HTML, and CSS. Familiarity with React.JS a plus.",
  "status": "closed",
  "job_posting_urls": [
    "https://www.techjobsite.com/listings/web-dev-0923"
  ]
}'

cURL with Remote Id

curl -X PUT "${BASE_URL}/api/v1/jobs/remote.aavCEuMXEgdL3QHtOL6bd" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "title": "Senior Web Engineer",
  "description": "Experienced Web Developer needed to join our dynamic tech team. Proficient in Javascript, HTML, and CSS. Familiarity with React.JS a plus.",
  "status": "closed",
  "job_posting_urls": [
    "https://www.techjobsite.com/listings/web-dev-0923"
  ]
}'

curl -X PUT "${BASE_URL}/api/v2/candidates/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "remote_id": "-LN7ISBnAcJiaa3TU8uoj",
  "first_name": "Test",
  "last_name": "Testerson",
  "phone_numbers": [],
  "email_addresses": [],
  "links": [],
  "unstructured_location": "San Francisco, CA",
  "unstructured_profile": {
    "about": [
        {
            "about_me": "I am a test candidate's about section."
        }
    ],
    "role_preferences": [
        {
            "role": "Software Engineer",
            "location": "San Francisco, CA",
            "type": "Full-time",
            "min_salary": 100000,
            "max_salary": 150000
        }
    ],
    "work_experiences": [
        {
            "company": "Test Company",
            "title": "Test Title",
            "location": "San Francisco, CA",
            "start_date": "2019-01-01",
            "end_date": "2019-01-01",
            "description": "I am a test candidate's work experience."
        }
    ],
    "screening": [
        {
            "type": "Coding Challenge",
            "status": "Pending",
            "due_date": "2019-01-01",
            "completed_date": "2019-01-01",
            "score": 100,
            "feedback": "I am a test candidate's screening."
        }
    ]
  }
}'

Partially update an existing job

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

Partially updates an existing job 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
title	string	The title of the job
description	string	The description of the job
status	string	The current status of the job: open, archived, or closed
job_posting_urls	string[]	List of publicly visible job posting urls
auto_evaluation_behavior	string	The automatic evaluation behavior of the job (see Bring AI-powered evaluations to your users): auto_evaluate_nominations, auto_nominate_and_evaluate_candidates, or null
default_nomination_stage_id	string	The default nomination stage id (UUID) to be used for Endorsed to automatically generate nominations. Required if the auto_evaluation_behavior is auto_nominate_and_evaluate_candidates.

200 Successfully updated

{
  "is_error": false,
  "result": {
    "id": "3c2914bb-b31b-47ab-8976-afaa2d995503"
  }
}

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 PATCH "${BASE_URL}/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "status": "open",
  "job_posting_urls": [
    "https://www.marketinghub.com/jobpost/digi-mark-special-1003"
  ]
}'