# Suptask API ### Overview Suptask offers an open API that enables you to integrate programmatically and automate your ticketing process. ### API Definition Review the OpenAPI v3 definition below. *** ## POST /ticket > Create a new ticket ```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"apiTokenAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"apiTokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the `Authorization` header with the value `Api-Token `. The token is assigned to a user.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}},"schemas":{"Field":{"type":"object","properties":{"fieldId":{"type":"string","description":"The UUID of the custom field."},"value":{"type":"string","description":"The value of the custom field."}}}}},"paths":{"/ticket":{"post":{"summary":"Create a new ticket","operationId":"createTicket","requestBody":{"description":"Payload to create a new ticket","required":true,"content":{"application/json":{"schema":{"type":"object","required":["description","requesterChannel","formId"],"properties":{"description":{"type":"string","description":"A detailed description of the ticket."},"priority":{"type":"string","description":"The priority of the ticket."},"status":{"type":"string","description":"The current status of the ticket."},"assignee":{"type":"string","nullable":true,"description":"The user Slack member ID assigned to the ticket."},"requester":{"type":"string","description":"The requester Slack member ID of the ticket."},"customFields":{"type":"array","description":"Custom fields for the ticket.","items":{"$ref":"#/components/schemas/Field"}},"requesterChannel":{"type":"string","description":"One of the Slack channel IDs which are assigned to form."},"tags":{"type":"array","nullable":true,"description":"Tags associated with the ticket.","items":{"type":"string"}},"formId":{"type":"string","description":"Identifier UUID for the form used to submit the ticket. Fetched from the Web url when editing a form."}}}}}},"responses":{"201":{"description":"Ticket successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","description":"The unique UUID of the created ticket."}}}}}},"400":{"description":"Invalid request payload"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}} ``` ## Get a ticket by ticket number > Retrieve ticket details by ticket number.\ > \ > \*\*Rate Limiting\*\*: This endpoint is rate limited to prevent abuse. Default limits are:\ > \- 100 requests per 15 minutes per API token\ > \ > Rate limit information is returned in response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).
```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}},"schemas":{"Ticket":{"type":"object","required":["id","ticketNumber","teamId","status","description","requesterId","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the ticket"},"ticketNumber":{"type":"integer","description":"Human-readable ticket number"},"teamId":{"type":"string","description":"ID of the team that owns this ticket"},"queueId":{"type":"string","nullable":true,"description":"ID of the queue this ticket belongs to"},"formId":{"type":"string","nullable":true,"description":"ID of the form used to create this ticket"},"status":{"type":"string","description":"Current status of the ticket"},"priority":{"type":"string","nullable":true,"description":"Priority level of the ticket"},"description":{"type":"string","description":"Detailed description of the ticket"},"assignee":{"type":"string","nullable":true,"description":"Slack member ID of the assigned user"},"requesterId":{"type":"string","description":"Slack member ID of the ticket requester"},"requester":{"type":"string","nullable":true,"description":"Display name or additional requester information"},"tags":{"type":"array","nullable":true,"description":"Tags associated with the ticket","items":{"type":"string"}},"customFields":{"type":"array","nullable":true,"description":"Custom field values with field names and values","items":{"type":"object","properties":{"fieldName":{"type":"string","description":"The label of the custom field"},"value":{"description":"The value of the custom field (string, array for multi-select, etc.)","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the ticket was created"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the ticket was last updated"},"closedDate":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601 timestamp when the ticket was closed"},"organization":{"type":"string","nullable":true,"description":"Organization associated with the ticket"},"source":{"type":"string","nullable":true,"description":"Source of the ticket (e.g., \"slack\", \"email\", \"api\")"},"archived":{"type":"boolean","description":"Whether the ticket has been archived"},"messageRequesterChannel":{"type":"string","nullable":true,"description":"Slack channel ID for requester messages"},"messageResponderChannel":{"type":"string","nullable":true,"description":"Slack channel ID for responder messages"},"responderThreadPermalink":{"type":"string","nullable":true,"description":"Permalink to the responder thread in Slack"},"requesterThreadPermalink":{"type":"string","nullable":true,"description":"Permalink to the requester thread in Slack"},"summaryTitle":{"type":"string","nullable":true,"description":"AI-generated or manually set summary title"},"summaryProblem":{"type":"string","nullable":true,"description":"AI-generated or manually set problem description"},"summarySolution":{"type":"string","nullable":true,"description":"AI-generated or manually set solution description"},"csatRating":{"type":"integer","nullable":true,"description":"Customer satisfaction rating (1-5)","minimum":1,"maximum":5},"csatComment":{"type":"string","nullable":true,"description":"Customer satisfaction comment"},"externalTicketRefs":{"type":"array","nullable":true,"description":"References to external tickets (e.g., Jira, Zendesk)","items":{"type":"string"}}}}}},"paths":{"/ticket/{ticketNumber}":{"get":{"summary":"Get a ticket by ticket number","operationId":"getTicketByNumber","description":"Retrieve ticket details by ticket number.\n\n**Rate Limiting**: This endpoint is rate limited to prevent abuse. Default limits are:\n- 100 requests per 15 minutes per API token\n\nRate limit information is returned in response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).\n","parameters":[{"name":"ticketNumber","in":"path","required":true,"description":"The numeric ticket number (e.g., 2075).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Ticket successfully retrieved","headers":{"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the current time window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Number of requests remaining in the current time window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO 8601 timestamp when the rate limit window resets","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"description":"Invalid ticket number (must be numeric)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"403":{"description":"Access denied - Ticket belongs to a different team","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"404":{"description":"Ticket not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"429":{"description":"Too many requests - Rate limit exceeded","headers":{"Retry-After":{"description":"Number of seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum number of requests allowed in the time window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Number of requests remaining (will be 0)","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO 8601 timestamp when the rate limit window resets","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}} ``` ## DELETE /ticket/{ticketId} > Delete a ticket ```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"apiTokenAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"apiTokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the `Authorization` header with the value `Api-Token `. The token is assigned to a user.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}}},"paths":{"/ticket/{ticketId}":{"delete":{"summary":"Delete a ticket","operationId":"deleteTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"The UUID of the ticket to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket successfully deleted"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}} ``` ## PATCH /ticket/{ticketId} > Update an existing ticket ```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"apiTokenAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"apiTokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the `Authorization` header with the value `Api-Token `. The token is assigned to a user.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}},"schemas":{"Field":{"type":"object","properties":{"fieldId":{"type":"string","description":"The UUID of the custom field."},"value":{"type":"string","description":"The value of the custom field."}}}}},"paths":{"/ticket/{ticketId}":{"patch":{"summary":"Update an existing ticket","operationId":"updateTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"The unique ID of the ticket to update.","schema":{"type":"object"}}],"requestBody":{"description":"Payload to update ticket properties. At least one property is required.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","description":"A detailed description of the ticket."},"priority":{"type":"string","nullable":true,"description":"The priority of the ticket."},"status":{"type":"string","description":"The current status of the ticket."},"assignee":{"type":"string","nullable":true,"description":"The user Slack member ID assigned to the ticket."},"requester":{"type":"string","description":"The requester Slack member ID of the ticket."},"customFields":{"type":"array","description":"Custom fields for the ticket.","items":{"$ref":"#/components/schemas/Field"}},"requesterChannel":{"type":"string","description":"One of the Slack channel IDs which are assigned to form."},"tags":{"type":"array","nullable":true,"description":"Tags associated with the ticket.","items":{"type":"string"}}},"oneOf":[{"required":["description"]},{"required":["priority"]},{"required":["status"]},{"required":["assignee"]},{"required":["requester"]},{"required":["customFields"]},{"required":["tags"]}]}}}},"responses":{"200":{"description":"Ticket successfully updated"},"400":{"description":"Invalid request payload"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}} ``` ## POST /ticket/external/{ticketId} > Create or associate an external ticket ```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"apiTokenAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"apiTokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the `Authorization` header with the value `Api-Token `. The token is assigned to a user.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}}},"paths":{"/ticket/external/{ticketId}":{"post":{"summary":"Create or associate an external ticket","operationId":"createExternalTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"The unique UUID of the Suptask ticket to associate with an external ticket.","schema":{"type":"object","required":["externalId","integrationType","url"]}}],"requestBody":{"description":"Payload to associate an external ticket with a Suptask ticket.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","description":"The ID of the external ticket."},"integrationType":{"type":"string","description":"The type of integration (e.g., \"Jira\", \"Zendesk\")."},"url":{"type":"string","format":"uri","description":"The URL of the external ticket."},"data":{"type":"object","additionalProperties":true,"description":"Additional key/value data or metadata for the external ticket."}}}}}},"responses":{"201":{"description":"External ticket successfully associated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid request payload"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}} ``` ## POST /ticket/reply/{ticketId} > Post a new reply to a ticket ```json {"openapi":"3.0.3","info":{"title":"Suptask Ticketing API","version":"1.2.1"},"security":[{"apiTokenAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"apiTokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the `Authorization` header with the value `Api-Token `. The token is assigned to a user.\n"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Use the `Authorization` header with the value `Bearer `. The JWT token contains user and team information.\n"}}},"paths":{"/ticket/reply/{ticketId}":{"post":{"summary":"Post a new reply to a ticket","operationId":"replyTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"The unique UUID of the Suptask ticket.","schema":{"type":"object","required":["text"]}}],"requestBody":{"description":"Payload to reply on a ticket","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The reply message text"},"username":{"type":"string","description":"The displayed username of the reply text."},"channel":{"type":"array","description":"Select between Requester (public reply) and/or Responder (internal comment reply) channel."}}}}}},"responses":{"200":{"description":"Returns","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid request payload"},"404":{"description":"Suptask ticket not found"},"500":{"description":"Server error"}}}}}} ``` ### Request API access The API requires a valid API token in order to authenticate to the API. {% hint style="info" %} Contact [Suptask Support](https://support.suptask.com/getting-started/contact-support) to retrieve your access token and get started with the API. {% endhint %} *** ### How to retrieve values for the API #### Retrieve the Form ID Retrieve the Form ID by opening up the Form from your Inbox and edit it. From the URL you can get the Form ID which is in a UUID format:
#### Retrieve the field ID Every created field in your Suptask account have a unique ID that can be retrieved from the [Manage fields](https://app.suptask.com/inboxes/fields) page by editing the field. The field ID is in a UUID format and be retried from the URL:
#### Retrieve the user Slack member ID [Retrieve the Slack member ID of a user.](https://support.suptask.com/getting-started/faq#how-to-locate-the-member-id-of-a-slack-user-or-app)