Alfa

ATS jobs

Create or update an ATS job

PUT/v1/integration/ats-jobs/{externalJobId}

Sends one of your ATS's jobs to Alfa, keyed by your own id. Recruiters link an Alfa job to it in the job form, and candidates on that Alfa job are reported back against this id. Sending the same id again updates it: a detail you leave out keeps its value, and `null` clears it. A `closed` job leaves the picker, but Alfa jobs already linked to it stay linked. A company that already uses another ATS integration is refused with 409 `ats_integration_conflict`. Requires an API key with the `ats_jobs:write` scope.

Requires an Alfa API key as a bearer token. How API keys work

Path parameters

  • externalJobIdstringrequired

    Your ATS's own id for the job.

    at least 1 characters · at most 200 characters

Headers

  • Alfa-Company-Idstring

    The Company ID of the company to act for. Required with a platform key, and that company must have authorized your platform; a company key acts for its own company and can leave it out.

Request body

  • titlestringrequired

    The job title shown in the Alfa job form picker.

    at least 1 characters · at most 300 characters

  • status"open" | "closed"required

    `open` jobs appear in the picker. `closed` removes the job from the picker; Alfa jobs already linked to it stay linked.

  • locationstring | null

    Where the job is based.

  • departmentstring | null

    The team or department.

  • urlstring | null

    A link to the job in your ATS.

Response body

  • externalJobIdstringrequired

    Your ATS's id for the job.

  • titlestringrequired

    The job title.

  • status"open" | "closed"required

    Whether the job is offered in the picker.

  • locationstring | nullrequired

    Where the job is based.

  • departmentstring | nullrequired

    The team or department.

  • urlstring | nullrequired

    A link to the job in your ATS.

  • createdAtstringrequired

    When Alfa first received the job.

  • updatedAtstringrequired

    When Alfa last received a change to the job.

Responses

  • 200Success.
  • 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
  • 401The bearer token is missing, expired or invalid. Problem details
  • 403The caller may not perform this operation, or has no active organisation. Problem details
  • 404The resource does not exist or is not visible to the caller. Problem details
  • 422The request failed validation; `errors` lists each invalid field. Problem details
  • 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
  • 500An unexpected error. Quote the `correlationId` to support. Problem details