DocumentationAPI Reference

Configs

The Configs API is used to find, create, and manage configuration settings for an integration.

JSON format

Configs are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
config object false false The Config JSON object. Other properties are metadata
created_at string true false The date and time the Config was created
id integer true false The unique ID of the Config
integration string true false Name of the integration that the Config belongs to
scope string false false Name of the scope that the Config belongs to
updated_at string true false The date and time the Config was last updated
zendesk_account_id integer true false The Zendesk account ID the Config belongs to

Show Configuration

  • GET /api/services/zis/integrations/{integration}/configs?filter[scope]={filter[scope]}

Returns configuration settings for the integration. The filter[scope] parameter accepts an asterisk (*) as a wildcard to match multiple scopes. Example: filter[scope]=foo*. The lookup is scoped to an account when used with a customer subdomain.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name Type In Required Description
filter[scope] string Query true The integration scope the configuration belongs to
page[after] integer Query false Specifies the start of the page returned
page[size] integer Query false The number of configurations to return. Returns a maximum of 100 records per page
integration string Path true Name of the integration.

Using cURL

curl 'https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs?filter[scope]=my_scope' \-g -H "Authorization: Bearer {access_token}"

Using cURL

curl "https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs?filter[scope]=my_scope&page[size]=2" \-g -H "Authorization: Bearer {access_token}"

Example response(s)

200 OK 
Status 200 OK
{  "configs": [    {      "config": {        "description": "A config object can be anything, this is an example.",        "id": 999,        "name": "my_config"      },      "created_at": "2021-08-30T04:40:17Z",      "id": 1,      "integration": "my_integration",      "scope": "my_scope",      "updated_at": "2021-08-31T04:40:17Z",      "zendesk_account_id": 123    }  ],  "links": {    "next": ""  },  "meta": {    "has_more": true  },  "next": null}
400 Bad Request 
Status 400 Bad Request
{  "errors": [    {      "code": "1100",      "detail": "Bad Request",      "status": "400"    }  ]}
401 Unauthorized 
Status 401 Unauthorized
{  "errors": [    {      "code": "1110",      "detail": "Authentication failed",      "status": "401"    }  ]}
404 Not Found 
Status 404 Not Found
{  "errors": [    {      "code": "1110",      "detail": "Not Found",      "status": "404"    }  ]}

Create Configuration

  • POST /api/services/zis/integrations/{integration}/configs

Creates configuration settings for an integration.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name Type In Required Description
integration string Path true Name of the integration.

Example body

{  "config": {    "description": "A config object can be anything, this is an example.",    "id": 999,    "name": "my_config"  },  "scope": "my_scope"}

Using cURL

curl -X POST 'https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs' \  -H "Authorization: Bearer {access_token}" \  -H 'Content-Type: application/json' \  -d '  {    "config": {      "description": "A config object can be anything, this is an example.",      "id": 999,      "name": "my_config"    },    "scope": "my_scope"  }'

Example response(s)

201 Created 
Status 201 Created
{  "config": {    "config": {      "description": "A config object can be anything, this is an example.",      "id": 999,      "name": "my_config"    },    "created_at": "2021-08-30T04:40:17Z",    "id": 1,    "integration": "my_integration",    "scope": "my_integration",    "updated_at": "2021-08-31T04:40:17Z",    "zendesk_account_id": 22  }}
400 Bad Request 
Status 400 Bad Request
{  "errors": [    {      "code": "1100",      "detail": "Bad Request",      "status": "400"    }  ]}
401 Unauthorized 
Status 401 Unauthorized
{  "errors": [    {      "code": "1110",      "detail": "Authentication failed",      "status": "401"    }  ]}
422 Unprocessable Entity 
Status 422 Unprocessable Entity
{  "errors": [    {      "code": "1110",      "detail": "Unprocessable entity",      "status": "422"    }  ]}

Update Configuration

  • PUT /api/services/zis/integrations/{integration}/configs/{scope}

Updates the configuration settings for an integration.

