Contacts

Contacts represent the customers who submit tickets to your helpdesk.

The contact object

Attribute	Type	Description
id	string	Unique identifier
name	string	Contact name (max 128 characters)
email	string	Contact email address (max 128 characters)
organizationId	string | null	Associated organization ID
organizationName	string | null	Associated organization name
notes	string | null	Free-text notes
ticketCount	integer	Number of tickets from this contact
createdAt	string	Creation time (ISO 8601 UTC)

List contacts

GET /helpdesk/api/contacts

Returns a paginated list of contacts.

Query parameters

Parameter	Type	Required	Description
search	string	no	Search by name or email
organization_id	string	no	Filter by organization
sort_by	string	no	name, email, created_at (default: created_at)
sort_order	string	no	asc or desc (default: desc)
page	integer	no	Page number (default: 1)
limit	integer	no	Results per page (default: 15, max: 100)

Response

{
  "success": true,
  "data": [ ... ],
  "meta": { "page": 1, "limit": 15, "total": 42, "totalPages": 3 }
}

Retrieve a contact

GET /helpdesk/api/contacts/:contactId

Find by email

GET /helpdesk/api/contacts/by-email/:email

Returns the contact matching the email address, or null if not found.

Create a contact

POST /helpdesk/api/contacts

Requires agent role or above.

Request body

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "organizationId": "org_abc123",
  "notes": "VIP customer"
}

Field	Type	Required	Description
name	string	yes	Contact name
email	string	yes	Email address
organizationId	string	no	Organization to associate
notes	string	no	Free-text notes

Response

Returns 201 Created with the contact object.

Update a contact

PATCH /helpdesk/api/contacts/:contactId

Requires agent role or above. All fields are optional.

Delete a contact

DELETE /helpdesk/api/contacts/:contactId

Requires agent role or above. Returns 204 No Content. Does not delete the contact’s tickets.