---
search:
  tags:
    - Contacts
    - POST
seo:
  description: >-
    BillionSend extension: returns up to 1000 contacts by id or by email address
    in… Reference for the POST /contacts/batch/get endpoint in the BillionSend
    API.
sidebar:
  label: Read contacts in bulk
  badge: POST
title: Read contacts in bulk
type: openapi-operation
---
BillionSend extension: returns up to 1000 contacts by id or by email address in one request, in request order, optionally with their properties and topic subscriptions. Entries that match no contact are listed under `missing` instead of failing the call. One call counts as one request against the rate limit.

`POST /contacts/batch/get`

**Request body** (`application/json`, required)

- `contacts` (object[], required) — Up to 1000 contacts, each by id or by email address (matched case-insensitively)
- `include` (string[]) — Facets to attach to every contact returned: properties and/or topics

Request body example:

```json
{
  "contacts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "user@example.com"
    }
  ],
  "include": [
    "properties"
  ]
}
```

**Responses**

- `200` — The contacts found, and the entries that matched none
- `401` — Missing, malformed, unknown or revoked API key
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "object": "list",
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "created_at": "string",
      "unsubscribed": true,
      "unsubscribed_domains": [
        {
          "domain_id": "b2f7354f-b74d-4332-ab10-1a5e3c56466c",
          "name": "string",
          "unsubscribed_at": "string"
        }
      ],
      "verification_status": "valid",
      "verified_at": "string",
      "properties": {
        "property1": {
          "type": "string",
          "value": "string"
        },
        "property2": {
          "type": "string",
          "value": "string"
        }
      },
      "topics": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "description": "string",
          "subscription": "opt_in",
          "explicit": true,
          "visibility": "public"
        }
      ],
      "object": "contact"
    }
  ],
  "missing": [
    {
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "email": "string"
    }
  ]
}
```
