> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Contacts — GET /v1/contacts Endpoint Reference

> GET /v1/contacts returns a paginated list of contacts. Filter by type, status, or free-text search. Revoked contacts are excluded by default.

Use this endpoint to retrieve all contacts associated with your account. Results are paginated and can be filtered by contact type, status, or a free-text search string matching name or email. Unless you explicitly filter by `status=revoked`, revoked contacts are excluded from the response.

## Base URL

```
GET https://api.cleo-pay.com/v1/contacts
```

## Authentication

All requests must include a Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer <token>
```

## Query Parameters

<ParamField query="page" type="number" default="1">
  The page number to retrieve. Minimum value is `1`.
</ParamField>

<ParamField query="pageSize" type="number" default="25">
  Number of contacts to return per page. Minimum value is `1`, maximum value is `100`.
</ParamField>

<ParamField query="type" type="ContactType">
  Filter contacts by type. Accepted values:

  * `payee` — a vendor managed by your business
  * `business` — an independent Cleo business
</ParamField>

<ParamField query="status" type="ContactStatus">
  Filter contacts by status. Accepted values: `active`, `archived`, `revoked`.

  <Note>
    By default, the response includes contacts with `active` or `archived` status. Revoked contacts are only returned when you explicitly pass `status=revoked`.
  </Note>
</ParamField>

<ParamField query="search" type="string">
  Free-text search string. Matches against a contact's display name or email address.
</ParamField>

## Response

Returns a `ContactList` object.

<ResponseField name="totalCount" type="number">
  The total number of contacts matching the query, across all pages.
</ResponseField>

<ResponseField name="items" type="Contact[]">
  Array of contact objects for the current page.

  <Expandable title="Contact fields">
    <ResponseField name="id" type="string">
      Unique identifier for the contact. This is the same ID referenced as `contact.id` in payables.
    </ResponseField>

    <ResponseField name="type" type="string">
      The contact type: `payee` or `business`.
    </ResponseField>

    <ResponseField name="status" type="string">
      The contact's current status: `active`, `archived`, or `revoked`.
    </ResponseField>

    <ResponseField name="displayName" type="string | null">
      The contact's display name, if set.
    </ResponseField>

    <ResponseField name="emails" type="string[]">
      List of email addresses associated with the contact. Always empty for `business`-type contacts.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      Phone number for the contact. Always `null` for `business`-type contacts.
    </ResponseField>

    <ResponseField name="paymentDirection" type="string">
      Indicates the allowed payment direction for this contact. One of: `bidirectional`, `can_pay`, `can_be_paid`, `none`.
    </ResponseField>

    <ResponseField name="netTerms" type="number | null">
      Net payment terms in days, if configured.
    </ResponseField>

    <ResponseField name="bankAccount" type="object | null">
      Summary of the contact's linked bank account, if any.

      <Expandable title="bankAccount fields">
        <ResponseField name="last4" type="string">
          Last four digits of the bank account number.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="taxInfo" type="object | null">
      Tax information for the contact, if provided.

      <Expandable title="taxInfo fields">
        <ResponseField name="legalName" type="string | null">
          Legal name associated with the tax ID.
        </ResponseField>

        <ResponseField name="taxIdType" type="string | null">
          Type of tax ID: `ein` or `ssn`.
        </ResponseField>

        <ResponseField name="taxIdMask" type="string | null">
          Last four digits of the tax ID. The full tax ID is never returned.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="paymentReady" type="boolean">
      Whether this contact can currently receive payments.
    </ResponseField>

    <ResponseField name="createdAt" type="datetime">
      ISO 8601 timestamp of when the contact was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="datetime | null">
      ISO 8601 timestamp of the most recent update, if any.
    </ResponseField>

    <ResponseField name="archivedAt" type="datetime | null">
      ISO 8601 timestamp of when the contact was archived, if applicable.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```bash curl theme={null}
curl --request GET \
  --url "https://api.cleo-pay.com/v1/contacts?page=1&pageSize=25&type=payee&status=active" \
  --header "Authorization: Bearer <token>"
```

## Example Response

```json 200 theme={null}
{
  "totalCount": 2,
  "items": [
    {
      "id": "cnt_01hq1z2k3m4n5p6q7r8s9t0u",
      "type": "payee",
      "status": "active",
      "displayName": "Acme Supplies LLC",
      "emails": ["billing@acmesupplies.com"],
      "phone": "+15550001234",
      "paymentDirection": "can_be_paid",
      "netTerms": 30,
      "bankAccount": {
        "last4": "7890"
      },
      "taxInfo": {
        "legalName": "Acme Supplies LLC",
        "taxIdType": "ein",
        "taxIdMask": "1234"
      },
      "paymentReady": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-03-01T08:00:00Z",
      "archivedAt": null
    },
    {
      "id": "cnt_02ab3c4d5e6f7g8h9i0j1k2l",
      "type": "payee",
      "status": "active",
      "displayName": "Global Freight Partners",
      "emails": ["ap@globalfreight.com", "invoices@globalfreight.com"],
      "phone": null,
      "paymentDirection": "can_be_paid",
      "netTerms": null,
      "bankAccount": null,
      "taxInfo": null,
      "paymentReady": false,
      "createdAt": "2024-02-20T14:45:00Z",
      "updatedAt": null,
      "archivedAt": null
    }
  ]
}
```

<Tip>
  Use the `search` parameter to quickly locate a contact by name or email without needing to paginate through all results.
</Tip>