Overview

The Teaching Vacancies ATS API lets an applicant tracking system create, update, list and delete job listings for the schools and trusts it acts for. Listings published through it appear on the Teaching Vacancies service, where people looking for school jobs can search for them and subscribe to alerts.

Access is by API key, issued as part of onboarding. To start an integration, email teachingvacancies.ats@education.gov.uk.

Documents

v1
Uploaded schema

Who can use this API

Applicant tracking system and HR software vendors acting for schools and trusts

Service level

24/7

Technologies

REST, Ruby on Rails

Environments

Environment Base URL
staging https://staging.teaching-vacancies.service.gov.uk
production https://teaching-vacancies.service.gov.uk

You need to sign in to subscribe to an API environment or view your existing subscriptions.

Sign in here using GOV.UK One Login

Current release

Release name Available from
v1

Operations

Show additional information

GET Returns a paginated list of vacancies that were created through the client's ATS.

Description

Returns a paginated list of vacancies that were created through the client's ATS.

URL template
/ats-api/v1/vacancies
Show / Hide additional information

Parameters

Name Type Location Field Description
page number Query Optional page number (1-based), defaults to 1

Response Codes

Status code Description
200 Returns a paginated list of all the client vacancies
401 Occurs when the provided API key is incorrect or missing
500 Indicates an unexpected issue on the server.

Example Request

curl -X GET \
  "https://{{baseURL}}/ats-api/v1/vacancies"

POST Creates a new vacancy for the client's ATS.

Description

Creates a new vacancy for the client's ATS.

URL template
/ats-api/v1/vacancies
Show / Hide additional information

Request Model Example

{
  "vacancy": [
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [
          []
        ],
        [
          [
            []
          ]
        ]
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      [
        []
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [],
        []
      ]
    ],
    [
      [
        [],
        []
      ]
    ]
  ]
}

Response Codes

Status code Description
201 Indicates that the vacancy was created and returns the newly created resource.
400 The request body is missing required parameters or has invalid data.
401 Occurs when the provided API key is incorrect or missing.
409 A conflicting vacancy exists.<br>The conflicting vacancy contains the same values for either:<ul><li>The external reference (must be unique per API Client).</li><li>All these fields (must be unique per school):</li><ul><li>job title</li><li>expiry date</li><li>contract type</li><li>working patterns</li><li>phases</li><li>salary</li></ul></ul>
422 One or more values failed validation.
500 A server-side issue occurred while creating the vacancy.

Example Request

curl -X POST \
  "https://{{baseURL}}/ats-api/v1/vacancies" \
  -H "Content-Type: application/json" \
  -d '{
  "vacancy": [
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [
          []
        ],
        [
          [
            []
          ]
        ]
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      [
        []
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [],
        []
      ]
    ],
    [
      [
        [],
        []
      ]
    ]
  ]
}'

DELETE Deletes a vacancy with the given ID, if it belongs to the client's ATS.

Description

Deletes a vacancy with the given ID, if it belongs to the client's ATS.

URL template
/ats-api/v1/vacancies/{id}
Show / Hide additional information

Parameters

Name Type Location Field Description
id string Path Required The id of the vacancy

Response Codes

Status code Description
204 Indicates the vacancy was removed from the system.
401 Occurs when the provided API key is incorrect or missing.
404 No vacancy was found with the provided ID that belongs to this client.
500 An unexpected error occurred on the server.

Example Request

curl -X DELETE \
  "https://{{baseURL}}/ats-api/v1/vacancies/{id}"

GET Retrieves details for a single vacancy by its unique ID, if it belongs to the requesting client.

Description

Retrieves details for a single vacancy by its unique ID, if it belongs to the requesting client.

URL template
/ats-api/v1/vacancies/{id}
Show / Hide additional information

Parameters

Name Type Location Field Description
id string Path Required The id of the vacancy

Response Codes

Status code Description
200 Returns the vacancy's attributes in JSON format.
401 Occurs when the provided API key is incorrect or missing.
404 No vacancy was found with the provided ID that belongs to this client.
500 An unexpected error occurred on the server.

Example Request

curl -X GET \
  "https://{{baseURL}}/ats-api/v1/vacancies/{id}"

PUT Updates an existing vacancy. The request body must include all required fields. Optional fields keep existing values if not provided.

Description

Updates an existing vacancy. The request body must include all required fields. Optional fields keep existing values if not provided.

URL template
/ats-api/v1/vacancies/{id}
Show / Hide additional information

Parameters

Name Type Location Field Description
id string Path Required The id of the vacancy

Request Model Example

{
  "vacancy": [
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [
          []
        ],
        [
          [
            []
          ]
        ]
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      [
        []
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [],
        []
      ]
    ],
    [
      [
        [],
        []
      ]
    ]
  ]
}

Response Codes

Status code Description
200 Indicates the vacancy was updated. Returns the updated resource data.
400 Missing or invalid fields in the request body.
401 Occurs when the provided API key is incorrect or missing.
404 No vacancy was found with the provided ID that belongs to this client.
409 A conflicting vacancy exists.<br>The conflicting vacancy contains the same values for either:<ul><li>The external reference (must be unique per API Client).</li><li>All these fields (must be unique per school):</li><ul><li>job title</li><li>expiry date</li><li>contract type</li><li>working patterns</li><li>phases</li><li>salary</li></ul></ul>
422 One or more values failed validation.
500 An unexpected error occurred on the server.

Example Request

curl -X PUT \
  "https://{{baseURL}}/ats-api/v1/vacancies/{id}" \
  -H "Content-Type: application/json" \
  -d '{
  "vacancy": [
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [
          []
        ],
        [
          [
            []
          ]
        ]
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      [
        []
      ]
    ],
    [
      [
        []
      ]
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      []
    ],
    [
      [
        [],
        []
      ]
    ],
    [
      [
        [],
        []
      ]
    ]
  ]
}'
Back to top