# List contacts

Returns a list of contacts (customers and leads) in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of contacts to return (1-100, default 10)
- cursor - Cursor from previous response for pagination
- contactType - Filter by contact type: "customer" (default), "lead", or "all"

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of contact objects
- nextCursor - Cursor for the next page, or null if no more results

### Contact Object

Each contact includes:
- id - Unique contact identifier
- userId - External user ID from SSO (if set)
- email - Contact email address
- name - Contact display name
- profilePicture - Profile picture URL
- type - Contact type ("customer" or "lead")
- companies - Array of companies the contact belongs to
- customFields - Custom field values
- postsCreated - Number of posts created
- commentsCreated - Number of comments created
- lastActivity - Last activity timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "676f0f6765bdaa7d7d760f88",
      "email": "john@example.com",
      "name": "John Doe",
      "type": "customer",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

Endpoint: GET /v2/contacts
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Query parameters:

  - `limit` (integer)
    A limit on the number of objects to be returned, between 1 and 100.
    Example: 10

  - `cursor` (string)
    An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.
    Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"

  - `contactType` (string)
    Filter contacts by type. Defaults to "customer".
    Enum: "customer", "lead", "all"

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "list"

  - `data` (array, required)
    Array of contacts
    Example: []

  - `nextCursor` (string,null, required)
    Cursor for fetching the next page (cursor-based pagination)
    Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_cursor"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400