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 Support account.

Overview

In the Zendesk API, creating an app means uploading an app package to a Zendesk Support account and kicking off a build of the app. You must develop and package the app separately using the Apps framework. See the App Framework v2 docs.

Updating an app means rebuilding an existing app with a new app package.

Creating or updating an app doesn't make it available to agents in the user interface yet. You must install the app in the user interface before agents can start using it.

Creating an App

Follow these steps to create an app in a Zendesk Support account with the API:

  1. Use the Upload App Package endpoint to upload the app package to the account.

  2. Use the Create App endpoint with the upload_id from the previous step to kick off a build of the app.

  3. Use the Get Job Status endpoint with the job_id from the previous step to query the build status.

When the job status is 'completed', the app has been built successfully. You can install the app using the app id in the response. 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 Support user interface before contacting support. See Uploading and installing your private app in Zendesk Support.

Updating an App

To update an app in a Zendesk Support account with the API:

  1. Use the Upload App Package endpoint to upload the new app package.

  2. Use the Update App endpoint with the upload_id from the previous step and the application's id to kick off a rebuild of the app.

  3. Use the Get Job Status endpoint with the job_id from the previous step to query the build status.

When the job status is 'completed', the app has been built successfully. You can install the app using the app id in the response. If the status is 'failed', check the message for the reason.

Installing the app

After successfully building an app, you must install it in the user interface before agents can start using it. See Install App.

Upload App Package

POST /api/v2/apps/uploads.json

Uploads a new app package to Zendesk Support. See Packaging your app.

Use the returned upload id to create or update the app in the Zendesk Support instance.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/uploads.json \
  -F uploaded_data=@/path/to/app_zip_file -X POST \
  -u {email_address}:{password}

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.

Example Response
Status: 200

{
  "id": 123
}

Get job status

GET /api/v2/apps/job_statuses/{id}.json

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 Support user interface before contacting support. See Uploading and installing your private app in Zendesk Support.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/job_statuses/{id}.json \
  -u {email_address}:{password}
JSON Format

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
Example Response
{
  "id":       "fa8cac3098330130f49c14109fd02dfb",
  "url":      "https://{subdomain}.zendesk.com/api/v2/apps/job_statuses/fa8cac3098330130f49c14109fd02dfb.json",
  "total":    126.0,
  "progress": 126.0,
  "status":   "completed",
  "message":  "Completed at 2013-05-06 15:02:40 +1000",
  "retry_in": 3,
  "app_url":  "https://{subdomain}.zendesk.com/api/v2/apps/123.json",
  "app_id":   123
}
Example Response for Failed Job
{
  "id":       "fa8cac3098330130f49c14109fd02dfb",
  "url":      "https://{subdomain}.zendesk.com/api/v2/apps/job_statuses/fa8cac3098330130f49c14109fd02dfb.json",
  "total":    null,
  "progress": null,
  "status":   "failed",
  "message":  "Cannot unzip the package",
  "retry_in": 3
}

Create App

POST /api/v2/apps.json

Adds a build of a new app to the job queue.

You must 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
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/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"
}

Update App

PUT /api/v2/apps/{id}.json

Adds a build of an existing app to the job queue.

You must provide the id of the application 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
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/{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"
}

Get Information About App

GET /api/v2/apps/{id}.json

Retrieves information about the specified app accessible to the current user and account.

Allowed For
  • Everyone
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/{id}.json \
-v -u {email_address}:{password}
Example Response
Status: 200

{
  "large_icon":                    "/api/v2/apps/12345/assets/logo.png",
  "author_name":                   "Zendesk User",
  "visibility":                    "private",
  "promoted":                      false,
  "author_email":                  "author@example.org",
  "installable":                   true,
  "installation_instructions":     "",
  "long_description":              "",
  "featured":                      false,
  "created_at":                    "2012-05-14T22:28:18Z",
  "raw_long_description":          null,
  "id":                            12345,
  "single_install":                true,
  "small_icon":                    "/api/v2/apps/12345/assets/logo-small.png",
  "version":                       "1.0",
  "name":                          "Bookmarks",
  "rating": {
    "total_count": 10,
    "average": 3,
    "count": {
      "1": 2,
      "2": 2,
      "3": 2,
      "4": 2,
      "5": 2
    }
  },
  "categories":                    [],
  "raw_installation_instructions": null,
  "parameters": [
    {
      "secure":        true,
      "position":      0,
      "name":          "name",
      "app_id":        12345,
      "created_at":    "2012-06-14T17:31:08Z",
      "kind":          "text",
      "required":      true,
      "updated_at":    "2012-06-14T17:31:08Z",
      "default_value": null,
      "id":            21
    }
  ],
  "default_locale":    "en",
  "short_description": null,
  "updated_at":        "2014-01-21T00:32:03Z",
  "owner_id":          1,
  "screenshots":       [],
  "framework_version": "1.0"
}

