Applicants

List of valid attributes:

Attribute	Description	Specifics
application_stage_id	ID of the application stage the applicant belongs to	Can only be set on update
created_at	Timestamp when the applicant was created	Cannot be set
documents	Applicant documents to create with the applicant	Optional on public create
email	Email address of the applicant	Must be set
name	Name of the applicant	Must be set

The following relationships can be included in requests:

Relationship	Type
applicant_documents	has_many
job_posting	belongs_to

List

Example response:

{
  "data": [
    {
      "id": "1e9f83a6-51a7-445a-bd6e-5e0350f24c93",
      "type": "applicant",
      "attributes": {
        "application_stage_id": "459e0b1e-caa0-4960-be61-dad0dbcd969e",
        "created_at": "2023-10-15T10:30:00Z",
        "email": "[email protected]",
        "name": "John Doe"
      }
    }
    // ...
  ]
}

This endpoint returns all applicants for the current account.

HTTP Request

GET /api/v1/applicants

Show

Example response:

{
  "data": {
    "id": "88eec07a-7bb4-4926-93b5-d4b60c895e9c",
    "type": "applicant",
    "attributes": {
      "application_stage_id": "459e0b1e-caa0-4960-be61-dad0dbcd969e",
      "created_at": "2023-10-15T10:30:00Z",
      "email": "[email protected]",
      "name": "John Doe"
    }
  }
}

This endpoint returns an applicant entry.

HTTP Request

GET /api/v1/applicants/:applicant_id

URL Parameters

Parameter	Description
applicant_id	ID of the applicant to be returned

Create applicant (public endpoint)

Example request:

{
  "data": {
    "type": "applicant",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]",
      "job_posting_id": "1e9f83a6-51a7-445a-bd6e-5e0350f24c93",
      "documents": [
        {
          "extension": "pdf",
          "name": "Resume"
        }
      ]
    }
  }
}

Example response:

{
  "data": {
    "id": "1e9f83a6-51a7-445a-bd6e-5e0350f24c93",
    "type": "applicant",
    "relationships": {
      "applicant_documents": {
        "data": [
          {
            "id": "890a4c4c-4ae3-4c9a-85b0-2c9a79d3f20d",
            "type": "applicant_document"
          }
        ]
      }
    },
    "meta": {}
  },
  "included": [
    {
      "id": "890a4c4c-4ae3-4c9a-85b0-2c9a79d3f20d",
      "type": "applicant_document",
      "attributes": {
        "applicant_id": "1e9f83a6-51a7-445a-bd6e-5e0350f24c93",
        "extension": "pdf",
        "name": "Resume"
      },
      "meta": {}
    }
  ]
}

This endpoint creates an applicant for a published job posting. The applicant will be automatically assigned to the first application stage of the job posting’s account. If documents are provided, they will be created as well. Created documents will have upload_status set to uploading.

HTTP Request

POST /public/v1/applicants?include=applicant_documents

Request Parameters

Parameter	Description	Required
name	Full name of the applicant	Yes
email	Email address of the applicant	Yes
job_posting_id	The id of the job posting to apply to	Yes
documents	Applicant documents to create, each with extension and name attributes	No

Notes

• The job posting must be active
• Each email can only apply once per job posting
• The applicant will be assigned to the first application stage automatically
• Document extensions must be one of pdf, doc, docx, jpg, jpeg, or png
• Document names are required
• If any validation fails, a 422 response will be returned and neither the applicant nor the documents will be created

Update

Example request:

{
  "data": {
    "type": "applicant",
    "attributes": {
      "application_stage_id": "823e0a1f-rrx0-4870-be21-drd0abad939a"
    }
  }
}

Example response:

{
    "data": {
        "id": "b1d925db-e688-4fa0-9432-db8db55ed370",
        "type": "applicant",
        "attributes": {
        ...
        }
    }
}

This endpoint updates an applicant.

HTTP Request

PUT /api/v1/applicants/:applicant_id

URL Parameters

Parameter	Description
applicant_id	ID of the applicant to be updated