---
title: "Create a project"
method: POST
path: "/projects"
tags: ["Projects"]
---

# Create a project

`POST /projects`

## Request

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

Create a project (matter or case), optionally linked to accounts and contacts. Visible to everyone in the organization unless access is restricted to specific members.

## Request body

- object
  - `name` string, required: Project name.
  - `access` union: Who can access the project. Defaults to everyone in the organization.
    - object
      - `type` 'everyone', required
    - object
      - `type` 'members', required
      - `memberIds` string[]: IDs of the users to add as members. The caller is always a member.
  - `accountIds` string[]: IDs of accounts to link. At most 100.
  - `contactIds` string[]: IDs of contacts to link. At most 100. A contact that belongs to an account can only be linked along with that account. Link both in the same call, or link the contact to a project with no accounts and its account is linked too.
  - `fields` object: Custom field values to set on the project, 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.

- Project
  - `id` string, required: The project ID.
  - `name` string, required: Project name.
  - `access` union, required: Who can see the project: everyone in the organization, or only its members.
    - EveryoneProjectAccess
      - `type` 'everyone', required
    - MembersProjectAccess
      - `type` 'members', required
      - `members` UserRef[], required: The people who can see the project.
        - `id` string, required: The user's ID.
        - `name` string, nullable, required: The user's full name, or null when it is unknown, as for someone who has left the organization.
        - `email` string, nullable, required: The user's email address, or null when it is unknown.
  - `accounts` AccountRef[], required: The accounts linked to the project. Direct links only: the accountId filter on the project list also matches projects linked through one of the account's contacts.
    - `type` 'account', required
    - `id` string, required: Its ID.
    - `name` string, required: The account name.
  - `contacts` ContactRef[], required: The contacts linked to the project.
    - `type` 'contact', required
    - `id` string, required: Its ID.
    - `name` string, required: The contact's first and last name, or an email address when it has no name.
  - `createdAt` string, date-time, required: When the project was created.
  - `updatedAt` string, date-time, required: When the project was last updated, including changes to its linked accounts and contacts. 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 projects (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/projects/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)