Developer API documentation

To begin using the API you need to create an API key. This can be done inside your agency account page. Click on the Create an API key link and fill in the form, you will then be given an API which you can use to access our API. Alternatively you can pass this API key along to your developer or multi-poster and they will be able to use it to interact with this API on your behalf.

Multi-posters: You will need an API key for each recruitment agency you want to post on behalf of.

Authentication

To interact with our platform you will need to send your API key as an HTTP header with every request

All successful requests will return a HTTP 200 status code. Any requests with errors will return a 500 status code along with a JSON response containing the error message. Please see below for an example.

    curl -X POST https://www.reccircle.co.uk/api/v1/jobs/add \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authentication: Bearer {api_key}'
  

Enter your API key to populate the examples

Creating a job

Request 
    curl -X POST https://www.reccircle.co.uk/api/v1/jobs/create \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authentication: Bearer {api_key}' \
    -d '
    {
    "job_title": "Test Engineer",
    "employment_type": "full-time",
    "recruitment_type": "contract",
    "job_description": "This is the detailed description",
    "job_sector": "accountancy",
    "suited_to": "technical-recruiter",
    "job_latitude": 1.5,
    "job_longitude": 53.2,
    "job_location": "London",
    "remote_work_options": [
        "remote-available"
    ],
    "salary_base": "30000",
    "salary_benefits": "Bonus and Pension",
    "available_at": "2025-04-07 10:13:47",
    "closes_at": "2025-04-30 10:13:47",
    "starts_at": "2025-06-29 10:13:47",
    "contact_name": "Bob Smith",
    "contact_email": "[email protected]",
    "test_post": 1
}'
    
Response
    {
    "success": true,
    "message": "https://www.reccircle.co.uk/job/job-slug/1234",
    "errors": []
}
    
Error
    {
    "success": false,
    "message": "There are one or more errors with your request",
    "errors": [
        "Sector is invalid",
        "Location is invalid"
    ]
}
    Expand/collapse
  

Please note that ALL fields are required.

Including "test_post":1 in your request will create a test post in our platform. The salary_base will be rounded to the nearest £5,000 and added to a salary bracket automatically.

Deleting a job

Request
    curl -X POST https://www.reccircle.co.uk/api/v1/jobs/delete \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authentication: Bearer {api_key}' \
    -d '
    {
    "id": 1234
}'
    
Response
    {
    "success": true,
    "message": "The job has been deleted",
    "errors": []
}
    
Error
    {
    "success": false,
    "message": "There was an error with your request",
    "errors": [
        "You do NOT own that job"
    ]
}
    Expand/collapse
  

Unpublishing / Closing a job

Request
    curl -X POST https://www.reccircle.co.uk/api/v1/jobs/unpublish \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authentication: Bearer {api_key}' \
    -d '
    {
    "job": "https://www.reccircle.co.uk/job/job-slug/1234"
}'
    
Response
    {
    "success": true,
    "message": "Job has been unpublished",
    "errors": []
}
    
Error
    {
    "success": false,
    "message": "There is an error with your request",
    "errors": [
        "That vacancy does not exist"
    ]
}
    Expand/collapse
  

Publishing a job

Request
    curl -X POST https://www.reccircle.co.uk/api/v1/jobs/publish \
    -H 'Content-Type: application/json; charset=utf-8' \
    -H 'Authentication: Bearer {api_key}' \
    -d '
    {
    "job": "https://www.reccircle.co.uk/job/job-slug/1234"
}'
    
Response
    {
    "success": true,
    "message": "Job has been unpublished",
    "errors": []
}
    
Error
    {
    "success": false,
    "message": "There is an error with your request",
    "errors": [
        "That vacancy does not exist"
    ]
}
    Expand/collapse
  

Fixed fields

Please note that the rigid data is subject to change as we add or remove industries etc. We have a json endpoint that has up to date values for these fields which we recommend you automatically check via your software from time to time.

https://www.reccircle.co.uk/api/v1/fields (Opens in new window)

Employment types

employment_type (one of)
[
    "full-time",
    "part-time"
]

Recruitment types

recruitment_type (one of)
[
    "contract",
    "permanent"
]

Sectors

sectors (one of)
[
    "accountancy",
    "banking",
    "call-centre",
    "commercial-office-services",
    "construction",
    "driving-logistics",
    "education",
    "engineering",
    "environment",
    "finance",
    "graduate",
    "health-social-care",
    "high-street",
    "hospitality-catering",
    "human-resources",
    "insurance",
    "industrial",
    "it",
    "legal",
    "management",
    "m-e",
    "pharmaceutical",
    "public-sector",
    "retail",
    "sales-marketing",
    "scientific",
    "search-and-selection",
    "supply-chain",
    "technical",
    "transport",
    "trainees",
    "unspecified"
]

Suited to

suited_to (one of)
[
    "technical-recruiter",
    "specialist-recruiter",
    "contract-specialist",
    "volume-recruiter",
    "key-account-manager",
    "business-developer",
    "hunter",
    "farmer",
    "general-recruiter"
]

Remote work options

remote_work_options (one of)
[
    "remote-available",
    "remote-not-available",
    "fully-remote",
    "hybrid",
    "not-specified"
]

Salaries

salary_base (one of)
[20000,21000,22000,23000,24000,25000,26000,27000,28000,29000,30000,31000,32000,33000,34000,35000,36000,37000,38000,39000,40000,41000,42000,43000,44000,45000,46000,47000,48000,49000,50000,51000,52000,53000,54000,55000,56000,57000,58000,59000,60000,61000,62000,63000,64000,65000,66000,67000,68000,69000,70000,71000,72000,73000,74000,75000,76000,77000,78000,79000,80000,81000,82000,83000,84000,85000,86000,87000,88000,89000,90000,91000,92000,93000,94000,95000,96000,97000,98000,99000,100000,101000,102000,103000,104000,105000,106000,107000,108000,109000,110000,111000,112000,113000,114000,115000,116000,117000,118000,119000,120000,121000,122000,123000,124000,125000,126000,127000,128000,129000,130000,131000,132000,133000,134000,135000,136000,137000,138000,139000,140000,141000,142000,143000,144000,145000,146000,147000,148000,149000,150000,151000,152000,153000,154000,155000,156000,157000,158000,159000,160000,161000,162000,163000,164000,165000,166000,167000,168000,169000,170000,171000,172000,173000,174000,175000,176000,177000,178000,179000,180000,181000,182000,183000,184000,185000,186000,187000,188000,189000,190000,191000,192000,193000,194000,195000,196000,197000,198000,199000,200000,201000,202000,203000,204000,205000,206000,207000,208000,209000,210000,211000,212000,213000,214000,215000,216000,217000,218000,219000,220000,221000,222000,223000,224000,225000,226000,227000,228000,229000,230000,231000,232000,233000,234000,235000,236000,237000,238000,239000,240000,241000,242000,243000,244000,245000,246000,247000,248000,249000,250000]Expand/collapse