---
title: "Create an account"
method: POST
path: "/accounts"
tags: ["Accounts"]
---

# Create an account

`POST /accounts`

## Request

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

Create an account (a client organization), optionally linked to projects. A contact joins an account through its accountId.

## Request body

- object
  - `name` string, required: Account name.
  - `projectIds` string[]: IDs of projects to link. At most 100. Each project must be one you can edit.
  - `fields` object: Custom field values to set on the account, 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.

- Account
  - `id` string, required: The account ID.
  - `name` string, required: Account name.
  - `contactCount` integer, required: How many contacts belong to the account. List them by filtering contacts by accountId.
  - `projectCount` integer, required: How many projects you can see are linked directly to the account. Filtering projects by accountId also returns the projects linked through the account's contacts. Linking or unlinking a project doesn't change the account's updatedAt.
  - `createdAt` string, date-time, required: When the account was created.
  - `updatedAt` string, date-time, required: When the account itself was last updated. Contacts joining or leaving the account, 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 accounts (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.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

## Changes

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

[Operation history](https://skmtc.dev/parley/apis/parley-api/changes/accounts/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)