TBC Job Post REST API V2

AuthorGareth Hale
Version2.1
Date14th September 2025

The TBC Job Post REST API provides an interface for applications to interact with the jobs posted on The Best Connection job board by sending and receiving data as JSON (JavaScript Object Notation) objects. The API is protected by OAuth 2.0 Authentication an open standard for token-based authentication.

* indicates a required key/field/value

Documents

1. Authentication (OAuth 2.0)

Overview
Grant type: Password
The application presents a traditional username and password login form to collect a user’s credentials and makes a POST request to the server to exchange the password for an access token. The response will include an access token which is to be used to access any API data, the token is valid for 1 hour. Users have to create a token each time they want to request the API access.
To create an API account, all that is needed is an email address to setup the password. TBC will provide all other credentials.
Request Access Token

To get the token, you need to send a token request as shown below.

POST https://thebestconnection.co.uk/job-posts/api/v1/token

Body Parameters

Name Type Description
grant_type * String Grant type being used: password
username * String Username provided by TBC
password * String Get Password
client_id * String Client ID provided by TBC
client_secret * String Client Secret provided by TBC

Curl Example

Responses

Code Description
200 Successful response

Example Model

{
  “token_type”:”Bearer”,
  “iat”:1573547305,
  “expires_in”:1573550905,
  “access_token”:”HChQjI9zU09pA7gQ”
  “code”:”200″
}
400 Bad Request

Example Model

{
  “status”:”error”,
  “error”:”BAD_REQUEST”,
  “error_description”:”Invalid grant Type.”
}
403 Forbidden response

Example Model

{
  “status”:”error”,
  “error”:”FORBIDDEN”,
  “error_description”:”Invalid Username or Password.”
}
Revoke Access Token

Although tokens expire, it is recommended to revoke a token after completing your API action(s), allowing the authorisation server to clean up any security credentials associated with the authorisation.

To revoke the token, you need to send request as shown below.

POST https://thebestconnection.co.uk/job-posts/api/v1/revoke-token

Body Parameters

Name Type Description
token * String The token that needs to be revoked
token_type_hint String Type of token: access_token

Curl Example

Responses

Code Description
200 Successful response

Example Model

{
  “success”: true
}
400 Bad Request

Example Model

{
  “error”: “unsupported_token_type”,
  “error_description”: “The token type used is unsupported or the token is invalid.”
}

2. Retrieve Jobs

GET all Jobs

Returns 10 jobs per request by default (can be altered {jobs_per_page}) and the data includes the maximum number of pages. Pagination parameter {page_number} is required to retrieve a page of results, see example below.

GET https://thebestconnection.co.uk/job-posts/tbc-api/v1/jobs

Header *required

Name Value
TBCAuth Bearer {access_token}

Note: Obtain {access_token} before API action (see authentication)

Authentication no longer required to retrieve jobs

GET Parameters

Key Type Value
page * Integer {page_number}
per_page Integer {jobs_per_page}

NOTE: The returned results includes ‘max_num_pages’ the maximum number of pages for all jobs. You can program your application to loop through this number and return each paged data to obtain all results.

Curl Example

Code Description
200 Successful response

Example Model

{
  “status”:”success”,
  “max_num_pages”: 95,
  “jobs”: [
    {
      “ID”: “170899”,
      “JobRef”: “TAD56DFF”,
      “Title”: “Machine Operative”,
      “Secondary”: “”,
      “Description”: “Full description including HTML format”,
      “Updated”: “2025-01-15 17:46:28”,
      “Expiry”: “2025-01-29”,
      “Type”: “Temporary”,
      “Contract”: “Full time”,
      “PayRateMin”: “12.75”,
      “PayRateMax”: “15.15”,
      “PayText”: “£12.75-15.15 per hour”,
      “PayPeriod”: “hour”,
      “PayRateHow”: “After working 12 continuous weeks”,
      “WeeklyHours”: “”,
      “Sector”: “industrial”,
      “Requirements”: “Lorem ipsum dolor sit amet, consectetur adipiscing elit…..”,
      “Benefits”: “Lorem ipsum dolor sit amet, consectetur adipiscing elit…..”,
      “JobUrl”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff”,
      “ApplyUrl”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff?apply=true”,
      “Aplitrak”:”bob.12345.123@smith.aplitrak.com”,
      “ContactNumber”: “Call Adam or Tom on 01823 330621 for more information”,
      “ContactEmail”: “taunton@thebestconnection.co.uk”,
      “BranchCode”: “TA”,
      “BranchName”: “Taunton”,
      “Address”: “Bath Road, Bridgwater, Somerset, TA6 4NZ, UK”,
      “Line1”: “Bath Road”,
      “Line2”: “”,
      “TownCity”: “Bridgwater”,
      “Region”: “Somerset”,
      “PostCode”: “TA64NZ”,
      “Latitude”: “51.1415321”,
      “Longitude”: “-2.985066”,
      “PlanCode”: “TAIND2”
   }
  ]
}

