Skip to Content
Support Ticket Management API

Support Ticket Management API

The Support Ticket Management API allows you to manage customer support tickets in your TaskIP CRM system. You can create, read, update, and delete tickets, reply as a client or an agent, change status and priority, assign agents in bulk, and manage ticket notes.

Tickets are identified by a UUID (string), not by a numeric ID, in every {uuid} path parameter below.

Endpoints Overview

MethodEndpointDescription
GET/api/public-v1/support-ticketGet all support tickets
POST/api/public-v1/support-ticketCreate a new support ticket
GET/api/public-v1/support-ticket/{uuid}Get a specific support ticket
PUT / PATCH/api/public-v1/support-ticket/{uuid}Update a support ticket
DELETE/api/public-v1/support-ticket/{uuid}Delete a support ticket
POST/api/public-v1/support-ticket/bulk-actionsDelete, change priority/status, or assign agents in bulk
GET/api/public-v1/support-ticket/{uuid}/repliesList replies of a ticket
POST/api/public-v1/support-ticket/reply/{uuid}Reply to a ticket
POST/api/public-v1/support-ticket/agent-reply/{uuid}Reply to a ticket as a specific agent
POST/api/public-v1/support-ticket/{uuid}/priorityUpdate ticket priority
POST/api/public-v1/support-ticket/status-update/{uuid}Update ticket status
POST/api/public-v1/support-ticket/{uuid}/note-storeAdd ticket note
DELETE/api/public-v1/support-ticket/{uuid}/note-delete/{id}Delete ticket note

Value Reference

Priority

ValueMeaning
0Low
1Medium
2High
3Urgent

Status

ValueMeaning
0Open
1In Progress
2Close
3Replied
4Waiting For Reply
5Queue

Note visibility (is_public)

ValueMeaning
0Private - agents only, visible across all of the client’s tickets
1Public - visible to the client across all of their tickets
2This ticket only - visible to the client, only on this ticket
3Private, this ticket only - agents only, only on this ticket

Get All Support Tickets

Retrieve a paginated list of support tickets, newest first.

GET /api/public-v1/support-ticket

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination
itemintegerNoTickets per page (default: 10). 0 returns all tickets without pagination
searchstringNoA numeric value matches the ticket id exactly; any other text matches the subject or the creator’s email
emailstringNoReturn only tickets created by the user with this email (must be a valid email)
statusintegerNoFilter by status (0-5, see Value Reference)
priorityintegerNoFilter by priority (0-3)
spamintegerNoFilter by spam flag (0 or 1)
💡

List results are cached for about 10 seconds, so a ticket you just created or changed may take a few seconds to appear in the list.

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/support-ticket?page=1&item=20&status=0&priority=2" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json"

JavaScript Example

const response = await fetch('https://public-api.taskip.net/api/public-v1/support-ticket?page=1&item=20', { method: 'GET', headers: { 'X-Secret-Key': 'your-secret-key-here', 'Content-Type': 'application/json' } }); const tickets = await response.json();

Example Response

