API Documentation - Sell Developers

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