API Reference
For Ticketing As A Service
Welcome to the API Reference for Ticketing as a Service! This comprehensive developer's guide is your key to seamlessly integrating ticketing functionality into your applications.
Whether you're looking to automate ticket creation, extract valuable ticket data for reporting, or enhance your existing tools with ticketing features, this documentation is your go-to resource. Explore the wide range of endpoints, methods, and parameters available to create, retrieve, and update tickets and activities. Get ready to revolutionize your ticketing experience!
PRODUCTION BASE URL
Ticketing API follows REST industry-standard practices, using widely supported HTTP methods such as GET, POST, PUT, and DELETE.
BULK UPDATE AND RATE LIMITING
Ticketing API doesn't support bulk updates. You can work on only one object per request.
There is a rate limit in place that allows for a maximum of 100 queries per 60 seconds to ensure system stability.
AUTHENTICATION
To ensure secure authentication with our Ticketing as a Service REST API, we utilize an API key as an authentication query parameter. You have the option to use either the primary or secondary key for authentication purposes.
To access your API key, please follow these steps:
-
Navigate to the Ticketing App settings area.
-
Look for the API key section within the settings.
-
You will find both the primary and secondary keys listed.
Please note that the API key provided for authentication purposes in the setting area is valid only for a single ticketing instance.
When making API requests, include the API key as a query parameter in your requests. This will authenticate your requests and grant you access to the desired functionalities of Ticketing API.
Remember to handle your API keys with care and keep them secure. They provide access to your Ticketing as a Service account, and misuse or unauthorized access to the API keys can compromise the security of your system.
If you have any further questions or need assistance regarding API key authentication or any other aspect of our Ticketing as a Service API, please don't hesitate to reach out to our support team. We are here to help you integrate and leverage the power of our API seamlessly.
SANDBOX ENVIRONMENT
We provide a dedicated sandbox environment for our Ticketing API. This test environment allows you to safely and securely test your integrations, functionality, and API calls without affecting your live or production environment.
Submit this request form so we can share you the access to the sendbox environment.
We encourage you to thoroughly test your integrations in the dedicated test environment before deploying them to your live production environment. This helps identify and resolve any issues or bugs, ensuring a smooth experience for your users.
ERRORS
Ticketing API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Ticketing's servers. Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.
PAGINATION
For some top level API resources, Ticketing API provide pagination functionality to allow you to retrieve large datasets in a controlled and manageable manner. To implement pagination, we follow the conventional approach of using "limit" and "offset" parameters.
limit: indicates the number of records to return in each page using the query parameter..
offset: sets the first position to return from the results of the query. The default is 0, which starts the page at the first result.
The response of a list API method represents a single page in a reverse chronological stream of objects.
CONTINUATION TOKEN
In addition to using the "offset" parametere, you can utilize the continuationToken mechanism. The continuationToken allows you to fetch subsequent pages of data without having to manually manage offsets.
Here's how you can implement auto-pagination using the continuationToken:
1. Make an initial API request to retrieve the first page of data, including a specified limit parameter for the number of records per page.
Example:
GET [Base URL]/tickets?limit=50
2. Check the response for the presence of the continuationToken field. If it exists, it indicates that there are additional pages of data available.
3. To fetch the next page of data, make a subsequent API request and include the continuationToken as a header parameter.
Repeat steps 2 and 3 until there is no continuationToken in the response, indicating that you have retrieved all the available data.
USER
See IUser in the Schema
A user is represented by an ID, name, and email. For users from your Microsoft 365 organization, it's important to ensure that this information remains consistent. Please note that the Ticketing API does not verify the consistency between the user's ID, name, and email.
If you require the ID, name, and email of a user, you can refer to the corresponding Object ID, Display Name, and Email attributes in Azure.
CUSTOM FIELDS
In the Ticketing API, you can fetch custom field information as well as populate these custom fields when creating new tickets using the unique 36-character hash identifier associated with each custom field.
Your custom fields information can be found in the instance end-point.
Endpoint: GET /tickets
Description: Retrieve a list of tickets. It provides a comprehensive view for several tickets, enabling you to access ticket details, statuses, and other relevant information.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
search: string
title: string, // searchByTitle
status: 'Open' | 'Reopened' | 'Started' | 'Resolved' | ' Closed',
priority: 'Low' | 'Medium' | 'Important' | 'Urgent',
tags: string, // tagString, comma separated 'tagCategoryId_tagText
orderBy: 'status' | 'ticketId' | 'title' | 'requestorName' | 'requestorEmail' | 'assigneeName' | 'assigneeEmail' | 'expectedDate' | 'priority' | 'createdDateTime' | 'lastInteraction',
order: 'ASC' | 'DESC',
select: comma separated: id, ticketId, title, description, status, requestor, customFields, priority, assignee, expectedDate, resolution, firstResponseOn, firstResolutionOn, lastResolutionOn, createdOn, tags, lastUpdatedOn, isFrtEscalated, isRtEscalated, createdBy, lastUpdatedBy, lastResolutionComment, etc...
offset: number,
limit: number, // max is 1000, default to 10
Request Headers:
continuationToken: string,
Request Body
N/A
Response Body
items: ticket[], // see ITicket in the Schema continuationToken: string,
Example
GET [Base URL]/tickets?key={your instance secret key}&timezone=0& orderBy=status&order=ASC&select=id,ticketId,title,description,status,requestorName&offset=0&limit=20
Endpoint: POST /tickets
Description: Create a new ticket using the Ticketing API, you can make a POST request to the tickets endpoint along with the necessary parameters and payload.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
Request Headers:
N/A
Response Body
N/A
Example
POST [Base URL]/tickets?key={your instance secret key}&timezone=0 Request Body: { "ticket": { "title": "My first ticket", "requestor": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "john.doe@teamswork.app" } }, "user": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "jason.doe@teamswork.app" } } Example 2: POST [Base URL]/tickets?key={your instance secret key} Request Body: { "ticket": { "title": "My first ticket", "requestor": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "john.doe@teamswork.app" }, "customFields": { "146db0c4-de24-4818-a131-a27161bb7ad0": [ // People picker { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Allan Deyoung", "email": "AllanD@xxxxxxxx.com" } ], "fef751d6-067d-431b-8a6d-667056eff6ee": [ // Multiple Items Picker "70d42d78-899a-4d5e-8cf0-79a0e4a6b0b1", "fe68df23-432e-4c0f-9841-a018b7f46d0b" ], "4aad4ef9-3242-4bb6-87f7-29428567429f": "long text area\nbla bla bla", // Text Area "7670050a-cf1a-4d3d-8179-5eba888dea5f": "text in custom field", // Text Field "862bd88d-f691-4a7b-a89a-f6f48550fc27": true, // Toggle "5b9f56bc-ec6a-45a3-b7ce-c25e1d8cfd69": [ // Single Item picker "f72541a9-c964-4c81-bc1a-4f1f2d948416" ], "7ee98e41-c4d0-4d4c-beb9-2b7f8f8c35c8": "2023-07-26T17:00:00Z" // Date Picker }, "description": "ticket descriptionline 1line 2", "priority": "Urgent", "assignee": { "id": "708edddc-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Alex Wilber", "email": "AlexW@xxxxxxxx.com" }, "expectedDate": "2023-07-26T17:00:00Z", "tags": [ { "tagCategoryId": "2283653a-8d36-40eb-9a68-73eb3b331811", "text": "sdsad" }, { "tagCategoryId": "2283653a-8d36-40eb-9a68-73eb3b331811", "text": "my tag" } ] }, "user": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "jason.doe@xxxxxxxx.com" } }
Endpoint: GET /tickets/{ticketId}
Description: Retrieve a ticket detail from its ID.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
Request Headers:
N/A
Request Body
N/A
Response Body
item: ticket
Example
GET [Base URL]/tickets/{ticket id}?key={your instance secret key}&timezone=0
Endpoint: PUT /tickets/{ticketId}
Description: Update a ticket.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
Request Headers:
N/A
Response Body
item: ticket
Example
PUT [Base URL]/tickets/{ticket id}?key={your instance secret key}&timezone=0 Request Body { "updates": { "title": "My 2nd ticket", "requestor": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "john.doe@wwwwww.com" }, "customFields": { "dcd58c80-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx": [ { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxx", "name": "Allan Deyoung", "email": "AllanD@xxxxxxxxxxx.com" } ] }, "priority": "Urgent", "assignee": { "id": "708edddc-xxxx-xxxx-xxxx-xxxxxxxxxx", "name": "Alex Wilber", "email": "AlexW@wwwwwww.com" } }, "user": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "jason.doe@wwwwwww.com" } }
Endpoint: PUT /tickets/{ticketId}/status
Description: Update the status of a ticket.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
Request Headers:
N/A
Response Body
item: ticket
Example
POST [Base URL]/tickets/{ticket id}/status?key={your instance secret key} Request Body { status : "Resolved", resolution: "fixed", comment: "Great job!" , "user": { "id": "23424-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "jason.doe@wwww.com" } }
Endpoint: GET /tickets/{ticketId}/activities
Description: Retrieve all activities (status change and comments) associated to a ticket.
Parameters:
N/A
Request Headers:
N/A
Request Body
N/A
Response Body
items: IActivity[]
Example
GET [Base URL]/tickets/{ticket id}/activities?key={your instance secret key}
Endpoint: POST /tickets/{ticketId}/activities
Description: Add a new comment to a ticket.
Parameters:
N/A
Request Headers:
N/A
Response Body
item: IComment
Example
POST [Base URL]/tickets/{ticket id}/comments?key={your instance secret key} Request Body { "comment": "comment from API", "user": { "id": "053660b7-xxxx-xxxx-xxxx-xxxxxxxxxxx", "name": "Jason Doe", "email": "jason.doe@wwwwww.com" } }
Endpoint: GET /instance
Description: Retrieve instance detail, including custom fields and assignee list information.
Parameters:
timezone: int, // timezone of the end user of the webapp origin of the call, ex: 7, means GMT +7
Request Headers:
N/A
Request Body
N/A
Response Body
item: instance export interface IInstance { id?: string, groupId: string, name: string, enabled: boolean, tenantId: string, teamId: string, channelId: string, subscriptionId?: string, mailAddress?: string, customFields?: ICustomField[], customFieldsLeft?: ICustomField[], customFieldsRight?: ICustomField[], optionalFieldsLeft?: ICustomField[], optionalFieldsRight?: ICustomField[], assignees?: { type: 'teamsOwner' | 'customAssignee', peoples?: IPersonaProps[] } assigneeRules?: IRule[], defaultRuleAssignee?: IRule[] isAutomaticAssignTickets?: boolean, alertNotification?: IAlertNotification isAutoAssignIdleTickets?: boolean, dayBeforeTicketsIdle?: number, idleTicketAssignedTo?: IPersonaProps[], isNotifyIdleTicket?: boolean }"
Example
GET [Base URL]/instance?key={your instance secret key}&timezone=0
Endpoint: GET /tags
Description: Retrieve tags details.
Parameters:
N/A
Request Headers:
N/A
Request Body
N/A
Response Body
items: ITagCategory[] export interface ITagCategory { id?: string, instanceId: string, text: string, color: string, tags: ITag[], deleted: boolean } export interface ITag { text: string, deleted: boolean }"
Example
GET [Base URL]/tags?key={your instance secret key}