{ "msg": "Support ticket list", "data": [ { "id": 1, "uuid": "550e8400-e29b-41d4-a716-446655440001", "subject": "Login Issues with Dashboard", "created_by": { "id": 15, "uuid": "9f1c2f0e-6c1b-4e6e-a1d2-0c3a8f7b2d11", "contact_id": 7, "first_name": "John", "last_name": "Smith", "full_name": "John Smith", "email": "john@acme.com", "image": null }, "user": { "id": 3, "uuid": "b7a0c1d4-33f2-4a8e-9a77-5e1d9a2c4f10", "contact_id": null, "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "email": "sarah@taskip.com", "image": null }, "agents": [ { "id": 3, "uuid": "b7a0c1d4-33f2-4a8e-9a77-5e1d9a2c4f10", "contact_id": null, "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "email": "sarah@taskip.com", "image": null } ], "priority": 3, "status": 1, "description": "User cannot access dashboard after password reset", "createAt": "2 hours ago", "date": "2024-01-15", "time": "09:30AM", "is_spam": 0, "is_shared": false, "replies_count": 2, "last_replied_at": "1 hour ago", "last_reply": { "id": 12, "message": "We are looking into this.", "created_at": "2024-01-15T10:30:00.000000Z", "updated_at": "2024-01-15T10:30:00.000000Z", "user": { "id": 3, "name": "Sarah Johnson", "email": "sarah@taskip.com", "image": null } }, "sla": null } ], "links": { "first": "https://public-api.taskip.net/api/public-v1/support-ticket?page=1", "last": "https://public-api.taskip.net/api/public-v1/support-ticket?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1 } }

user is the primary assigned agent and agents lists all assigned agents. sla is null unless an SLA tracker exists for the ticket; otherwise it contains first_response_status, first_response_status_label, first_response_due_at, first_response_seconds_remaining, resolution_status, resolution_status_label, resolution_due_at and resolution_seconds_remaining. When search is used, meta.search echoes the search term.


Create a Support Ticket

Create a new support ticket in your system.

POST /api/public-v1/support-ticket

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Request Body

FieldTypeRequiredDescription
subjectstringYesTicket subject (max 191 characters)
priorityintegerYesPriority level: 0=Low, 1=Medium, 2=High, 3=Urgent (any other value returns 422)
statusintegerNoStatus (0-5, see Value Reference). Defaults to 0 (Open)
descriptionstringNoDetailed description of the issue. Also stored as the ticket’s first reply
attachmentintegerNoAttachment media ID (a single ID, not an array)
emailstringNoEmail of the client the ticket is created for (max 191, must be valid). If a user with this email exists it must be a contact (otherwise 422); if none exists a contact is created automatically
created_byintegerNoUser ID of the ticket creator (ignored when email is provided)
user_idintegerNoUser ID of the agent to assign the ticket to
user_idsarray of integerNoUser IDs of agents to assign (at least 1). The first ID becomes the primary agent (user). Takes precedence over user_id

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "subject": "Email Notifications Not Working", "priority": 2, "status": 0, "description": "Customer reports that email notifications for new orders are not being received. This started happening 2 days ago.", "attachment": 101, "email": "emma@startup.com", "user_id": 18 }'

Python Example

import requests headers = { 'X-Secret-Key': 'your-secret-key-here', 'Content-Type': 'application/json' } ticket_data = { "subject": "Email Notifications Not Working", "priority": 2, "status": 0, "description": "Customer reports that email notifications for new orders are not being received. This started happening 2 days ago.", "attachment": 101, "email": "emma@startup.com", "user_id": 18 } response = requests.post( 'https://public-api.taskip.net/api/public-v1/support-ticket', headers=headers, json=ticket_data ) result = response.json()

Example Response

Status: 200 OK

{ "msg": "SupportTicket updated successfully", "ticket": { "id": 46, "uuid": "550e8400-e29b-41d4-a716-446655440046", "subject": "Email Notifications Not Working", "created_by": { "id": 40, "uuid": "1c9d3a52-8e0b-4d57-9c1e-2f6b7a3d4e90", "contact_id": 12, "first_name": "emma", "last_name": "", "full_name": "emma", "email": "emma@startup.com", "image": null }, "user": { "id": 18, "uuid": "6d2e8b1a-5f3c-4a09-b1d7-8c4e2f9a0b33", "contact_id": null, "first_name": "David", "last_name": "Chen", "full_name": "David Chen", "email": "david@taskip.com", "image": null }, "agents": [ { "id": 18, "uuid": "6d2e8b1a-5f3c-4a09-b1d7-8c4e2f9a0b33", "contact_id": null, "first_name": "David", "last_name": "Chen", "full_name": "David Chen", "email": "david@taskip.com", "image": null } ], "priority": 2, "status": 0, "description": "Customer reports that email notifications for new orders are not being received. This started happening 2 days ago.", "createAt": "just now", "date": "2024-01-16", "time": "10:30AM", "is_spam": 0, "is_shared": false, "replies_count": null, "last_replied_at": null, "sla": null } }

Validation failures return 422 with { "error": { "<field>": ["..."] } }.


Get a Specific Support Ticket

Retrieve details of a specific support ticket by UUID, including the latest 10 replies and the latest 10 activities.

GET /api/public-v1/support-ticket/{uuid}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesTicket UUID

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json"

Example Response

