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:

Example

{  "author_email": "[email protected]",  "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": "[email protected]",      "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/apps

Adds a build of an app to the job queue.

You must specify 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/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 202 Accepted
{  "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 the installed app is active in the product.

Allowed for

• Agents

JSON format

App installations are represented as JSON objects with the following properties:

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",        "blocklist": null,        "items_per_page": "6",        "name": "Attachment Manager",        "new_attachment_tag": "has_new_attachment",        "title": "Attachment Manager",        "allowlist": null      },      "settings_objects": [        {          "name": "attachment_tag",          "value": "has_attachment"        },        {          "name": "blocklist",          "value": null        },        {          "name": "items_per_page",          "value": "6"        },        {          "name": "name",          "value": "Attachment Manager"        },        {          "name": "new_attachment_tag",          "value": "has_new_attachment"        },        {          "name": "title",          "value": "Attachment Manager"        },        {          "name": "allowlist",          "value": null        }      ],      "stripe_account": "acct_1CyabcGO5FKrIYc5",      "stripe_subscription_id": null,      "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.

Installation settings

All apps support the "name" installation setting. App developers can define other installation settings using the app's manifest file. For more information about defining installation settings, see Defining installation settings.

You specify installation setting values using the settings or settings_objects properties. settings formats the settings as a flat object. settings_objects formats the settings as an array of objects.

You must specify at least one installation setting value in settings. If you specify a setting value in both settings and settings_objects, only the value in settings is used.

App requirements

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:

{  "id":     16,  "app_id": 82,  "settings": {    "title": "100 requirements API app"  },  "enabled":              false,  "updated":              "20141209034341",  "pending_installation": true,  "pending_job_id":       "648c47b0618d01326d443c15c2bba27e"}

Disabling apps on installation

By default, apps are enabled upon installation. To install an app and immediately disable it, pass "enabled": false in the install request.

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 201 Created
{  "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",    "blocklist": null,    "items_per_page": "6",    "name": "Attachment Manager",    "new_attachment_tag": "has_new_attachment",    "title": "Attachment Manager",    "allowlist": null  },  "settings_objects": [    {      "name": "attachment_tag",      "value": "has_attachment"    },    {      "name": "blocklist",      "value": null    },    {      "name": "items_per_page",      "value": "6"    },    {      "name": "name",      "value": "Attachment Manager"    },    {      "name": "new_attachment_tag",      "value": "has_new_attachment"    },    {      "name": "title",      "value": "Attachment Manager"    },    {      "name": "allowlist",      "value": null    }  ],  "stripe_account": "acct_1CyabcGO5FKrIYc5",  "stripe_subscription_id": null,  "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:

Parameters

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.

Allowed for

• Agents

JSON format

The Show App Installation endpoint doesn't return an app installation object. Instead, the endpoint returns a JSON object with the following properties:

Parameters

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": {    "agent_count": 0,    "app_id": 218618,    "app_installation_count": null,    "author_email": "[email protected]",    "email": "[email protected]",    "framework_versions": {        "current": "2.0",        "version": "2.0"    },    "group_restrictions": [],    "has_custom_object_requirements": false,    "has_incomplete_subscription": false,    "has_oauth_client": false,    "has_unpaid_subscription": null,    "id": 361234573552,    "installed_at": "2023-01-05T15:25:16Z",    "locale": "en-US-x-1",    "locations": [        {            "name": "deal_card",            "visible": true        }    ],    "marketing_only": false,    "new_installation": false,    "obsolete": false,    "paid": null,    "plan_id": null,    "require_category_terms": false,    "require_oauth_subdomain": false,    "role_restrictions": [],    "settings": [      {        "attachment_tag": "has_attachment",        "blocklist": null,        "items_per_page": "6",        "name": "Attachment Manager",        "new_attachment_tag": "has_new_attachment",        "title": "Attachment Manager",        "allowlist": null      }    ],    "supports_group_restrictions": false,    "supports_role_restrictions": false,    "third_party_paid": false,    "version": "1.0.0",    "zendesk_labs_license_url": null  }}

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

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
{  "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",    "blocklist": null,    "items_per_page": "6",    "name": "Attachment Manager",    "new_attachment_tag": "has_new_attachment",    "title": "Attachment Manager",    "allowlist": null  },  "settings_objects": [    {      "name": "attachment_tag",      "value": "has_attachment"    },    {      "name": "blocklist",      "value": null    },    {      "name": "items_per_page",      "value": "6"    },    {      "name": "name",      "value": "Attachment Manager"    },    {      "name": "new_attachment_tag",      "value": "has_new_attachment"    },    {      "name": "title",      "value": "Attachment Manager"    },    {      "name": "allowlist",      "value": null    }  ],  "stripe_account": "acct_1CyabcGO5FKrIYc5",  "stripe_subscription_id": null,  "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

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:

Parameters

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": "[email protected]",      "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

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 201 Created
{  "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

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": "[email protected]",  "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

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

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