For information about the API endpoints, head over to the API documentation. And for more about Workflows head here to the page about Workflows.
The API currently supports two types of authentication tokens, namely user- and contact-tokens. Contact tokens belong to a tenant's contact and user tokens belong to a tenant's user. Almost all API endpoints are set up to work only with user-tokens. The contact-tokens can only be used on endpoints starting with "/api/css/". CSS is short for Customer-Self- Service. These are the endpoints that can be used to allow the contact to manage their data or retrieve data that is assigned to them.
The regular API endpoints can be accessed via /api/ or /api/vX/ (x >= 1). These endpoints feature a REST design and return paginated results.
The system also features "css" routes. These routes are accessible with a contact token and limit the results based on the access permissions of the contact. Instead of returning all tickets, the css ticket endpoint only returns the tickets that are relevant for the current contact.
The last type of endpoint is the "app" endpoint type. These endpoints are return custom data for a specific use case,
e.g. a specific app. It is not possible to use the include operation on those endpoints. They should not be used by
external developers as they may be subject of change without notice.
Some models have relations to other models. For example, a contact can belong to multiple contact groups. An applicant status can have multiple mail templates attached.
The API only returns the model in its response and not its related models. When a contact is retrieved, the response
only contains the contact and none of the contact groups the contact belongs to. To retrieve the contact groups the
contact belongs to, add include=contactGroups to the request. This is going to fetch the complete model and return it
with the response.
Some models do not return the full related model when the include is requested, and instead return a "tiny"
representation of the related models. For example, only the most basic contact details are returned as part of the tiny
representation when requesting information about a mail campaign.
Some models do not return the full related model when the include is requested, and instead only return the IDs of the
related models. Those IDs can then be used to look up the original models.
The Accept header is not required, however its use is highly recommended whenever an API endpoint is called. It is
used to decide how the response should be returned.
The Authorization header is required whenever a protected API endpoint is called. Failure to supply the authorization
bearer token results in an unauthenticated error message.
The X-Tenant header is required whenever an action against a specific tenant is performed. The header helps by
identifying the tenant that should be used when checking the supplied contact API token. Failure to supply the token
result in an error indicating that the X-Tenant header is missing. The value of the header is the UUIDv4 tenant
identifier.
Dates used in filters or when assigning values must be provided using the following format: 'Y-m-d H:i:s' for dates with time information or 'Y-m-d' for dates without time information. The time should be provided based on the Europe/Vienna timezone.
The API allows the user to access custom fields defined on models. A custom field is a custom value that belongs to a
model as defined by a tenant. There are two different types of custom fields, namely global custom fields and specific
custom fields. Fields defined in a global custom field, annotated by the _0 identifier, are available on all models of
this type. Specific custom fields, annotated by _X (X > 0), are only available on models that belong to the same
subtype as the custom field. To give a more specific example: a CalendarEvent can belong to a specific
CalendarCategory. The specific custom fields depend on which category the event belongs to. If a global custom field
is defined, all events, independent of the category, can access the defined fields.
The custom-fields/<model> endpoints enable the user to retrieve the display name mapping of all custom fields the
user has access to. The endpoint can be used to retrieve the display name that belongs to a specific custom field.
Furthermore, it lets the user know which custom fields can be retrieved.
To retrieve the custom fields for a model, a include=custom_fields_X (X >= 0) (if defined) can be used to retrieve
the models along with their custom fields.
To update a custom field's value, the custom field along with its prefix can be defined in a POST or PUT route. To give a more concrete example, the following payload can be used to update a model's global custom field.
{
"custom_fields_0.i_1": 123
}
1Tool uses placeholders to enable dynamic content to be used in templates. Invoice templates and contact mail templates use the placeholder system to customize the resulting document for each recipient.
To avoid conflicting placeholder names, each models placeholder has a unique prefix. The available prefixes are listed below:
| Type | Prefix |
|---|---|
| Contact | contact |
| Course | course |
| Event | event |
| EventParticipation | participation |
| Project | project |
| Survey | survey |
An example placeholder would look like this: ###course.title###. This placeholder would output the name of the current
course. Not all placeholders are available all the time, for example course placeholders are not available when sending
a mail to a contact from the contact detail page, because the placeholder replacement service is missing which course
should serve as the base of the placeholder.
To get an overview of the available placeholders, check the placeholder list.
Some properties are not returned 1:1 but in a modified form. This includes some date properties, they are instead
formatted using the following format: d.m.Y.