Fields

Job objects have the following fields and links:

Fields

field name description
type the type of job. Options include bulk_case_update or customer_merge
status_message a descriptive message of the job's status
progress percent complete
created_at when the job was created
completed_at when the job was finished
last_error any errors encountered while finishing the job. null if job completes successfully.

Links

rel class embeddable? description
self job no this job
user user yes user who created this job

List

Retrieve a paginated list of all jobs.

GET https://yoursite.desk.com/api/v2/jobs

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/jobs \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/jobs?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/jobs?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/jobs?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "type": "bulk_case_update",
        "status_message": "Completed",
        "progress": 100,
        "created_at": "2017-07-20T21:53:30Z",
        "completed_at": "2017-07-20T22:43:30Z",
        "last_error": null,
        "_links": {
          "self": {
            "href": "/api/v2/jobs/1",
            "class": "job"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "type": "bulk_case_update",
        "status_message": "Completed",
        "progress": 100,
        "created_at": "2017-07-20T21:53:30Z",
        "completed_at": "2017-07-20T22:43:30Z",
        "last_error": null,
        "_links": {
          "self": {
            "href": "/api/v2/jobs/2",
            "class": "job"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single job.

GET https://yoursite.desk.com/api/v2/jobs/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/jobs/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "type": "bulk_case_update",
  "status_message": "Completed",
  "progress": 100,
  "created_at": "2017-07-20T21:53:30Z",
  "completed_at": "2017-07-20T22:43:30Z",
  "last_error": null,
  "_links": {
    "self": {
      "href": "/api/v2/jobs/1",
      "class": "job"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Example Response when Job has errors

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "type": "bulk_case_update",
  "status_message": "Completed",
  "progress": 100,
  "created_at": "2017-07-20T21:53:30Z",
  "completed_at": "2017-07-20T22:43:30Z",
  "last_error": "\nhttps://acmeinc.desk.com/agent/case/1\nlocked",
  "_links": {
    "self": {
      "href": "/api/v2/jobs/1",
      "class": "job"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Create

Create a background job.

POST https://yoursite.desk.com/api/v2/jobs

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Shared Fields

field name description
type The job's type; currently only bulk_case_update is supported

Types

type name description
bulk_case_update updates a given set of cases, or all cases matching a filter, with the provided options. the options are identical to those accepted by the case update endpoint

Bulk Case Update Top Level Fields

field name description
type The job's type; currently only bulk_case_update is supported
case_ids An array of case ids to which the update should be applied; case_ids takes precedence over any provided filter_id. Links to cases are also accepted.
filter_id A filter id; update will be applied to all cases matched by the filter. A link to a filter is also acceptable. Either is overridden by any provided case_ids or case links.

Bulk Case Update Top Level Links

name relation description
cases case Update will be applied to the array of linked cases. Overridden by any provided case_ids
filter filter Update will be applied to all cases matched by the filter. Overridden by any provided filter_id

Bulk Case Update Case Fields

parent field name description
case label_action Whether to append or replace the labels (see below). The default is append.
case labels An array of labels to associate with this case. An empty array (using a label_action of replace) will clear all labels from the case.
case priority Priority (1-10)
case status Status of the cases: new, open, pending, resolved, closed
case assigned_user_id User to which the cases should be assigned. assigned_user_id will override a user link
case assigned_group_id Group to which the cases should be assigned. assigned_group_id will override a group link
case quick_reply Content to use when replying to cases

Bulk Case Update Case Links

parent name relation description
case assigned_user user User to which the cases should be assigned. Overridden by any provided assigned_user_id
case assigned_group group Group to which the cases should be assigned. Overridden by any provided assigned_group_id

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/jobs \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type": "bulk_case_update", "case": {"priority": 5, "_links": { "assigned_user": {"href": "/api/v2/users/1", "class": "user"}}}, "case_ids": [1,2,3]}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "type": "bulk_case_update",
  "case": {
    "priority": 5,
    "_links": {
      "assigned_user": {
        "href": "/api/v2/users/1",
        "class": "user"
      }
    }
  },
  "case_ids": [
    1,
    2,
    3
  ]
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "type": "bulk_case_update",
  "status_message": "Completed",
  "progress": 100,
  "created_at": "2017-07-20T21:53:30Z",
  "completed_at": "2017-07-20T22:43:30Z",
  "last_error": null,
  "_links": {
    "self": {
      "href": "/api/v2/jobs/1",
      "class": "job"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}