Candidates

Candidates represents an individual that exists in a candidate pool. It may or may not have an association with a nomination

Relationships:

• Job to Candidates has no direct relationship; Candidate relationships are through nominations

Create a Candidate

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

Creates a new Candidate and returns the Candidate'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
first_name*	string	The first name of the candidate
last_name	string	The last name of the candidate
title	string	The current title of the candidate
company_name	string	The current company name of the candidate
location	string	The current location of the candidate
phone_numbers	PhoneNumber[]	List of phone numbers for the candidate. Empty array is allowed
phone_numbers[*].value*	string	String representing a candidate phone number
phone_numbers[*].type	string	Type of the candidate phone number: home , work , mobile , or other .
email_addresses	EmailAddress[]	List of email addresses for the candidate. Empty array is allowed
email_addresses[*].value*	string	String representing the candidate email address
email_addresses[*].type	string	Type of the candidate email address: personal or work
links	Link[]	List of personal links for the candidate. Empty array is allowed
links[*].value*	string	String represnting the candidate's url links
links[*].type	string	Type of the candidate url link: personal , portfolio , blog , social_media , linkedin , or github
remote_id*	string	The id of the candidate from the originating system

201 Successfully created

{
  "is_error": false,
  "result": {
    "id": "b8c76214-d518-4d69-9aab-77b0166696d2"
  }
}

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/candidates" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "first_name": "John",
  "last_name": "Doe",
  "title": "Software Engineer",
  "company_name": "Tech Corp",
  "location": "San Francisco, CA",
  "phone_numbers": [
    {
      "value": "123-456-7890",
      "type": "mobile"
    },
    {
      "value": "098-765-4321",
      "type": "work"
    }
  ],
  "email_addresses": [
    {
      "value": "[e-mail]",
      "type": "work"
    },
    {
      "value": "[e-mail]",
      "type": "personal"
    }
  ],
  "links": [
    {
      "value": "https://www.johndoe.com",
      "type": "personal"
    },
    {
      "value": "https://github.com/johndoe",
      "type": "github"
    },
    {
      "value": "https://www.linkedin.com/in/johndoe",
      "type": "linkedin"
    }
  ],
  "remote_id": "remote-id_from-originating-system"
}'

Get an existing candidate

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

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

Path Parameters

Name	Type	Description
id*	string	UUID id of the Candidate

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": "b8c76214-d518-4d69-9aab-77b0166696d2",
    "first_name": "Bob",
    "last_name": "Smith",
    "title": "Software Engineer",
    "company_name": "Google",
    "location": "San Francisco, CA",
    "phone_numbers": [
      {
        "value": "123-456-7890",
        "type": "mobile"
      }
    ],
    "email_addresses": [
      {
        "value": "[e-mail]",
        "type": "personal"
      }
    ],
    "links": [
      {
        "value": "https://www.linkedin.com/in/ryanroslansky/",
        "type": "linkedin"
      }
    ],
    "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 Endorsed Id

curl -X GET "${BASE_URL}/api/v1/candidates/b13dc10a-78de-4213-b7d8-2e01c4b2c589" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

cURL with Remote Id

curl -X GET "${BASE_URL}/api/v1/candidates/remote.73Yfih1Z9F21OYDUqrNL8" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Update an existing Candidate

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

Updates an existing Candidate 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
first_name*	string	The first name of the candidate
last_name	string	The last name of the candidate
title	string	The current title of the candidate
company_name	string	The current company name of the candidate
location	string	The current location of the candidate
phone_numbers	PhoneNumber[]	List of phone numbers for the candidate
phone_numbers[*].value*	string	String representing a candidate phone number
phone_numbers[*].type	string	Type of the candidate phone number: home , work , mobile , or other .
email_addresses	EmailAddress[]	List of email addresses for the candidate
email_addresses[*].value*	string	String representing the candidate email address
email_addresses[*].type	string	Type of the candidate email address: personal or work
links	Link[]	List of personal links for the candidate
links[*].value*	string	String represnting the candidate's url links
links[*].type	string	Type of the candidate url link: personal , portfolio , blog , social_media , linkedin , or github

200 Successfully updated

{
  "is_error": false,
  "result": {
    "id": "b8c76214-d518-4d69-9aab-77b0166696d2"
  }
}

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/candidates/b13dc10a-78de-4213-b7d8-2e01c4b2c589" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d '{
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "Senior Software Engineer",
  "company_name": "Updated Tech Corp",
  "location": "New York, NY",
  "phone_numbers": [
    {
      "value": "987-654-3210",
      "type": "home"
    }
  ],
  "email_addresses": [
    {
      "value": "[e-mail]",
      "type": "work"
    }
  ],
  "links": [
    {
      "value": "https://www.janesmith-portfolio.com",
      "type": "portfolio"
    },
    {
      "value": "https://blob.janesmith.com",
      "type": "blog"
    },
    {
      "value": "https://instagram.com/janesmith",
      "type": "social_media"
    }
  ]
}'