Support Tickets

Support Tickets is the New Instance customer-support product: a hosted support portal for your customers, an agent inbox in your dashboard, and this REST API so your own app can 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 - Receiving Platform Events.

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

Note: Agents (your support team) manage tickets from the merchant dashboard. These REST endpoints are for your application backend to create tickets on behalf of customers and let customers retrieve their own tickets.

POST/api/v1/support-tickets/auth/login-linksMint customer sign-in link

Mint customer sign-in link

Mint 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 - 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 `/`)

Success - 200 OK

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

Headers

x-api-key

Request body

application/json

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

Responses

200 – Link minted

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

boltTry it

env

POSThttps://api.newinstance.cloud/api/v1/support-tickets/auth/login-links

Headers

x-api-key

Request body

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

Code samples

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

GET/api/v1/support-tickets/ticketsList customer tickets

List customer tickets

List tickets for a customer, identified by email.

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

Query params

Param	Type	Notes
`customerEmail`	string (required, email)	Customer to fetch tickets for
`status`	string (optional)	`OPEN`
`page`	integer (optional, min 1, default 1)	Page number
`limit`	integer (optional, 1–100, default 20)	Items per page

Success - 200 OK returns paginated ticket list.

Headers

x-api-key

Parameters

customerEmailquerystringdefault: Customer email (required)

pagequerystringdefault: Page number (default 1)

limitquerystringdefault: Items per page (1–100, default 20)

Responses

200 – Tickets list

{
  "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
}

boltTry it

env

GEThttps://api.newinstance.cloud/api/v1/support-tickets/tickets

Query parameters

customerEmail

page

limit

Headers

x-api-key

Code samples

curl -X GET 'https://api.newinstance.cloud/api/v1/support-tickets/tickets'

POST/api/v1/support-tickets/ticketsCreate ticket

Create ticket

Create a support ticket on behalf of a customer. Auto-creates the customer record if not found.

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`
`category`	string (optional, max 100)	Ticket category

Success - 201 Created

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

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

Headers

x-api-key

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

201 – Ticket created

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

boltTry it

env

POSThttps://api.newinstance.cloud/api/v1/support-tickets/tickets

Headers

x-api-key

Request body

{
  "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"
}

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/support-tickets/tickets' \
  -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"
}'

POST/api/v1/support-tickets/tickets/commentsAdd customer comment

Add customer comment

Add a public comment from the customer to a ticket.

Scope: full-access or ticket-management

Side effects:

Auto-reopens RESOLVED tickets to IN_PROGRESS
Cannot comment on CLOSED tickets (returns 422)

Path param: ticketId (auto-filled from environment)

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

Success - 201 Created

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

Headers

x-api-key

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

201 – Comment added

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

boltTry it

env

POSThttps://api.newinstance.cloud/api/v1/support-tickets/tickets/comments

Headers

x-api-key

Request body

{
  "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"
    }
  ]
}

Code samples

curl -X POST 'https://api.newinstance.cloud/api/v1/support-tickets/tickets/comments' \
  -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"
    }
  ]
}'

arrow_back

Deployments (CI/CD)

Support Portal Customer Authentication

arrow_forward