# How can we help?

## Search

## Overview

The Jobs resource contains all background Job activity and status for retrieval via GET calls.

**API set name: jobs**

### Additional information

- Jobs are generated by the application to manage and track contact imports and exports using the [Contact import](https://support.cordial.com/hc/en-us/articles/203886058) and [Contact export APIs](https://support.cordial.com/hc/en-us/articles/203886068).
- The Job information includes Job status, Job ID, Job name, total items, completed items and start and end times.
- For import Jobs specifically, Jobs also include total records, number updated, number inserted, number rejected, duplicate records, invalid records and new records.
- Job names and IDs are given to the job automatically based on the API initiating the job type. For example, contactimports will assign the value of `ImportContacts` to the `jobName`.
- Jobs can have a status of Scheduled, Pending, Processing, Failed, and Done.
- Jobs records are retained for 60 days.
- Job rejections and import rejections are downloadable in the UI.
- Job rejections are retained for 7 days.

## Authentication

Cordial's core APIs use HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded [API key for your account](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

- [Learn more about Cordial API authentication here](https://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).

## Resource associations

The following resource collections are associated to this collection.

| Collection | Association |
| --- | --- |
| contactimports | The **contactimports** resource creates job records in the **jobs** collection. |
| contactexports | The **contactexports** resource creates job records in the **jobs** collection. |

## Methods, parameters, and examples

- [GET/v2/jobs](https://support.cordial.com/hc/en-us/articles/204570807-Jobs-API#getJobs)
- [GET/v2/jobs/{ID}](https://support.cordial.com/hc/en-us/articles/204570807-Jobs-API#getJobsID)

## GET/v2/obs

| Method | URL Path |
| --- | --- |
| GET | /v2/jobs |
| Retrieves all jobs from the Cordial database. |

- [Query string parameters](https://support.cordial.com/hc/en-us/articles/204570807-Jobs-API#zp-1-0)
- [Example request URLs](https://support.cordial.com/hc/en-us/articles/204570807-Jobs-API#zp-1-1)

| Parameter | Type | Description | Example |
| --- | --- | --- | --- |
| `jobName` | string | Name given to the job. | ```<br>?jobName=ImportContacts<br>``` |
| `times[start][gt]` | string | Returns results where the start time is greater than the specified date. | ```<br>?times%5Bstart%5D%5Bgt%5D=01-01-2025<br>``` |
| `times[start][gte]` | string | Returns results where the start time is greater than or equal to the specified date. | ```<br>?times%5Bstart%5D%5Bgte%5D=01-01-2018<br>``` |
| `times[start][lt]` | string | Returns results where the start time is less than specified date. | ```<br>?times%5Bstart%5D%5Blt%5D=01-01-2018<br>``` |
| `times[start][lte]` | string | Returns results where the start time is less than or equal to the specified date. | ```<br>?times%5Bstart%5D%5Blte%5D=01-01-2025<br>``` |
| `times[end][gt]` | string | Returns results where the end time is greater than specified date. | ```<br>?times%5Bend%5D%5Bgt%5D=01-01-2025<br>``` |
| `times[end][gte]` | string | Returns results where the end time is greater than or equal to the specified date. | ```<br>?times%5Bend%5D%5Bgte%5D=01-01-2018<br>``` |
| `times[end][lt]` | string | Returns results where the end time is less than the specified date. | ```<br>?times%5Bend%5D%5Blt%5D=01-01-2018<br>``` |
| `times[end][lte]` | string | Returns results where the end time is less than or equal to the specified date. | ```<br>?times%5Bend%5D%5Blte%5D=01-01-2025<br>``` |
| `status` | string | The active Job status.<br>**Possible Values**: <br>Scheduled, Pending, Processing, Failed, Done | ```<br>?status=Scheduled<br>``` |
| `page` | string | Specifies the results page number. | ```<br>?page=3<br>``` |
| `per_page` | string | Specifies the number of records returned per page. | ```<br>?per_page=100<br>``` |

The following URL will retrieve all jobs and include all fields.

```
https://<path>/v2/jobs
```

The following URL will retrieve the job with the `jobName` of `ImportContacts`.

```
https://<path>/v2/jobs?jobName=ImportContacts
```

The following URL will retrieve all jobs, but will only include jobs that have a `status` of `Failed`.

```
https://<path>/v2/jobs?status=Failed
```

The following URL will retrieve all jobs starting from the third page grouping jobs by 10. For example, `page-1` would include the first 10, `page-2` the second group of 10, and so on.

```
https://<path>/v2/jobs?page=3&per_page=10
```

## GET/v2/jobs/{id}

| Method | URL Path |
| --- | --- |
| GET | /v2/jobs/{id} |
| - Retrieves a specific job record from the Cordial database. The job record is defined by the Job's unique ID value.<br>- For example, /jobs/548817d0367df1ef518b4567 would return the response data for the job with the id of `548817d0367df1ef518b4567`. |

The following URL will retrieve the job with the ID value of `123123`.

```
https://<path>/v2/jobs/123123
```

## Error responses

The Cordial API will return an error object with an `errorKey` and `message` if there is a problem with an API call. Below is a list of errors specific to the Jobs API endpoint, along with suggested modifications to resolve each error. If you receive an error from the Jobs API endpoint that is not listed in this table, it is likely recorded within the [Global API Error Responses](https://support.cordial.com/hc/en-us/articles/4402427843597-Global-API-Error-Responses) page.

| errorKey | Message | Modifications |
| --- | --- | --- |
| `JOBS_COULD_NOT_BE_CREATED` | Job could not be created | Ensure input values are correct. |
| `JOBS_INCORRECT_FILTER` | Time value is incorrect | Time values should be in ISO 08601 date format e.g. `YYYY-MM-DDThh:mm:ss`. |