---
updatedAt: 2026-02-05T15:11:46.000Z
agentTools:
  projectIndex: https://workable.readme.io/llms.txt
---

# /candidates

Returns a collection of the job's candidates. Required scope: `r_candidates`. Accessible with all token types.

## Results

Calling the `/candidates` endpoint will return a collection of the job's candidates. If no query parameter is defined, all candidates will be returned.

By default results are limited to 50. The limit can be updated via the request parameter limit. The value specified cannot be more than 100 per page.

| key        | description                                                                                                       |
| :--------- | :---------------------------------------------------------------------------------------------------------------- |
| candidates | array of candidates                                                                                               |
| paging     | Includes the `next` URL pointing to the next results page, in case there are more results than the provided limit |

Each candidate will have the following keys:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        key
      </th>

      <th>
        type
      </th>

      <th>
        description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        `string`
      </td>

      <td>
        The candidate identifier
      </td>
    </tr>

    <tr>
      <td>
        name
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's full name
      </td>
    </tr>

    <tr>
      <td>
        firstname
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's first name
      </td>
    </tr>

    <tr>
      <td>
        lastname
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's last name
      </td>
    </tr>

    <tr>
      <td>
        headline
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's headline
      </td>
    </tr>

    <tr>
      <td>
        account/subdomain
      </td>

      <td>
        `string`
      </td>

      <td>
        Account's subdomain
      </td>
    </tr>

    <tr>
      <td>
        account/name
      </td>

      <td>
        `string`
      </td>

      <td>
        Account's name
      </td>
    </tr>

    <tr>
      <td>
        job/shortcode
      </td>

      <td>
        `string`
      </td>

      <td>
        Job's system generated code
      </td>
    </tr>

    <tr>
      <td>
        job/title
      </td>

      <td>
        `string`
      </td>

      <td>
        Job's title
      </td>
    </tr>

    <tr>
      <td>
        stage
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's stage slug
      </td>
    </tr>

    <tr>
      <td>
        stage_kind
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's stage kind
      </td>
    </tr>

    <tr>
      <td>
        disqualified
      </td>

      <td>
        `boolean`
      </td>

      <td>
        True if the candidate is disqualified
      </td>
    </tr>

    <tr>
      <td>
        withdrew
      </td>

      <td>
        `boolean`
      </td>

      <td>
        True if the candidate withdrew and was disqualified
      </td>
    </tr>

    <tr>
      <td>
        disqualification_reason
      </td>

      <td>
        `string`
      </td>

      <td>
        null if the member has not provided a disqualification reason
      </td>
    </tr>

    <tr>
      <td>
        sourced
      </td>

      <td>
        `boolean`
      </td>

      <td>
        True if the candidate has been sourced
      </td>
    </tr>

    <tr>
      <td>
        profile_url
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's URL in Workable
      </td>
    </tr>

    <tr>
      <td>
        email
      </td>

      <td>
        `string`
      </td>

      <td>
        Candidate's email
      </td>
    </tr>

    <tr>
      <td>
        domain
      </td>

      <td>
        `string`
      </td>

      <td>
        Where candidate come from
      </td>
    </tr>

    <tr>
      <td>
        created_at
      </td>

      <td>
        `string`
      </td>

      <td>
        Timestamp when the candidate  was created
      </td>
    </tr>

    <tr>
      <td>
        updated_at
      </td>

      <td>
        `string`
      </td>

      <td>
        Last timestamp when the candidate was updated
      </td>
    </tr>

    <tr>
      <td>
        hired_at
      </td>

      <td>
        `date`
      </td>

      <td>
        The date the candidate was moved to the hired stage
      </td>
    </tr>

    <tr>
      <td>
        address
      </td>

      <td>
        `string`
      </td>

      <td>
        The address of the candidate
      </td>
    </tr>

    <tr>
      <td>
        phone
      </td>

      <td>
        `string`
      </td>

      <td>
        The phone number of the candidate
      </td>
    </tr>

    <tr>
      <td>
        resume_metadata
      </td>

      <td>
        `object`
      </td>

      <td>
        Information extracted from candidate’s resume. It includes   
        `filename`, `filetype`, `created_at`, `updated_at`
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "account-root",
    "version": "3.16.2"
  },
  "servers": [
    {
      "url": "https://{subdomain}.workable.com/spi/v3",
      "variables": {
        "subdomain": {
          "default": "subdomain"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "",
        "x-default": "Bearer"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/candidates": {
      "get": {
        "summary": "/candidates",
        "description": "Returns a collection of the job's candidates. Required scope: `r_candidates`. Accessible with all token types.",
        "operationId": "job-candidates-index",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "The email of the candidate to filter by",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shortcode",
            "in": "query",
            "description": "The job's system generated code",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stage",
            "in": "query",
            "description": "The job's stage slug, can be retrieved from the `/stages` endpoint",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Specifies the number of candidates to try and retrieve per page",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "since_id",
            "in": "query",
            "description": "Returns results with an ID greater than or equal to the specified ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_id",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "description": "Returns results created after the specified timestamp.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_after",
            "in": "query",
            "description": "Returns results updated after the specified timestamp.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"candidates\": [\n    {\n      \"id\": \"ce4da98\",\n      \"name\": \"Lakita Marrero\",\n      \"firstname\": \"Lakita\",\n      \"lastname\": \"Marrero\",\n      \"headline\": \"Operations Manager\",\n      \"account\": {\n        \"subdomain\": \"groove-tech\",\n        \"name\": \"Groove Tech\"\n      },\n      \"job\": {\n        \"shortcode\": \"GROOV005\",\n        \"title\": \"Office Manager\"\n      },\n      \"stage\": \"Interview\",\n      \"disqualified\": true,\n      \"disqualification_reason\": null,\n      \"sourced\": false,\n      \"profile_url\": \"https://groove-tech.workable.com/backend/jobs/376844767/candidates/216323526\",\n      \"email\": \"lakita_marrero@gmail.com\",\n      \"domain\": \"twitter.com\",\n      \"created_at\": \"2015-06-26T00:00:00Z\",\n      \"updated_at\": \"2015-07-08T14:46:48Z\"\n    },\n    {\n      \"id\": \"108d1748\",\n      \"name\": \"Cindy Sawyers\",\n      \"firstname\": \"Cindy\",\n      \"lastname\": \"Sawyers\",\n      \"headline\": \"Talented Operations Executive\",\n      \"account\": {\n        \"subdomain\": \"groove-tech\",\n        \"name\": \"Groove Tech\"\n      },\n      \"job\": {\n        \"shortcode\": \"GROOV005\",\n        \"title\": \"Office Manager\"\n      },\n      \"stage\": \"Applied\",\n      \"disqualified\": false,\n      \"disqualification_reason\": null,\n      \"sourced\": false,\n      \"profile_url\": \"https://groove-tech.workable.com/backend/jobs/376844767/candidates/277680758\",\n      \"email\": \"cindy_sawyers@gmail.com\",\n      \"domain\": \"indeed.com\",\n      \"created_at\": \"2015-07-08T00:00:00Z\",\n      \"updated_at\": \"2015-07-08T14:46:48Z\"\n    }\n  ],\n  \"paging\": {\n    \"next\": \"https://www.workable.com/spi/v3/accounts/groove-tech/candidates?limit=3&since_id=2789d6dg\"\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "ce4da98"
                          },
                          "name": {
                            "type": "string",
                            "example": "Lakita Marrero"
                          },
                          "firstname": {
                            "type": "string",
                            "example": "Lakita"
                          },
                          "lastname": {
                            "type": "string",
                            "example": "Marrero"
                          },
                          "headline": {
                            "type": "string",
                            "example": "Operations Manager"
                          },
                          "account": {
                            "type": "object",
                            "properties": {
                              "subdomain": {
                                "type": "string",
                                "example": "groove-tech"
                              },
                              "name": {
                                "type": "string",
                                "example": "Groove Tech"
                              }
                            }
                          },
                          "job": {
                            "type": "object",
                            "properties": {
                              "shortcode": {
                                "type": "string",
                                "example": "GROOV005"
                              },
                              "title": {
                                "type": "string",
                                "example": "Office Manager"
                              }
                            }
                          },
                          "stage": {
                            "type": "string",
                            "example": "Interview"
                          },
                          "disqualified": {
                            "type": "boolean",
                            "example": true,
                            "default": true
                          },
                          "disqualification_reason": {},
                          "sourced": {
                            "type": "boolean",
                            "example": false,
                            "default": true
                          },
                          "profile_url": {
                            "type": "string",
                            "example": "https://groove-tech.workable.com/backend/jobs/376844767/candidates/216323526"
                          },
                          "email": {
                            "type": "string",
                            "example": "lakita_marrero@gmail.com"
                          },
                          "domain": {
                            "type": "string",
                            "example": "twitter.com"
                          },
                          "created_at": {
                            "type": "string",
                            "example": "2015-06-26T00:00:00Z"
                          },
                          "updated_at": {
                            "type": "string",
                            "example": "2015-07-08T14:46:48Z"
                          },
                          "resume_metadata": {
                            "type": "object",
                            "properties": {
                              "filename": {
                                "type": "string"
                              },
                              "filetype": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "name1": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "paging": {
                      "type": "object",
                      "properties": {
                        "next": {
                          "type": "string",
                          "example": "https://www.workable.com/spi/v3/accounts/groove-tech/candidates?limit=3&since_id=2789d6dg"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"error\":\"Not authorized\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Not authorized"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"error\":\"Not found\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Not found"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```