---
name: unified-ticketing
description: >-
  Build helpdesk, support-desk, and issue-tracking features against many
  ticketing platforms (Zendesk, Jira, Freshdesk, ServiceNow, and more) through
  the single Unified.to Ticketing API. Use when a coding task involves creating
  or syncing tickets, customers, notes, or categories across one or more support
  systems.
license: MIT
metadata:
  category: ticketing
  api_base: https://api.unified.to
  docs: https://docs.unified.to/ticketing/overview
---

# Build a helpdesk / ticketing integration with the Unified.to Ticketing API

Unified.to normalizes many ticketing platforms behind one REST API. Write your
support/issue-tracking integration once and it works across every supported
platform. This skill teaches an agent how to build against the Unified Ticketing
API.

## When to use this skill

Use this skill when the task is to:

- Create tickets from your product and sync their status back
- Two-way sync tickets between systems
- Add notes/comments to tickets
- Manage customers and ticket categories across more than one platform

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**.
2. An activated ticketing integration (e.g. Zendesk) — start in the Sandbox.
3. A **connection ID** from the embedded Authorization component
   (https://docs.unified.to/concepts/embedded-components).

Keep the API key server-side only.

## Core request pattern

```
https://api.unified.to/ticketing/{connection_id}/{object}
```

Authenticate every request:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `api.unified.to` (NA), `api-eu.unified.to` (EU),
`api-au.unified.to` (AU).

## Data objects

| Object     | Purpose                                  |
| ---------- | ---------------------------------------- |
| `ticket`   | A support ticket / issue                 |
| `customer` | The requester / customer on a ticket     |
| `note`     | A note / comment on a ticket             |
| `category` | A ticket category / queue                |

### Supported operations (ticket shown; others follow the same shape)

| Method   | Path                              | Description        |
| -------- | --------------------------------- | ------------------ |
| `GET`    | `/ticketing/{cid}/ticket`         | List tickets       |
| `GET`    | `/ticketing/{cid}/ticket/{id}`    | Get one ticket     |
| `POST`   | `/ticketing/{cid}/ticket`         | Create a ticket    |
| `PATCH`  | `/ticketing/{cid}/ticket/{id}`    | Update a ticket    |
| `DELETE` | `/ticketing/{cid}/ticket/{id}`    | Delete a ticket    |

The same verbs apply to `customer`, `note`, and `category`.

Not every platform supports every object or field. Check the **Feature Support**
tab in `app.unified.to`; a `501` response means unsupported.

## Pagination, filtering & sorting

- `limit` (max 100) and `offset` (zero-based).
- `updated_gte=YYYY-MM-DDTHH:MM:SSZ` for incremental sync.
- `sort` (`created_at`, `updated_at`) + `order` (`asc` / `desc`).

## Example: create a ticket and add a note (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// Create a ticket
const ticketRes = await fetch(`${BASE}/ticketing/${connectionId}/ticket`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        subject: 'Cannot reset password',
        description: 'The reset email never arrives.',
        priority: 'HIGH',
    }),
});
const ticket = await ticketRes.json();

// Add an internal note to it
await fetch(`${BASE}/ticketing/${connectionId}/note`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        ticket_id: ticket.id,
        note: 'Escalated to the auth team.',
    }),
});
```

Consult the ticket data model at https://docs.unified.to/ticketing/ticket/model
for canonical fields.

## Example: with the official SDK

```bash
npm install @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY! } });

const { ticketingTickets } = await unified.ticketing.listTicketingTickets({
    connectionId,
    limit: 100,
});
```

SDKs for Python, PHP, Java, Go, C#, and Ruby: https://docs.unified.to/reference/sdks.

## Keeping data in sync (recommended)

- Register **webhooks** for `ticket` and `note` events and upsert by `id` so
  your inbox stays current without polling. See
  https://docs.unified.to/reference/webhooks.

## Error handling

| Code | Meaning & action                                            |
| ---- | ----------------------------------------------------------- |
| 401  | Connection broken — re-authorize the end-user.              |
| 403  | Missing scopes — fix provider app + Unified.to scopes.      |
| 429  | Provider rate limit — back off; prefer webhook sync.        |
| 501  | Operation unsupported by platform — check Feature Support.  |

## References

- Ticketing API overview & data model: https://docs.unified.to/ticketing/overview
- Ticket data model: https://docs.unified.to/ticketing/ticket/model
- REST basics: https://docs.unified.to/reference/rest
- Pagination & filtering: https://docs.unified.to/reference/pagination