---
title: "Create intake"
method: POST
path: "/v1/intakes"
tags: ["Intakes"]
---

# Create intake

`POST /v1/intakes`

## Request

- Base URL: `https://api.briefgate.dev`
- URL: `https://api.briefgate.dev/v1/intakes`
- Auth: HTTP bearer

Create a new client intake. If `send` is true (the default), the client receives an invite email immediately and the intake moves to `sent`. If `send` is false, the intake stays as `draft` until POST /v1/intakes/:id/send is called.

Supply an `Idempotency-Key` header (max 128 chars) to make this operation safe to retry — duplicate requests within 24 hours return the original response.

## Headers

- `Idempotency-Key` string

## Request body

- CreateIntake
  - `project_name` string, required
  - `client` object, required
    - `email` string, email, required
    - `name` string, required
    - `phone` string
    - `language` 'cs' | 'sk' | 'pl' | 'de' | 'es' | 'en'
    - `timezone` string
    - `also_notify` object[]
      - `email` string, email, required
      - `name` string
  - `due_date` string
  - `branding` object
    - `logo_url` string, uri
    - `accent_color` string
    - `sender_name` string
    - `reply_to` string, email
  - `client_brief` string
  - `chase_schedule` 'default' | 'gentle' | 'aggressive' | 'custom' | 'off'
  - `chase_interval` integer
  - `chase_interval_unit` 'minutes' | 'hours' | 'days'
  - `respect_quiet_hours` boolean
  - `max_reminders` union
    - integer
    - 'unlimited'
  - `chase_at_time` string
  - `email_copy` object
    - `invite_subject` string
    - `invite_intro` string
    - `reminder_subject` string
    - `reminder_intro` string
  - `items` object[]: Item definitions. Required (at least one) unless `template` is set, in which case it may be omitted or empty — every item then comes from the template. With `template`, items here merge with the template's own by key, `items` winning on a clash.
    - `key` string, required
    - `type` 'text' | 'longtext' | 'file' | 'file_list' | 'image' | 'color_list' | 'select' | 'multiselect' | 'boolean' | 'url' | 'secret' | 'structured', required
    - `assignee` 'client' | 'owner'
    - `label` string, required
    - `help` string
    - `required` boolean
    - `constraints` object
      - `formats` string[]
      - `min_width` integer
      - `min_height` integer
      - `max_width` integer
      - `max_height` integer
      - `max_bytes` integer
      - `min_chars` integer
      - `max_chars` integer
      - `min_count` integer
      - `max_count` integer
      - `transparent_background` boolean
    - `schema` object
    - `options` object[]
      - `value` string, required
      - `label` string, required
    - `pattern` string
    - `proposed` object
      - `value` union, required
        - string
        - string[]
      - `rationale` string
  - `template` string: Slug of a saved template (GET/POST /v1/templates). Template items are merged with `items` above by key, with `items` winning on a clash. A template can also carry every other setting below (chase cadence, retention, branding, folder, ...) as defaults: such a setting applies only where this request body itself leaves the matching field unset — anything the request sets explicitly always wins over the template, field by field.
  - `auto_approve_hours` integer
  - `retention` object
    - `mode` 'days' | 'on_delivery'
    - `days` integer
    - `anonymize` boolean
  - `folder_id` string
  - `send` boolean

## Response `201`

Intake created

- object
  - `intake_id` string, required
  - `portal_url` string, uri, required
  - `status` 'draft' | 'sent', required
  - `items` object[], required
    - `key` string
    - `status` 'pending'
  - `follow_up` object, required: How to learn the intake is done — see the Webhooks guide and get_intake_status.
    - `recommended` 'webhook' | 'schedule'
    - `reason` string
    - `webhook` object
      - `active_endpoints` integer
      - `events` string[]
      - `register_with` string
    - `schedule` object
      - `check_with` string
      - `every_hours` integer
      - `until` string, date-time
  - `invitation_sent` boolean: Present and false only when an invitation limit was hit — the hourly one, or the daily one a plan may carry (`invites_per_day` in /pricing.json); the intake was created as a draft instead.
  - `note` string: Present alongside invitation_sent: false, explaining what to do next.

## Other responses

- `400`: Invalid request — malformed body or query parameters
- `401`: Missing or invalid API key
- `402`: Quota exceeded or plan upgrade required
- `422`: Validation error — the body shape is correct but values are invalid
- `429`: Rate limit exceeded

---

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