## List contacts

**get** `/v2/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.

### Query Parameters

- `contactType: optional "customer" or "lead" or "all"`

  Filter contacts by type. Defaults to "customer".

  - `"customer"`

  - `"lead"`

  - `"all"`

- `cursor: optional string`

  An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

- `limit: optional number`

  A limit on the number of objects to be returned, between 1 and 100.

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

  - `"2026-01-01.nova"`

  - `"2025-12-12.clover"`

### Returns

- `ContactList object { data, nextCursor, object }`

  - `data: array of Contact`

    Array of contacts

  - `nextCursor: string`

    Cursor for fetching the next page (cursor-based pagination)

  - `object: "list"`

    Object type identifier

    - `"list"`

### Example

```http
curl https://do.featurebase.app/v2/contacts \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "676f0f6765bdaa7d7d760f88",
      "name": "John Steezy",
      "object": "contact",
      "type": "customer",
      "commentsCreated": 0,
      "companies": [
        {
          "id": "507f1f77bcf86cd799439011",
          "companyId": "comp_12345",
          "companySize": 250,
          "createdAt": "2025-01-01T12:00:00.000Z",
          "industry": "Technology",
          "lastActivity": "2025-01-15T00:00:00.000Z",
          "linkedUsers": 15,
          "monthlySpend": 5000,
          "name": "Acme Inc",
          "object": "company",
          "plan": "enterprise",
          "updatedAt": "2025-01-10T15:30:00.000Z",
          "website": "https://acme.com",
          "customFields": {
            "location": "bar",
            "priority": "bar"
          }
        }
      ],
      "customFields": {
        "foo": "bar"
      },
      "description": "",
      "email": "john@example.com",
      "lastActivity": "2025-01-03T21:42:30.181Z",
      "locale": "en",
      "manuallyOptedOutFromChangelog": false,
      "organizationId": "5febde12dc56d60012d47db6",
      "postsCreated": 0,
      "profilePicture": "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png",
      "roles": [
        "string"
      ],
      "subscribedToChangelog": true,
      "userId": "676f0f673dbb299c8a4f3057",
      "verified": true
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list"
}
```