Introduction

Zammad provides a powerful REST-API which allows all operations that are available via UI as well.

This page gives you a first impression for things that generally count for all endpoints and how to adapt.

API clients

There are API clients available. Please note that these clients may not provide access to all available endpoints listed here.

Authentication

Zammad supports three different authentication methods for its API.

HTTP Basic Authentication (username/password)
The username / password must be provided as HTTP header in the HTTP call.
This authentication method can be disabled and may not be available in your system.
$ curl -u {username}:{password} https://{fqdn}/{endpoint}

Note

We strongly suggest against using basic authentication. Use access tokens when ever possible!

HTTP Token Authentication (access token)
The access token must be provided as HTTP header in the HTTP call.
Each user can create several access tokens in their user preferences.
This authentication method can be disabled and may not be available in your system.
$ curl -H "Authorization: Token token={your_token}" https://{fqdn}/{endpoint}
OAuth2 (token access)
The token must be provided as HTTP header in your calls.
This allows 3rd party applications to authenticate against Zammad.
$ curl -H "Authorization: Bearer {your_token}" https://{fqdn}/{endpoint}

Endpoints and example data

For simplicity we’ll not provide specific commands on the next pages, but instead tell the possible call method (e.g. GET) and the endpoint to use (e.g. /api/v1/users). In case Zammad expects information within these endpoint urls, we’ll put them into curly braces like so: /api/v1/users/{user id}

The response format will be a complete JSON response from a default Zammad instance. Please keep in mind that you may see more fields or general information in case you added objects or other information.

Content Type

Zammad returns JSON payloads whenever you retrieve data. If you’re going to provide data, no matter of the general request type, don’t forget to provide the content type application/json as well.

Response Payloads (expand)

Zammad always returns information including hints to all relations. If you need more information than that (because IDs may not be enough) you can also extend your endpoint calls with ?expand=true.

This switch will provide even more information — at least named relations on top of the ID ones. Below you can find two examples to compare - one for ticket and user each.

{
   "active": true,
   "login_failed": 0,
   "verified": false,
   "source": null,
   "login": "chris@chrispresso.com",
   "last_login": "2021-09-23T13:17:24.817Z",
   "id": 3,
   "updated_by_id": 1,
   "organization_id": 2,
   "firstname": "Christopher",
   "lastname": "Miller",
   "email": "chris@chrispresso.com",
   "image": "7a6a0d1d94ad2037153cf3a6c1b49a53",
   "image_source": null,
   "web": "",
   "phone": "",
   "fax": "",
   "mobile": "",
   "department": "",
   "street": "",
   "zip": "",
   "city": "",
   "country": "",
   "address": "",
   "vip": false,
   "note": "",
   "out_of_office": false,
   "out_of_office_start_at": null,
   "out_of_office_end_at": null,
   "out_of_office_replacement_id": null,
   "preferences":
   {
      "notification_config":
      {
         "matrix":
         {
            "create":
            {
               "criteria":
               {
                  "owned_by_me": true,
                  "owned_by_nobody": true,
                  "subscribed": true,
                  "no": true
               },
               "channel":
               {
                  "email": true,
                  "online": true
               }
            },
            "update":
            {
               "criteria":
               {
                  "owned_by_me": true,
                  "owned_by_nobody": true,
                  "subscribed": true,
                  "no": true
               },
               "channel":
               {
                  "email": true,
                  "online": true
               }
            },
            "reminder_reached":
            {
               "criteria":
               {
                  "owned_by_me": true,
                  "owned_by_nobody": false,
                  "no": true
               },
               "channel":
               {
                  "email": true,
                  "online": true
               }
            },
            "escalation":
            {
               "criteria":
               {
                  "owned_by_me": true,
                  "owned_by_nobody": false,
                  "no": true
               },
               "channel":
               {
                  "email": true,
                  "online": true
               }
            }
         },
         "group_ids":
         [
            "2",
            "1",
            "3"
         ]
      },
      "locale": "de-de",
      "intro": true,
      "notification_sound":
      {
         "file": "Xylo.mp3",
         "enabled": true
      },
      "cti": true,
      "tickets_closed": 0,
      "tickets_open": 1
   },
   "created_by_id": 1,
   "created_at": "2021-07-26T14:44:41.066Z",
   "updated_at": "2021-09-23T13:17:24.825Z",
   "role_ids":
   [
      1,
      2
   ],
   "organization_ids":
   [],
   "authorization_ids":
   [],
   "karma_user_ids":
   [
      1
   ],
   "group_ids":
   {
      "1":
      [
         "full"
      ],
      "2":
      [
         "full"
      ],
      "3":
      [
         "full"
      ]
   }
}

Warning

Please note that Core Workflows may restrict access to attributes or values. see Core Workflows limitations to learn more.

Sorting search results

Zammad allows you to sort your search results by field if needed.

sort_by

Append ?sort_by={row name} to your query to sort by a specific row that appears in the search result.

order_by

Append ?order_by={direction} to your query to switch in between ascending and descending order.

Directions are: asc and desc.

Note

Usually you’ll want to combine both parameters in your searches - e.g.: ?query={search string}&sort_by={row name}&order_by={direction}

Actions on behalf of other users

Note

The user used for running the on behalf query requires admin.user permission.

Running API queries on behalf of other users allows you to e.g. create tickets on behalf of the user. The UI will display these kind of operations much better.

To do so, add a new HTTP header named X-On-Behalf-Of to your request. The value of this header can be one of the following:

  • user ID

  • user login

  • user email

On behalf of is available for all endpoints.

Encoding

The API expects UTF-8 encoding. Keep in mind that especially when using URLs with get options (e.g. ?query=this) you may need to encode your URL accordingly.

If you want to learn more about URL encoding, this Wikipedia article may be of help