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 Authentication All requests must include a Bearer token in the Authorization header.
Query Parameters The page number to retrieve. Minimum value is 1.
Number of contacts to return per page. Minimum value is 1, maximum value is 100.
Filter contacts by type. Accepted values:
payee — a vendor managed by your businessbusiness — an independent Cleo business Filter contacts by status. Accepted values: active, archived, revoked. By default, the response includes contacts with active or archived status. Revoked contacts are only returned when you explicitly pass status=revoked.
Free-text search string. Matches against a contact’s display name or email address.
Response Returns a ContactList object.
The total number of contacts matching the query, across all pages.
Array of contact objects for the current page. Unique identifier for the contact. This is the same ID referenced as contact.id in payables.
The contact type: payee or business.
The contact’s current status: active, archived, or revoked.
The contact’s display name, if set.
List of email addresses associated with the contact. Always empty for business-type contacts.
Phone number for the contact. Always null for business-type contacts.
Indicates the allowed payment direction for this contact. One of: bidirectional, can_pay, can_be_paid, none.
Net payment terms in days, if configured.
Summary of the contact’s linked bank account, if any. Last four digits of the bank account number.
Tax information for the contact, if provided. Legal name associated with the tax ID.
Type of tax ID: ein or ssn.
Last four digits of the tax ID. The full tax ID is never returned.
Whether this contact can currently receive payments.
ISO 8601 timestamp of when the contact was created.
ISO 8601 timestamp of the most recent update, if any.
ISO 8601 timestamp of when the contact was archived, if applicable.
Example Request Example Response Use the search parameter to quickly locate a contact by name or email without needing to paginate through all results.
