API specification
Omnidesk's API specification
Last updated
Omnidesk's API specification
Last updated
We are hard at work to make this documentation as readable and user-friendly as possible. Here is a quick guide as to how to read this documentation:
The type is specified underneath the parameter name.
Sometimes this is a .
If there is an equals sign next to the parameter type, it indicates that this parameter is optional. The value after the equals sign indicates the default value that will be used if no value is specified.
All the endpoints that can be called on the Chat controller.
All endpoints require the API_CHAT permission.
All the endpoints that can be called on the Customer controller.
Endpoints that require the CUSTOMER_READ permission:
GET index
GET item
POST searchByPrimaryExternalId
GET timelineByCustomerExternalID
Endpoints that require the CUSTOMER_CUD permission:
POST index
PUT index
PUT item
DELETE item
POST addChannelOnly
PUT updateCustomer
DELETE itemChannel
DELETE itemPurgeData
POST externalEvent
POST syncWithCRM
POST createCustomerCRUD
All the endpoints that can be called on the Email controller.
All these endpoints require the SETTINGS_CRUD permission, except for GET itemDownloadMail, which requires TICKET_READ
All the endpoints that can be called on the Form controller.
Endpoints that require the FORM_READ permission:
GET index
GET item
GET getFormForTicket
Endpoints that require the FORM_CUD permission:
POST index
PUT item
DELETE item
Additionally, PUT saveFormFields requires the FORM_SAVE permission.
All the endpoints that can be called on the Formfield controller.
Each endpoint requires the FORM_CUD permission, except for GET index, which requires the FORM_READ permission.
All the endpoints that can be called on the Message controller.
All of the endpoints require the MESSAGE_CREATE permission.
All the endpoints that can be called on the Notification controller.
All the endpoints require the SETTINGS_CRUD permission.
All the endpoints that can be called on the Raw controller.
All the endpoints require the API_RAW_TABLE_READ permission.
All the endpoints that can be called on the Statisticsv2 controller.
All the endpoints require the API_STATISTICS permission, except for:
POST dashboardDelete
PUT dashboard
Which require the DASHBOARD_CUD permission.
All the endpoints that can be called on the Ticket controller.
Endpoints that require the TICKET_READ permission:
GET index
GET item
Endpoints that require the TICKET_CREATE permission:
POST index
Endpoints that require the TICKET_UPDATE permission:
PUT item
POST setPriority
Endpoints that require the TICKET_DELETE permission:
DELETE item
DELETE multi
Endpoints that require the SET_STATUS permission:
POST setStatus
PUT solveUnfinishedTickets
Endpoints that require the TICKET_BATCH permission:
POST batch
All the endpoints that can be called on the User controller.
Endpoints that require the USER_READ permission:
GET index
GET settings
Endpoints that require the API_RESERVER_USER permission:
POST reserveUserForLiveChannel
Endpoints that require the USER_ANONYMOUS_BROWSING_UPDATE permission:
PUT ticketIncognitoMode
All other endpoints require the USER_CUD permission.
All the endpoints that can be called on the View controller.
Endpoints that require the VIEW_READ permission:
GET index
Endpoints that require the VIEW_CUD permission:
POST index
POST item
DELETE item
Endpoints that require the GROUP_CUD permission:
GET item
Endpoints that require the SETTINGS_CRUD permission:
GET viewCategories
Returns the timeline from this customer by external primary ID.
External primary ID of the customer.
Include this with any value to also return ticket history for the customer.
No content
The actual data can be fetched with this endpoint. Use the data of the method above to generate a valid URL with valid columns and filters.
The table to get the data from, sample: telephone_calls_inbound
Comma separated list of the columns you want data from.
Array of filters you want to apply. Availability is dependent per table. Simply give the filter name as index for this parameter.
type: ISO datetime
Timestamp of when the data should start, example: 2025-01-01 00:00:00
type: ISO datetime
Timestamp of when the data should end, example: 2025-02-01 00:00:00
The record that should be started at.
Amount of records to return.
tableData tickets
Returns all data of this widget to show.
Widget data specifics can be added how is shown in the example. Adjust to your own needs.
User to be filtered out.
ID of the user to be filtered out.
Disables caching if sent with request.
Enables debug mode and disables caching if sent with request.
ID of the panel/widget.
showDataGETexample
Returns and downloads all data of this widget, or of the data you sent along with the request.
You either need to send the widget/panel ID, or the data in such a way provided in the example.
User to be filtered out.
ID of the user to be filtered out.
Disables caching if sent with request.
Enables debug mode and disables caching if sent with request.
ID of the panel/widget.
downloadDataGETexample
Returns all tickets with optional filters such as search queries, views and result limits.
The view to get the tickets from.
No content
Notifies the user of a new chat message.
type: string = ' '
type: number = 8
type: ^[a-zA-Z0-9]+$
type: ^[a-zA-Z0-9\.\:\/\-]+$
type: ^\+?[a-zA-Z0-9\-]+$
type: ^[a-zA-Z 0-9]+$ = null
type: email
type: string = ' '
type: string
type: number = 1
type: ^\+[0-9]+$ = null
type: string = ' '
type: string = false
No content
Checks the origin and IP address of this user.
type: ^[a-zA-Z0-9]+$
type: ^[a-zA-Z0-9\.\:\/\-]+$
type: string
type: ^[a-zA-Z0-9\.\-]+$
The hostname from the domain to be checked.
No content
Updates any fields existing on this customer, including custom fields.
See the example for how to update custom fields. It should always follow the pattern of "custom_" followed by the name of the custom field.
If you want to update or add multiple customer channels at once, it should be done in 2 parameters:
customerChannelType_0 (corresponding to the channel type ID)
customerChannelValue_0 (corresponding to the address of the channel you want to add)
The 0 would be incremental if you choose to do multiple.
3example21+31613794826jane.doe@smith.incJaneDoeitemPUTexample
Updates the fields of this customer.
Similar to how PUT item works.
If you want to update custom fields, just put the name of the field you want to update as the key and the value of the field you want to update as the value.
No content
Creates a new customer event e.g. an order or marketing mail to the customer timeline.
type: number
type: number = null
type: string = null
The external primary ID of the customer.
type: string
type: string
type: string
No content
Creates a customer using the CRUD.
type: number
type: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
type: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\' ]+$
type: string
The external primary ID of the customer.
No content
Creates a new inbound email message and decides if a new ticket is needed.
If you want to add multiple items to a request, just copy the keys and add indices to the empty square brackets.
type: string = null
The BCC address where this message is being sent to.
type: string = ' '
External ID of the ticket.
No content
Creates a new email address.
type: number
type: string
Has to be a valid email address format.
type: number = 0
type: ^[0,1]$
type: string
Has to be a valid email address format.
type: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿŠš\.\-\', ]+$ = null
type: string = ' '
No content
Updates this specific email address.
No content
Creates a new form field.
If you want to add multiple required statuses, multiply the required_statuses key and give the empty brackets indices.
type: number = null
type: number
type: ^(text(area|readonly|hidden)?|select(readonly|hidden)?)$
type: ^(open|pending|holding|solved)$ = null
type: string
No content
Updates this form field.
Identical to POST index, except this one also has an external code parameter.
If you want to update multiple required statuses, multiply the required_statuses key and give the empty brackets indices.
No content
Creates a new message.
The ticket must already exist. It will clear the ticket's cache before processing this data.
type: string = ' '
Must be a valid email address format.
type: string = ' '
Must be a valid email address format.
type: number = null
If you want to forward existing files.
type: number = 0
Add this parameter if it is a reply to an existing message.
type: string 'Y-m-d H:i' = current time
A special parameter as it is a string that would be following the date format specified.
type: string = ' '
Nullable for contactforms and notes.
No content
Creates a new widget.
See the example for how to write the dataURL.
type: ^([0-9]+)$
2type: ^[a-zA-Z0-9\.\:\/\-\ \=\?\&\[\]\_\:\+\*\@]+$ = ' '
Identical to the way showData allows these requested paramters in the URL.
facts[]=ticketIncoming&factTitleticketIncoming=&groupBy[]=timeHour&filters[]=timeRelativeToday&font_size_title=12&font_size_data=12type: ^([0-9]+)$
10type: ^([0-9]+)$
12type: ^([0-9]+)$ = 5
type: ^([0-9]+)$ = 0
help
type: ^([0-9]+)$ = 0
type: ^([0-9]+)$ = 0
type: ^(true|false)$ = 'false'
type: ^[0-9a-zA-Z :+*\-]+$ = ' '
type: ^([a-zA-Z]+)$ = 'table'
type: ^([0-9]+)$ = 5
widgetPOSTexample
Updates an existing widget.
See the example for how to write the dataURL. You need to fill in all the data, not just the changed data.
facts[]=ticketIncoming&factTitleticketIncoming=&groupBy[]=timeHour&filters[]=timeRelativeToday&font_size_title=12&font_size_data=10&pivot_on_column=0101210widgetPUTexample
Creates a setting to send all widget data to an email.
type: number
type: ^([0-9a-zA-Z\ \: \*]+)$
Set for if you want to send it with a regular interval.
type: ^([a-zA-Z0-9 @+-_.,]+)$
Has to be an email address or multiple email addresses comma-separated
No content
Performs miscellaneous actions on tickets given in an array.
type: ^[0-9, ]+$
Can be multiple ID's comma-separated (space allowed).
type: string
Needs to be an action type.
type: string
Needs to be the value the action would use.
No content
Creates a new user.
type: string
Must be a valid email address format.
type: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿ\- ]+$
type: number = null
type: ^[a-zA-ZÀ-ÖØ-Þß-öø-ÿ\- ]+$
type: ^[a-zA-Z0-9\.\-]+$
type: boolean = true
type: ^\+[0-9]+$
No content
Updates the user's data.
Leaving any parameter empty will submit it as such. If you don't want to change a property, do not include it at all.
No content
Updates this user's status.
type: number = 0
type: number = null
type: number
type: string
Must be a valid email address format.
type: number = null
No content
Creates a new view.
View the example on how to create conditions and columns.
Channel Iconchannel_icontype: columns
View example
type: condition
View example
brand_idequalsall1type: ^[a-z_]+$
nonetype: asc|desc = 'asc'
type: ^[a-z_]+$
nonetype: asc|desc = 'asc'
type: ^[0-9a-zA-Z \-\_]+$
example titletype: number = null
type: number
1indexPOSTexample
Updates this specific view.
View the example of POST index on how to update the conditions and columns.
No content