--- title: "Create a new customer" method: POST path: "/customers" tags: ["Customers"] --- # Create a new customer `POST /customers` Add a new customer account in the CareCloud platform. **What happens when a customer is created** - A customer record is created and its server-generated `customer_id` is returned. - One or more customer-partner relations are created automatically. The assignment depends on the project configuration: - If the project is configured for store-based partner assignment and `store_id` is set in `personal_information` - a single relation is created for the partner derived from the store. - If the project is not configured for store-based partner assignment - relations are created for all partners accessible to the authenticated API user. The `store_id`, if set, is still recorded on the customer account but does not determine partner assignment. - If called from the customer interface with `autologin=true`, the customer is logged in as part of the response. - If `referral_code` is provided and valid, a customer relation is created between the new customer and the referral code holder. The relation type used is determined by the referral campaign configuration. See [GET /customers/{customer_id}/related-customers](https://carecloud.readme.io/reference/getsubcustomerrelatedcustomers) to view the resulting relation. **Conditional requirements** - When `autologin` is `true`, `password` is required. - When `autologin` is `false`, `password` is optional. `autologin` is meaningful only when this endpoint is called from the customer interface. In the enterprise interface, `autologin=true` causes the password to be validated but does not log the customer in - the enterprise interface does not establish customer sessions. **Related operations** - [POST /customers/actions/set-partners](https://carecloud.readme.io/reference/postsubcustomersetpartners) - replace all partner assignments on a customer in a single call (enterprise interface only). - [POST /customers/actions/validate-customer-data](https://carecloud.readme.io/reference/postcustomersvalidatecustomerdata) - validate a referral code before submitting this request. ## Headers - `Accept-Language` string ## Request body - object - `customer` Customer, required — Basic information about a customer. - `customer_id` string — The unique ID of the customer. - `personal_information` PersonalInformation, required — Personal information of the customer. - `salutation` string — Customer's salutation. If it is not set in POST or PUT calls, it will be generated automatically. - `gender` 1 | 2 | 3 | 4 | 5, nullable — Gender of the customer *Possible values: 1 - Male / 2 - Female / 3 - Miss / 4 - Private / 5 - Other * - `first_name` string — First name of the customer. - `last_name` string — Last name of the customer. - `pre_nominals` string — Academic degrees, academic titles, other titles of customer placed before name. - `post_nominals` string — Academic degrees, academic titles, other titles of customer placed after name. - `birthdate` string, date — Customer's date of birth in ISO-8601 format (`YYYY-MM-DD`). - `email` string — Email of the customer. If you provide an email address, CareCloud validates its format and the validity of the domain. Here is the general regular expression that is used for validation: `^[-a-z0-9!#$%&'*+\\/=?^_`{|}~]+(\\.[-a-z0-9!#$%&'*+\\/=?^_`{|}~]+)*@([a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?\\.)+[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])$` - `phone` string — Phone number of the customer with international prefix (420000000000). - `language_id` string, required — The unique ID of the language by ISO 639-1 code. [GET /languages](https://carecloud.readme.io/reference/getlanguages) - `store_id` string — The unique ID of the original customer account store of registration. In case of customer update, the value can only be updated, not removed. When provided during customer registration and the project is configured for store-based partner assignment, the system derives the partner from the store and creates a single customer-partner relation. [GET /stores](https://carecloud.readme.io/reference/getstores) - `photo_url` string — URL address of the customer photo. If customer has no photo, this parameter is not send. - `address` Address — The Address Structure in the API defines the standardized format for representing addresses throughout the system. This resource ensures consistency and accuracy in capturing address details, facilitating seamless integration and data exchange. - `address1` string — Street name of the address. - `address2` string — Street number (Land registry number). - `address3` string — House number. - `address4` string — Next address data. - `address5` string — Next address data. - `address6` string — Next address data. - `address7` string — Next address data. - `zip` string — ZIP code. - `city` string — City. - `country_code` string — ISO code of the country. *Possible values de / gb / us / it / cz / etc* - `agreement` Agreement — Customer's consents. - `agreement_gtc` 0 | 1 | 2 — Consent to the Personal data processing. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set* - `agreement_profiling` 0 | 1 | 2 — Consent to the Profiling. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set* - `agreement_marketing_communication` 0 | 1 | 2 — Consent to the Marketing communication. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set* - `custom_agreements` CustomAgreements[] — Custom consent list. The list of consents is available in the [Consents resource](https://carecloud.readme.io/reference/getconsents) - `agreement_id` string, required — The unique ID of the consent in CareCloud from [consents](https://carecloud.readme.io/reference/getconsents) resource. - `agreement_value` 0 | 1 | 2, required — Value of the specific consent. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set* - `consents` Consents[] — The list of all customer consents. The list of consents is available in the [Consents resource](https://carecloud.readme.io/reference/getconsents). This parameter replaces the deprecated `agreement` parameter. If both parameters are provided, `consents` takes effect and `agreement` is ignored entirely. - `consent_id` string, required — The unique ID of the consent in CareCloud from [consents](https://carecloud.readme.io/reference/getconsents) resource. - `consent_value` 0 | 1 | 2, required — Value of the specific consent. *Possible values: 0 - no, consent canceled / 1 - yes, consent given / 2 - consent not set* - `last_change` string — Timestamp of the last change of the record. Format: `YYYY-MM-DD HH:MM:SS`. All times are in the local timezone. - `doi_email` string — Date and time of obtaining the customer's email consent (Double opt-in confirmation). *(YYYY-MM-DD HH:MM:SS)* - `doi_phone` string — Date and time of obtaining the customer's phone consent (Double opt-in confirmation). *(YYYY-MM-DD HH:MM:SS)* - `last_change` string — Date and time of the last change. *(YYYY-MM-DD HH:MM:SS)* - `state` 0 | 1 | 2 — State of the customer. *Possible values are: 0 - deleted / 1 - active / 2 - non active* - `customer_source` CustomerSourceRecord, required — Customer source. - `customer_source_record_id` string — The unique ID of the customer source record. - `customer_source_id` string, required — The unique ID of the customer source. It identifies the system where the customer belongs or the customer account was created. For the list of all available customer sources please look at: [GET /customer-sources](https://carecloud.readme.io/reference/getcustomersources). - `customer_id` string — The unique ID of the customer. [GET /customers](https://carecloud.readme.io/reference/getcustomers) - `external_id` string — The external ID of the customer in the external system. - `last_change` string — Timestamp of the last change. Format: `YYYY-MM-DD HH:MM:SS`. All times are in the local timezone. - `password` string, password — Password of the customer. Password must satisfy the following criteria and contain: At least one number (Example: 1 2 3); At least one uppercase letter (Example: A B C); Minimum lenght of password is 8 characters; Password is not part of a common password list (Example: abc123, password, 12345). If parameter `autologin=true`, password is required, otherwise is optional. - `autologin` boolean, required — If true, password is required and customer is logged in. Otherwise password is optional. - `social_network_credentials` SocialNetworkCredentials — This is the customer’s social media credentials. Special Rule for PUT Request with social network credentials: _Unlike typical HTTP PUT requests, the request will not erase existing data if parameters are missing. If you do not include the social media credentials in the PUT request, the existing credentials will remain unchanged._ - `social_network_id` string, required — The unique ID of the social network. - `social_network_token` string, required — Social network customer's token. - `property_records` PropertyRecord[] — List of customer property records. - `property_record_id` string — The unique ID of the property record. - `property_id` string, required — The unique ID of the property. - `property_name` string — Name of the property. - `property_value` union — Value of the property record. The format depends on the data type of the property. - **string** – a plain text value: ```json { "property_id": "p1_note", "property_value": "VIP customer" } ``` - **date** – a date string in `YYYY-MM-DD` format: ```json { "property_id": "p1_birth_date", "property_value": "1985-06-15" } ``` - **integer** – a whole number: ```json { "property_id": "p1_visit_count", "property_value": 42 } ``` - **float** – a decimal number: ```json { "property_id": "p1_average_spend", "property_value": 149.90 } ``` - **enum** – a single-item array containing a PropertyItem object: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 } ] } ``` - **multiselect** – a multi-item array of PropertyItem objects: ```json { "property_id": "p1_favourite_color", "property_value": [ { "id": "86e05affc7a7abefcd513ab400", "name": "Blue", "resource_record_id": null, "state": 1 }, { "id": "81eaeea13b8984a169c490a325", "name": "Green", "resource_record_id": null, "state": 1 } ] } ``` - **custom data type** – the format depends on the specific data type configuration. For example, a serialized JSON object: ```json { "property_id": "p1_address", "property_value": "{\"street\":\"Main St\",\"city\":\"Prague\"}" } ``` - string - number - integer - boolean - unknown[] - unknown - object - `last_change` string — Date and time of the last change. *(YYYY-MM-DD HH:MM:SS)* - `referral_code` string — Referral code of an existing customer who referred the new registrant. When provided, a customer relation is created between the new customer and the referral code holder after successful registration. This field is optional. ## Response `201` Created - object - `data` object - `customer_id` string — The unique ID of the customer. ## Other responses - `400` — Bad input parameter. The response body's `error.error_data.invalid_params[]` array lists the parameters that caused the failure, each carrying a `reason` code. See the `BadRequestErrorBody` schema for the generic reason taxonomy. Operations with domain-specific business rules document additional reasons at the operation level. - `401` — The client has invalid credentials or auth token. - `403` — The client does not exist or the client tried to access an unauthorized property or resource. - `404` — The resource was not found. - `405` — The resource does not support the specified HTTP method. - `429` — Too many requests - more than the resource limit. - `500` — Server is not working as expected. - `503` — Temporary state when the service is temporarily unavailable, overloaded or there is a maintenance window. --- [API](https://skmtc.net/crmcarecloud/apis/rest-api-reference.md) · [All operations](https://skmtc.net/crmcarecloud/apis/rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/crmcarecloud/rest-api-reference/revisions/329c06dbf8d9/schema)