---
title: "Contacts"
description: "Manage the people you email. Create and update contacts one at a time or import thousands in the background, with standard and custom field values that templates can reference as variables."
url: https://www.unitpost.com/docs/api/contacts
section: API reference
updated: 2026-07-31
---
# Contacts

## Contacts

> Manage the people you email. Create and update contacts one at a time or import thousands in the background, with standard and custom field values that templates can reference as variables.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/contacts.

## Operations

### `GET /api/v1/contacts`

List contacts

Retrieve a list of the contacts in your workspace, newest-first and cursor-paginated. Each row includes the contact's core fields and any custom field values. Use a contact's `id` (or email) with [Retrieve a contact](#get-contacts-id) for the full record, add contacts with [Create a contact](#post-contacts), or bring a list in bulk with [Start an async contact import](#post-contacts-imports). Requires the `contacts:read` capability.

### `POST /api/v1/contacts`

Create a contact

Add a single contact to your workspace. Set an `email` plus any standard or custom field values; custom fields must already exist (define them with [Create a custom contact field](#post-contact-fields)). Emails are unique per workspace, so creating one that already exists returns `409` — use [Update a contact](#patch-contacts-id) to change an existing contact, or [Start an async contact import](#post-contacts-imports) to add many at once. Requires the `contacts:write` capability.

### `GET /api/v1/contacts/{id}`

Retrieve a contact

Retrieve a single contact and all of its field values. The `{id}` path segment accepts either the contact's id or its email address, so you can look a contact up without storing our id. Change it with [Update a contact](#patch-contacts-id), or see which subscription topics it's opted into with [List a contact's topic subscriptions](#get-contacts-id-topics). Requires the `contacts:read` capability.

### `PATCH /api/v1/contacts/{id}`

Update a contact

Update a contact's standard or custom field values. Only the fields you send are changed; omitted fields are left as-is. The `{id}` accepts a contact id or email. To manage a contact's subscription preferences instead, use [Set a contact's topic preference](#post-contacts-id-topics). Requires the `contacts:write` capability.

### `DELETE /api/v1/contacts/{id}`

Delete a contact

Permanently delete a contact and its field values. This also removes the contact from every segment it belonged to. To stop mailing someone without deleting them, unsubscribe them from a topic with [Set a contact's topic preference](#post-contacts-id-topics) or add them to your [suppression list](#post-suppressions) instead. Requires the `contacts:write` capability.

### `GET /api/v1/contacts/imports`

List contact imports

Retrieve a list of your bulk contact-import jobs, newest-first and cursor-paginated. Each row is a reference to one import and its current progress. Start a new one with [Start an async contact import](#post-contacts-imports), or drill into a single job with [Retrieve a contact import](#get-contacts-imports-id). Requires the `contacts:read` capability.

### `POST /api/v1/contacts/imports`

Start an async contact import

Import a batch of contacts (up to 5,000 per request) in the background. The call returns immediately with an import job you poll for progress and per-row results — new contacts are created and existing ones (matched by email) are updated. Track it with [Retrieve a contact import](#get-contacts-imports-id), or see all your imports via [List contact imports](#get-contacts-imports). To add a single contact synchronously, use [Create a contact](#post-contacts). Requires the `contacts:write` capability.

### `GET /api/v1/contacts/imports/{id}`

Retrieve a contact import

Retrieve a bulk import job by `id` to check its status and per-row results — how many contacts were created, updated, or skipped, and why any rows failed. Poll this while an import runs. Start one with [Start an async contact import](#post-contacts-imports). Requires the `contacts:read` capability.

## Related

- [Contact fields](https://www.unitpost.com/docs/api/contact-fields): Define the typed custom attributes (text, number, date, …) your contacts carry — usable in templates as per-recipient variables.
- [Segments](https://www.unitpost.com/docs/api/segments): Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.
- [Topics](https://www.unitpost.com/docs/api/topics): Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically.