Fields

Customer objects have the following fields and links:

Fields

field name description
id string identifier for this object
first_name customer's first name
last_name customer's last name
company customer's company
title customer's title
avatar customer's avatar URL - image sourced from Twitter, Facebook or Gravatar. See note on avatar_size param below.
uid customer's Multipass SSO UID
external_id unique external identifier to reference this customer to an external system
background any background information for the customer
language customer's ISO language code, nil unless multi-lingual support is enabled
locked_until time in which the lock on this customer will expire
created_at time when customer was created
updated_at time when customer was last updated at
emails array of email objects, each specifying the contact type and value of the email address
phone_numbers array of phone number objects, each specifying the contact type and value of the phone number
addresses array of address objects, each specifying the contact type and value of the location
custom_fields hash of values for custom fields
access_private_portal whether or not customer can access private portal
access_company_cases whether or not customer can access company cases

Links

rel class embeddable? description
self customer no this customer
locked_by user no the user currently editing this customer
locked_by site no customer is locked by the system
cases case no cases belonging to this customer
company company no company to which the customer belongs
facebook_user facebook_user yes this customer's Facebook user
twitter_user twitter_user yes this customer's Twitter User

List

Retrieve a paginated list of all customers.

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

Applicable Roles

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

Limits

The maximum page parameter value for this endpoint is currently 500.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/customers \
    -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
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/customers?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/customers?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/customers?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "first_name": "John",
        "last_name": "Doe",
        "company": "ACME, Inc",
        "title": "Senior Ninja",
        "external_id": null,
        "background": "This guy can be a challenge to work with",
        "language": "en_us",
        "locked_until": null,
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "access_private_portal": true,
        "access_company_cases": true,
        "emails": [
          {
            "type": "work",
            "value": "john@acme.com"
          },
          {
            "type": "home",
            "value": "john@home.com"
          }
        ],
        "phone_numbers": [
          {
            "type": "work",
            "value": "123-456-7890"
          }
        ],
        "addresses": [
          {
            "type": "work",
            "value": "123 Main St, San Francisco, CA 94105"
          }
        ],
        "_links": {
          "self": {
            "href": "/api/v2/customers/1",
            "class": "customer"
          },
          "cases": {
            "href": "/api/v2/customers/1/cases",
            "class": "case"
          },
          "company": {
            "href": "/api/v2/companies/1",
            "class": "company"
          },
          "facebook_user": {
            "href": "/api/v2/facebook_users/1",
            "class": "facebook_user"
          },
          "twitter_user": {
            "href": "/api/v2/twitter_users/1",
            "class": "twitter_user"
          },
          "locked_by": null
        }
      },
      {
        "id": 1,
        "first_name": "Bob",
        "last_name": "Doe",
        "company": "ACME, Inc",
        "title": "Senior Ninja",
        "external_id": null,
        "background": "Easy to work with",
        "language": "en_us",
        "locked_until": null,
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "access_private_portal": true,
        "access_company_cases": true,
        "emails": [
          {
            "type": "work",
            "value": "bob@acme.com"
          },
          {
            "type": "home",
            "value": "bob@home.com"
          }
        ],
        "phone_numbers": [
          {
            "type": "work",
            "value": "123-456-7890"
          }
        ],
        "addresses": [
          {
            "type": "work",
            "value": "123 Main St, San Francisco, CA 94105"
          }
        ],
        "_links": {
          "self": {
            "href": "/api/v2/customers/2",
            "class": "customer"
          },
          "cases": {
            "href": "/api/v2/customers/1/cases",
            "class": "case"
          },
          "company": {
            "href": "/api/v2/companies/1",
            "class": "company"
          },
          "facebook_user": {
            "href": "/api/v2/facebook_users/1",
            "class": "facebook_user"
          },
          "twitter_user": {
            "href": "/api/v2/twitter_users/1",
            "class": "twitter_user"
          },
          "locked_by": null
        }
      }
    ]
  }
}

Show

Retrieve a single customer.

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

You may use an external_id if prefaced with e-: e-CUSTOMER-EXTERNAL-ID

Applicable Roles

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

Parameters

resolve_merged

If a customer has been previously merged, the regular request above will return a 404. To retreive the new customer record for a customer that was merged into another, use the resolve_merged parameter. The only value is true.

avatar_size

Customer GET endpoints accept an optional param, avatar_size. If provided, for Facebook and Gravatar, the returned avatar URL will have a square image with width and height equal to the given value. Due to limitations of Twitter's platform, any Twitter avatar images will be returned at the requested size if it is an exact match, or rounded up to the next available size. For example, a request for a 60 px avatar will return a 73x73 px avatar.

