Skip to main content

Try the live demo!

Search

Get Contacts

Requires the `contacts:read_all` permission.

GET /api/v1/contacts

Requires the contacts:read_all permission.

Authentication

Use an agent API key and secret.

Parameters

All parameters are query parameters. All parameters are optional.

Name Type Description
page integer Page number (defaults to 1) default: 1 minimum: 1
page_size integer Number of items per page (defaults to 30, max 500) default: 30 minimum: 1 maximum: 500
order string (enum) Sort direction (case-insensitive). Used only with order_by, defaults to ascending. enum: ["asc", "desc"]
order_by string (enum) Field to sort by, as model.field. Results are unordered when omitted. enum: ["users.email", "users.created_at", "users.updated_at"]
filters string 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.

All fields are optional.

Field Type Description
status string example: "success"
data object
data.results array of object
data.results[].id integer example: 163
data.results[].type string example: "contact"
data.results[].first_name string example: "Jane"
data.results[].last_name string example: ""
data.results[].email string (email) nullable: true example: "[email protected]"
data.results[].enabled boolean example: true
data.results[].avatar_url string nullable: true example: null
data.results[].created_at string (date-time) example: "2025-09-14T18:53:01.172243Z"
data.results[].updated_at string (date-time) example: "2025-09-14T18:53:01.172243Z"
data.results[].external_user_id string External identifier for the user in your own system nullable: true
data.results[].availability_status string (enum) enum: ["online", "away", "away_manual", "offline", "away_and_reassigning"] example: "offline"
data.total integer example: 39
data.per_page integer example: 100
data.total_pages integer example: 1
data.page integer example: 1

401

Unauthorized

Content type: application/json.

All fields are optional.

Field Type Description
status string example: "error"
message string Error message example: "Invalid request"
data unspecified Additional error data nullable: true
error_type string (enum) enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

403

Forbidden

Content type: application/json.

Response fields match the 401 response.

500

Internal server error

Content type: application/json.

Response fields match the 401 response.

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`

Was this article helpful?