List contacts

Returns a paginated list of the contacts in your organization, oldest first. A contact is one person who has written to you. Filter by email or externalId to find a specific person, for example as the first step of exporting everything about them. With no filter you get every contact.

GET /v1/contacts

Authentication

Bearer token in the Authorization header. A read-only key is enough. See Authentication.

Authorization: Bearer rfl_live_...

Query parameters

Pagination

integer

default:"20"

Number of contacts per page. Range 1 to 100.

string

Opaque cursor from the previous response’s nextCursor. See Pagination.

Filters

string

Only return contacts with this email address. The match is exact and ignores case. It can return more than one contact, see Several contacts can share an email address.

string

Only return the contact with this externalId, your own user ID for the person. The match is exact. An externalId is unique, so you get zero or one contact.

Only a verified address is unique. When a visitor merely types an address, for example in the chat widget, Replyful creates a separate contact with email.verified: false. A lookup by email can therefore return several contacts. Export each one and judge whether it is the same person. A contact has exactly one email address. A person who has written from two addresses is two contacts, so look up each address. Erased contacts are not returned.

Response

Returns a list envelope containing Contact objects.

The Contact object

The fields a ticket’s requester has carry the same names here.

string

Unique identifier, usually prefixed with con_.

string

Always "contact".

string | null

Your own user ID for the contact, from the API or user identification. null if none.

string | null

First name, if known.

string | null

Last name, if known.

string | null

Contact display name.

object | null

The contact’s email address, or null if none is known.

Show properties

string

The email address.

boolean

true when ownership of the address is proven: verified by the contact or asserted by your own backend via user identification. false for an address the contact merely typed in.

string | null

The contact’s phone number as they typed it (for example in the chat handover), or null. Not normalised.

object | null

The company the contact belongs to, or null if none.

Show properties

string

Client ID.

string

Company name.

object[]

The data fields remembered on the contact, like a customer number. Empty when none are saved. Values saved on a single ticket are on that ticket instead.

Show properties

string

The field’s key, as processes mention it (customer_number).

string

The field’s name.

string

The value, written in the field’s format.

string

ticket or contact, as on a ticket.

string

handover when the visitor typed it in the handover form, ai when the AI read it in the chat.

string

ISO 8601 UTC timestamp of the latest save.

string | null

ISO 8601 UTC timestamp of when the contact accepted the privacy policy in the chat widget. null if they have not.

object | null

Set when Replyful stopped emailing this address. null otherwise.

Show properties

string

bounce (email could not be delivered) or complaint (the recipient marked an email as spam).

string

ISO 8601 UTC timestamp of when emailing stopped.

string

ISO 8601 UTC timestamp of contact creation.

string

ISO 8601 UTC timestamp of the most recent update.

Examples

Find contacts by email address

curl --get "https://api.replyful.com/v1/contacts" \
  -H "Authorization: Bearer rfl_live_..." \
  --data-urlencode "[email protected]"

const url = new URL("https://api.replyful.com/v1/contacts");
url.searchParams.set("email", "[email protected]");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` },
});
const { data } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "id": "con_9dKmT3xWq6bYrN8cJfA2e",
      "object": "contact",
      "externalId": "user_42",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "name": "Ada Lovelace",
      "email": { "email": "[email protected]", "verified": true },
      "phone": "+46 70 123 45 67",
      "client": { "id": "cli_4mHbW8xKq2eYd7Tf3pLz9", "name": "Analytical Engines Ltd" },
      "dataFields": [
        {
          "key": "customer_number",
          "name": "Customer number",
          "value": "C-10482",
          "savedOn": "contact",
          "source": "handover",
          "updatedAt": "2026-04-29T14:31:10Z"
        }
      ],
      "optedInAt": "2026-04-29T14:29:40Z",
      "suppression": null,
      "createdAt": "2026-03-02T08:15:00Z",
      "updatedAt": "2026-04-29T14:31:10Z"
    },
    {
      "id": "con_p3Tf8xWq2mKb6rNw7Yc4d",
      "object": "contact",
      "externalId": null,
      "firstName": null,
      "lastName": null,
      "name": null,
      "email": { "email": "[email protected]", "verified": false },
      "phone": null,
      "client": null,
      "dataFields": [],
      "optedInAt": "2026-05-11T10:02:00Z",
      "suppression": null,
      "createdAt": "2026-05-11T10:02:00Z",
      "updatedAt": "2026-05-11T10:04:30Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/contacts"
}

Find a contact by your own user ID

curl --get "https://api.replyful.com/v1/contacts" \
  -H "Authorization: Bearer rfl_live_..." \
  --data-urlencode "externalId=user_42"

Error responses

Status	`error.code`	When
`401`	`missing_api_key`	The `Authorization` header is absent.
`401`	`invalid_api_key`	The token is malformed, unknown, or archived.
`422`	`invalid_query_parameter`	A query parameter failed validation. The `param` field names the offender.
`422`	`invalid_cursor`	The `startingAfter` cursor could not be decoded.
`429`	`too_many_requests`	Rate limit exceeded. Honor `Retry-After`.

See Errors for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

Authentication

Query parameters

Filters

Response

The Contact object

Examples

Find contacts by email address

Find a contact by your own user ID

Error responses

​Authentication

​Query parameters

​Pagination

​Filters

​Several contacts can share an email address

​Response

​The Contact object

​Examples

​Find contacts by email address

​Find a contact by your own user ID

​Error responses

Authentication

Query parameters

Pagination

Filters

Several contacts can share an email address

Response

The Contact object

Examples

Find contacts by email address

Find a contact by your own user ID

Error responses