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

# Import contacts in bulk

> Import up to 10,000 contacts in one request.

`POST /v1/contacts/bulk` imports 1 to 10,000 contacts and answers when it's done, with counts and one result per contact. Every plan can use it.

Contacts are matched to existing ones by phone, then email. By default, only empty fields on a match are filled. Send `"overwriteExisting": true` to overwrite filled ones.

`tagIds` adds tags to every imported contact. Every id must be a tag in the workspace, or the request gets a `400` listing the unknown ids and nothing is imported. The response's `tagsAttached` counts the tag links added. `tagAttachError` is `true` when the contacts imported but adding the tags failed.

The request body can be up to 16 MB, which is about 10,000 typical contacts. A larger body gets a `413`.

* `dnd: true` turns Do Not Disturb on.
* Bulk import never turns DND off: `dnd: false` is ignored. Use [update](/api-reference/contacts/update) for that.
* Custom field values use the field's id: `"customFields": [{ "fieldId": "...", "value": "Website" }]`.

```bash theme={null}
curl -X POST "https://api.nedzo.ai/v1/contacts/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "workspaceId": "789e4567-e89b-12d3-a456-426614174000", "contacts": [{ "firstName": "Ana", "phone": "+14155551234" }, { "email": "bo@example.com", "dnd": true }] }'
```

```json Response theme={null}
{ "total": 2, "created": 2, "updated": 0, "skipped": 0, "errors": 0, "tagsAttached": 0, "tagAttachError": false, "results": [{ "index": 0, "status": "created", "contactId": "123e4567-e89b-12d3-a456-426614174000", "reason": null }, { "index": 1, "status": "created", "contactId": "223e4567-e89b-12d3-a456-426614174000", "reason": null }] }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.