Apps

These APIs relate to the management of and interaction with Zendesk Apps. All actions from those endpoints will be logged into the Audit Log console of the Zendesk account you are operating on.

Overview

Create an App

To create an App using the API, you'll need to follow 3 steps in the following order.

  1. Upload the App package.

  2. Create a job to build the app using the upload_id from the previous step.

  3. Query the job status using the job_id from previous step.

When the job is 'completed', the app has been built successfully, then 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, please try running the creation process through the Zendesk interface first before contacting support.

Update an App

To update an App using the API, you'll need to follow 3 steps in the following order.

  1. Upload the App package.

  2. Create a job to update the app using the upload_id from the previous step and the application's id.

  3. Query the job status using the job_id from previous step.

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

Apps vs Installations

Note the difference between uploading and creating an App and installing that said App. If you would like to understand the creating vs installing App behavior please check out the "Apps" section of your Zendesk account Admin panel.

Upload a new app package

POST /api/v2/apps/uploads.json

Upload a new zip file package for an app. Use the returned upload id to create or update an app.

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

{
  "id": 123
}

Get upload status

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

Queries the application build job status using a job id given from the job creation step.

When the job is 'completed', the app has been built successfully then 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, please try running the creation process through the Zendesk interface first before contacting support.

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

Job statuses have the below attributes

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned as job gets enqueued
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 that have already been completed
status string yes no The current status: "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 Failure Response:
{
  "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 to the queue a build of a new app from a new upload, as specified by the upload_id parameter

The returned job_id can be used to query the status of the build from the /api/v2/apps/job_statuses/{job_id}.json endpoint.

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 to the queue a build of an existing app from a new upload, as specified by the upload_id parameter

The returned job_id can be used to query the status of the build from the /api/v2/apps/job_statuses/{job_id}.json endpoint

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 owned by the current account.

Allowed For:
  • Admins
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",
  "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"
}

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

Delete an App

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

Deletes the specified app and removes it from Manage Apps.

Allowed For:
  • Helpdesk Administrators
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

The notify endpoint allows you to send messages to currently-open instances of an app. For example, you could send a message to all logged-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.

The Notify API is rate limited. Only a certain number of requests are allowed per minute. Zendesk reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients. For more information, see Rate Limiting.

Allowed For:
  • Agents
Parameters
Name Type Mandatory Comment
app_id number 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 will be passed to your App as a JavaScript object.
agent_id number no Lets you send your notification to only one agent

For example, if you want to send a user's updated phone number to agent #534 using the app with an id of 375, you might send 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"}' \
v -u {email_address}:{password}
Example Response
Status: 200 OK

List App installations

GET /api/v2/apps/installations.json

Lists all App installations on the account.

Allowed For:
  • Agents
Using curl
curl -u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/v2/apps/installations.json
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 also pass include=app as a parameter to side-load the app object associated with each installation.

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

Other possible side-loads include: categories, parameters, ugc_fields (which controls app description and installation instructions visibility) and upload (which controls the visiblity of the corresponding upload id for private apps).

By default, categories, parameters, ugc_fields will be included, however you can set the exclude parameter to remove them.

Install an App

POST /api/v2/apps/installations.json

Installs an App on the account. app_id is required, as is a settings hash containing keys for all required parameters for the app. Any values in settings that don't correspond to a parameter that the app declares will be silently ignored.

Optionally, pass "enabled": false to create the installation but immediately disable it.

Allowed For:
  • Admins
Using curl
curl -u {email_address}:{password} \
-d '{"app_id":"225", "settings":{"name":"Helpful App", "api_token": "53xjt93n6tn4321p", "use_ssl": true}}' \
-H "Content-Type: application/json" -X POST \
https://{subdomain}.zendesk.com/api/v2/apps/installations.json
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 the job ID you can poll while your requirements are being installed:

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

Get settings for an App installation

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

Retrieve information about an App installation, including the settings for that App installation.

Allowed For:
  • Agents
Example Response
Status: 200 OK

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

Update an App installation

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

Updates an installation. app_id will be ignored; otherwise, this behaves much like creating installations.

Use the installation id from the installation list response to make this request. You can also use this endpoint to update hidden settings (see Apps documentation for hidden settings).

Allowed For:
  • Admins
Using curl
curl -u {email_address}:{password} \
-d '{"settings":{"name":"Helpful App - Updated", "api_token":  "659323ngt4ut9an"}}' \
-H "Content-Type: application/json" -X PUT \
https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}.json
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 an App installation

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

Removed an installed App. Use the installation id from the installation list response to make this request.

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

Get requirements install status

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

Queries the requirements installation job status using a job id given from the installation step.

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, please try running the creation process through the Zendesk interface first before contacting support.

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

Job statuses have these attributes:

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned as job gets enqueued
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 tasks that have already been completed
status string yes no The current status: "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":              "fa8cac3098330130f49c14109fd02dfb",
  "url":             "https://{subdomain}.zendesk.com/api/v2/apps/installations/job_statuses/fa8cac3098330130f49c14109fd02dfb.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 Apps Requirements for an installation.

Allowed For:
  • Agents
Using curl
curl -u {email_address}:{password} \
https://{subdomain}.zendesk.com/api/v2/apps/installations/{id}/requirements.json
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"
    }]
}