Tickets API Reference

Tickets API Reference

This comprehensive reference covers all 52 ticket-related API endpoints in the Pulse API. All endpoints require authentication and appropriate permissions.

Authentication

All requests must include an Authorization header and account ID:

Authorization: Bearer YOUR_API_TOKEN
x-account-id: YOUR_ACCOUNT_ID

Base URL

https://api.pulse.com

---

Core Ticket Operations

List Tickets

GET /api/tickets

Retrieve a list of tickets with filtering, pagination, and search capabilities.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
status	string	Filter by status
priority	string	Filter by priority
assignedTo	string	Filter by assigned user ID
assignedTeamId	string	Filter by assigned team ID
category	string	Filter by category
search	string	Search in subject, description, and comments
sort	string	Sort field (e.g., “createdAt”, “-priority”)

Example Request

const response = await fetch(
  "/api/tickets?status=open&priority=urgent&page=1&pageSize=20",
  {
    headers: {
      Authorization: `Bearer ${token}`,
      "x-account-id": accountId,
    },
  }
);

const data = await response.json();

Response

{
  "data": [
    {
      "id": "uuid",
      "category": "Technical Support",
      "status": "open",
      "priority": "urgent",
      "assignedTo": "user-uuid",
      "assignedTeamId": "team-uuid",
      "source": "web",
      "requesterType": "user",
      "requesterId": "user-uuid",
      "createdAt": "2025-11-01T14:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 145,
  "totalPages": 8
}

Permission Required: readSupport

---

Create Ticket

POST /api/tickets

Create a new support ticket.

Request Body

{
  "category": "Technical Support",
  "source": "web",
  "requesterType": "user",
  "requesterId": "user-uuid",
  "requesterName": "John Doe",
  "requesterEmail": "john@example.com",
  "status": "open",
  "priority": "high",
  "assignedTo": "user-uuid",
  "assignedTeamId": "team-uuid"
}

Required Fields

• category (string) - Ticket category
• source (string) - Ticket source (web, email, api, phone)
• requesterType (string) - Type of requester (user, external)
• requesterId (string) - ID of requester
• For external requesters:
  • requesterName (string)
  • requesterEmail (string)

Optional Fields

• status (string) - Initial status (default: open)
• priority (string) - Priority level
• assignedTo (string) - User to assign to
• assignedTeamId (string) - Team to assign to

Permission Required: writeSupport

---

Get Ticket

GET /api/tickets/{ticketId}

Retrieve detailed information about a specific ticket.

Permission Required: readSupport

---

Update Ticket

PUT /api/tickets/{ticketId}

Update an existing ticket. All fields are optional.

Request Body

{
  "category": "Technical Support",
  "priority": "medium",
  "assignedTo": "user-uuid",
  "status": "in_progress"
}

Permission Required: writeSupport

---

Delete Ticket

DELETE /api/tickets/{ticketId}

Permanently delete a ticket.

⚠️ Warning: This action cannot be undone.

Permission Required: writeSupport

---

Ticket Status Management

Change Status

PATCH /api/tickets/{ticketId}/status

Update ticket status with automatic SLA tracking.

Request Body

{
  "status": "resolved"
}

Available Statuses

• open - Newly created, awaiting assignment
• in_progress - Being actively worked on
• waiting_customer - Awaiting customer response (pauses SLA)
• waiting_internal - Waiting on internal team
• resolved - Issue resolved, awaiting confirmation
• closed - Ticket closed and archived

Permission Required: writeSupport

---

Ticket Assignment

Assign Ticket

PATCH /api/tickets/{ticketId}/assign

Assign ticket to a user or team.

Request Body

{
  "assignedTo": "user-uuid",
  "assignedTeamId": "team-uuid"
}

At least one of assignedTo or assignedTeamId is required.

Permission Required: writeSupport

---

Comments

List Comments

GET /api/tickets/{ticketId}/comments

Get all comments for a ticket.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)

Permission Required: readSupport

---

Add Comment

POST /api/tickets/{ticketId}/comments

Add a comment or response to a ticket.

Request Body

{
  "body": "We've identified the issue and implementing a fix now.",
  "isInternal": false
}

Note: The comment author information (authorId, authorName, authorEmail, authorType) is automatically populated from the authenticated session.

Permission Required: writeSupport

---

Rule Execution History

Get Rule Executions for Ticket

GET /api/tickets/{ticketId}/rule-executions

Get all automation rule executions for a specific ticket.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)

Shows which automation rules were applied to this ticket and their results.

Permission Required: readSupport

---

Bulk Operations

Bulk Update Tickets

POST /api/tickets/bulk

Perform bulk operations on multiple tickets.

Request Body

