top of page

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.
 

Microsoft Teams Teamswork ticketing blank tablet
Image by Florian Olivo

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:

  1. Navigate to the Ticketing App settings area.

  2. Look for the API key section within the settings.

  3. 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 recommend setting up your own sandbox or test environment. Having a dedicated test environment allows you to safely and securely test your integrations, functionality, and API calls without affecting your live or production environment.

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

Request Body

See insertTicketRequest in the Schema 

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

Request Body

 

See updateTicketRequest in the Schema 

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

Request Body

See updateTicketStatusRequest in the Schema 

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

Request Body

See insertCommentRequest in the Schema 

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}