---
title: "Create a contact"
method: POST
path: "/contacts"
tags: ["Contacts"]
---

# Create a contact

`POST /contacts`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/contacts`
- Auth: HTTP bearer

Create a contact (a person), optionally belonging to an account and linked to projects. An email address can belong to only one contact, so a second contact with the same address returns 409 EMAIL_TAKEN.

## Request body

- object
  - `firstName` string, required: First name.
  - `lastName` string, required: Last name.
  - `accountId` string: ID of the account the contact belongs to.
  - `emails` string[]: The email address, as a list. A contact has at most one address for now, and an address can belong to only one contact.
  - `projectIds` string[]: IDs of projects to link. At most 100. Each project must be one you can edit. If the contact belongs to an account, that account must be linked to each project too; a project with no accounts gets it linked along with the contact.
  - `fields` object: Custom field values to set on the contact, keyed by field name or ID. A value replaces the current one, null clears it, and fields you don't mention are left alone. Each value must match its field's type: a string for text, long_text, email, url, single_select (one of the field's options), and user (the id of an active user in the organization); a number; true or false; an ISO 8601 date-time or YYYY-MM-DD date; a list of strings for collection ([] clears it); or { streetAddress, cityTown, state, country } for address. At most 50 fields.

## Response `201`

Created.

- Contact
  - `id` string, required: The contact ID.
  - `firstName` string, required: First name. Empty for some contacts created from email.
  - `lastName` string, required: Last name. Empty for some contacts created from email.
  - `emails` string[], required: Email addresses, lowercased. A contact has at most one address for now.
  - `account` AccountRef, required: The account's type, ID, and name.
    - `type` 'account', required
    - `id` string, required: Its ID.
    - `name` string, required: The account name.
  - `projectCount` integer, required: How many projects you can see are linked to the contact. List them by filtering projects by contactId. Linking or unlinking a project doesn't change the contact's updatedAt.
  - `createdAt` string, date-time, required: When the contact was created.
  - `updatedAt` string, date-time, required: When the contact was last updated, including changes to its email address. Links to projects and field value changes do not change it.
  - `fields` object, required: Custom field values, keyed by field name, with a key for every field defined for contacts (null when unset). The value's shape follows the field's type.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE, LINK_CONFLICT, INVALID_FIELD_VALUES.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `409`: The request conflicts with the current state. EMAIL_TAKEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

## Changes

- **2026-11-02** `6b78aeee07bc`: 2 breaking
  - added the pattern `^[^\p{Cc}\p{Bidi_Control}]*$` to the request property `firstName`
  - added the pattern `^[^\p{Cc}\p{Bidi_Control}]*$` to the request property `lastName`

[Operation history](https://skmtc.dev/parley/apis/parley-api/changes/contacts/post.md)

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)