Get App Public Key

GET /api/v2/apps/{id}/public_key.pem

Reveals the app's public key in PEM format.

You can use it to verify that certain requests from the app are legitimate.

Allowed For
  • Agents
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/{id}/public_key.pem \
  -u {email_address}:{password}
Example Response
Status: 200 OK

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6Z6U0KVY2HstBHKDiNIx
FoxzkhhMjvyB3LiBWLqre+H1rHiqZl3Q3oQ1+61qNyBBulu+6hr1GkkIVVEHBnfe
9OO+u2F9UAMi6JMl2L7QaaTxa+fR8ADNRNmg+5vsdKq/+nNTf2EA2ynwpwt/F5yp
mKg6n8jhy0eqsea4qKpYLLEE6AguR04KXgQymb0Mg0PQsNowpFCoLTg3IXZGCIVE
ztOfgYaYPOVwGr3pN71L4cW5euyKPl36tpp42iHyuJ3mP3q2d7GPfLwUoLNsDZYQ
Z8vcOkvkA7N0tZUDqIzofKGwsjk/++LYBFL04Qbj3avRHcouo70q13Lb+k4rm20u
lwIDAQAB
-----END PUBLIC KEY-----

List Owned Apps

GET /api/v2/apps/owned.json

Lists apps owned by the current account.

Allowed For
  • Admins
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/owned.json \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "apps": [
    {
      "large_icon":                    "/api/v2/apps/12345/assets/logo.png",
      "author_name":                   "Zendesk User",
      "visibility":                    "private",
      "promoted":                      false,
      "author_email":                  "author@example.org",
      "installable":                   true,
      "installation_instructions":     "",
      "long_description":              "",
      "featured":                      false,
      "created_at":                    "2012-05-14T22:28:18Z",
      "raw_long_description":          null,
      "id":                            12345,
      "single_install":                true,
      "small_icon":                    "/api/v2/apps/12345/assets/logo-small.png",
      "version":                       "1.0",
      "name":                          "Bookmarks",
      "categories":                    [],
      "raw_installation_instructions": null,
      "parameters": [
        {
          "secure":        true,
          "position":      0,
          "name":          "name",
          "app_id":        12345,
          "created_at":    "2012-06-14T17:31:08Z",
          "kind":          "text",
          "required":      true,
          "updated_at":    "2012-06-14T17:31:08Z",
          "default_value": null,
          "id":            21
        }
      ],
      "default_locale":    "en",
      "short_description": null,
      "updated_at":        "2014-01-21T00:32:03Z",
      "owner_id":          1,
      "screenshots":       [],
      "framework_version": "1.0"
    }
  ]
}

Side-loading

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/v2/apps/owned.json?exclude=parameters \
  -u {email_address}:{password}

List All Apps

GET /api/v2/apps.json

Lists all private and public apps, including Marketplace apps.

Allowed For
  • Admins

#### Using cURL

curl https://{subdomain}.zendesk.com/api/v2/apps.json \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "apps": [
    {
      "id":                7,
      "name":              "Bookmarks",
      "default_locale":    "en",
      "short_description": "Access bookmarked tickets from our iOS app",
      "author_name":       "Zendesk",
      ...
      "updated_at":        "2016-01-21T00:32:03Z"
    }
  ]
}

Delete App

DELETE /api/v2/apps/{id}.json

Deletes the specified app and removes it from the Manage pages in Zendesk Support.

Allowed For
  • Admins
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/{id}.json \
  -u {email_address}:{password} -X DELETE
Example Response
Status: 200 OK

Send Notification to App

POST /api/v2/apps/notify.json

Sends messages to currently open instances of an app. The messages cause a notification event to fire in the app. See Notification events in the ZAF v1 docs. For example, you could send a message to all signed-in agents telling them to take the day off.

Note: When developing with the Zendesk App Tools, you can send messages to your unpublished app by setting the app_id parameter to 0.

This API is rate limited. Only a certain number of requests are allowed per minute. For more information, see Rate Limits.

Allowed For
  • Agents
Parameters
Name Type Mandatory Comment
app_id integer yes The id of the app you want to send the message to
event string yes The name of the event you want to fire in your app
body string no If it's valid JSON, it's passed to your app as a JavaScript object.
agent_id integer no Send the notification to only one agent