{
  "ticketIds": ["uuid1", "uuid2", "uuid3"],
  "action": "assign",
  "payload": {
    "assignedTo": "user-uuid",
    "assignedTeamId": "team-uuid"
  }
}

Supported Actions

1. assign - Bulk assign tickets

   {
     "action": "assign",
     "payload": {
       "assignedTo": "user-uuid",
       "assignedTeamId": "team-uuid"
     }
   }

2. change_status - Bulk status update

   {
     "action": "change_status",
     "payload": {
       "status": "in_progress"
     }
   }

3. change_priority - Bulk priority change

   {
     "action": "change_priority",
     "payload": {
       "priority": "high"
     }
   }

4. add_tag - Bulk add tag

   {
     "action": "add_tag",
     "payload": {
       "tag": "urgent"
     }
   }

5. remove_tag - Bulk remove tag

   {
     "action": "remove_tag",
     "payload": {
       "tag": "pending"
     }
   }

Permission Required: writeSupport

---

Merge Tickets

POST /api/tickets/merge

Merge multiple duplicate tickets into one primary ticket.

Request Body

{
  "primaryTicketId": "uuid-primary",
  "ticketIdsToMerge": ["uuid1", "uuid2"],
  "mergeComments": true,
  "mergeAttachments": true,
  "closeSecondaryTickets": true
}

Parameters

• primaryTicketId (string, required) - Ticket to merge into
• ticketIdsToMerge (string[], required) - Tickets to merge from
• mergeComments (boolean, optional) - Copy comments to target (default: true)
• mergeAttachments (boolean, optional) - Copy attachments to target (default: true)
• closeSecondaryTickets (boolean, optional) - Close merged tickets (default: true)

Permission Required: writeSupport

---

Statistics & Reporting

Get Ticket Statistics

GET /api/tickets/statistics

Get comprehensive ticket statistics for the account.

Response

{
  "total": 1250,
  "byStatus": {
    "open": 145,
    "in_progress": 234,
    "resolved": 567,
    "closed": 304
  },
  "byPriority": {
    "urgent": 45,
    "high": 189,
    "medium": 678,
    "low": 338
  }
}

Permission Required: readSupport

---

Settings

Get Ticket Settings

GET /api/tickets/settings

Get ticket configuration settings for the account.

Response

{
  "slaThresholds": {
    "urgent": {
      "firstResponseMinutes": 15,
      "resolutionMinutes": 240
    },
    "high": {
      "firstResponseMinutes": 60,
      "resolutionMinutes": 480
    }
  },
  "defaultStatus": "open",
  "defaultPriority": "medium"
}

Permission Required: readSupport

---

Update Ticket Settings

PUT /api/tickets/settings

Update ticket settings.

Request Body

{
  "defaultStatus": "open",
  "defaultPriority": "medium"
}

Permission Required: writeSupport

---

Update SLA Thresholds

PUT /api/tickets/settings/sla

Update SLA threshold configuration.

Request Body

{
  "slaThresholds": {
    "urgent": {
      "firstResponseMinutes": 15,
      "resolutionMinutes": 240
    },
    "high": {
      "firstResponseMinutes": 60,
      "resolutionMinutes": 480
    },
    "medium": {
      "firstResponseMinutes": 240,
      "resolutionMinutes": 1440
    },
    "low": {
      "firstResponseMinutes": 480,
      "resolutionMinutes": 2880
    }
  }
}

Permission Required: writeSupport

---

Update Notification Channels

PUT /api/tickets/settings/notifications/channels

Configure notification channels for ticket events.

Request Body

{
  "channels": [
    {
      "type": "email",
      "enabled": true
    },
    {
      "type": "slack",
      "enabled": true,
      "webhookUrl": "https://hooks.slack.com/..."
    },
    {
      "type": "sms",
      "enabled": false
    }
  ]
}

Permission Required: writeSupport

---

Update Notification Recipients

PUT /api/tickets/settings/notifications/recipients

Configure who receives ticket notifications.

Request Body

{
  "recipients": [
    {
      "userId": "user-uuid",
      "events": ["ticket_created", "ticket_assigned", "sla_breached"]
    }
  ]
}

Permission Required: writeSupport

---

Templates

List Templates

GET /api/tickets/templates

Get all ticket templates (canned responses).

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
search	string	Search templates by name
sort	string	Sort field

Permission Required: readSupport

---

Create Template

POST /api/tickets/templates

Create a new template.

Request Body

{
  "name": "Initial Response",
  "content": "Thank you for contacting support. We're reviewing your issue and will respond shortly."
}

Permission Required: writeSupport

---

Get Template

GET /api/tickets/templates/{id}

Get a specific template by ID.

Permission Required: readSupport

---

Update Template

PUT /api/tickets/templates/{id}

Update an existing template.

Permission Required: writeSupport

---

Delete Template

DELETE /api/tickets/templates/{id}

