--- title: "Update a user" method: PATCH path: "/v1/user/{userId}/" tags: ["/v1/user"] --- # Update a user `PATCH /v1/user/{userId}/` ## 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/{userId}/` - Auth: HTTP bearer Update a user's properties. If a field is not provided, it will not be updated. If you need to unset a field, pass an explicit null value. Only optional fields can be unset. Phone numbers can be updated for organizations that don't manage onboarding through Counsel. Updates may return 409 if your organization enforces phone-number uniqueness and the new number is already taken. To grant or extend a user's access (set `access_expires_at`), use `POST /v1/user/{userId}/enable` instead — this endpoint does not accept `access_expires_at`. This API will not deep-merge nested fields. Instead it operates on the top-level fields only. ```json { medical_profile: { conditions: ["condition1", "condition2"], medications: ["medication1", "medication2"], } } ``` This will replace the existing medical_profile object with the new one provided in the request body. ## Path parameters - `userId` string, required ## 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 - `phone` string, nullable: US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000 - `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 - `sex_assigned_at_birth` 'Male' | 'Female' - `gender` 'Male' | 'Female' | 'Other', nullable - `body_measurements` object, nullable - `height_ft` integer, required - `height_in` integer, required - `weight_lbs` integer, required - `race` string[], nullable - `medical_profile` object - `conditions` string[], required - `medications` string[], required - `medication_allergies` string[] - `surgeries` string[] - `family_history` string[] - `doctors` object - `pcp_name` string - `pcp_last_seen` 'Within the last year' | '1-2 years ago' | '2-5 years ago' | 'Longer than that or I do not remember' - `specialist_types` string[] - `substances` object - `tobacco` string[] - `alcohol` '0-4' | '5-8' | '9-14' | '15+' - `additional_details` object: Pass additional medical profile details - `email` string, email, nullable: email address - `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. - `first_name` string: Legal given name(s) - `last_name` string: Legal family name - `preferred_name` string, nullable: Preferred name ## Response `200` Default Response - union - object: A fully onboarded API user with clinical profile and contact info. - `id` string, uuid, required - `created_at` string, date-time, required: datetime in ISO 8601 format - `first_name` string, required - `last_name` string, required - `preferred_name` string, nullable - `dob` string, required: date of birth in YYYY-MM-DD format (ISO 8601) - `phone` string, nullable: US phone number. Supported formats: 8007006000, 800-700-6000, +1 800-700-6000, +18007006000, +1(800)7006000, (800)700-6000 - `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 - `sex_assigned_at_birth` 'Male' | 'Female', required - `gender` 'Male' | 'Female' | 'Other', nullable - `body_measurements` object, nullable - `height_ft` integer, required - `height_in` integer, required - `weight_lbs` integer, required - `race` string[], nullable - `medical_profile` object, required - `conditions` string[], required - `medications` string[], required - `medication_allergies` string[] - `surgeries` string[] - `family_history` string[] - `doctors` object - `pcp_name` string - `pcp_last_seen` 'Within the last year' | '1-2 years ago' | '2-5 years ago' | 'Longer than that or I do not remember' - `specialist_types` string[] - `substances` object - `tobacco` string[] - `alcohol` '0-4' | '5-8' | '9-14' | '15+' - `additional_details` object: Pass additional medical profile details - `access_expires_at` string, date-time, nullable: datetime in ISO 8601 format - `email` string, email, nullable: email address - `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` string, date-time, nullable: datetime in ISO 8601 format - `external_id` string, 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_verified` boolean, 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. - `consents` object, required: Consent state for this user. Fields are only populated for consents the organization tracks. - `hipaa_authorization` boolean: Whether this user has granted HIPAA authorization consent — i.e. waived their right to HIPAA privacy protections so that PHI can be shared back to your organization. Only present when the organization requires HIPAA authorization consent. When false on such an org, API responses redact HIPAA-gated fields and PHI-rich endpoints return 403. - 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)