Fields

Integration URL objects have the following fields and links:

Fields

field name description
name name of the URL
description an optional description
enabled whether or not the URL is enabled for use
markup liquid code to parse which creates the rendered URL
rendered rendered URL
open_location location of where the URL should be opened, values: lightbox, new_window, inline
created_at when the URL was created
updated_at when the URL was last_updated

Links

rel class embeddable? description
self integration_url no this integration URL
group group no the only group allowed to use this integration URL
user user no the only user allowed to use this integration URL
  • An integration URL may belong to either a group or user, but not both.

List

Retrieve a paginated list of all integration URLs.

For details about providing params to be rendered in the markup, see Fields.

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

Applicable Roles

Agent, Reporting Agent, Knowledgebase Manager, Content Manager, and Knowledgebase Adminstrator roles are restricted to reading integration URLs that are enabled and which have they permissions to use, as set in the Desk.com Admin.

Workflow Manager, Business Manager, Administrative Manager, Administrator, and Billing Administrator roles can read all integration URLs.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/integration_urls \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/integration_urls?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/integration_urls?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/integration_urls?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Sample URL",
        "description": "A sample Integration URL",
        "enabled": true,
        "markup": "http://www.example.com/name={{customer.name | url_encode}}",
        "rendered": "http://www.example.com/name=",
        "open_location": "new_window",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "_links": {
          "self": {
            "href": "/api/v2/integration_urls/1",
            "class": "integration_url"
          }
        }
      },
      {
        "name": "Another URL",
        "description": "A sample Integration URL",
        "enabled": true,
        "markup": "http://www.example.com/caseid={{case.id}}",
        "rendered": "http://www.example.com/caseid=",
        "open_location": "new_window",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "_links": {
          "self": {
            "href": "/api/v2/integration_urls/2",
            "class": "integration_url"
          }
        },
        "position": 2
      }
    ]
  }
}

Show

Retrieve a single integration URL.

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

Applicable Roles

Agent, Reporting Agent, Knowledgebase Manager, Content Manager, and Knowledgebase Adminstrator roles are restricted to reading integration URLs that are enabled and which have they permissions to use, as set in the Desk.com Admin.

Workflow Manager, Business Manager, Administrative Manager, Administrator, and Billing Administrator roles can read all integration URLs.

Parameters

Numeric ids are accepted for these parameters, which will dynamically alter the rendered URL: case_id, customer_id, and reply_id.

Example Curl Request

Assuming the customer with id of 1 is named 'Andrew':

1
2
3
$ curl https://yoursite.desk.com/api/v2/integration_urls/:id\?customer_id\=1 \
    -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
{
  "name": "Sample URL",
  "description": "A sample Integration URL",
  "enabled": true,
  "markup": "http://www.example.com/name={{customer.name | url_encode}}",
  "rendered": "http://www.example.com/name=Andrew",
  "open_location": "new_window",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/integration_urls/1",
      "class": "integration_url"
    }
  }
}

Create

Create an integration URL.

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

Applicable Roles

Workflow Manager, Business Manager, Administrative Manager, Administrator, and Billing Administrator

Fields

field name description
name name of the URL
description an optional description
enabled whether or not the URL is enabled for use
markup liquid code to parse which creates the rendered URL

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/integration_urls \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Sample URL", "description": "A sample Integration URL", "markup": "http://www.example.com"}'

Example Request Body

1
2
3
4
5
{
  "name": "Sample URL",
  "description": "A sample Integration URL",
  "markup": "http://www.example.com"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "name": "Sample URL",
  "description": "A sample Integration URL",
  "enabled": false,
  "markup": "http://www.example.com/name={{customer.name | url_encode}}",
  "rendered": "http://www.example.com/name=",
  "open_location": "new_window",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/integration_urls/1",
      "class": "integration_url"
    }
  }
}

Update

Update an integration URL.

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

Applicable Roles

Workflow Manager, Business Manager, Administrative Manager, Administrator, and Billing Administrator

Fields

Please see Create for details on the fields available for update.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/integration_urls/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{enabled:false}'

Example Request Body

1
2
3
{
  "enabled": false
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "name": "Sample URL",
  "description": "A sample Integration URL",
  "enabled": false,
  "markup": "http://www.example.com/name={{customer.name | url_encode}}",
  "rendered": "http://www.example.com/name=",
  "open_location": "new_window",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/integration_urls/1",
      "class": "integration_url"
    }
  }
}

Example Curl Request

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

Example Request Body

1
2
3
{
  "open_location": "lightbox"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "name": "Sample URL",
  "description": "A sample Integration URL",
  "enabled": true,
  "markup": "http://www.example.com/name={{customer.name | url_encode}}",
  "rendered": "http://www.example.com/name=",
  "open_location": "lightbox",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/integration_urls/1",
      "class": "integration_url"
    }
  }
}

Delete

Delete an integration_url.

DELETE https://yoursite.desk.com/api/v2/integration_urls/:id

Applicable Roles

Workflow Manager, Business Manager, Administrative Manager, Administrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/integration_urls/1 \
    -u email:password \
    -X DELETE

Example Response

1
204 No Content