Delete a template.

Permission Required: writeSupport

---

Automation Rules

List Automation Rules

GET /api/tickets/automation-rules

Get all automation rules.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
search	string	Search rules by name
sort	string	Sort field

Permission Required: readSupport

---

Create Automation Rule

POST /api/tickets/automation-rules

Create a new automation rule.

Request Body

{
  "name": "Auto-assign urgent tickets",
  "trigger": "ticket_created",
  "conditions": [
    {
      "field": "priority",
      "operator": "equals",
      "value": "urgent"
    }
  ],
  "actions": [
    {
      "type": "assign_to_team",
      "teamId": "team-uuid"
    }
  ],
  "enabled": true,
  "executionOrder": 1
}

Permission Required: writeSupport

---

Get Automation Rule

GET /api/tickets/automation-rules/{id}

Get a specific automation rule by ID.

Permission Required: readSupport

---

Update Automation Rule

PUT /api/tickets/automation-rules/{id}

Update an existing automation rule.

Permission Required: writeSupport

---

Delete Automation Rule

DELETE /api/tickets/automation-rules/{id}

Delete an automation rule.

Permission Required: writeSupport

---

Test Automation Rule

POST /api/tickets/automation-rules/{id}/test

Test a rule in dry-run mode (preview actions without executing).

Request Body

{
  "ticketId": "ticket-uuid",
  "trigger": "ticket_created"
}

Response

{
  "wouldExecute": true,
  "conditionsMatched": true,
  "actionsToPerform": [
    {
      "type": "assign_to_team",
      "teamId": "team-uuid"
    }
  ]
}

This endpoint does NOT execute actions, only previews what would happen.

Permission Required: readSupport

---

Get Rule Executions

GET /api/tickets/automation-rules/{id}/executions

Get execution history for a specific automation rule.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
includeStats	boolean	Include execution statistics
executionStatus	string	Filter by status (success, failure)
ticketId	string	Filter by ticket ID
trigger	string	Filter by trigger event
dateFrom	string	ISO 8601 date
dateTo	string	ISO 8601 date

Permission Required: readSupport

---

Escalation Rules

List Escalation Rules

GET /api/tickets/escalation-rules

Get all escalation rules.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
search	string	Search rules by name
sort	string	Sort field

Permission Required: readSupport

---

Create Escalation Rule

POST /api/tickets/escalation-rules

Create a new escalation rule.

Request Body

{
  "name": "Urgent Ticket Escalation",
  "escalateTo": "manager",
  "escalateAfterMinutes": 30,
  "notificationChannels": ["email", "slack"],
  "conditions": [
    {
      "field": "status",
      "operator": "not_in",
      "value": ["resolved", "closed"]
    }
  ],
  "enabled": true
}

Required Fields

• name (string) - Rule name
• escalateTo (string) - manager, team, specific_user, or rotation
• escalateAfterMinutes (number) - Time threshold
• notificationChannels (string[]) - At least one channel required
• conditions (array) - Escalation conditions

Permission Required: writeSupport

---

Get Escalation Rule

GET /api/tickets/escalation-rules/{id}

Get a specific escalation rule by ID.

Permission Required: readSupport

---

Update Escalation Rule

PUT /api/tickets/escalation-rules/{id}

Update an existing escalation rule.

Permission Required: writeSupport

---

Delete Escalation Rule

DELETE /api/tickets/escalation-rules/{id}

Delete an escalation rule.

Permission Required: writeSupport

---

Maverick Integration

The Maverick integration provides bi-directional synchronization with the Maverick merchant services platform.

List Maverick Tickets

GET /api/tickets/maverick

Fetch tickets from Maverick integration (read-only view).

Query Parameters

Parameter	Type	Description
applicationId	string	Filter by application ID
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)

Permission Required: readSupport

---

Sync Maverick Tickets

POST /api/tickets/maverick

Sync Maverick tickets to local database.

Response

{
  "created": 15,
  "updated": 23,
  "skipped": 7,
  "conflicts": 3,
  "errors": 2,
  "totalProcessed": 50
}

Permission Required: writeSupport

---

Get Maverick Categories

GET /api/tickets/maverick/categories

Get Maverick ticket categories with Pulse category mappings.

Response

{
  "categories": [
    {
      "maverickCategoryId": "tech-support",
      "maverickCategoryName": "Technical Support",
      "pulseCategoryId": "category-uuid",
      "pulseCategoryName": "Technical Support"
    }
  ]
}

Permission Required: readSupport

---

Get Maverick Ticket

GET /api/tickets/maverick/{ticketId}

Get a specific Maverick ticket (read-only).

Permission Required: readSupport

---

Get Maverick Ticket Responses

GET /api/tickets/maverick/{ticketId}/responses