Note: Requirements and Benefits could return an object array, this is how it was stored previously

401 Invalid Signature response

Example Model

{
  “status”:”error”,
  “error”:”INVALID_ACCESS_TOKEN”,
  “error_description”:”Invalid Access Token.”
}
401 Missing Authorization Header

Example Model

{
  “status”:”error”,
  “error”:”MISSING_AUTHORIZATION_HEADER”,
  “error_description”:”Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons. Check more details for the error on”
}
GET single Job

To return information about a job, it requires the job ID {identifier} to be passed as a lookup, see example below.

GET https://thebestconnection.co.uk/job-posts/tbc-api/v1/job

Header *required

Name Value
TBCAuth Bearer {access_token}

Note: Obtain {access_token} before API action (see authentication)

Authentication no longer required to retrieve jobs

GET Parameters

Key Type Value
ID * Integer {identifier}

NOTE: The returned results includes ‘max_num_pages’ but this is redundant for singular job and only used for all jobs.

Curl Example

Code Description
200 Successful response

Example Model

{
  “status”:”success”,
  “max_num_pages”: 1,
  “jobs”: [
    {
      “ID”: “170899”,
      “JobRef”: “TAD56DFF”,
      “Title”: “Machine Operative”,
      “Secondary”: “”,
      “Description”: “Full description including HTML format”,
      “Updated”: “2025-01-15 17:46:28”,
      “Expiry”: “2025-01-29”,
      “Type”: “Temporary”,
      “Contract”: “Full time”,
      “PayRateMin”: “12.75”,
      “PayRateMax”: “15.15”,
      “PayText”: “£12.75-15.15 per hour”,
      “PayPeriod”: “hour”,
      “PayRateHow”: “After working 12 continuous weeks”,
      “WeeklyHours”: “”,
      “Sector”: “industrial”,
      “Requirements”: “Lorem ipsum dolor sit amet, consectetur adipiscing elit…..”,
      “Benefits”: “Lorem ipsum dolor sit amet, consectetur adipiscing elit…..”,
      “JobUrl”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff”,
      “ApplyUrl”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff?apply=true”,
      “Aplitrak”:”bob.12345.123@smith.aplitrak.com”,
      “ContactNumber”: “Call Adam or Tom on 01823 330621 for more information”,
      “ContactEmail”: “taunton@thebestconnection.co.uk”,
      “BranchCode”: “TA”,
      “BranchName”: “Taunton”,
      “Address”: “Bath Road, Bridgwater, Somerset, TA6 4NZ, UK”,
      “Line1”: “Bath Road”,
      “Line2”: “”,
      “TownCity”: “Bridgwater”,
      “Region”: “Somerset”,
      “PostCode”: “TA64NZ”,
      “Latitude”: “51.1415321”,
      “Longitude”: “-2.985066”,
      “PlanCode”: “TAIND2”
   }
  ]
}

Note: Requirements and Benefits could return an object array, this is how it was stored previously

401 Invalid Signature response

Example Model

{
  “status”:”error”,
  “error”:”INVALID_ACCESS_TOKEN”,
  “error_description”:”Invalid Access Token.”
}
401 Missing Authorization Header

