For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help CenterAPI KeysStatusSign In
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
  • Introduction
    • Getting started
  • Email API
  • Transactional SMS
  • Transactional WhatsApp
  • Marketing Campaigns
  • Contact Management
      • GETGet all the contacts
      • POSTCreate a contact
      • POSTCreate Contact via DOI (Double-Opt-In) Flow
      • GETGet a contact's details
      • DELDelete a contact
      • PUTUpdate a contact
      • GETGet email campaigns' statistics for a contact
      • GETGet all the segments
      • POSTExport contacts
      • POSTImport contacts
  • Events
    • GETGet events
    • POSTCreate an event
    • POSTCreate events in batch
  • Object Management
  • Accounts and Settings
  • Sales CRM
  • Conversations
  • Ecommerce
  • Loyalty
LogoLogo
Help CenterAPI KeysStatusSign In
Contact ManagementContacts

Get all the contacts

GET
https://api.brevo.com/v3/contacts
GET
/v3/contacts
1import { BrevoClient } from "@getbrevo/brevo";
2
3async function main() {
4    const client = new BrevoClient({
5        apiKey: "YOUR_API_KEY_HERE",
6    });
7    await client.contacts.getContacts({});
8}
9main();
1{
2  "contacts": [
3    {
4      "attributes": {
5        "ACTION_CODE": "17HH98CH",
6        "ADDRESS": "1 5th avenue",
7        "CITY": "New-York",
8        "CIV": "MS",
9        "DOB": "1986-05-02",
10        "FIRST_NAME": "Meg",
11        "IDENTIFICATION": "1-3RHQ-259",
12        "LAST_NAME": "Brennon",
13        "SMS": "33058407250",
14        "ZIP_CODE": "44300"
15      },
16      "createdAt": "2017-05-01T17:05:03Z",
17      "emailBlacklisted": true,
18      "id": 247,
19      "listIds": [
20        43,
21        58
22      ],
23      "modifiedAt": "2017-05-01T17:05:03Z",
24      "smsBlacklisted": true,
25      "whatsappBlacklisted": false,
26      "email": "contact1@example.com"
27    },
28    {
29      "attributes": {
30        "ACTION_CODE": "17HU765",
31        "ADDRESS": "5 Flower Street",
32        "CITY": "Seattle",
33        "CIV": "MS",
34        "DOB": "1980-09-11",
35        "FIRST_NAME": "Sophia",
36        "IDENTIFICATION": "1-78JS-432",
37        "LAST_NAME": "Press",
38        "SMS": "33058407248",
39        "ZIP_CODE": "44119"
40      },
41      "createdAt": "2017-05-01T17:05:03Z",
42      "emailBlacklisted": true,
43      "id": 245,
44      "listIds": [
45        43,
46        61,
47        58
48      ],
49      "modifiedAt": "2017-05-01T17:05:03Z",
50      "smsBlacklisted": false,
51      "whatsappBlacklisted": false,
52      "email": "33058407248@mailin-sms.com"
53    }
54  ],
55  "count": 3
56}
Retrieve all contacts from your Brevo account with support for pagination, filtering, and sorting. Results default to 50 contacts per page (maximum 1000) sorted in descending order of creation, and can be filtered by modification date, creation date, contact IDs (up to 20), list IDs, segment ID, or contact attributes using the equals operator. Note that either listIds or segmentId can be passed but not both simultaneously.
Was this page helpful?
Previous

Create a contact

Next
Built with

Retrieve all contacts from your Brevo account with support for pagination, filtering, and sorting. Results default to 50 contacts per page (maximum 1000) sorted in descending order of creation, and can be filtered by modification date, creation date, contact IDs (up to 20), list IDs, segment ID, or contact attributes using the equals operator. Note that either listIds or segmentId can be passed but not both simultaneously.

Authentication

api-keystring

The API key should be passed in the request headers as api-key for authentication.

Query parameters

limitlongOptional1-1000Defaults to 50
Number of documents per page
offsetlongOptionalDefaults to 0
Index of the first document of the page
modifiedSincestringOptional

Filter (urlencoded) the contacts modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result.

createdSincestringOptional

Filter (urlencoded) the contacts created after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result.

sortenumOptionalDefaults to desc

Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed

Allowed values:
idslist of longsOptional

Filter by a list of contact IDs. You can pass a maximum of 20 IDs. All elements must be integers.

segmentIdlongOptional>=1

Id of the segment. Either listIds or segmentId can be passed. Must be a positive integer (minimum value of 1).

listIdslist of longsOptional

Ids of the list. Either listIds or segmentId can be passed.

filterstringOptional
Filter the contacts on the basis of attributes. **Allowed operator: equals. For multiple-choice options, the filter will apply an AND condition between the options. For category attributes, the filter will work with both id and value. (e.g. filter=equals(FIRSTNAME,"Antoine"), filter=equals(B1, true), filter=equals(DOB, "1989-11-23"), filter=equals(GENDER, "1"), filter=equals(GENDER, "MALE"), filter=equals(COUNTRY,"USA, INDIA")**

Response

All contacts listed
contactslist of objects
countlong
Number of contacts

Errors

400
Bad Request Error
429
Too Many Requests Error

Filter the contacts on the basis of attributes. Allowed operator: equals. For multiple-choice options, the filter will apply an AND condition between the options. For category attributes, the filter will work with both id and value. (e.g. filter=equals(FIRSTNAME,“Antoine”), filter=equals(B1, true), filter=equals(DOB, “1989-11-23”), filter=equals(GENDER, “1”), filter=equals(GENDER, “MALE”), filter=equals(COUNTRY,“USA, INDIA”)