Get responses and notes for a Maverick ticket (mapped to Pulse comment format).

Permission Required: readSupport

---

Ticket Rotations

Rotations provide round-robin assignment of tickets to users.

List Rotations

GET /api/ticket-rotations

Get all ticket rotations.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
search	string	Search rotations
sort	string	Sort field

Permission Required: readSupport

---

Create Rotation

POST /api/ticket-rotations

Create a new rotation.

Request Body

{
  "name": "Support Team Rotation",
  "userRotationArray": ["user-uuid-1", "user-uuid-2", "user-uuid-3"],
  "status": "active"
}

Permission Required: writeSupport

---

Get Rotation

GET /api/ticket-rotations/{id}

Get a specific rotation by ID.

Permission Required: readSupport

---

Update Rotation

PUT /api/ticket-rotations/{id}

Update an existing rotation.

Permission Required: writeSupport

---

Delete Rotation

DELETE /api/ticket-rotations/{id}

Delete a rotation.

Permission Required: writeSupport

---

Toggle Rotation Status

PATCH /api/ticket-rotations/{id}/status

Toggle rotation status between active and inactive.

Request Body

{
  "status": "active"
}

Valid values: active, inactive

Permission Required: writeSupport

---

Preview Next User

GET /api/ticket-rotations/{id}/next-user

Preview the next user in rotation without incrementing the rotation.

Response

{
  "userId": "user-uuid",
  "userName": "John Doe",
  "userEmail": "john@example.com"
}

Note: This is READ-ONLY and does not advance the rotation counter.

Permission Required: readSupport

---

Ticket Types

Ticket types define categories and can be linked to rotations for automatic assignment.

List Ticket Types

GET /api/ticket-types

Get all ticket types. Auto-creates default types if none exist.

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 50)
search	string	Search ticket types
sort	string	Sort field

Permission Required: readSupport

---

Create Ticket Type

POST /api/ticket-types

Create a new ticket type.

Request Body

{
  "category": "Technical Support",
  "rotationId": "rotation-uuid"
}

Required Fields

• category (string) - Category name

Optional Fields

• rotationId (string) - Link to rotation for auto-assignment

Permission Required: writeSupport

---

Get Ticket Type

GET /api/ticket-types/{id}

Get a specific ticket type by ID.

Permission Required: readSupport

---

Update Ticket Type

PUT /api/ticket-types/{id}

Update an existing ticket type.

Permission Required: writeSupport

---

Delete Ticket Type

DELETE /api/ticket-types/{id}

Delete a ticket type.

Permission Required: writeSupport

---

Error Responses

All endpoints follow consistent error response format:

400 Bad Request

{
  "error": "Validation failed",
  "message": "Invalid priority value",
  "field": "priority"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions",
  "requiredPermission": "writeSupport"
}

404 Not Found

{
  "error": "Not found",
  "message": "Ticket not found",
  "ticketId": "uuid"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred",
  "requestId": "req-12345"
}

---

Rate Limiting

API requests are rate limited per account:

• Standard tier: 1000 requests/hour
• Professional tier: 5000 requests/hour
• Enterprise tier: 20000 requests/hour

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1635789600

---

Pagination

List endpoints support pagination with consistent parameters:

• page - Page number (1-indexed)
• pageSize - Items per page

Response includes pagination metadata:

{
  "data": [...],
  "page": 1,
  "pageSize": 50,
  "total": 1250,
  "totalPages": 25
}

---

Complete Endpoint Summary

This API reference documents 52 ticket-related endpoints:

Core Tickets: 10 endpoints

• List, Create, Get, Update, Delete
• Change Status, Assign
• List Comments, Add Comment
• Get Rule Executions

Bulk Operations: 2 endpoints

• Bulk Update
• Merge Tickets

Statistics & Settings: 6 endpoints

• Get Statistics
• Get/Update Settings
• Update SLA Thresholds
• Update Notification Channels/Recipients

Templates: 5 endpoints

• List, Create, Get, Update, Delete

Automation Rules: 7 endpoints

• List, Create, Get, Update, Delete
• Test Rule
• Get Executions

Escalation Rules: 5 endpoints

• List, Create, Get, Update, Delete

Maverick Integration: 5 endpoints

• List Tickets, Sync
• Get Categories, Get Ticket, Get Responses

Ticket Rotations: 7 endpoints

• List, Create, Get, Update, Delete
• Toggle Status, Preview Next User

Ticket Types: 5 endpoints

• List, Create, Get, Update, Delete

---

Permissions

Permission	Operations
readSupport	View tickets, templates, rules, settings
writeSupport	Create, update, delete tickets and related resources

---

Related Documentation

• Tickets Overview
• Automation Rules Guide
• Escalation Rules Guide
• SLA Tracking Guide
• Maverick Integration Guide