{ "msg": "SupportTicket retrieved successfully", "data": { "id": 46, "uuid": "550e8400-e29b-41d4-a716-446655440046", "subject": "Email Notifications Not Working", "created_by": { "id": 40, "uuid": "1c9d3a52-8e0b-4d57-9c1e-2f6b7a3d4e90", "contact_id": 12, "first_name": "emma", "last_name": "", "full_name": "emma", "email": "emma@startup.com", "image": null }, "user": null, "agents": [], "priority": 2, "status": 1, "description": "Customer reports that email notifications for new orders are not being received.", "attachment": { "id": 101, "title": "error_logs.txt", "ext": "txt", "size": 15420, "url": "https://cdn.taskip.net/attachments/error_logs.txt", "media_type": "text", "createdAt": "16-01-2024 10:30:00" }, "replies": [ { "id": 55, "user": { "id": 40, "uuid": "1c9d3a52-8e0b-4d57-9c1e-2f6b7a3d4e90", "contact_id": 12, "first_name": "emma", "last_name": "", "full_name": "emma", "email": "emma@startup.com", "image": null }, "description": "Customer reports that email notifications for new orders are not being received.", "attachment": [], "createAt": "3 hours ago", "date": "16-Jan-2024", "time": "10:30AM", "created_at": "2024-01-16T10:30:00+00:00" } ], "createAt": "3 hours ago", "date": "16-Jan-2024", "time": "10:30AM", "shares": [], "is_shared": false, "activities": [], "time_tracking_enabled": false, "manual_time_track_permission": true, "live_time_track_permission": true, "sla": null } }

A missing ticket returns 404 with { "msg": "Ticket not found" }.


Update a Support Ticket

Update an existing support ticket. Supports both PUT and PATCH.

PUT /api/public-v1/support-ticket/{uuid} PATCH /api/public-v1/support-ticket/{uuid}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesTicket UUID to update

Request Body

The update uses the same validation as create, so subject and priority are required on every update (even PATCH). The other fields (status, description, attachment, created_by, user_id, user_ids) are optional. See Create a Support Ticket for field descriptions.

Only the keys you send among subject, priority, status and description are written; fields you omit keep their current value (nothing is reset). If user_ids (or user_id) is sent, the ticket’s assignees are replaced with those agents (the first ID becomes the primary agent); invalid agent IDs return 422 with { "msg": "..." }. If attachment is sent, the ticket’s existing attachment media is replaced by the given media ID. An update does not create an initial reply and does not fire the “ticket created” webhook or workflows, and you do not need to send the ticket’s current user_id.

The ticket is looked up by uuid; an unknown UUID returns 404 with { "msg": "Ticket not found" }.

Example Request

curl -X PUT "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "subject": "Email Notifications Not Working - URGENT", "priority": 3, "status": 1, "description": "Customer reports critical email notification failures affecting order processing" }'

Example Response

Status: 201 Created

{ "msg": "SupportTicket stored successfully", "ticket": { "id": 46, "uuid": "550e8400-e29b-41d4-a716-446655440046", "subject": "Email Notifications Not Working - URGENT", "priority": 3, "status": 1, "description": "Customer reports critical email notification failures affecting order processing", "createAt": "3 hours ago", "date": "2024-01-16", "time": "10:30AM" } }

The ticket object has the same shape as in Create a Support Ticket (abbreviated above).


Delete a Support Ticket

Delete a specific support ticket from your system.

DELETE /api/public-v1/support-ticket/{uuid}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesTicket UUID to delete
⚠️

Warning: Deleting a support ticket cannot be undone.

Example Request

curl -X DELETE "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here"

Example Response

{ "msg": "SupportTicket deleted successfully" }

A missing ticket returns 404 with { "msg": "Ticket not found" }.


Bulk Actions

Perform an operation on up to 1000 tickets at once.

POST /api/public-v1/support-ticket/bulk-actions

Request Body

FieldTypeRequiredDescription
idsarray of stringYesTicket UUIDs (1 to 1000)
actionstringYesOne of delete, priority, status, assign
priorityintegerRequired if action is priorityNew priority (0-3)
statusintegerRequired if action is statusNew status (0-5)
user_idsarray of integerNoAgent user IDs for assign (at least 1). Takes precedence over user_id
user_idintegerNoSingle agent user ID for assign

For assign, the supplied agents replace the current assignees of every selected ticket. Invalid agent IDs return 422.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/bulk-actions" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "ids": ["550e8400-e29b-41d4-a716-446655440040", "550e8400-e29b-41d4-a716-446655440041"], "action": "status", "status": 2 }'

Example Response

{ "msg": "SupportTicket status updated successfully" }

