---
title: "Create Client"
method: POST
path: "/clients"
tags: ["Clients"]
---

# Create Client

`POST /clients`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/clients`
- Auth: HTTP bearer

Add a client to the contact book. The owner is the current user; an
Organization owner is accepted when the caller can edit that organization.
The mobile number is normalized to E.164 (+61…).

## Query parameters

- `include` string

## Request body

- ClientCreateModelAttributes: Flat attributes-adapter request body (Content-Type application/json). Attribute fields and relationships live directly under `data` (no nested `attributes` / `relationships` envelopes). Each relationship is a resource identifier object ({ id, type }). Equivalent JSON:API (nested) shape: `ClientCreateModel` sent as application/vnd.api+json.
  - `data` object, required
    - `name` string
    - `mobile` string: Australian mobile in any common format; normalized to E.164.
    - `email` string, nullable
    - `location` string, nullable
    - `user` object, nullable
      - `id` string
      - `type` 'user'
    - `owner` object: The owner (contractor) of this client — a User or an Organization the caller can edit. Defaults to the current user when omitted.
      - `id` string
      - `type` 'user' | 'organization'

## Response `201`

Created

- ClientsShowResponseAttributes: Single client response for Accept application/json (attributes adapter).
  - `data` ClientModelAttributes: Single client in attributes-adapter shape (Accept application/json). id, type, and attribute fields at top level; no nested attributes/relationships. The owner/user relationship keys may appear when include is used.
    - `id` string
    - `type` string
    - `name` string
    - `mobile` string, nullable
    - `email` string, nullable
    - `location` string, nullable
    - `tasks_count` integer
    - `last_task_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `owner` object: Present when include=owner
    - `user` object: Present when include=user
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/29c5c990d66e?raw)