Available Twitter avatar sizes are: 24, 48, 73, and 400 pixels. Any avatar_size larger than 400 will return a link to the original image on Twitter. These sizes are subject to change at any time based on what Twitter provides, and all images should be constrained by the consuming client.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/customers/: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
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
61
62
63
{
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "company": "ACME, Inc",
  "title": "Senior Ninja",
  "external_id": null,
  "background": "This guy can be a challenge to work with",
  "language": "en_us",
  "locked_until": null,
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "access_private_portal": true,
  "access_company_cases": true,
  "emails": [
    {
      "type": "work",
      "value": "john@acme.com"
    },
    {
      "type": "home",
      "value": "john@home.com"
    }
  ],
  "phone_numbers": [
    {
      "type": "work",
      "value": "123-456-7890"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "value": "123 Main St, San Francisco, CA 94105"
    }
  ],
  "_links": {
    "self": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "cases": {
      "href": "/api/v2/customers/1/cases",
      "class": "case"
    },
    "company": {
      "href": "/api/v2/companies/1",
      "class": "company"
    },
    "facebook_user": {
      "href": "/api/v2/facebook_users/1",
      "class": "facebook_user"
    },
    "twitter_user": {
      "href": "/api/v2/twitter_users/1",
      "class": "twitter_user"
    },
    "locked_by": null
  }
}

Example Resolve Merge Request

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

Create

Create a customer.

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

Applicable Roles

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

Fields

field name description
first_name customer's first name
last_name customer's last name
company customer's company
title customer's title
external_id unique external identifier to reference this customer to an external system
background any background information for the customer
language customer's language code, nil unless multi-lingual support is enabled
locked_until time in which the lock on this customer will expire
custom_fields hash of values for custom fields
emails array of email objects, each specifying the contact type and value of the email address. type can be one of home, work, mobile, or other. value must be a unique email address.
phone_numbers array of phone number objects, each specifying the contact type and value of the phone number. type can be one of home, work, mobile, or other.
addresses array of address objects, each specifying the contact type and value of the location. type can be one of home, work, mobile, or other.
custom_fields hash of values for custom fields

Links

name relation description
locked_by user lock this customer to the given user. any update attempts from other users will fail as long as this customer is locked.*
company company link to the company for which this customer will be assigned

Note: Setting the company with links overrides the company value set in fields

*At this time the API does not obey locks.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/customers \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"first_name":"John","last_name":"Doe"}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "first_name": "John",
  "last_name": "Doe",
  "emails": [
    {
      "type": "work",
      "value": "john@acme.com"
    },
    {
      "type": "home",
      "value": "john@home.com"
    }
  ],
  "custom_fields": {
    "level": "vip"
  }
}

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
{
  "id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "company": null,
  "title": null,
  "external_id": null,
  "background": null,
  "language": "en_us",
  "locked_until": null,
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "access_private_portal": true,
  "access_company_cases": true,
  "emails": [
    {
      "type": "work",
      "value": "john@acme.com"
    },
    {
      "type": "home",
      "value": "john@home.com"
    }
  ],
  "phone_numbers": [

  ],
  "addresses": [

  ],
  "_links": {
    "self": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "cases": {
      "href": "/api/v2/customers/1/cases",
      "class": "case"
    },
    "company": {
      "href": "/api/v2/companies/1",
      "class": "company"
    },
    "facebook_user": {
      "href": "/api/v2/facebook_users/1",
      "class": "facebook_user"
    },
    "twitter_user": {
      "href": "/api/v2/twitter_users/1",
      "class": "twitter_user"
    },
    "locked_by": null
  }
}

Update

Update a customer.

PATCH https://yoursite.desk.com/api/v2/customers/:id

Applicable Roles

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

Fields

field name description
first_name customer's first name
last_name customer's last name
company customer's company
title customer's title
external_id unique external identifier to reference this customer to an external system
background any background information for the customer
language customer's language code, nil unless multi-lingual support is enabled
locked_until time in which the lock on this customer will expire
custom_fields hash of values for custom fields
emails array of email objects, each specifying the contact type and value of the email address. type can be one of home, work, mobile, or other. value must be a unique email address.*
phone_numbers array of phone number objects, each specifying the contact type and value of the phone number. type can be one of home, work, mobile, or other.*
addresses array of address objects, each specifying the contact type and value of the location. type can be one of home, work, mobile, or other.*

*By default, passing an array to this field will append the new elements to the existing set. It can optionally be entirely replaced by setting the corresponding addresses_update_action, emails_update_action, or phone_numbers_update_action param to replace. The action may also be set to append for explicit control. An empty array with the param set to replace will clear all values for the field.