Note: The configuration settings provided will completely overwrite the existing configuration.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name Type In Required Description
integration string Path true Name of the integration.
scope string Path true Name of the scope that the config belongs to. Special characters should be URL encoded in a URL path. Example: "foo/bar" to "foo%2Fbar"

Example body

{  "config": {    "description": "A config object can be anything, this is an example.",    "id": 999,    "name": "my_config"  }}

Using cURL

curl -X PUT \'https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs/foo_bar_baz1' \-H "Authorization: Bearer {access_token}" \-H 'Content-Type: application/json' \-d '{"Config": {"enable_comment_sync": "false"} }'

Example response(s)

200 OK 
Status 200 OK
{  "config": {    "config": {      "description": "A config object can be anything, this is an example.",      "id": 999,      "name": "my_config"    },    "created_at": "2021-08-30T04:40:17Z",    "id": 1,    "integration": "my_integration",    "scope": "my_integration",    "updated_at": "2021-08-31T04:40:17Z",    "zendesk_account_id": 22  }}
400 Bad Request 
Status 400 Bad Request
{  "errors": [    {      "code": "1100",      "detail": "Bad Request",      "status": "400"    }  ]}
401 Unauthorized 
Status 401 Unauthorized
{  "errors": [    {      "code": "1110",      "detail": "Authentication failed",      "status": "401"    }  ]}
422 Unprocessable Entity 
Status 422 Unprocessable Entity
{  "errors": [    {      "code": "1110",      "detail": "Unprocessable entity",      "status": "422"    }  ]}

Merge Configuration

  • PATCH /api/services/zis/integrations/{integration}/configs/{scope}

Merges the provided configuration settings with the existing configuration.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name Type In Required Description
integration string Path true Name of the integration.
scope string Path true Name of the scope that the config belongs to. Special characters should be URL encoded in a URL path. Example: "foo/bar" to "foo%2Fbar"

Example body

{  "config": {    "description": "A config object can be anything, this is an example.",    "id": 999,    "name": "my_config"  }}

Using cURL

curl -X PATCH \'https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs/foo_bar_baz1' \-H "Authorization: Bearer {access_token}" \-H 'Content-Type: application/json' \-d '{"Config": {"enable_comment_sync": "false"} }'

Example response(s)

200 OK 
Status 200 OK
{  "config": {    "config": {      "description": "A config object can be anything, this is an example.",      "id": 999,      "name": "my_config"    },    "created_at": "2021-08-30T04:40:17Z",    "id": 1,    "integration": "my_integration",    "scope": "my_integration",    "updated_at": "2021-08-31T04:40:17Z",    "zendesk_account_id": 22  }}
400 Bad Request 
Status 400 Bad Request
{  "errors": [    {      "code": "1100",      "detail": "Bad Request",      "status": "400"    }  ]}
422 Unprocessable Entity 
Status 422 Unprocessable Entity
{  "errors": [    {      "code": "1110",      "detail": "Unprocessable entity",      "status": "422"    }  ]}

Delete Configuration

  • DELETE /api/services/zis/integrations/{integration}/configs/{scope}

Deletes the existing configuration settings.

Authentication

You can authorize requests using a ZIS OAuth access token. A Zendesk app can also authorize requests to this endpoint using an admin's browser session. See Making API requests from a Zendesk app.

Parameters

Name Type In Required Description
integration string Path true Name of the integration.
scope string Path true Name of the scope that the config belongs to. Special characters should be URL encoded in a URL path. Example: "foo/bar" to "foo%2Fbar"

Using cURL

curl -X DELETE "https://{subdomain}.zendesk.com/api/services/zis/integrations/{integration}/configs/my_scope" \-H "Authorization: Bearer {access_token}"

Example response(s)

204 No Content 
Status 204 No Content
400 Bad Request 
Status 400 Bad Request
{  "errors": [    {      "code": "1100",      "detail": "Bad Request",      "status": "400"    }  ]}
401 Unauthorized 
Status 401 Unauthorized
{  "errors": [    {      "code": "1110",      "detail": "Authentication failed",      "status": "401"    }  ]}
404 Not Found 
Status 404 Not Found
{  "errors": [    {      "code": "1110",      "detail": "Not Found",      "status": "404"    }  ]}