COcounselhealth
/v1/user

Create a new user

Once a user completes your onboarding process, create a user within Counsel. We recommend passing an Idempotency-Key header to ensure that the user is created only once. Response replays are available for one day after the request completes.

Idempotency keys are best-effort and may be lost before the one-day window elapses. If a key is no longer available, a retry is executed as a new request rather than replayed, so do not rely on replays as a durable record of the original response. The API accepts a predefined ID as UUID for the user. If you do not pass an ID, the API will generate one for you.

Phone number must be unique per user. The API will throw if you try to create two users with the same number. On Sandbox, you can use +1 800 700 6000 as a test number which is permissioned to create multiple users.

Set the access_expires_at field to expire the user's access to the platform at a future date.

post/v1/user/

Request

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

Headers

Idempotency-Keystring
Example:550e8400-e29b-41d4-a716-446655440000

Optional idempotency key. Repeat requests with the same key and body return the original result.

Request body

dobstring required

date of birth in YYYY-MM-DD format (ISO 8601). Must be between 18 and 120 years old

phonestring nullable

US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000

sex_assigned_at_birth'Male' | 'Female' required
gender'Male' | 'Female' | 'Other' nullable
racestring[] nullable
emailstring email nullable

email address

metadataobject nullable

Custom key-value metadata for external users. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.

external_idstring nullable

Client-supplied stable identifier for this user, unique within your organization. Can be used in place of the Counsel user ID on GET/PATCH /v1/user/{id}.

id_verifiedboolean nullable

Whether this user's identity has been verified. Sending true requires your organization to be granted API identity verification by Counsel support; otherwise the request fails with 403.

access_expires_atstring date-time nullable

datetime in ISO 8601 format

first_namestring required

Legal given name(s)

last_namestring required

Legal family name

preferred_namestring nullable

Preferred name

idstring uuid

Example request

{
  "dob": "1990-01-01",
  "phone": "+18007006000",
  "addresses": [
    {
      "line1": "123 Main St",
      "line2": "Apt 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "12345"
    }
  ],
  "race": [
    "White",
    "Asian"
  ],
  "medical_profile": {
    "conditions": [
      "Diabetes"
    ],
    "medications": [
      "Metformin"
    ],
    "medication_allergies": [
      "Tylenol"
    ],
    "surgeries": [
      "Appendectomy"
    ],
    "family_history": [
      "Diabetes"
    ],
    "doctors": {
      "pcp_name": "Dr. Joe Doe",
      "specialist_types": [
        "Cardiologist"
      ]
    },
    "additional_details": {}
  },
  "email": "john.doe@example.com",
  "metadata": {
    "plan": "pro",
    "external_id": "1234567890"
  },
  "external_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "access_expires_at": "2030-01-01T00:00:00Z",
  "first_name": "John",
  "last_name": "Doe",
  "preferred_name": "Bob",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response

A fully onboarded API user with clinical profile and contact info.

idstring uuid required
created_atstring date-time required

datetime in ISO 8601 format

first_namestring required
last_namestring required
preferred_namestring nullable
dobstring required

date of birth in YYYY-MM-DD format (ISO 8601)

phonestring nullable

US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000

sex_assigned_at_birth'Male' | 'Female' required
gender'Male' | 'Female' | 'Other' nullable
racestring[] nullable
access_expires_atstring date-time nullable

datetime in ISO 8601 format

emailstring email nullable

email address

metadataobject nullable

Custom key-value metadata for external users. Max 25 keys, each value ≤ 1800 characters. Keys must be alphanumeric with underscores/hyphens only.

onboarded_atstring date-time nullable

datetime in ISO 8601 format

external_idstring nullable

Client-supplied stable identifier for this user, unique within your organization. Can be used in place of the Counsel user ID on GET/PATCH /v1/user/{id}.

id_verifiedboolean nullable

Whether this user's identity has been verified. Sending true requires your organization to be granted API identity verification by Counsel support; otherwise the request fails with 403.

Example response

{
  "created_at": "2030-01-01T00:00:00Z",
  "dob": "1990-01-01",
  "phone": "+18007006000",
  "addresses": [
    {
      "line1": "123 Main St",
      "line2": "Apt 2",
      "city": "San Francisco",
      "state": "CA",
      "zip": "12345"
    }
  ],
  "race": [
    "White",
    "Asian"
  ],
  "medical_profile": {
    "conditions": [
      "Diabetes"
    ],
    "medications": [
      "Metformin"
    ],
    "medication_allergies": [
      "Tylenol"
    ],
    "surgeries": [
      "Appendectomy"
    ],
    "family_history": [
      "Diabetes"
    ],
    "doctors": {
      "pcp_name": "Dr. Joe Doe",
      "specialist_types": [
        "Cardiologist"
      ]
    },
    "additional_details": {}
  },
  "access_expires_at": "2030-01-01T00:00:00Z",
  "email": "john.doe@example.com",
  "metadata": {
    "plan": "pro",
    "external_id": "1234567890"
  },
  "onboarded_at": "2030-01-01T00:00:00Z",
  "external_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

Changes

No recorded changes to this operation across all 1 revision of this API.