Links

name relation description
locked_by user User that this customer is locked to. Any update attempts from other users will fail as long as this customer is locked.
company company link to the company for which this customer will be assigned

Note: Setting the company with links overrides the company value set in fields

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/customers/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"title":"Updated Title"}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "first_name": "Johnny",
  "emails": [
    {
      "type": "work",
      "value": "johnny@acme.com"
    },
    {
      "type": "other",
      "value": "johnny@other.com"
    }
  ],
  "custom_fields": {
    "level": "super"
  }
}

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
61
62
63
{
  "id": 1,
  "first_name": "Johnny",
  "last_name": "Doe",
  "company": "ACME, Inc",
  "title": "Senior Ninja",
  "external_id": null,
  "background": "This guy can be a challenge to work with",
  "language": "en_us",
  "locked_until": null,
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "custom_fields": {
    "level": "super"
  },
  "access_private_portal": true,
  "access_company_cases": true,
  "emails": [
    {
      "type": "work",
      "value": "johnny@acme.com"
    },
    {
      "type": "other",
      "value": "johnny@other.com"
    }
  ],
  "phone_numbers": [
    {
      "type": "work",
      "value": "123-456-7890"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "value": "123 Main St, San Francisco, CA 94105"
    }
  ],
  "_links": {
    "self": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "cases": {
      "href": "/api/v2/customers/1/cases",
      "class": "case"
    },
    "company": {
      "href": "/api/v2/companies/1",
      "class": "company"
    },
    "facebook_user": {
      "href": "/api/v2/facebook_users/1",
      "class": "facebook_user"
    },
    "twitter_user": {
      "href": "/api/v2/twitter_users/1",
      "class": "twitter_user"
    },
    "locked_by": null
  }
}

Customer Locking

We provide the ability to lock customers in order to prevent multiple agents from simultaneously updating a customer. Once locked, only the agent who holds the lock may update the customer. If a customer is locked and another agent tries to update the customer, they will receive a 409 - Conflict response.

Locking a Customer

Locking a customer is done by setting the locked_by to an agent.

1
2
3
4
5
6
7
{
  "_links": {
    "locked_by": {
      "href": "/api/v2/users/1"
    }
  }
}

Unlocking a Customer

Unlocking a customer is done by setting the locked_by link to null.

1
2
3
4
5
{
  "_links": {
    "locked_by": null
  }
}

List Cases

Retrieve a paginated list of all cases for a customer.

GET https://yoursite.desk.com/api/v2/customers/:id/cases

Applicable Roles

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

Sorting

Sorting is supported on cases by using sort_field and sort_direction parameters in your request.

  • sort_field - case field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting cases: id, created_at, priority, received_at, status, and updated_at. The default sort field is created_at and the default direction is asc.

Limits

The maximum page parameter value for this endpoint is currently 500. See Case list for more information.

Example Curl Request

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

Example Curl Request with sorting

