---
title: "Contacts API Overview"
description: "Manage contact groups and contacts programmatically with the Bulkit Contacts API."
---

# Contacts API Overview

Bulkit Contacts API lets you retrieve contact groups, create contacts, create contacts in bulk, and delete contacts from your Bulkit account.

## Available endpoints

- `GET /api/v2/contacts/groups`
- `POST /api/v2/contacts`
- `POST /api/v2/contacts/bulk`
- `DELETE /api/v2/contacts/:id`

## Authentication

Contacts API uses standard Bearer authentication across all endpoints:

- **Bearer Token (Recommended)**: `Authorization: Bearer <your_api_token>`
- Legacy headers: `X-API-Key` and `X-API-Secret`
- URL query parameters (`?apikey=...`) for `GET` and `DELETE` requests where needed

## Current group behavior

Contacts currently support a single group assignment in the backend.

The API accepts `group_ids` for forward compatibility, but only one group is supported at a time.

If you send more than one group ID, Bulkit returns:

```json
{
  "status": "error",
  "message": "Only one group is supported for now"
}
```

## Custom metadata

The API accepts `custom_metadata` in the request shape for integration compatibility. At the moment, Bulkit accepts it but does not persist it in the contact record.