---
title: "Create a new user that will go through the Counsel onboarding flow"
method: POST
path: "/v1/user/draft/"
tags: ["/v1/user"]
---

# Create a new user that will go through the Counsel onboarding flow

`POST /v1/user/draft/`

## Request

- Base URL: `https://api.counselhealth.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.counselhealth.com/v1/user/draft/`
- Auth: HTTP bearer

Create a new "draft" user that will go through the onboarding flow within Counsel.

    This API is only available if the organization has enabled the onboarding flow. Contact your Counsel representative to enable this feature.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `dob` string: date of birth in YYYY-MM-DD format (ISO 8601). Must be between 18 and 120 years old
  - `sex_assigned_at_birth` 'Male' | 'Female'
  - `gender` 'Male' | 'Female' | 'Other'
  - `body_measurements` object, nullable
    - `height_ft` integer, required
    - `height_in` integer, required
    - `weight_lbs` integer, required
  - `email` string, email: email address
  - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC': US state abbreviation
  - `metadata` object, nullable: Custom key-value metadata for external users. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.
  - `external_id` string, nullable: Client-supplied stable identifier for this user, unique within your organization. Carried over to the onboarded user when the draft converts.
  - `id_verified` boolean, nullable: Whether this user's identity has been verified. Persists into the full user record when the draft converts. Sending `true` requires your organization to be granted API identity verification by Counsel support; otherwise the request fails with 403.
  - `addresses` object[], nullable
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC', required: US state abbreviation
    - `zip` string, required: US zip code with optional 4 digit extension. Supported formats: 12345, 12345-1234
    - `metadata` object
      - `is_primary` boolean
  - `first_name` string: Legal given name(s)
  - `last_name` string: Legal family name
  - `preferred_name` string, nullable: Preferred name
  - `id` string, uuid
  - `unconfirmed_phone_number` string: US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000

## Response `200`

A partially-created user still going through onboarding. Used if we need to handle consents and onboarding within Counsel. Converts to a user once onboarding completes.

- object: A partially-created user still going through onboarding. Used if we need to handle consents and onboarding within Counsel. Converts to a user once onboarding completes.
  - `id` string, uuid, required
  - `first_name` string
  - `last_name` string
  - `preferred_name` string, nullable
  - `dob` string: date of birth in YYYY-MM-DD format (ISO 8601)
  - `sex_assigned_at_birth` 'Male' | 'Female'
  - `gender` 'Male' | 'Female' | 'Other'
  - `body_measurements` object, nullable
    - `height_ft` integer, required
    - `height_in` integer, required
    - `weight_lbs` integer, required
  - `email` string, email: email address
  - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC': US state abbreviation
  - `created_at` string, date-time, required: datetime in ISO 8601 format
  - `metadata` object, nullable: Custom key-value metadata for external users. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.
  - `onboarded_at` unknown
  - `external_id` string, nullable: Client-supplied stable identifier for this user, unique within your organization. Carried over to the onboarded user when the draft converts.
  - `id_verified` boolean, nullable: Whether this user's identity has been verified. Persists into the full user record when the draft converts. Sending `true` requires your organization to be granted API identity verification by Counsel support; otherwise the request fails with 403.
  - `addresses` object[], nullable
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC', required: US state abbreviation
    - `zip` string, required: US zip code with optional 4 digit extension. Supported formats: 12345, 12345-1234
    - `metadata` object
      - `is_primary` boolean

## Other responses

- `400`: 400 error with a machine-readable `code` for client branching.
- `401`: Standard error body returned for non-2xx responses.
- `403`: Standard error body returned for non-2xx responses.
- `404`: Standard error body returned for non-2xx responses.
- `409`: Standard error body returned for non-2xx responses.
- `413`: Standard error body returned for non-2xx responses.
- `429`: Standard error body returned for non-2xx responses.
- `500`: Standard error body returned for non-2xx responses.
- `502`: Default Response
- `503`: Default Response
- `504`: Default Response

---

[API](https://skmtc.dev/counselhealth/apis/counsel-api.md) - [All operations](https://skmtc.dev/counselhealth/apis/counsel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/counselhealth/apis/counsel-api/revisions/4110a89127e8?raw)