GET /api/v1/contacts
Requires the contacts:read_all permission.
Authentication
Use an agent API key and secret.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | No | Page number (defaults to 1) default: 1 minimum: 1 |
| page_size | query | integer | No | Number of items per page (defaults to 30, max 500) default: 30 minimum: 1 maximum: 500 |
| order | query | string (enum) | No | Sort direction (case-insensitive). Used only with order_by, defaults to ascending. enum: ["asc", "desc"] |
| order_by | query | string (enum) | No | Field to sort by, as model.field. Results are unordered when omitted. enum: ["users.email", "users.created_at", "users.updated_at"] |
| filters | query | string | No | JSON-encoded filter. Either an array of conditions that are AND-ed, e.g. [{"model":"conversations","field":"status_id","operator":"equals","value":"1"}], or a group {"logic":"AND","rules":[...]} with at most one level of nested groups. Operators: equals, not equals, greater than, less than, set, not set, in, between, contains, ilike, not contains. Filterable fields: users (email, created_at, updated_at). |
Responses
200
List of contacts
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | No | example: "success" |
| data | object | No | |
| data.results | array of object | No | |
| data.results[].id | integer | No | example: 163 |
| data.results[].type | string | No | example: "contact" |
| data.results[].first_name | string | No | example: "Jane" |
| data.results[].last_name | string | No | example: "" |
| data.results[].email | string (email) | No | nullable: true example: "[email protected]" |
| data.results[].enabled | boolean | No | example: true |
| data.results[].avatar_url | string | No | nullable: true example: null |
| data.results[].created_at | string (date-time) | No | example: "2025-09-14T18:53:01.172243Z" |
| data.results[].updated_at | string (date-time) | No | example: "2025-09-14T18:53:01.172243Z" |
| data.results[].external_user_id | string | No | External identifier for the user in your own system nullable: true |
| data.results[].availability_status | string (enum) | No | enum: ["online", "away", "away_manual", "offline", "away_and_reassigning"] example: "offline" |
| data.total | integer | No | example: 39 |
| data.per_page | integer | No | example: 100 |
| data.total_pages | integer | No | example: 1 |
| data.page | integer | No | example: 1 |
401
Unauthorized
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | No | example: "error" |
| message | string | No | Error message example: "Invalid request" |
| data | unspecified | No | Additional error data nullable: true |
| error_type | string (enum) | No | enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"] |
403
Forbidden
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | No | example: "error" |
| message | string | No | Error message example: "Invalid request" |
| data | unspecified | No | Additional error data nullable: true |
| error_type | string (enum) | No | enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"] |
500
Internal server error
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
| status | string | No | example: "error" |
| message | string | No | Error message example: "Invalid request" |
| data | unspecified | No | Additional error data nullable: true |
| error_type | string (enum) | No | enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"] |
Specification
Download the complete OpenAPI specification.
OpenAPI definition for this endpoint
openapi: 3.0.0
info:
title: Libredesk API
description: >-
REST API documentation for Libredesk helpdesk system.
## Authentication
The Libredesk API supports two authentication methods:
### 1. Basic Authentication
Use your API key and secret with Basic authentication:
```
Authorization: Basic <base64_encoded_api_key:api_secret>
```
### 2. Token Authentication
Use your API key and secret with token authentication:
```
Authorization: token api_key:api_secret
```
To obtain API credentials, generate them from your agent profile in the
Libredesk dashboard.
version: 1.0.0
servers:
- url: http://localhost:8080
description: Local development server
security:
- basicAuth: []
- tokenAuth: []
paths:
/api/v1/contacts:
get:
tags:
- Contacts
summary: Get Contacts
description: Requires the `contacts:read_all` permission.
operationId: handleGetContacts
parameters:
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: Page number (defaults to 1)
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 500
default: 30
description: Number of items per page (defaults to 30, max 500)
- name: order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
description: >-
Sort direction (case-insensitive). Used only with `order_by`,
defaults to ascending.
- name: order_by
in: query
required: false
schema:
type: string
enum:
- users.email
- users.created_at
- users.updated_at
description: >-
Field to sort by, as `model.field`. Results are unordered when
omitted.
- name: filters
in: query
required: false
schema:
type: string
description: >-
JSON-encoded filter. Either an array of conditions that are AND-ed,
e.g.
`[{"model":"conversations","field":"status_id","operator":"equals","value":"1"}]`,
or a group `{"logic":"AND","rules":[...]}` with at most one level of
nested groups. Operators: `equals`, `not equals`, `greater than`,
`less than`, `set`, `not set`, `in`, `between`, `contains`, `ilike`,
`not contains`. Filterable fields: `users` (email, created_at,
updated_at).
responses:
'200':
description: List of contacts
content:
application/json:
schema:
$ref: '#/components/schemas/ContactListResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- basicAuth: []
- tokenAuth: []
components:
schemas:
ContactListResponse:
type: object
properties:
status:
type: string
example: success
data:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ContactList'
total:
type: integer
example: 39
per_page:
type: integer
example: 100
total_pages:
type: integer
example: 1
page:
type: integer
example: 1
ErrorResponse:
type: object
description: Error response format
properties:
status:
type: string
example: error
message:
type: string
description: Error message
example: Invalid request
data:
nullable: true
description: Additional error data
error_type:
type: string
enum:
- GeneralException
- PermissionException
- InputException
- DataException
- NetworkException
- NotFoundException
- ConflictException
- UnauthorizedException
- RateLimitException
ContactList:
type: object
properties:
id:
type: integer
example: 163
type:
type: string
example: contact
first_name:
type: string
example: Jane
last_name:
type: string
example: ''
email:
type: string
format: email
example: [email protected]
nullable: true
enabled:
type: boolean
example: true
avatar_url:
type: string
nullable: true
example: null
created_at:
type: string
format: date-time
example: '2025-09-14T18:53:01.172243Z'
updated_at:
type: string
format: date-time
example: '2025-09-14T18:53:01.172243Z'
external_user_id:
type: string
nullable: true
description: External identifier for the user in your own system
availability_status:
type: string
enum:
- online
- away
- away_manual
- offline
- away_and_reassigning
example: offline
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication using base64 encoded API key and secret. Format:
`Authorization: Basic <base64(api_key:api_secret)>`
tokenAuth:
type: apiKey
name: Authorization
in: header
description: >-
Token authentication using API key and secret. Format: `Authorization:
token api_key:api_secret`