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"
}
]
}