Support Tickets

Support Tickets gives your customers a hosted support portal and your team an agent inbox in the dashboard. This REST API lets your own app create and read tickets on your customers' behalf.

How the product fits togetherlink

Your customers raise and follow tickets, either on the hosted portal (your subdomain or custom domain) or inside your own app via this API.
Your agents answer from Dashboard → Support: assignment, priorities, internal notes, canned replies, knowledge-base articles.
Your systems stay in sync through outbound webhooks (ticket.created / ticket.updated / ticket.comment_added); see Webhooks.

Conceptslink

Concept	Values / meaning
Ticket status	`OPEN` → `IN_PROGRESS` → `RESOLVED` → `CLOSED`. A customer comment on a RESOLVED ticket reopens it.
Priority	`LOW` · `NORMAL` · `HIGH` · `URGENT`
Comments	`PUBLIC` (customer-visible, delivered by webhook) vs `INTERNAL` agent notes (never leave the platform)
Customer identity	Tickets are keyed by `customerEmail`; every read requires it, so one customer can never see another's tickets.
Portal sign-in	Three modes: single-use sign-in links minted by your backend (below), hosted SSO, or delegated login against your own user store (see Webhooks → Customer authentication).

Using this APIlink

Your backend calls these endpoints on behalf of your customers.

Scope required: full-access or ticket-management

All requests use: x-api-key: {{apiKey}}

Ticket statuses: OPEN → IN_PROGRESS → RESOLVED → CLOSED Priorities: LOW, NORMAL, HIGH, URGENT

Mint customer sign-in link

POST/api/v1/support-tickets/auth/login-links

Mints a single-use support-portal sign-in link for a customer your backend has already authenticated.

Returns a URL that signs the customer into the support portal without a password. The link expires in 10 minutes and is single-use.

Scope: full-access or ticket-management

Request body

Field	Type	Notes
`email`	string (required)	Customer email, used as the portal identity
`name`	string (optional, max 100)	Customer display name
`externalId`	string (optional, max 200)	Your internal customer ID
`returnTo`	string (optional, max 500)	Portal path to land on (must start with `/`)

Authorization

x-api-keyAPI key · headerrequired

Request body

application/json

{
  "email": "alice@example.com",
  "name": "Alice Smith",
  "externalId": "cust_789",
  "returnTo": "/tickets"
}

Responses

200Link minted

400Invalid email

401Invalid or missing API key

403Missing permission scope

curl -X POST 'https://api.newinstance.cloud/api/v1/support-tickets/auth/login-links' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "alice@example.com",
  "name": "Alice Smith",
  "externalId": "cust_789",
  "returnTo": "/tickets"
}'

Response

{
  "url": "https://support.yourcompany.com/auth/redeem?token=abc123",
  "expiresAt": "2026-06-26T10:10:00.000Z"
}

List customer tickets

GET/api/v1/support-tickets/tickets

Lists one customer's tickets, page by page. The customer is identified by email.

Scope: full-access, ticket-management or read-only

Authorization

x-api-keyAPI key · headerrequired

Parameters

customerEmailquery · stringdefault:

Required. Email of the customer whose tickets to list.

pagequery · stringdefault:

Optional. Page number, from 1. Defaults to 1.

limitquery · stringdefault:

Optional. Tickets per page, 1 to 100. Defaults to 20.

Responses

200Tickets list

400Missing customerEmail

401Invalid or missing API key

403Missing permission scope

curl -X GET 'https://api.newinstance.cloud/api/v1/support-tickets/tickets?customerEmail=alice%40example.com&page=1&limit=20' \
  -H 'x-api-key: YOUR_API_KEY'

Response

