Menu

API Documentation

Available endpoints

POST -> https://www.datatalentjobs.co.uk/api/v1/jobs/add
POST -> https://www.datatalentjobs.co.uk/api/v1/jobs/delete
POST -> https://www.datatalentjobs.co.uk/api/v1/jobs/close
POST -> https://www.datatalentjobs.co.uk/api/v1/jobs/repost

GET -> https://www.datatalentjobs.co.uk/api/v1/jobs/statistics?job=[job-slug-from-a-previous-response]
GET -> https://www.datatalentjobs.co.uk/api/v1/jobs/applications?job=[job-slug-from-a-previous-response]
GET -> https://www.datatalentjobs.co.uk/api/v1/jobs/application?job=[job-slug-from-a-previous-response]

Content types

Currently Our API ONLY accepts JSON (application/json). The content type must be sent as a header e.g: Content-type: application/json this will determine the output response, if you add an Accept header then the first found value (split on ";") will override the output response type. You may also optionaly add an Accept-Encoding header, we currently support gzip but there are plans to add to this at a later date.

Authentication

curl -X [VERB] https://www.datatalentjobs.co.uk/api/v1/jobs \
-H 'Content-Type: application/json; charset=utf-8' \
--user '[provider_token]:[recruiter_token]' \
...

Your user credentials including your API key/token are created by each client inside their dashboard. They are used with HTTP basic authentication and have the form [provider_token]:[recruiter_token] One set of credentials can be used for multiple users of the same CLIENT i/e recruiter, this is because the client identifier is extrapolated from the recruiter_token sent with each request. This means if you as a provider have multiple clients using this system then each of them will need a separate recruiter_token, however the provider_token will stay the same across requests unless you report an information credential leak and we need to cycle your token.

Example job post data

Please note the "test_post": 1 field. This allows you to send jobs to our platform without using up a credit and without it ending up in the search index. A job with "test_post": 1 will still have a URL which is returned to you so that you may view the job and delete the job on the system.

Example job delete data

  curl -X POST https://www.datatalentjobs.co.uk/api/v1/jobs/delete \
  -H 'Content-Type: application/json; charset=utf-8' \
  --user '[provider_token]:[recruiter_token]' \
  -d '
  {
    "job": "full-time-test-engineer-london-acme-123"
}
  '

Example job close data

curl -X POST https://www.datatalentjobs.co.uk/api/v1/jobs/close \
-H 'Content-Type: application/json; charset=utf-8' \
--user '[provider_token]:[recruiter_token]' \
-d '
{
    "job": "full-time-test-engineer-london-acme-123"
}
'

Example job respost data

  curl -X POST https://www.datatalentjobs.co.uk/api/v1/jobs/repost \
  -H 'Content-Type: application/json; charset=utf-8' \
  --user '[provider_token]:[recruiter_token]' \
  -d '
  {
    "job": "full-time-test-engineer-london-acme-123"
}
  '

Please note that slugs are unique across our job board!

Rigid data

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.

Certain fields have rigid requirements in our system. These are outlined below. Any other field is classed as free text.

https://www.datatalentjobs.co.uk/api/v1/jobs/fields
job_sector (one of)
[
    "data-analysis-jobs",
    "big-data-jobs",
    "data-science-jobs",
    "other-support-jobs"
]
job_discipline (one of) | Format: "parent_sector" : ["array of disciplines"]
Please note that job_discipline must be a child value of the parent job_sector. If you attempt to send a job_discipline that is from a different sector or does not exist your job post will fail!

{
    "data-analysis-jobs": [
        "data-analyst",
        "business-intelligence-analyst",
        "financial-analyst",
        "marketing-analyst"
    ],
    "big-data-jobs": [
        "database-administrator",
        "data-architect",
        "data-engineer"
    ],
    "data-science-jobs": [
        "data-scientist",
        "machine-learning-engineer",
        "statistician"
    ],
    "other-support-jobs": [
        "administrators",
        "support",
        "other",
        "data-entry"
    ]
}
job_type (one of)
[
    "Part time",
    "Full time"
]
contract_type (one of)
[
    "Permanent",
    "Contract",
    "Temporary",
    "Maternity cover"
]
salary_unit (one of)
[
    "Per year",
    "Per month",
    "Per week",
    "Per day",
    "Per hour"
]
salary_currency "GBP"
job_telecommute (one of)
[
    0,
    1
]

Exceptions

If available_from is set the date format is YYYY-MM-DD H:i (ex 2020-01-28 09:00). If days_to_advertise is set the number must not exceed 30 - exceeding this will generate an error.

job_longitude and job_latitude which are double's and MUST point to a specific point on the geo plane. job_postcode is free text and (as with latitude/longitude) is NEVER shown to the candidate. job_location is the visible location shown to the candidate in job results and filters and can be any text string.

If application_url is set the scheme must be secure (https).

Required fields

    job_title
    job_reference
    job_sector
    job_discipline
    job_telecommute
    job_location
    job_latitude (not required if using value from pre-defined job_location list)
    job_longitude (not required if using value from pre-defined job_location list)
    job_postcode (not required if using value from pre-defined job_location list)
    job_description
    job_type
    contract_type
    contact_name
    contact_email
    salary_visible
    salary_precise
    salary_unit
    salary_currency

All fields listed above are required

JSON Responses

successful post

{
    "status": 200,
    "message": "https://www.datatalentjobs.co.uk/job/full-time-test-engineer-london-acme-1234"
}
errored post

{
    "status": 412,
    "message": "Salary unit invalid"
}
successful close

{
    "status": 200,
    "message": "Job has been closed"
}
successful deletion

{
    "status": 200,
    "message": "Job has been deleted"
}

Returning applications

Inside the applications and if one exists a path to the attached resume will be presented. To download the resume you will need to send an authenticated request using your provider_token and recruiter_token (as with all other examples) to the url located in the resume.filepath value (example below)

    curl -X GET https://www.datatalentjobs.co.uk/api/v1/jobs/application?id=12345 \
    -H 'Content-Type: application/json; charset=utf-8' \
    --user '[provider_token]:[recruiter_token]'
    
GET application resume

{
    "status": 200,
    "message": "https://www.datatalentjobs.co.uk/api/v1/jobs/application?id=42543",
    "resume": {
        "data": "base64 encoded data string of the file contents",
        "name": "finely-bennett-resume.pdf",
        "size": "205126"
    }
}

Returning statistics

  curl -X GET https://www.datatalentjobs.co.uk/api/v1/jobs/statistics?job=slug-from-a-previous-response \
  -H 'Content-Type: application/json; charset=utf-8' \
  --user '[provider_token]:[recruiter_token]'
  
GET job statistics

{
    "status": 200,
    "message": "https://www.datatalentjobs.co.uk/job/full-time-test-engineer-london-acme-1234",
    "statistics": {
        "views": 356,
        "applications": 12
    }
}