1
2
3
4
$ curl https://yoursite.desk.com/api/v2/customers/:id/cases \
    -u email:password \
    -d 'sort_field=created_at&sort_direction=asc' -G \
    -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
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "external_id": null,
        "blurb": null,
        "subject": "Welcome",
        "priority": 5,
        "locked_until": null,
        "description": null,
        "status": "new",
        "type": "email",
        "labels": [

        ],
        "label_ids": [

        ],
        "language": "en_us",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:24:27Z",
        "changed_at": "2017-08-18T22:23:27Z",
        "active_at": "2017-08-18T22:24:27Z",
        "received_at": "2017-08-18T22:19:27Z",
        "first_opened_at": "2017-08-18T22:20:27Z",
        "opened_at": "2017-08-18T22:21:27Z",
        "first_resolved_at": "2017-08-18T22:24:27Z",
        "resolved_at": "2017-08-18T22:24:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "_links": {
          "self": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "message": {
            "href": "/api/v2/cases/1/message",
            "class": "message"
          },
          "customer": {
            "href": "/api/v2/customers/1",
            "class": "customer"
          },
          "assigned_user": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "assigned_group": {
            "href": "/api/v2/groups/1",
            "class": "group"
          },
          "locked_by": null,
          "replies": {
            "href": "/api/v2/cases/1/replies",
            "class": "reply"
          },
          "draft": {
            "href": "/api/v2/cases/1/replies/draft",
            "class": "reply"
          },
          "notes": {
            "href": "/api/v2/cases/1/notes",
            "class": "note"
          },
          "history": {
            "href": "/api/v2/cases/1/history",
            "class": "history"
          },
          "macro_preview": {
            "href": "/api/v2/cases/1/macros/preview",
            "class": "macro_preview"
          },
          "attachments": {
            "href": "/api/v2/cases/1/attachments",
            "class": "attachment"
          }
        }
      },
      {
        "id": 1,
        "external_id": null,
        "blurb": null,
        "subject": "Help Please!",
        "priority": 5,
        "locked_until": null,
        "description": null,
        "status": "new",
        "type": "email",
        "labels": [

        ],
        "label_ids": [

        ],
        "language": "en_us",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:24:27Z",
        "changed_at": "2017-08-18T22:23:27Z",
        "active_at": "2017-08-18T22:24:27Z",
        "received_at": "2017-08-18T22:19:27Z",
        "first_opened_at": "2017-08-18T22:20:27Z",
        "opened_at": "2017-08-18T22:21:27Z",
        "first_resolved_at": "2017-08-18T22:24:27Z",
        "resolved_at": "2017-08-18T22:24:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "_links": {
          "self": {
            "href": "/api/v2/cases/2",
            "class": "case"
          },
          "message": {
            "href": "/api/v2/cases/1/message",
            "class": "message"
          },
          "customer": {
            "href": "/api/v2/customers/1",
            "class": "customer"
          },
          "assigned_user": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "assigned_group": {
            "href": "/api/v2/groups/1",
            "class": "group"
          },
          "locked_by": null,
          "replies": {
            "href": "/api/v2/cases/1/replies",
            "class": "reply"
          },
          "draft": {
            "href": "/api/v2/cases/1/replies/draft",
            "class": "reply"
          },
          "notes": {
            "href": "/api/v2/cases/1/notes",
            "class": "note"
          },
          "history": {
            "href": "/api/v2/cases/1/history",
            "class": "history"
          },
          "macro_preview": {
            "href": "/api/v2/cases/1/macros/preview",
            "class": "macro_preview"
          },
          "attachments": {
            "href": "/api/v2/cases/1/attachments",
            "class": "attachment"
          }
        }
      }
    ]
  }
}

Merge

Merge 2 or more customers. Merging customers involves merging customer tickets, emails, phones, addresses. You can preview the merge operation by passing in the preview parameter. If there is a merge conflict the API returns a 409 along with a list of conflicting attributes. You can provide override attribute values for resolving merge conflicts.

POST https://yoursite.desk.com/api/v2/customers/:id/merge

A merge is not an instantaeneous operation. It is achieved using a background Job. Once a merge has started, you can check the status of the merge using the Jobs endpoint.

Applicable Roles

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

Fields (optional)

field name description
preview Preview merge operation
first_name Override first name for customer
last_name Override last name for customer
company Override company for customer
title Override title for customer
desc Override description for customer
external_id Override external_id for customer
site_language_type_id Override site_language_type_id for customer
custom_fields Override hash of values for custom fields

Links

name relation description
customers customer an array of links to customers to merge

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/customers/1/merge \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "_links": {
    "customers": [
      {
        "href": "/api/v2/customers/2",
        "class": "customer"
      },
      {
        "href": "/api/v2/customers/3",
        "class": "customer"
      }
    ]
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "first_name": "John",
  "last_name": "Doe",
  "_links": {
    "self": {
      "href": "/api/v2/customer/1/merge",
      "class": "customer_merge"
    },
    "job": {
      "href": "/api/v2/jobs/12",
      "class": "job"
    }
  }
}

Example Preview Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/customers/1/merge \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d 'preview=true'

Example Preview Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "_links": {
    "customers": [
      {
        "href": "/api/v2/customers/2",
        "class": "customer"
      },
      {
        "href": "/api/v2/customers/3",
        "class": "customer"
      }
    ]
  }
}

Example Preview Response

1
2
3
4
5
6
7
8
9
{
  "first_name": "John",
  "last_name": "Doe",
  "email": [
    "john1@foo.com",
    "john2@foo.com",
    "john3@foo.com"
  ]
}

Example Conflict Resolution Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "_links": {
    "first_name": "John",
    "last_name": "Not Doe",
    "email": "john1@foo.com",
    "customers": [
      {
        "href": "/api/v2/customers/2",
        "class": "customer"
      },
      {
        "href": "/api/v2/customers/3",
        "class": "customer"
      }
    ]
  }
}

Example Conflict Resolution Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "first_name": "John",
  "last_name": "Doe",
  "_links": {
    "self": {
      "href": "/api/v2/customer/1/merge",
      "class": "customer_merge"
    },
    "job": {
      "href": "/api/v2/jobs/12",
      "class": "job"
    }
  },
  "email": "john1@foo.com"
}