API Reference

https://api.dispatchtickets.com/v1

Authorization: Bearer sk_live_your_api_key

import { DispatchTickets } from '@dispatchtickets/sdk';

const dispatch = new DispatchTickets({
  apiKey: process.env.DISPATCH_API_KEY!
});

curl https://api.dispatchtickets.com/v1/brands \
  -H "Authorization: Bearer sk_live_your_api_key"

const { data: brands } = await dispatch.brands.list();

// Response
[
  {
    "id": "br_abc123",
    "name": "Acme Support",
    "slug": "acme-support",
    "createdAt": "2024-01-01T00:00:00Z"
  }
]

const brand = await dispatch.brands.get('br_abc123');

const brand = await dispatch.brands.create({
  name: 'New Brand',
  slug: 'new-brand' // Optional, auto-generated if omitted
});

const { data: tickets, pagination } = await dispatch.tickets.list('br_abc123', {
  status: 'open',
  limit: 20,
  cursor: 'cursor_xyz' // For pagination
});

// Response
{
  "data": [
    {
      "id": "tkt_xyz789",
      "ticketNumber": "TKT-1042",
      "title": "Need help with my order",
      "status": "open",
      "priority": "normal",
      "customer": {
        "id": "cus_def456",
        "email": "[email protected]",
        "name": "Jane Doe"
      },
      "customFields": {},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cursor_abc"
  }
}

const ticket = await dispatch.tickets.get('br_abc123', 'tkt_xyz789');

const ticket = await dispatch.tickets.create('br_abc123', {
  title: 'Need help with my order',
  body: 'My order #12345 has not arrived yet.',
  customerEmail: '[email protected]',
  customerName: 'Jane Doe', // Optional
  priority: 'normal', // 'low' | 'normal' | 'high' | 'urgent'
  customFields: {
    orderId: '12345',
    orderTotal: 99.99
  }
});

const ticket = await dispatch.tickets.update('br_abc123', 'tkt_xyz789', {
  status: 'pending',
  priority: 'high',
  assigneeId: 'usr_abc123',
  customFields: {
    resolution: 'Shipped replacement'
  }
});

await dispatch.tickets.close('br_abc123', 'tkt_xyz789', {
  resolution: 'Resolved - replacement shipped'
});

const { data: comments } = await dispatch.tickets.listComments(
  'br_abc123',
  'tkt_xyz789'
);

// Response
[
  {
    "id": "cmt_abc123",
    "body": "Thanks for reaching out! Let me look into this.",
    "authorType": "STAFF",
    "authorName": "Support Team",
    "authorId": "usr_xyz789",
    "createdAt": "2024-01-15T11:00:00Z"
  }
]

const comment = await dispatch.tickets.addComment('br_abc123', 'tkt_xyz789', {
  body: 'Your order has shipped! Tracking: 1Z999...',
  authorType: 'STAFF', // 'STAFF' | 'CUSTOMER' | 'SYSTEM'
  authorName: 'Support Team',
  authorId: 'usr_xyz789', // Optional
  internal: false // Set true for internal notes
});

const { data: customers } = await dispatch.customers.list('br_abc123', {
  search: '[email protected]'
});

const customer = await dispatch.customers.get('br_abc123', 'cus_def456');

// Response
{
  "id": "cus_def456",
  "email": "[email protected]",
  "name": "Jane Doe",
  "ticketCount": 5,
  "createdAt": "2024-01-01T00:00:00Z"
}

const { data: tickets } = await dispatch.customers.listTickets(
  'br_abc123',
  'cus_def456'
);

const { uploadUrl, attachmentId } = await dispatch.attachments.getUploadUrl(
  'br_abc123',
  'tkt_xyz789',
  {
    filename: 'screenshot.png',
    contentType: 'image/png',
    size: 102400 // bytes
  }
);

// Upload file directly to the presigned URL
await fetch(uploadUrl, {
  method: 'PUT',
  body: fileBuffer,
  headers: { 'Content-Type': 'image/png' }
});

// Confirm upload
await dispatch.attachments.confirmUpload('br_abc123', 'tkt_xyz789', attachmentId);

const { downloadUrl } = await dispatch.attachments.getDownloadUrl(
  'br_abc123',
  'tkt_xyz789',
  'att_abc123'
);

// URL is valid for 15 minutes

const { data, pagination } = await dispatch.tickets.list('br_abc123', {
  // Pagination
  limit: 20,           // 1-100, default 20
  cursor: 'cursor_xyz', // From previous response

  // Filtering
  status: 'open',       // 'open' | 'pending' | 'closed'
  priority: 'high',     // 'low' | 'normal' | 'high' | 'urgent'
  assigneeId: 'usr_abc123',
  customerId: 'cus_def456',

  // Search
  search: 'order #12345',

  // Date range
  createdAfter: '2024-01-01T00:00:00Z',
  createdBefore: '2024-01-31T23:59:59Z',

  // Sorting
  sort: 'createdAt',    // Field to sort by
  order: 'desc'         // 'asc' | 'desc'
});

// Paginate through all results
let allTickets = [];
let cursor = undefined;

do {
  const { data, pagination } = await dispatch.tickets.list('br_abc123', {
    cursor,
    limit: 100
  });

  allTickets.push(...data);
  cursor = pagination.nextCursor;
} while (cursor);

{
  "error": {
    "code": "TICKET_NOT_FOUND",
    "message": "Ticket with ID tkt_xyz789 not found",
    "details": {} // Additional context if available
  }
}

import { DispatchError } from '@dispatchtickets/sdk';

try {
  const ticket = await dispatch.tickets.get('br_abc123', 'tkt_invalid');
} catch (error) {
  if (error instanceof DispatchError) {
    console.error(error.code);    // 'TICKET_NOT_FOUND'
    console.error(error.message); // 'Ticket with ID...'
    console.error(error.status);  // 404
  }
}