Example Model

{
  “status”:”error”,
  “error”:”MISSING_AUTHORIZATION_HEADER”,
  “error_description”:”Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons. Check more details for the error on”
}
422 Missing ID Parameter

Example Model

{
  “status”:”error”,
  “error”:”UNPROCESSABLE”,
  “error_description”:”The job ID parameter is missing”
}
404 No results found

Example Model

{
  “status”:”error”,
  “error”:”NOT FOUND”,
  “error_description”:”No results found”
}

3. Add/Update Jobs

POST a new Job

To add a new job, see example below.

POST https://thebestconnection.co.uk/job-posts/tbc-api/v1/update-job

Header *required

Name Value
TBCAuth Bearer {access_token}

Note: Obtain {access_token} before API action (see authentication)

POST Parameters

Key Type Value (Example)
ID * Integer 171431
JobRef * String MFGNROP1
Title * String Assembly Operative
Secondary String …
Description * String Full description including HTML format
Updated * Date (YYYY-MM-DD HH:MM:SS) 2025-01-15 16:58:59
Expiry * Date (YYYY-MM-DD) 2025-02-12
Type * String Temporary
Contract * String Full time
PayRateMin * Float 12.11
PayRateMax * Float 18.16
PayText * String £12.11-18.16 per hour
PayPeriod * String hour
PayRateHow * String Working Overtime
WeeklyHours Float 35
Sector * String warehouse & production
Requirements String Lorem ipsum dolor sit amet, consectetur adipiscing elit…..
Benefits String Lorem ipsum dolor sit amet, consectetur adipiscing elit…..
Aplitrak * String bob.12345.123@smith.aplitrak.com
ContactNumber * String Call Laura or Lauren 01623414281 for further information on this role!
ContactEmail * String mansfield@thebestconnection.co.uk
BranchCode * String(2) MF
BranchName * String Mansfield
Address String Mansfield, Nottinghamshire, NG18 5BY
Line1 String …
Line2 String …
TownCity String Mansfield
Region String Nottinghamshire
PostCode * String NG18 5BY
Latitude * String 53.1281037
Longitude * String -1.2160904
PlanCode String MFIND4

Note: Required fields cannot be NULL

Curl Example

Responses

Code Description
200 Successful response

Example Model

{
  “status”: “success”
  “response”: “job has been posted successfully”
  “job_url”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff”
  “apply_url”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff?apply=true”
}
401 Invalid Signature response

Example Model

{
  “status”:”error”,
  “error”:”INVALID_ACCESS_TOKEN”,
  “error_description”:”Invalid Access Token.”
}
401 Missing Authorization Header

Example Model

{
  “status”:”error”,
  “error”:”MISSING_AUTHORIZATION_HEADER”,
  “error_description”:”Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons. Check more details for the error on”
}
409 Duplicate ERROR

Example Model

{
  “status”:”error”,
  “error”:”DUPLICATE ERROR”,
  “error_description”:”Failed to insert the job post correctly, JobRef duplication detected”
}
422 Missing Required Parameter

Example Model

{
  “status”:”error”,
  “error”:”UNPROCESSABLE”,
  “error_description”:”One or more required parameters are missing”
  “missing_parameters”:”Contract,Type,Sector,Title”
}
PUT update a Job

Updating a job uses the same endpoint as adding a job, it looks up to check if the job ID already exists and performs an update action if it does.

PUT https://thebestconnection.co.uk/job-posts/tbc-api/v1/update-job

Header *required

Name Value
TBCAuth Bearer {access_token}

Note: Obtain {access_token} before API action (see authentication)

POST Parameters

Key Type Value (Example)
JobRef* String MFGNROP1
___ … Any available fields for adding a job (see above). Not all fields are required but if they are defined as required they cannot be set to NULL.

Curl Example

Responses

Code Description
200 Successful response

Example Model

{
  “status”: “success”
  “response”: “job has been updated successfully”
  “job_url”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff”
  “apply_url”: “https://www.thebestconnection.co.uk/jobs/machine-operative__tad56dff?apply=true”
}
401 Invalid Signature response

