# Managing Contacts via API

Create, read, update, and delete contacts programmatically

The Contacts API lets you programmatically create, retrieve, update, and delete contacts in your Mailnaptic account. This is the foundation for most integrations — syncing subscribers from your application, importing data from external systems, or building custom signup flows.

## Create a contact

Send a POST request to create a new contact. If a contact with the same email already exists, the record is updated (upsert behavior).

```
POST /api/v1/contacts

{
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "list_ids": [1, 3],
  "tags": ["website-signup", "trial"],
  "custom_fields": {
    "company": "Acme Inc",
    "plan": "pro"
  }
}
```

**Required fields:**

- `email` (string) — must be a valid email address.

**Optional fields:**

- `first_name`, `last_name` (string)
- `list_ids` (array of integers) — subscribe the contact to these lists.
- `tags` (array of strings) — attach tags. Tags are created automatically if they don't exist.
- `custom_fields` (object) — key-value pairs matching your organization's custom field slugs.

## Get a contact

```
GET /api/v1/contacts/:id
```

Returns the full contact record including email, name, status, tags, custom fields, list memberships, and timestamps.

## List contacts

```
GET /api/v1/contacts?page=1&per_page=50
```

Returns a paginated list of contacts. You can filter by:

| Parameter | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by status: `active`, `unsubscribed`, `bounced`, `complained` |
| `list_id` | integer | Only contacts in this list |
| `tag` | string | Only contacts with this tag |
| `search` | string | Search by email, first name, or last name |

## Update a contact

```
PUT /api/v1/contacts/:id

{
  "first_name": "Janet",
  "custom_fields": {
    "plan": "enterprise"
  },
  "tags": ["enterprise", "upgrade"]
}
```

Only the fields you include in the request body are updated. Omitted fields are left unchanged. Tags in the request are **added** to existing tags — they do not replace them.

## Delete a contact

```
DELETE /api/v1/contacts/:id
```

Permanently removes the contact and all associated data (tag mappings, list memberships, site events, frequency cap records, and consent logs). This is a **hard delete** for GDPR compliance and cannot be undone.

## Manage tags

You can also manage tags independently:

```
// Add tags
POST /api/v1/contacts/:id/tags
{"tags": ["vip", "high-value"]}

// Remove a tag
DELETE /api/v1/contacts/:id/tags/:tag_name
```

## Manage list memberships

```
// Subscribe to lists
POST /api/v1/contacts/:id/lists
{"list_ids": [2, 5]}

// Unsubscribe from a list
DELETE /api/v1/contacts/:id/lists/:list_id
```

## Error handling

Common errors when working with the Contacts API:

- `400` — Invalid email format or missing required fields.
- `403` — API key lacks `contacts:write` scope.
- `404` — Contact ID does not exist.
- `429` — Rate limit exceeded. Back off and retry.

## Batch operations

For importing large numbers of contacts, use the CSV import feature in the Mailnaptic UI or send multiple API requests with reasonable concurrency (5-10 parallel requests). Mailnaptic's upsert behavior ensures no duplicates are created.

> **Tip:** After creating or updating contacts via the API, they are immediately available for segmentation and campaign targeting — no delay or sync required.
