---
title: "Job API List"
slug: "job-api-list"
updated: 2026-10-21T12:26:17Z
published: 2026-10-21T12:26:17Z
canonical: "support.carehome.co.uk/job-api-list"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.carehome.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Job API List

Read the jobs you have posted, look up the allowed values for a job's fields, find the settings you can brand a job as, and check your job credit balance.

> [!NOTE]
> **Who can use it:** Enhanced and Platinum subscribers.

Every endpoint on this page accepts GET only. Base URL `https://api.carehome.co.uk`. Authentication, errors and support are covered in the [Jobs API overview](https://support.carehome.co.uk/docs/jobs-api).

## List your jobs

```
GET /index.cfm/jobs
```

Returns the jobs posted with your API key, newest first. A group's key also returns the jobs posted by each setting in the group. Closed jobs are left out; jobs that have expired are included, so check `job_expiry_date`.

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | string | Yes | Your API key. |

### Example request

```
curl "https://api.carehome.co.uk/index.cfm/jobs?api_key=YOUR_API_KEY"
```

### Example response

`200 OK`. The values below are illustrative.

```
{
  "data": [
    {
      "job_id": 96000000001,
      "job_title": "Care Assistant (example)",
      "job_setting": "Care Home / Nursing Home",
      "job_setting_id": 10,
      "job_category": "Carer / Care Assistant / Care Support Worker",
      "job_category_id": 5,
      "job_posted_date": "2026-10-01 09:30:00",
      "job_updated_date": "2026-10-01 09:30:00",
      "job_expiry_date": "31-Oct-2026 00:00:00",
      "job_location_text": "Exampletown, ",
      "job_member_id": 65432100000,
      "job_member_name": "Example Care Home",
      "job_town_id": 12345,
      "job_town_name": "Exampletown",
      "job_type": "Full Time",
      "job_type_id": "1",
      "job_contact_name": "Example Name",
      "job_contact_url": "",
      "job_contact_email": "example@example.com",
      "job_admin_email": "example@example.com",
      "job_reference": "EXAMPLE-001",
      "job_description": "<p>An example job description.</p>",
      "job_link": "https://www.carehome.co.uk/jobs/job.cfm/id/96000000001",
      "jobs_pay_type_id": 2,
      "jobs_salary_from": 12.5,
      "jobs_salary_to": 13.5,
      "job_salary": "",
      "job_skills": "Example skill, another example skill",
      "job_accept_applicant_uk_only": 0
    }
  ],
  "error": [],
  "warn": []
}
```

If you have no jobs, the response is `404` with `"error": ["No job record found."]` and an empty `data` array.

### Job object

| Field | Type | Description |
| --- | --- | --- |
| `job_id` | integer | ID of the job. |
| `job_title` | string | Job title. |
| `job_setting` | string | Name of the job setting (the kind of workplace). |
| `job_setting_id` | integer | ID from [`/jobs/settings`](/docs/job-api-list#lookups). |
| `job_category` | string | Name of the job category. |
| `job_category_id` | integer | ID from [`/jobs/categories`](/docs/job-api-list#lookups). |
| `job_posted_date` | string | When the job was posted, as `YYYY-MM-DD HH:MM:SS`. |
| `job_updated_date` | string | When the job was last changed, as `YYYY-MM-DD HH:MM:SS`. |
| `job_expiry_date` | string | When the job expires, as `DD-Mon-YYYY HH:MM:SS`, for example `31-Oct-2026 00:00:00`. Note the different format. |
| `job_location_text` | string | Deprecated; use `job_town_id` and `job_town_name`. |
| `job_member_id` | integer | ID of the setting or group the job is branded as. See [Job Post](https://support.carehome.co.uk/docs/job-post). |
| `job_member_name` | string | Name of the setting or group the job is branded as. |
| `job_town_id` | integer | ID from [`/jobs/towns`](/docs/job-api-list#lookups). |
| `job_town_name` | string | Town name. |
| `job_type` | string | Name of the job type, for example `Full Time`. |
| `job_type_id` | string | ID from [`/jobs/types`](/docs/job-api-list#lookups). Returned as a string, for example `"1"`. |
| `job_contact_name` | string | Contact name for the job. |
| `job_contact_url` | string | Application URL. Empty string if applications go by email. |
| `job_contact_email` | string | Email address applications are sent to. Empty string if applicants use the application URL. |
| `job_admin_email` | string | Email address for reminders about the job. |
| `job_reference` | string | Your own reference for the job. |
| `job_description` | string | Job description as HTML, after our clean-up; see [Job Post](https://support.carehome.co.uk/docs/job-post). |
| `job_link` | string | Link to the job on carehome.co.uk. |
| `jobs_pay_type_id` | integer | ID from [`/jobs/pay_types`](/docs/job-api-list#lookups). Empty string if not set. Note the `jobs_` prefix in this list. |
| `jobs_salary_from` | number | Lowest pay. Empty string if not set. |
| `jobs_salary_to` | number | Highest pay. Empty string if not set. |
| `job_salary` | string | Salary details as text. |
| `job_skills` | string | Skills and qualifications. |
| `job_accept_applicant_uk_only` | integer | `1` if the job only accepts applicants based in the UK, otherwise `0`. |

A field with no value is returned as an empty string.

## Get a job

```
GET /index.cfm/jobs/{job_id}
```

Returns one of your jobs. A group's key can also get a job posted by a setting in the group.

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | integer | Yes | In the path. ID of the job. |
| `api_key` | string | Yes | Your API key. |

### Example request

```
curl "https://api.carehome.co.uk/index.cfm/jobs/96000000001?api_key=YOUR_API_KEY"
```

### Response

`200 OK` with the job in `data` as an object, and an `error` array. The job has the same fields as the [job object](/docs/job-api-list#job-object), except that:

- the pay fields are named `job_pay_type_id`, `job_salary_from` and `job_salary_to` (no `s`);
- `job_location_text` includes the county, for example `Exampletown, Exampleshire`;
- `job_skills` and `job_accept_applicant_uk_only` are not included.

| Status | When | error |
| --- | --- | --- |
| 400 | `job_id` is not a number. | `A numeric value is required for job_id.` |
| 404 | The job does not exist, is closed, or is not yours. | `No record found for the job_id (# 96000000001 ) passed.` |

## Lookups

Use these to find the IDs a job needs. The values can change, so fetch them rather than hard-coding them; refreshing once a day is enough.

| Endpoint | Returns | Fields in each item |
| --- | --- | --- |
| `/index.cfm/jobs/categories` | Job categories, for `job_category_id` | `job_category_id`, `job_category_name`, `job_category_sequence` |
| `/index.cfm/jobs/settings` | Job settings (the kind of workplace), for `job_setting_id` | `job_setting_id`, `job_setting_name`, `job_setting_sequence` |
| `/index.cfm/jobs/types` | Job types such as Full Time, for `job_type_id` | `job_type_id`, `job_type_name`, `job_type_sequence` |
| `/index.cfm/jobs/pay_types` | Pay types, for `job_pay_type_id` | `job_pay_type_id`, `job_pay_type_name`, `job_pay_type_sequence` |
| `/index.cfm/jobs/towns` | All towns, for `job_town_id`. This is a large response. | `job_town_id`, `job_town_name` |
| `/index.cfm/jobs/towns/{job_town_id}` | One town | `job_town_id`, `job_town_name` |

`job_town_name` is the town, county and country, for example `Exampletown - Exampleshire - England`.

The pay types are:

| job_pay_type_id | Meaning |
| --- | --- |
| `1` | Per annum |
| `2` | Per hour |
| `5` | Non-specific salary: describe the pay in `job_salary` |

### Example request

```
curl "https://api.carehome.co.uk/index.cfm/jobs/types?api_key=YOUR_API_KEY"
```

### Example response

```
{
  "data": [
    { "job_type_id": 1, "job_type_name": "Full Time", "job_type_sequence": 10 },
    { "job_type_id": 2, "job_type_name": "Part Time", "job_type_sequence": 20 }
  ],
  "error": []
}
```

An unknown `job_town_id` returns `404` with `No town record found for the job_town_id passed.`; one that is not a number returns `400` with `job_town_id needs to be numeric.`

## Settings you can brand a job as

```
GET /index.cfm/jobs/members
GET /index.cfm/jobs/members/{member_id}
```

Returns the settings and groups you can use as `job_member_id` when posting a job. Which ones you get depends on your API key:

- a setting's key returns that setting only;
- a group's key returns the group and each setting in it.

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | string | Yes | Your API key. |
| `search_term` | string | Yes, unless `partner_key` is sent | At least three characters of the name to search for. Useful for an autocomplete. |
| `partner_key` | string | No | Partners only. Send it without `search_term` to get the full list. The full list can be large, so cache it and refresh it once a day. |

### Example request

```
curl "https://api.carehome.co.uk/index.cfm/jobs/members?api_key=YOUR_API_KEY&search_term=example"
```

### Example response

```
{
  "data": [
    {
      "member_id": 65432100000,
      "member_name": "(Self Branded) Example Care Home, Exampletown, Exampleshire, AB1 2CD [Care Home]",
      "member_is_group": 0
    }
  ],
  "error": []
}
```

| Field | Type | Description |
| --- | --- | --- |
| `member_id` | integer | Use as `job_member_id` when posting a job. |
| `member_name` | string | Name, town, county, postcode and type, for showing to users. Your own setting or group is marked `(Self Branded)` and listed first. |
| `member_is_group` | integer | `1` for a group, `0` for a setting. |

`/jobs/members/{member_id}` returns one item in the same format, with a shorter `member_name`, or `404` if you cannot brand a job as it. A `search_term` shorter than three characters returns `400`; a search with no matches returns `404`.

## Job credit balance

```
GET /index.cfm/jobs/credits
```

Returns how many job credits you have used and how many you have left. Posting a job uses one credit.

### Example request

```
curl "https://api.carehome.co.uk/index.cfm/jobs/credits?api_key=YOUR_API_KEY"
```

### Example response

```
{
  "data": {
    "job_credit_used": 12.0,
    "job_credit_balance": 8
  },
  "error": []
}
```

| Field | Type | Description |
| --- | --- | --- |
| `job_credit_used` | number | Credits used so far. Returned with a decimal point, for example `12.0`. |
| `job_credit_balance` | integer | Credits you can use now. |

## Related

- [Jobs API Changelog](/jobs-api-change-log.md)
- [Jobs API overview](/jobs-api.md)
- [Job Post](/job-post.md)
- [Job Edit](/job-edit.md)
- [Job Close](/job-close.md)