Custom Objects Jobs

The Jobs API lets you define and run asynchronous batch operation jobs on object records and relationship records. For example, you can define and run a single job that creates many object records.

For more information, see Jobs in the Custom objects developer guide.

See also Rate limits in the introduction.

JSON format

A job consists of a JSON object with the following properties.

Name Type Required Comment
type string yes One of "resources" or "relationships". Resources refer to object records. Relationships refer to relationship records
action string yes One of the following depending on job type: "post", "delete", "update", "external_id_delete", "external_id_set". See action property
data array yes An array of object or relationship records or ids to process. See data property
action property

The action you can specify depends on the job type.

A job of type "resources" (object records) supports the following actions:

  • "post"
  • "delete"
  • "update"
  • "external_id_delete"
  • "external_id_set"

A job of type "relationships" (relationship records) supports the following action:

  • "post"
  • "delete"
data property

The data property in the request body specifies an array of JSON objects to batch process. The format of the JSON objects you can specify depends on the job.

Jobs to post object records or relationship records

When a job's type is "resources" or "relationships" and its action is "post", the data property supports object records or relationship records. The format of each object is the same as the data object for the equivalent single-operation endpoints for object records or relationship records.

Example:

{
  "type": "resources",
  "action": "post",
  "data": [
    {
      "type": "product",
      "external_id": "3",
      "attributes": {
        "id": "3",
        "name": "Strawberry Chewing Gum"
      }
    },
    {
      "type": "product",
      "external_id": "4",
      "attributes": {
        "id": "4",
        "name": "Coffee Chewing Gum"
      }
    }
  ]
}
Jobs to update object records

When a job's type is "resources" and its action is "update", the data property supports JSON objects with the following properties:

Name Type Description
id string The id of the object record to update
attributes object An object containing the properties to update

For each object, the id value is used to locate the object record in the database and the attributes value is used to patch the existing value.

Example:

{
  "type": "resources",
  "action": "update",
  "data": [
    {
      "id": "576a0d0d-fb3f-11e9-80f8-65590b274410",
      "attributes": {
        "name": "Strawberry Chewing Gum v2"
      }
    },
    {
      "id": "576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c",
      "attributes": {
        "name": "Coffee Chewing Gum (decaf)"
      }
    }
  ]
}
Jobs to set object records using external id

When a job's type is "resources" and its action is "external_id_set", the data property supports JSON objects with the following properties:

Name Type Description
type string The object type of the object record
external_id string The external_id of the object record to set
attributes object An object containing the properties to set

For each object, the external_id and resource type values are used to locate the object record in the database. If the resource exists, the attributes value is used to patch the existing value. If the resource does not exist, a new resource of the given resource type is created with the external_id and attributes.

Example:

{
  "type": "resources",
  "action": "external_id_set",
  "data": [
    {
      "type": "product",
      "external_id": "4",
      "attributes": {
        "name": "Coffee Chewing Gum (decaf)"
      }
    },
    {
      "type": "product",
      "external_id": "5",
      "attributes": {
        "name": "Blueberry Chewing Gum"
      }
    }
  ]
}
Jobs to delete object records or relationship records

When a job's type is "resources" or "relationships" and its action is "delete", the data property supports a list of ids of the object or relationship records to be deleted.

Examples:

{
  "type": "resources",
  "action": "delete",
  "data": [
    "576a0d0d-fb3f-11e9-80f8-65590b274410",
    "576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c",
    "69d0b3e2-ec4e-11e9-ad75-4b6f5c0467f5"
  ]
}
{
  "type": "relationships",
  "action": "delete",
  "data": [
    "576a0d0d-fb3f-11e9-80f8-65590b274410",
    "576a5b2e-fb3f-11e9-80f8-f1af99ee4b4c",
    "69d0b3e2-ec4e-11e9-ad75-4b6f5c0467f5"
  ]
}
Jobs to delete object records using external id

When a job's type is "resources" and its action is "delete", the data property supports a list of object type and external_id of the object records to be deleted.

Examples:

{
  "type": "resources",
  "action": "external_id_delete",
  "data": [
    {
      "type": "product",
      "external_id": "4"
    },
    {
      "type": "product",
      "external_id": "5"
    }
  ]
}

Job statuses

A job can have one of the following statuses:

Status Description
queued Processing the job hasn't started yet
processing The job is being processed
completed The job has been processed completely and the record is available. The result indicates if some records have failed. A job can be completed even if some or all the records have failed
failed The job failed to process the full request due to an unexpected error, such as the request is compressed with an unsupported format, or an internal server error. Even if the job failed, some records could have been completed successfully
aborted The job won't be processed. This status is assigned when a job is aborted while the job is queued

You might also receive an "404 Not Found" HTTP response. Jobs and their related ids expire after a day.

Create Job

POST /api/sunshine/jobs

Creates a job with supported type and action.

The API doesn't wait for the job to finish before sending a response. The response gives you a job id that you can use to poll the API for the status of the job. See Show Job and Job statuses.

The maximum number of concurrent jobs that can be processed for an account is 1000.

Allowed For
  • Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/jobs \
  -d '{"type": "resources", "action": "post", "data": [{...}, {...}, ...]}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
  "data": {
    "id": "8b72559ae838-c9a0-11e7-abc4-cec278b6b50a6e6",
    "job_status": "queued",
    "created_at": "2017-11-03T16:00:06Z",
    "updated_at": "2017-11-03T16:00:06Z",
    "completed_at": null,
    "results": []
  }
}

Show Job

GET /api/sunshine/jobs/{id}

Returns the status of the specified job. See Job statuses.

Jobs expire after one day, after which they can no longer be accessed.

Allowed For
  • Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/jobs/{id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": {
    "id": "8b72559ae838-c9a0-11e7-abc4-cec278b6b50a6e6",
    "job_status": "completed",
    "created_at": "2017-11-03T16:00:06Z",
    "updated_at": "2017-11-03T16:00:16Z",
    "completed_at": "2017-11-03T16:00:16Z",
    "results": [
      {
        "success": true,
        "data": {"id": "73c698be-cb64-4678-ba73-29683d2c32er"}
      },
      {
        "success": false,
        "errors": [
          {
            "code": "UnprocessableEntity",
            "status": "422",
            "title": "Unprocessable Entity",
            "detail": "External Id is already in use for the Resource Type key: product"
          }
        ]
      }
    ]
  }
}

List Jobs

GET /api/sunshine/jobs

Returns all current jobs or a list filtered by status. See Job statuses.

Jobs expire after one day, after which they can no longer be accessed.

You can use a parameter named status to filter the results. Example:

GET /api/sunshine/jobs?status=queued

The allowed parameter values are queued, processing, failed, completed, or aborted.

Allowed For
  • Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/sunshine/jobs \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "data": [
    {
      "id": "559ae838-c9a0-11e7-abc4-cec278b6b50a",
      "job_status": "completed",
      "created_at": "2017-11-03T16:00:06Z",
      "updated_at": "2017-11-03T16:04:06Z",
      "completed_at": "2017-11-03T16:04:06Z"
    },
    {
      "id": "886ae838-c9a0-11e7-abc4-cec278b6b50a",
      "job_status": "processing",
      "created_at": "2017-11-03T16:02:06Z",
      "updated_at": "2017-11-03T16:04:06Z",
      "completed_at": null
    },
    ...
  ]
}