# Create a customer

Creates a new customer.
**Duplicate handling:**
- The system checks for duplicates by
**email OR phones**
 (any match on the same site).
- Without
`check_duplicate`
: if a duplicate is found, the existing customer is
**silently
updated**
 with the provided data and its ID is returned (HTTP 201).
- With
`check_duplicate: true`
: returns HTTP 409 if a duplicate is found.

Endpoint: POST /customers
Version: 1.6.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Request fields (application/json):

  - `gender` (string | null)
    Customer gender code. Use `GET /users/genders` for available values.
    Example: m

  - `first_name` (string | null)
    Example: Jean

  - `last_name` (string | null)
    Example: Dupont

  - `business_name` (string | null)
    Company name (for professional customers).

  - `email` (string, required)
    Customer email address. **Required.**
    Example: jean.dupont@example.com

  - `phones` (array | null)
    Phone numbers, one entry per slot (1-4). `slot` and `number` are required and
identifies the position; `type_id`, and `stop_sms` are optional.

  - `phones.slot` (integer, required)
    Phone slot (1-4).
    Example: 1

  - `phones.number` (string | null, required)
    Example: +33201010101

  - `phones.type_id` (integer | null)
    Phone type ID.

  - `phones.stop_sms` (boolean | null)
    SMS opt-out flag for this number.
    Example: false

  - `phone` (string | null)
    **Deprecated.** Use the `phones` array (slot 1).
    Example: +33201010101

  - `mobile_phone` (string | null)
    **Deprecated.** Use the `phones` array (slot 3).
    Example: +33601010101

  - `origin_id` (integer | null)
    Customer origin ID. Use `GET /customers/origins`.
    Example: 12

  - `assigned_user_id` (integer | null)
    Assigned negotiator (agent) ID.
    Example: 123456

  - `agency_id` (integer | null)
    Agency ID (within the authenticated site's scope).
    Example: 123456

  - `next_contact_at` (string | null)

  - `reference` (string | null)
    Internal reference of the customer.

  - `comments` (string | null)
    Internal notes

  - `current_situation_id` (integer | null)
    Current situation list value ID (liste 5).

  - `group` (integer | null)
    Customer group ID. Use `GET /customers/groups`.
    Example: 1

  - `groups` (array | null)
    Array of customer group IDs. Takes precedence over `group`.
    Example: [1,2]

  - `address` (object)
    Customer address block.

  - `address.street` (string | null)
    Example: 105 Rue Charles Nungesser

  - `address.complement` (string | null)

  - `address.postcode` (string | null)
    Example: 29490

  - `address.city` (string | null)
    Example: Guipavas

  - `address.country` (string | null)
    Country name or ISO 3166-1 alpha-2 code (e.g. `FR`).
    Example: FR

  - `address.residence` (string | null)

  - `address.latitude` (string | null)
    Example: 48.44145

  - `address.longitude` (string | null)
    Example: -4.415114

  - `newsletter` (boolean | null)
    Whether or not the customer agrees to receive communications by email.

  - `subscriptions` (array | null)
    Customer alert subscriptions. Each item controls a specific subscription channel.
    Example: [{"id":"proposition_bien","active":true},{"id":"abonne_newsletter","active":false}]

  - `subscriptions.id` (string, required)
    Available subscriptions: * `proposition_bien` - Accepts property proposals * `abonne_newsletter` - Accepts newsletters * `customers_partenaires` - Accepts partner emails
    Enum: "proposition_bien", "abonne_newsletter", "customers_partenaires"

  - `subscriptions.active` (boolean, required)
    Whether this subscription is active.

  - `rgpd_consent` (boolean | null)
    GDPR consent flag.

  - `color_id` (integer | null)
    Customer color ID.

  - `notary_id` (integer | null)
    Notary customer ID.
    Example: 123456789

  - `check_duplicate` (boolean | null)
    - `false`
 or omitted: silently updates an existing duplicate and returns its ID.
- `true`
: returns HTTP 409 when a duplicate is found.
    Example: true

  - `firstname` (string | null)
    **Deprecated.** Use `first_name`.

  - `lastname` (string | null)
    **Deprecated.** Use `last_name`.

  - `user_id` (integer | null)
    **Deprecated.** Use `assigned_user_id`.

  - `type_id` (integer | null)
    **Deprecated.** Use `current_situation_id`.

## Response 201:

  - `201` (unknown)
    Customer created (or updated if duplicate found without checkDuplicate)

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (integer)
    ID of the created or existing customer.

## Response 403:

  - `403` (unknown)
    Access denied. The error `code` is always `FORBIDDEN`; the `message` gives the cause:
- `You do not have permission to perform this action.`
 — the access does not

hold the API pack / right required by the endpoint.
- `Insufficient scope for this request.`
 — the resource targeted by the request

(user, customer, product, agency, transaction, ...) is outside the scope of

the authenticated access.
- `Access denied for this editor.`
 /
`Your IP address has been blocked.`
 —

editor or IP restriction.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 409:

  - `409` (unknown)
    Duplicate customer detected (only when `checkDuplicate: true`).

## Response 409 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 422:

  - `422` (unknown)
    Validation failed

## Response 422 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Enum: "VALIDATION_ERROR"

  - `error.message` (string)

  - `error.details` (array)

  - `error.details.field` (string)

  - `error.details.message` (string)

## Response 403 examples:

  - `Missing API pack / right` (unknown)

  - `Resource outside the scope of the access` (unknown)