Success messages by action: SupportTicket deleted successfully, SupportTicket priority updated successfully, SupportTicket status updated successfully, SupportTicket assigned successfully. If none of the UUIDs match a ticket, 404 is returned with SupportTicket not found.


List Ticket Replies

Retrieve the replies of a ticket, oldest first.

GET /api/public-v1/support-ticket/{uuid}/replies

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesTicket UUID

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number
per_pageintegerNoReplies per page (default: 10)

Example Request

curl -X GET "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046/replies?per_page=20" \ -H "X-Secret-Key: your-secret-key-here"

Example Response

{ "data": [ { "id": 55, "user": { "id": 40, "uuid": "1c9d3a52-8e0b-4d57-9c1e-2f6b7a3d4e90", "contact_id": 12, "first_name": "emma", "last_name": "", "full_name": "emma", "email": "emma@startup.com", "image": null }, "description": "Customer reports that email notifications for new orders are not being received.", "attachment": [], "createAt": "3 hours ago", "date": "16-Jan-2024", "time": "10:30AM", "created_at": "2024-01-16T10:30:00+00:00" } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 20, "total": 1 } }

A missing ticket returns 404 with { "msg": "Ticket not found" }.


Reply to Support Ticket

Add a reply to an existing support ticket. The reply is attributed to the user given in reply_by_user_id.

POST /api/public-v1/support-ticket/reply/{uuid}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesSupport ticket UUID

Request Body

FieldTypeRequiredDescription
reply_by_user_idintegerYes (in practice)ID of the user the reply is posted as. This field is not part of the validation rules; if it is missing or does not match a user (and no user is authenticated), the request returns 422 with { "msg": "A valid reply_by_user_id is required" }
descriptionstringConditionalReply content. Required unless attachment is provided
attachmentarray of integerConditionalMedia upload IDs to attach. Each must exist. Required unless description is provided
statusanyNoAccepted but ignored; the ticket status is set automatically (see below)

The ticket status is set automatically: 3 (Replied) when the replier is a contact (client), 1 (In Progress) when the replier is an agent/team member. Agent notifications are suppressed on this endpoint; use Agent Reply to notify agents.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/reply/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "reply_by_user_id": 40, "description": "Thanks, the problem is still happening this morning.", "attachment": [123] }'

Example Response

{ "msg": "SupportTicket reply successfully", "status": 200, "reply": { "id": 789, "user": { "id": 40, "uuid": "1c9d3a52-8e0b-4d57-9c1e-2f6b7a3d4e90", "contact_id": 12, "first_name": "emma", "last_name": "", "full_name": "emma", "email": "emma@startup.com", "image": null }, "description": "Thanks, the problem is still happening this morning.", "attachment": [ { "id": 123, "title": "solution_guide.pdf", "ext": "pdf", "size": 245760, "url": "https://cdn.taskip.net/attachments/solution_guide.pdf", "media_type": "document", "createdAt": "26-01-2024 15:30:00" } ], "createAt": "just now", "date": "26-Jan-2024", "time": "03:30PM", "created_at": "2024-01-26T15:30:00+00:00" } }

Errors: 404 { "msg": "Ticket not found" }; 422 validation error { "error": { ... } }; 422 { "msg": "A valid reply_by_user_id is required" } when reply_by_user_id is missing or does not match a user.


Agent Reply to Support Ticket

Reply to a ticket as an agent (team member). Unlike Reply to Support Ticket, agent notifications are not suppressed, and the replier must be an agent user.

POST /api/public-v1/support-ticket/agent-reply/{uuid}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesSupport ticket UUID

Request Body

FieldTypeRequiredDescription
agent_idintegerYesUser ID of the agent posting the reply. Must exist and must not be a contact or lead
descriptionstringConditionalReply content. Required unless attachment is provided
attachmentarray of integerConditionalMedia upload IDs to attach. Required unless description is provided
statusanyNoAccepted but ignored; the ticket status is set to 1 (In Progress)

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/agent-reply/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "agent_id": 3, "description": "We have reviewed your issue and will provide a solution shortly." }'

Example Response

{ "msg": "SupportTicket reply successfully", "reply": { "id": 790, "user": { "id": 3, "uuid": "b7a0c1d4-33f2-4a8e-9a77-5e1d9a2c4f10", "contact_id": null, "first_name": "Sarah", "last_name": "Johnson", "full_name": "Sarah Johnson", "email": "sarah@taskip.com", "image": null }, "description": "We have reviewed your issue and will provide a solution shortly.", "attachment": [], "createAt": "just now", "date": "26-Jan-2024", "time": "03:35PM", "created_at": "2024-01-26T15:35:00+00:00" } }