{
  "tickets": [
    {
      "ticketId": "tkt_abc123",
      "title": "Unable to export invoice PDF",
      "status": "OPEN",
      "priority": "HIGH",
      "createdAt": "2026-06-26T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Create ticket

POST/api/v1/support-tickets/tickets

Creates a support ticket on behalf of a customer, and creates the customer record if it does not exist yet.

Scope: full-access or ticket-management

Request body

Field	Type	Notes
`title`	string (required, max 200)	Ticket title
`description`	string (required, max 5000)	Full description
`customerName`	string (required, max 100)	Customer full name
`customerEmail`	string (required, email)	Customer email
`priority`	string (optional)	`LOW`, `NORMAL`, `HIGH` or `URGENT`
`category`	string (optional, max 100)	Ticket category

The returned ticketId is what the detail and comment endpoints take.

Authorization

x-api-keyAPI key · headerrequired

Request body

application/json

{
  "title": "Unable to export invoice PDF",
  "description": "When I click \"Export as PDF\" on any invoice page, I get a blank file. Tested on Chrome 125 and Firefox 128. The file is 0 bytes. My account ID is ACC-4471.",
  "customerName": "Alice Smith",
  "customerEmail": "alice@example.com",
  "priority": "HIGH",
  "category": "Billing"
}

Responses

201Ticket created

400Validation error

401Invalid or missing API key

403Missing permission scope

curl -X POST 'https://api.newinstance.cloud/api/v1/support-tickets/tickets' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "Unable to export invoice PDF",
  "description": "When I click \"Export as PDF\" on any invoice page, I get a blank file. Tested on Chrome 125 and Firefox 128. The file is 0 bytes. My account ID is ACC-4471.",
  "customerName": "Alice Smith",
  "customerEmail": "alice@example.com",
  "priority": "HIGH",
  "category": "Billing"
}'

Response

{
  "ticketId": "tkt_abc123",
  "status": "OPEN",
  "createdAt": "2026-06-26T10:00:00.000Z"
}

Get ticket detail

GET/api/v1/support-tickets/tickets/{ticketId}

Returns one ticket with its public, customer-facing comments.

Scope: full-access, ticket-management or read-only

ticketId in the path is the ticketId returned by Create ticket; Postman fills it in after that request runs. customerEmail must belong to the customer who owns the ticket: any other email answers 404, so one customer can never read another's ticket.

Authorization

x-api-keyAPI key · headerrequired

Parameters

customerEmailquery · stringdefault:

Required. Email of the customer who owns the ticket, used as the ownership check.

ticketIdpath · stringrequireddefault:

Responses

200Ticket detail

400Missing customerEmail

401Invalid or missing API key

403Missing permission scope

404Ticket not found

curl -X GET 'https://api.newinstance.cloud/api/v1/support-tickets/tickets/{ticketId}?customerEmail=alice%40example.com' \
  -H 'x-api-key: YOUR_API_KEY'

Response

{
  "ticketId": "tkt_abc123",
  "title": "Unable to export invoice PDF",
  "status": "OPEN",
  "priority": "HIGH",
  "category": "Billing",
  "description": "When I click \"Export as PDF\"...",
  "createdAt": "2026-06-26T10:00:00.000Z",
  "comments": []
}

Add customer comment

POST/api/v1/support-tickets/tickets/{ticketId}/comments

Adds a public comment from the customer to a ticket.

Scope: full-access or ticket-management

ticketId in the path is the ticketId returned by Create ticket; Postman fills it in after that request runs.

A comment on a RESOLVED ticket reopens it to OPEN. A CLOSED ticket takes no more comments.

Request body

Field	Type	Notes
`customerEmail`	string (required, email)	Ownership verification
`content`	string (required, max 5000)	Comment text
`attachments`	array (optional, max 5)	Each item: URI string or `{url, name}` object. Host the file at a URL you control (your storage or CDN); the API stores the reference, it does not accept file uploads

Authorization

x-api-keyAPI key · headerrequired

Parameters

ticketIdpath · stringrequireddefault:

Request body

application/json

{
  "customerEmail": "alice@example.com",
  "content": "I tried on Edge as well and the PDF is still blank. I noticed it only happens for invoices older than 90 days. Recent invoices export fine.",
  "attachments": [
    {
      "url": "https://storage.example.com/screenshots/blank-pdf.png",
      "name": "blank-pdf.png"
    }
  ]
}

Responses

201Comment added

400Ticket is closed

401Invalid or missing API key

403Missing permission scope

404Ticket not found

curl -X POST 'https://api.newinstance.cloud/api/v1/support-tickets/tickets/{ticketId}/comments' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "customerEmail": "alice@example.com",
  "content": "I tried on Edge as well and the PDF is still blank. I noticed it only happens for invoices older than 90 days. Recent invoices export fine.",
  "attachments": [
    {
      "url": "https://storage.example.com/screenshots/blank-pdf.png",
      "name": "blank-pdf.png"
    }
  ]
}'

Response

{
  "commentId": "cmt_xyz789",
  "createdAt": "2026-06-26T10:05:00.000Z"
}