Example Model

{
  “status”:”error”,
  “error”:”INVALID_ACCESS_TOKEN”,
  “error_description”:”Invalid Access Token.”
}
401 Missing Authorization Header

Example Model

{
  “status”:”error”,
  “error”:”MISSING_AUTHORIZATION_HEADER”,
  “error_description”:”Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons. Check more details for the error on”
}
422 Missing Required Parameter

Example Model

{
  “status”:”error”,
  “error”:”UNPROCESSABLE”,
  “error_description”:”The job ID or job ref parameter is missing”
}

4. Remove Jobs

DELETE a Job

To remove a job, see example below..

DELETE https://thebestconnection.co.uk/job-posts/tbc-api/v1/delete-job

Header *required

Name Value
TBCAuth Bearer {access_token}

Note: Obtain {access_token} before API action (see authentication)

POST Parameters

Key Type Value (Example)
JobRef * String MFGNROP1

Curl Example

Responses

Code Description
200 Successful response

Example Model

{
  “status”: “success”
  “response”: “job has been deleted successfully”
}
401 Invalid Signature response

Example Model

{
  “status”:”error”,
  “error”:”INVALID_ACCESS_TOKEN”,
  “error_description”:”Invalid Access Token.”
}
401 Missing Authorization Header

Example Model

{
  “status”:”error”,
  “error”:”MISSING_AUTHORIZATION_HEADER”,
  “error_description”:”Authorization header not received. Either authorization header was not sent or it was removed by your server due to security reasons. Check more details for the error on”
}
422 Missing Required Parameter

Example Model

{
  “status”:”error”,
  “error”:”UNPROCESSABLE”,
  “error_description”:”The job ID or job ref parameter is missing”
}
404 Missing Required Parameter

Example Model

{
  “status”:”error”,
  “error”:”NOT FOUND”,
  “error_description”:”job was not found or has already been removed”
}

5. Other

Contact & Support

Any questions or issues using the API

Gareth Hale
gareth@citcom.co.uk

Download the Postman examples

Download

Job Field Explained
Key (Field) Type Description Required Allow NULL
ID Integer The ID shared between systems (The unique identifier) Y N
JobRef String Branch issued Ref (BranchCode+Ref) Y N
Title String Main job title Y N
Secondary String Secondary additional refined title N Y
Description String Full text in html as entered by the consultant for the position. (contains html) Y N
Updated Date (YYYY-MM-DD HH:MM:SS) Date last edited and approved Y N
Expiry Date (YYYY-MM-DD) Date Job Expires Y N
Type String Position term “Temporary” or “Permanent” Y N
Contract String Contract term “Full time” or “Part time” or “‘Full or Part time” Y N
PayRateMin Float Pay (min) Y N
PayRateMax Float Pay (max) Y N
PayText String Pay text in words e.g. “£11.74-17.61 per hour” Y N
PayPeriod String Pay period types “annum”, “month”, “week”, “day”, “hour” Y N
PayRateHow String How to achieve the max pay rate N Y
WeeklyHours Float Specific hours listed N Y
Sector String Job Sector name (should be consistant, for creating taxonamy) Y N
Requirements String List of requirements for the position (new method accepts string with HTML) N Y
Benefits String List of benefits for the position (new method accepts string with HTML) N Y
JobUrl String URL to job single page N N
ApplyUrl String URL used to apply N N
Aplitrak String Email address used for forwarding applications to. Y N
ContactNumber String Mobile & Contact details often out of hours Y N
ContactEmail String Branch email contact address to be used Y N
BranchCode String (2) TBC allocated BranchCode ref Y N
BranchName String Branch name listed Y N
PlanCode String TBC allocated plan code including BranchCode e.g. NEHGV1 N Y
Address String Address lineage, full address not always available N Y
Line1 String Address line 1 N Y
Line2 String Address line 2 N Y
TownCity String Town or City location N Y
Region String Region N Y
PostCode String Postcode of recruiter or branch if not available Y N
Latitude String Approx Latitude positioning Y N
Longitude String Approx Longitude positioning Y N