Error Responses

StatusBody
422{ "msg": "agent_id is required" }
422{ "msg": "Agent not found" }
422{ "msg": "The provided agent_id does not belong to an agent user" }
404{ "msg": "Ticket not found" }

Update Ticket Priority

POST /api/public-v1/support-ticket/{uuid}/priority

Request Body

FieldTypeRequiredDescription
priorityintegerYes0=Low, 1=Medium, 2=High, 3=Urgent

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046/priority" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "priority": 3 }'

Example Response

{ "msg": "SupportTicket status updated successfully" }

The success message says “status” even though the priority was updated. A missing ticket returns 404 (Ticket not found).


Update Ticket Status

POST /api/public-v1/support-ticket/status-update/{uuid}

Request Body

FieldTypeRequiredDescription
statusintegerYes0=Open, 1=In Progress, 2=Close, 3=Replied, 4=Waiting For Reply, 5=Queue

Setting 2 (Close) records the ticket as resolved for SLA purposes and fires the “status updated” webhook; 4 and 5 pause the SLA timer; 0 and 1 resume it.

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/status-update/550e8400-e29b-41d4-a716-446655440046" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "status": 2 }'

Example Response

{ "msg": "SupportTicket status updated successfully" }

Errors: 404 (Ticket not found), 422 { "error": { "status": [...] } }.


Add Ticket Note

Add an internal or client-visible note to a ticket.

POST /api/public-v1/support-ticket/{uuid}/note-store

Request Body

FieldTypeRequiredDescription
titlestringNoNote title (max 191 characters)
descriptionstringYesNote content (max 1000 characters)
is_publicintegerNoVisibility: 0=Private, 1=Public, 2=This ticket only, 3=Private this ticket only (default: 0)

Example Request

curl -X POST "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046/note-store" \ -H "X-Secret-Key: your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{ "title": "Escalation", "description": "Customer is on the Enterprise plan, handle with priority.", "is_public": 0 }'

Example Response

Status: 201 Created

{ "msg": "Ticket stored successfully", "data": { "title": "Escalation", "description": "Customer is on the Enterprise plan, handle with priority.", "is_public": 0, "notable_type": "Modules\\SupportTicket\\Models\\SupportTicket", "notable_id": 46, "updated_at": "2024-01-16T11:00:00.000000Z", "created_at": "2024-01-16T11:00:00.000000Z", "id": 9 } }

Delete Ticket Note

DELETE /api/public-v1/support-ticket/{uuid}/note-delete/{id}

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesTicket UUID
idintegerYesNote ID

Example Request

curl -X DELETE "https://public-api.taskip.net/api/public-v1/support-ticket/550e8400-e29b-41d4-a716-446655440046/note-delete/9" \ -H "X-Secret-Key: your-secret-key-here"

Example Response

{ "msg": "Note deleted successfully" }

A note is only deleted if it belongs to the ticket in the URL. Errors: 404 with Ticket not found or Note not found (including when the note ID belongs to a different ticket).


Error Responses

Common Error Codes

Status CodeError TypeDescription
401UnauthorizedInvalid or missing X-Secret-Key
403ForbiddenPlan or module access restriction
404Not FoundTicket or note not found
422Validation ErrorRequest data failed validation
429Too Many RequestsRate limit exceeded

Validation Error Shape

Create, update, reply and status-update requests return validation failures as:

{ "error": { "subject": ["The subject field is required."], "priority": ["The priority field is required."] } }

List, bulk-actions, priority and note requests use the standard Laravel shape:

{ "message": "The description field is required.", "errors": { "description": ["The description field is required."] } }

Non-validation errors from this API have the form { "msg": "Ticket not found" }.


Best Practices

  1. Use UUIDs: every ticket path parameter is the ticket UUID, not the numeric ID.
  2. Send full payloads on update: update re-runs the create routine, so always include subject, priority and any other values you want to keep.
  3. Pick the right reply endpoint: use reply/{uuid} for client replies and agent-reply/{uuid} when an agent should be notified-by-reply.
  4. Use notes for internal context: set is_public to 0 or 3 to keep notes agent-only.
Last updated on