Apps
This API lets you manage and interact with Zendesk apps. All actions from these endpoints are recorded in the Audit Log console of the affected Zendesk Sell account.
To learn more about the process of creating and managing apps using the Apps REST API described on this page, see Creating and managing private apps
JSON Format
Apps are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
author_email | string | true | false | The app author’s email |
author_name | string | true | false | The app author’s name |
categories | array | true | false | The categories that the app belongs to |
created_at | string | true | false | When the app was created |
default_locale | string | true | false | The default locale for translations for the app |
featured | boolean | true | false | Whether or not the app is featured in the app marketplace |
framework_version | string | true | false | The app framework version for which the app was written |
id | integer | true | false | The ID of the app |
installable | boolean | true | false | Whether or not the app can be installed |
installation_instructions | string | true | false | Instructions for installing the app |
large_icon | string | true | false | The large icon url for an app |
long_description | string | true | false | The app’s long description in the marketplace |
name | string | true | false | The name of the app |
owner_id | integer | true | false | The app developer id corresponding to the app |
parameters | array | true | false | The parameters for the app |
promoted | boolean | true | false | Whether or not the app is a promoted app in the app marketplace |
rating | object | true | false | The ratings of the app |
rawinstallationinstructions | string | true | false | The raw installation instructions |
rawlongdescription | string | true | false | The raw long description for the app in the marketplace |
screenshots | array | true | false | Screenshots for the app when displayed in the app marketplace |
short_description | string | true | false | The short description of the app in the marketplace |
single_install | boolean | true | false | Whether or not this app can only be installed once |
small_icon | string | true | false | The url for the small logo for the app |
updated_at | string | true | false | When the app was last updated |
version | string | true | false | The version of the app |
visibility | string | true | false | The app is a private app which is only visible to your account, or a public app. An example value is private. |
Example
{
"author_email": "author@example.org",
"author_name": "Zendesk User",
"categories": [],
"created_at": "2012-05-14T22:28:18Z",
"default_locale": "en",
"featured": false,
"framework_version": "1.0",
"id": 12345,
"installable": true,
"installation_instructions": "",
"large_icon": "/api/sell/apps/12345/assets/logo.png",
"long_description": "",
"name": "Bookmarks",
"owner_id": 1,
"parameters": [
{
"app_id": 12345,
"created_at": "2012-06-14T17:31:08Z",
"default_value": null,
"id": 21,
"kind": "text",
"name": "name",
"position": 0,
"required": true,
"secure": true,
"updated_at": "2012-06-14T17:31:08Z"
}
],
"promoted": false,
"rating": {
"average": 3,
"count": {
"1": 2,
"2": 2,
"3": 2,
"4": 2,
"5": 2
},
"total_count": 10
},
"raw_installation_instructions": null,
"raw_long_description": null,
"screenshots": [],
"short_description": null,
"single_install": true,
"small_icon": "/api/sell/apps/12345/assets/logo-small.png",
"updated_at": "2014-01-21T00:32:03Z",
"version": "1.0",
"visibility": "private"
}
List All Apps
GET /api/sell/apps
Lists private apps and public apps available in Zendesk Sell.
Allowed For
- Admins
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"apps": [
{
"author_email": "author@example.org",
"author_name": "Zendesk User",
"categories": [],
"created_at": "2012-05-14T22:28:18Z",
"default_locale": "en",
"featured": false,
"framework_version": "1.0",
"id": 12345,
"installable": true,
"installation_instructions": "",
"large_icon": "/api/sell/apps/12345/assets/logo.png",
"long_description": "",
"name": "Bookmarks",
"owner_id": 1,
"parameters": [
{
"app_id": 12345,
"created_at": "2012-06-14T17:31:08Z",
"default_value": null,
"id": 21,
"kind": "text",
"name": "name",
"position": 0,
"required": true,
"secure": true,
"updated_at": "2012-06-14T17:31:08Z"
}
],
"promoted": false,
"rating": {
"average": 3,
"count": {
"1": 2,
"2": 2,
"3": 2,
"4": 2,
"5": 2
},
"total_count": 10
},
"raw_installation_instructions": null,
"raw_long_description": null,
"screenshots": [],
"short_description": null,
"single_install": true,
"small_icon": "/api/sell/apps/12345/assets/logo-small.png",
"updated_at": "2014-01-21T00:32:03Z",
"version": "1.0",
"visibility": "private"
}
]
}
Create App
POST /api/sell/apps
Adds a build of a new app to the job queue.
You must provide an upload_id
in the post payload to this endpoint in order
to specify the uploaded app package to use
for the build. See Upload App Package.
The response contains a job_id
to check the status of the build. See
Get Job Status.
Allowed For
- Admins
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps.json \
-d '{"name":"My App", "short_description":"My App description", "upload_id":"123"}' \
-H "Content-Type: application/json" -X POST \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"job_id": "fa8cac3098330130f49c14109fd02dfb"
}
List App Installations
GET /api/sell/apps/installations
Lists app installations in the Zendesk Sell account. In the response, the enabled
property indicates
whether or not the installed app is active in the product.
Allowed For
- Admins
Sideloads
You can pass include=app
as a parameter to side-load the app object
associated with each installation.
curl https://{subdomain}.zendesk.com/api/sell/apps/installations.json?include=app \
-u {email_address}:{password}
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"installations": [
{
"app_id": 218618,
"collapsible": true,
"created_at": "2020-06-11T06:12:48Z",
"enabled": true,
"group_restrictions": [],
"has_incomplete_subscription": false,
"has_unpaid_subscription": null,
"id": 361234573552,
"paid": null,
"pending_installation": true,
"pending_job_id": "587986abda901cde3873697585091dab",
"plan_information": {
"name": null
},
"product": "sell",
"recurring_payment": false,
"redirect_path": "/sell/apps/manage",
"role_restrictions": null,
"servable": true,
"settings": {
"attachment_tag": "has_attachment",
"blacklist": null,
"items_per_page": "6",
"name": "Attachment Manager",
"new_attachment_tag": "has_new_attachment",
"title": "Attachment Manager",
"whitelist": null
},
"stripe_account": "acct_1CyabcGO5FKrIYc5",
"stripe_publishable_key": "pk_live_zMw5abcdYBbd6axDbyrzrRl9",
"updated": "20200305221223",
"updated_at": "2020-06-11T06:12:48Z"
}
]
}
Install App
POST /api/sell/apps/installations
Installs an app in the Zendesk Sell account.
You must provide the app_id
and a settings
object containing
properties for all required parameters for the app. You can use
the List All Apps endpoint to get the id of
the app you want to install.
Any values in settings
that don’t correspond to a parameter that the app
declares are silently ignored.
Optionally, you can pass "enabled": false
to create the installation but
immediately disable it.
If the app has requirements, the API response includes a job ID you can use to poll the installation status. See Get Requirements Install Status. Example:
{
"installation": {
"id": 16,
"app_id": 82,
"settings": {
"title": "100 requirements API app"
},
"enabled": false,
"updated": "20141209034341",
"pending_installation": true,
"pending_job_id": "648c47b0618d01326d443c15c2bba27e"
}
}
Allowed For
- Admins
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations.json \
-d '{"app_id": "225", "settings": {"name": "Helpful App", "api_token": "53xjt93n6tn4321p", "use_ssl": true}}' \
-H "Content-Type: application/json" -X POST \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"app_id": 218618,
"collapsible": true,
"created_at": "2020-06-11T06:12:48Z",
"enabled": true,
"group_restrictions": [],
"has_incomplete_subscription": false,
"has_unpaid_subscription": null,
"id": 361234573552,
"paid": null,
"pending_installation": true,
"pending_job_id": "587986abda901cde3873697585091dab",
"plan_information": {
"name": null
},
"product": "sell",
"recurring_payment": false,
"redirect_path": "/sell/apps/manage",
"role_restrictions": null,
"servable": true,
"settings": {
"attachment_tag": "has_attachment",
"blacklist": null,
"items_per_page": "6",
"name": "Attachment Manager",
"new_attachment_tag": "has_new_attachment",
"title": "Attachment Manager",
"whitelist": null
},
"stripe_account": "acct_1CyabcGO5FKrIYc5",
"stripe_publishable_key": "pk_live_zMw5abcdYBbd6axDbyrzrRl9",
"updated": "20200305221223",
"updated_at": "2020-06-11T06:12:48Z"
}
Get Requirements Install Status
GET /api/sell/apps/installations/job_statuses/{job_id}
If a job has kicked off to install an app and the app has requirements, this endpoint returns the status of the requirements installation. The job id is supplied in the response to the app installation request.
If the status
is completed
, the installation has been created successfully
with its requirements, and is available for use.
If the status
is failed
check the message for the reason.
If you’re constantly getting the same error message and the error message isn’t clear, try installing the app with the Zendesk Sell user interface. See Uploading and installing your private app in Zendesk Sell.
Allowed For
- Admins
JSON Format
Installation job statuses are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Comment |
---|---|---|---|---|
id | string | yes | no | Automatically assigned when job is queued |
url | string | yes | no | The URL to poll for status updates |
total | integer | yes | no | The total number of tasks this job is batching through |
progress | integer | yes | no | Number of completed tasks |
status | string | yes | no | queued, working, failed, completed, killed |
message | string | yes | no | Message from the job worker, if any |
installation_id | integer | yes | no | Unique ID of the installation |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
job_id | integer | Path | true | The ID of the job |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations/job_statuses/{job_id}.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"id": "fa8cac3098",
"installation_id": 16,
"message": "Completed at 2013-05-06 15:02:40 +1000",
"progress": 100,
"status": "completed",
"total": 100,
"url": "https://{subdomain}.zendesk.com/api/sell/apps/installations/job_statuses/fa8cac3098.json"
}
Show App Installation
GET /api/sell/apps/installations/{app_installation_id}
Retrieves information about the specified app installation available in Zendesk Sell, including the installation settings.
The value of the servable
property depends on the user making the API request.
The value is true for installations that you can use.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
appinstallationid | integer | Path | true | The ID of the app installation |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations/{app_installation_id}.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"installation": {
"app_id": 218618,
"collapsible": true,
"created_at": "2020-06-11T06:12:48Z",
"enabled": true,
"group_restrictions": [],
"has_incomplete_subscription": false,
"has_unpaid_subscription": null,
"id": 361234573552,
"paid": null,
"pending_installation": true,
"pending_job_id": "587986abda901cde3873697585091dab",
"plan_information": {
"name": null
},
"product": "sell",
"recurring_payment": false,
"redirect_path": "/sell/apps/manage",
"role_restrictions": null,
"servable": true,
"settings": {
"attachment_tag": "has_attachment",
"blacklist": null,
"items_per_page": "6",
"name": "Attachment Manager",
"new_attachment_tag": "has_new_attachment",
"title": "Attachment Manager",
"whitelist": null
},
"stripe_account": "acct_1CyabcGO5FKrIYc5",
"stripe_publishable_key": "pk_live_zMw5abcdYBbd6axDbyrzrRl9",
"updated": "20200305221223",
"updated_at": "2020-06-11T06:12:48Z"
}
}
Update App Installation
PUT /api/sell/apps/installations/{app_installation_id}
Updates the specified installation. Use the List App Installations endpoint to get the installation id.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
appinstallationid | integer | Path | true | The ID of the app installation |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations/{app_installation_id}.json \
-d '{"settings": {"name": "Helpful App - Updated", "api_token": "659323ngt4ut9an"}}' \
-H "Content-Type: application/json" -X PUT \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"installation": {
"app_id": 218618,
"collapsible": true,
"created_at": "2020-06-11T06:12:48Z",
"enabled": true,
"group_restrictions": [],
"has_incomplete_subscription": false,
"has_unpaid_subscription": null,
"id": 361234573552,
"paid": null,
"pending_installation": true,
"pending_job_id": "587986abda901cde3873697585091dab",
"plan_information": {
"name": null
},
"product": "sell",
"recurring_payment": false,
"redirect_path": "/sell/apps/manage",
"role_restrictions": null,
"servable": true,
"settings": {
"attachment_tag": "has_attachment",
"blacklist": null,
"items_per_page": "6",
"name": "Attachment Manager",
"new_attachment_tag": "has_new_attachment",
"title": "Attachment Manager",
"whitelist": null
},
"stripe_account": "acct_1CyabcGO5FKrIYc5",
"stripe_publishable_key": "pk_live_zMw5abcdYBbd6axDbyrzrRl9",
"updated": "20200305221223",
"updated_at": "2020-06-11T06:12:48Z"
}
}
Remove App Installation
DELETE /api/sell/apps/installations/{app_installation_id}
Removes an installed app from Zendesk Sell. Use the List App Installations endpoint to get the installation id.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
appinstallationid | integer | Path | true | The ID of the app installation |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/installations/{app_installation_id}.json \
-u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content
Get job status
GET /api/sell/apps/job_statuses/{job_status_id}
Gets the application build job status. You must provide the job id returned when the job was created.
When the job status is ‘completed’, the app has been built successfully. You can proceed to install the app using the app id in the response. See Install App.
If the status is 'failed’, check the message for the reason.
If you’re constantly getting the same error message and the error message isn’t clear, try creating the app through the Zendesk Sell user interface before contacting support. See Uploading and installing your private app in Zendesk Sell.
Allowed For
- Admins
JSON Format
App creation job statuses have the following attributes:
Name | Type | Read-only | Mandatory | Comment |
---|---|---|---|---|
id | string | yes | no | Automatically assigned when the job is queued |
url | string | yes | no | The URL to poll for status updates |
app_id | integer | yes | no | The ID of the app created by this job, if it exists |
total | integer | yes | no | The total number of tasks this job is batching through |
progress | integer | yes | no | Number of tasks completed |
status | string | yes | no | One of queued, working, failed, completed, killed |
message | string | yes | no | Message from the job worker, if any |
retry_in | integer | yes | no | Number of seconds after which you may re-check status |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
jobstatusid | integer | Path | true | The ID of the job |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/job_statuses/{job_status_id}.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"app_id": 123,
"app_url": "https://{subdomain}.zendesk.com/api/sell/apps/123.json",
"id": "fa8cac3098330130f49c14109fd02dfb",
"message": "Completed at 2013-05-06 15:02:40 +1000",
"progress": 126,
"retry_in": 3,
"status": "completed",
"total": 126,
"url": "https://{subdomain}.zendesk.com/api/sell/apps/job_statuses/fa8cac3098330130f49c14109fd02dfb.json"
}
List Owned Apps
GET /api/sell/apps/owned
Lists apps owned by the current Zendesk Sell account.
Allowed For
- Admins
Sideloads
The categories
and parameters
objects are automatically side-loaded
with each app object. However, you can exclude them from the response.
Example:
curl https://{subdomain}.zendesk.com/api/sell/apps/owned.json?exclude=parameters \
-u {email_address}:{password}
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/owned.json \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"apps": [
{
"author_email": "author@example.org",
"author_name": "Zendesk User",
"categories": [],
"created_at": "2012-05-14T22:28:18Z",
"default_locale": "en",
"featured": false,
"framework_version": "1.0",
"id": 12345,
"installable": true,
"installation_instructions": "",
"large_icon": "/api/sell/apps/12345/assets/logo.png",
"long_description": "",
"name": "Bookmarks",
"owner_id": 1,
"parameters": [
{
"app_id": 12345,
"created_at": "2012-06-14T17:31:08Z",
"default_value": null,
"id": 21,
"kind": "text",
"name": "name",
"position": 0,
"required": true,
"secure": true,
"updated_at": "2012-06-14T17:31:08Z"
}
],
"promoted": false,
"rating": {
"average": 3,
"count": {
"1": 2,
"2": 2,
"3": 2,
"4": 2,
"5": 2
},
"total_count": 10
},
"raw_installation_instructions": null,
"raw_long_description": null,
"screenshots": [],
"short_description": null,
"single_install": true,
"small_icon": "/api/sell/apps/12345/assets/logo-small.png",
"updated_at": "2014-01-21T00:32:03Z",
"version": "1.0",
"visibility": "private"
}
]
}
Upload App Package
POST /api/sell/apps/uploads
Uploads a new app package to Zendesk Sell.
Use the returned upload id to create or update the app in the Zendesk Sell instance.
Allowed For
- Admins
Example Response
Status: 200
{
"id": 123
}
Using curl
If you run the curl command in the app root folder where you packaged the
app, the file path for the
uploaded_data
attribute should look as follows: uploaded_data=@tmp/app-20170210150930.zip
.
curl https://{subdomain}.zendesk.com/api/sell/apps/uploads.json \
-F uploaded_data=@/path/to/app_zip_file -X POST \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"id": 123
}
Get Information About App
GET /api/sell/apps/{app_id}
Retrieves information about the specified app accessible to the current user and Zendesk Sell account.
Allowed For
- Everyone
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
app_id | integer | Path | true | The ID of the app to be retrieved |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/{app_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"author_email": "author@example.org",
"author_name": "Zendesk User",
"categories": [],
"created_at": "2012-05-14T22:28:18Z",
"default_locale": "en",
"featured": false,
"framework_version": "1.0",
"id": 12345,
"installable": true,
"installation_instructions": "",
"large_icon": "/api/sell/apps/12345/assets/logo.png",
"long_description": "",
"name": "Bookmarks",
"owner_id": 1,
"parameters": [
{
"app_id": 12345,
"created_at": "2012-06-14T17:31:08Z",
"default_value": null,
"id": 21,
"kind": "text",
"name": "name",
"position": 0,
"required": true,
"secure": true,
"updated_at": "2012-06-14T17:31:08Z"
}
],
"promoted": false,
"rating": {
"average": 3,
"count": {
"1": 2,
"2": 2,
"3": 2,
"4": 2,
"5": 2
},
"total_count": 10
},
"raw_installation_instructions": null,
"raw_long_description": null,
"screenshots": [],
"short_description": null,
"single_install": true,
"small_icon": "/api/sell/apps/12345/assets/logo-small.png",
"updated_at": "2014-01-21T00:32:03Z",
"version": "1.0",
"visibility": "private"
}
Update App
PUT /api/sell/apps/{app_id}
Adds a build of an existing app to the job queue.
You must provide the id of the app you want to update. Use the List Owned Apps endpoint to get the id.
You must also provide an upload_id
to specify the uploaded app package
to use for the build. See Upload App Package.
The response contains a job_id
to check the status of the build. See
Get Job Status.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
app_id | integer | Path | true | The ID of the app to be updated |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/{app_id}.json \
-d '{"name":"My App", "short_description":"My App description", "upload_id":"123"}' \
-H "Content-Type: application/json" -X PUT \
-u {email_address}:{password}
Example Response
Status 200 OK
{
"job_id": "fa8cac3098330130f49c14109fd02dfb"
}
Delete App
DELETE /api/sell/apps/{app_id}
Deletes the specified app and removes it from the My Apps page in Zendesk Sell.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
app_id | integer | Path | true | The ID of the app to be deleted |
Using curl
curl https://{subdomain}.zendesk.com/api/sell/apps/{app_id}.json \
-u {email_address}:{password} -X DELETE
Example Response
Status 204 No Content