Menu
Clear
Recommended
Recommended
Recommended
Recommended
Recommended

API Documentation

Authentication example

  curl -X [VERB] https://www.positiveoutcome.co.uk/api/v1/metrics/list \
  --user 'your_username:strong_password!'

User credentials are created inside your control panel. They are used with HTTP basic authentication and have the form [username]:[password].

Content types

  • For POSTrequests (adding/closing jobs etc) this API only accepts JSON (application/json). The content type must be sent as a header e.g: Content-type: application/json.
  • For GET requests no content type is required, sending a content type header will not be honoured for GET requests.

Request & Response examples

Each section in this documentation has examples of a request and subsequent response data for the endpoints contained within.

Request rate limited

Please note that requests to these enpoints are rate limited. You may make one request per endpoint per 15 minutes And enpoint is denoted as a request, for example downloading a document and then a resume are treated as different endpoints as are ?page=1 and ?page=2. These API's are not intended to give you an interface to query real-time data for your application / third party software, it's intended to keep your website data in sync across third party providers that choose not to have API's in to their system. If you make too many requests in the time period you will recieve a 429 response header along with a Retry-after header which has the value in seconds to retry the request, this will allow you to gracefully queue your request to retry after the given amount of time.

Available endpoints for jobs

(VERB -> Endpoint)

POST → https://www.positiveoutcome.co.uk/api/v1/job/add
POST → https://www.positiveoutcome.co.uk/api/v1/job/delete
POST → https://www.positiveoutcome.co.uk/api/v1/job/close
POST → https://www.positiveoutcome.co.uk/api/v1/job/expire
POST → https://www.positiveoutcome.co.uk/api/v1/job/repost

GET → https://www.positiveoutcome.co.uk/api/v1/job/fields

Endpoint descriptions

/add (self explanitory!)
/delete (removes job from system - be careful!)
/close (marks as unpublished and will 404)
/expire (marks as no longer accepting applications)
/repost (reposts the job with new closing and expiry dates +1 month)

Example job post data

Example job delete data

curl -X POST https://www.positiveoutcome.co.uk/api/v1/job/delete \
-H 'Content-Type: application/json; charset=utf-8' \
--user 'your_username:strong_password!' \
-d '
{
    "id": 1234
}
'

Example job repost data

curl -X POST https://www.positiveoutcome.co.uk/api/v1/job/repost \
-H 'Content-Type: application/json; charset=utf-8' \
--user 'your_username:strong_password!' \
-d '
{
    "id": 1234,
    "closing_date": "2022-02-28 09:00"
}
'

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.positiveoutcome.co.uk/api/v1/job/fields
job_industry (one of)
[
    "Adult Social Care",
    "Children's Social Care",
    "Education & Training",
    "Healthcare, Nursing & Therapy",
    "HR, Recruitment & Administration",
    "Property, Catering & Domestic",
    "Senior Management"
]
    
A forward slash denotes the sub-sector or discipline of the sector, you can use just the sector name or [Sector]/[Sub_sector] and we will parse out the sector and sub-sector for you.
job_type (one of)
[
    "Full time",
    "Part time"
]
contract_type (one of)
[
    "Permanent"
]
salary_unit (one of)
[
    "Per hour",
    "Per year",
    "Per week"
]
salary_currencies (one of)
[
    "GBP"
]
job_telecommute (one of)
[
    "yes",
    "no"
]

Exceptions to rigid data

If available_from is set the date format is YYYY-MM-DD H:i (ex 2020-01-28 09:00).

job_longitude and job_latitude which are double's and MUST point to a specific point on the geo plane. job_location is the visible location shown to the candidate in job results and filters and can be any text string.

Required fields

    published (1 or 0)
    featured (1 or 0)
    job_title
    job_reference
    job_industry
    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_type
    contract_type
    job_description
    contact_name
    contact_email
    salary_visible
    salary_precise
    salary_unit
    salary_currency
    require_cv (1 or 0)

All fields listed above are required

JSON Responses

Successful post

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

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

{
    "status": 200,
    "message": "Job has been closed (unpublished)"
}
Successful deletion

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

{
    "status": 200,
    "message": "Job has been expired"
}
Successful repost

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

Available endpoints for candidates

(VERB -> Endpoint)

GET → https://www.positiveoutcome.co.uk/api/v1/candidates/list
GET → https://www.positiveoutcome.co.uk/api/v1/candidates/details/{id}
GET → https://www.positiveoutcome.co.uk/api/v1/candidates/timesheet/{id}
GET → https://www.positiveoutcome.co.uk/api/v1/candidates/document/{id}
GET → https://www.positiveoutcome.co.uk/api/v1/candidates/resume/{id}

Endpoint descriptions

/list List all candidates parameter since
/details/{id} Show specific candidate details with parameter id
/timesheet/{id} Downloads timesheet of parameter id (from previous request/response)
/resume/{id} Downloads resume of parameter id (from previous request/response)
/document/{id} Downloads document of parameter id (from previous request/response)

Example candidate list request & response

Example candidate details request & response

Available endpoints for applications

(VERB -> Endpoint)

GET → https://www.positiveoutcome.co.uk/api/v1/applications/list
GET → https://www.positiveoutcome.co.uk/api/v1/applications/details/{id}
GET → https://www.positiveoutcome.co.uk/api/v1/applications/attachment/{id}

Endpoint descriptions

/list List all applications with since or vacancy paramter(s)
/details/{id} Show specific application details with parameter id
/attachment/{id} Downloads attachment of parameter id (from previous request/response)

Example application list request & response

Example application details request & response

Example application attachment request & response

Please note that it is your responsibility to check attachments with up-to-date anti virus software. We cannot be held responsible for any infections, malware or other kind of expolits that pertain to downloaded files from this platform.

Available endpoints for timesheets

(VERB -> Endpoint)

GET → https://www.positiveoutcome.co.uk/api/v1/timesheets/list
GET → https://www.positiveoutcome.co.uk/api/v1/candidates/timesheets/download/{id}

Endpoint descriptions

/list List all timesheets parameter since
/download/{id} Download specific timesheet details with parameter id

Request rate limited

Please note that requests to these enpoints are rate limited. You may make one request per endpoint per 15 minutes And enpoint is denoted as a request, for example downloading a document and then a resume are treated as different endpoints as are ?page=1 and ?page=2. These API's are not intended to give you an interface to query real-time data for your application / third party software, it's intended to keep your website data in sync across third party providers that choose not to have API's in to their system. If you make too many requests in the time period you will recieve a 429 response header along with a Retry-after header which has the value in seconds to retry the request, this will allow you to gracefully queue your request to retry after the given amount of time.

Authentication example

curl -X [VERB] https://www.positiveoutcome.co.uk/api/v1/timesheets/list \
--user 'your_username:strong_password!'

User credentials are created inside your control panel. They are used with HTTP basic authentication and have the form [username]:[password].

Example timesheet list request & response

Example timesheet download request & response

Please note that it is your responsibility to check attachments with up-to-date anti virus software. We cannot be held responsible for any infections, malware or other kind of expolits that pertain to downloaded files from this platform.

Available endpoints for marketing

(VERB -> Endpoint)

GET → https://www.positiveoutcome.co.uk/api/v1/marketing/list

Endpoint descriptions

/list List all marketing approvals/revocations parameter since

Example timesheet list request & response

Available endpoints for metrics

(VERB -> Endpoint)

GET → https://www.positiveoutcome.co.uk/api/v1/metrics/list

Endpoint descriptions

/list List all metrics & aggregations

Example metrics list request & response