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

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

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

{
  "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/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": "john.doe@example.com",
      "type": "work"
    },
    {
      "value": "johndoe@gmail.com",
      "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>

{
  "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": "hello@google.com",
        "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"
  }
}

{
  "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/candidates/b13dc10a-78de-4213-b7d8-2e01c4b2c589" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

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

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

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

{
  "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/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": "jane.smith.updated@example.com",
      "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"
    }
  ]
}'

Last updated 9 months ago