For example, to send a user's updated phone number to agent #534 using the app with an id of 375, the request body might look something like this:

{
  "app_id": 375,
  "event": "updateUsersPhoneNumber",
  "body": "+61455534512",
  "agent_id": 534
}
Using cURL
curl https://{subdomain}.zendesk.com/api/v2/apps/notify.json \
  -d '{"event": "updateUsersPhoneNumber", "app_id": 375, "agent_id": 534, "body": "+61455534512"}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

List App Installations

GET /api/v2/apps/installations.json

Lists all app installations in the account. The enabled property indicates whether or not the installed app is active in the product.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations.json \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "installations": [
    {
      "id":        53931,
      "app_id":    225,
      "enabled":   true,
      "settings": {
        "title":     "Helpful App",
        "api_token": "53xjt93n6tn4321p",
        "use_ssl":   true
      }
    }
  ]
}
Side-loading

You can pass include=app as a parameter to side-load the app object associated with each installation.

curl https://{subdomain}.zendesk.com/api/v2/apps/installations.json?include=app \
  -u {email_address}:{password}

Install App

POST /api/v2/apps/installations.json

Installs an app in the 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.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/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
Location: https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}.json

{
  "installation": {
    "id":        53931,
    "app_id":    225,
    "enabled":   true,
    "settings": {
      "title":     "Helpful App",
      "api_token": "53xjt93n6tn4321p",
      "use_ssl":   true
    }
  }
}

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 Response
{
  "installation": {
    "id":     16,
    "app_id": 82,
    "settings": {
      "title": "100 requirements API app"
    },
    "enabled":              false,
    "updated":              "20141209034341",
    "pending_installation": true,
    "pending_job_id":       "648c47b0618d01326d443c15c2bba27e"
  }
}

Show App Installation

GET /api/v2/apps/installations/{id}.json

Retrieves information about the specified app installation, including the installation settings.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}.json \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "installation": {
    "id":       53931,
    "app_id":   225,
    "enabled":  true,
    "servable": true,
    "settings": {
      "title":     "Helpful App",
      "api_token": "53xjt93n6tn4321p",
      "use_ssl":   true
    }
  }
}

The value of the servable property depends on the calling API user. It'll be true for installations that you can use.

Update App Installation

PUT /api/v2/apps/installations/{id}.json

Updates the specified installation. Use the [List App Installations](#list-app-installations] endpoint to get the installation id.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations/{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": {
    "id":      53931,
    "app_id":  225,
    "enabled": true,
    "settings": {
      "title":     "Helpful App - Updated",
      "api_token": "659323ngt4ut9an",
      "use_ssl":   true
    }
  }
}

Remove App Installation

DELETE /api/v2/apps/installations/{id}.json

Removes an installed app. Use the List App Installations endpoint to get the installation id.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}.json \
  -u {email_address}:{password} -X DELETE
Example Response
Status: 200 OK

Get Requirements Install Status

GET /api/v2/apps/installations/job_statuses/{id}.json

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 Support user interface before contacting support. See Uploading and installing your private app in Zendesk Support.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations/job_statuses/{id}.json \
  -u {email_address}:{password}
JSON Format

Job statuses have the following attributes:

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
Example Response
Status: 200 OK

{
  "id":              "fa8cac3098",
  "url":             "https://{subdomain}.zendesk.com/api/v2/apps/installations/job_statuses/fa8cac3098.json",
  "total":           100.0,
  "progress":        100.0,
  "status":          "completed",
  "message":         "Completed at 2013-05-06 15:02:40 +1000",
  "installation_id": 16
}

List Requirements

GET /api/v2/apps/installations/{id}/requirements.json

Lists all app requirements for an installation.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}/requirements.json \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "requirements": [{
        "account_id": 2,
        "identifier": "a_basecamp_target",
        "requirement_id": 302,
        "requirement_type": "targets",
        "created_at": "2014-03-26T00:57:43Z",
        "updated_at": "2014-03-26T00:57:43Z"
    }, {
        "account_id": 2,
        "identifier": "an_email_target",
        "requirement_id": 307,
        "requirement_type": "targets",
        "created_at": "2014-03-26T00:57:43Z",
        "updated_at": "2014-03-26T00:57:43Z"
    }, {
        "account_id": 2,
        "identifier": "sample_ticket_field",
        "requirement_id": 137,
        "requirement_type": "ticket_fields",
        "created_at": "2014-03-26T00:57:43Z",
        "updated_at": "2014-03-26T00:57:43Z"
    }]
}