# Create or update a patient.

Use this endpoint to create a patient entity or update an existing one if it already exists. A patient is considered existing if it matches by social security number, or by the combination of firstName + lastName + dateOfBirth. The externalId is stored but never used to match an existing patient, since external folder numbers may be reassigned by the source software. The status tells the two outcomes apart: 201 when a new patient was created, 200 when an existing patient was matched and updated (the response body is that existing patient).

Endpoint: POST /patients
Version: 1.94.0
Security: oauth_auth_code

## Security:

  - `oauth_auth_code` (unknown)
    oauth2 scopes: write:patients

## Query parameters:

  - `expand[]` (array)

## Request body:

  - `application/json, application/ld+json, multipart/form-data` (unknown)
    The new Patient resource

## Request fields (application/json):

  - `firstName` (string | null, required)
    Patient first name.

  - `lastName` (string | null, required)
    Patient last name.

  - `languageSpoken` (string)
    Patient language.

  - `dateOfBirth` (string | null)
    Patient date of birth. Must be strictly before today.

  - `gender` (string | null)
    Patient gender.
    Enum: "female", "male", "unknown", "null"

  - `visibilityOption` (string | null)
    Enum: "shared", "private", "null"

  - `externalId` (string | null)
    Patient external app identifier (must be a string).

  - `externalCreatedAt` (string | null)
    Patient creation date from external app.

  - `email` (string | null)
    Patient email address.

  - `phone` (string | null)
    Patient phone number.
    Example: +33757590893

  - `maidenName` (string | null)
    Patient birth name, when it differs from the current legal name. Helps front-desk identity checks and the social-security link (the NIR is tied to the birth name). Not a dedup key: patient matching uses the NIR, or first name + last name + date of birth.
    Example: Moreau

  - `notes` (string | null)
    Free-text practice notes about the patient record.

  - `medicalAlert` (string | null)
    Critical medical information (allergies, medical risks) meant to be surfaced prominently on the patient record, not buried in notes.
    Example: Allergie pénicilline — risque hémorragique (AVK)

  - `referringPractitioner` (string | null)
    The internal practitioner designated as this patient's referring practitioner ("praticien référent"). Must belong to the same organization as the patient.
    Example: 123e4567-e89b-12d3-a456-426614174000

  - `treatingPhysician` (string | null)
    The patient's declared "médecin traitant" (GP registered with health insurance), as free text.
    Example: Dr Martin Schmidt

  - `anonymousCode` (string | null)
    Patient anonymous code.

  - `customPrompt` (string | null)
    Custom AI prompt instructions for this patient.

  - `socialSecurityNumber` (string | null)
    Patient French social security number (NIR, 15 characters).
    Example: 269054958815799

  - `streetAddress` (string | null)
    Patient street address.

  - `postalCode` (string | null)
    Patient postal code.

  - `city` (string | null)
    Patient city.

  - `recordNumber` (string | null)
    Patient record/folder number from the source software (e.g. Logosw).

  - `civility` (string | null)
    How the patient is addressed: mr | mrs | dr | pr | none. Null means nobody has declared it — clients fall back to the gender-derived form. Distinct from `gender`: a patient who is a doctor is addressed "Dr" whatever their gender.
    Enum: "mr", "mrs", "dr", "pr", "none", "null"

  - `birthGivenNames` (array | null)
    Civil-status given names in order, the first being the birth first name. Distinct from `firstName`, which stays the name the patient goes by. Populated from the Vitale card when available.
    Example: ["Marie","Claire"]

  - `birthPlaceCode` (string | null)
    INSEE (COG) code of the birthplace, an INS identity trait. Five characters — Corsican codes are 2A/2B and a birth abroad carries a 99xxx country code.
    Example: 75056

  - `insMatricule` (string | null)
    National health identity (INS) matricule. Distinct from `socialSecurityNumber`: the NIR is the number the patient is covered under and may belong to a parent, the INS identifies the patient themselves.
    Example: 269054958815799

  - `insOid` (string | null)
    OID qualifying the INS matricule: 1.2.250.1.213.1.4.8 for a NIR, 1.2.250.1.213.1.4.9 for a NIA (temporary identifier).
    Example: 1.2.250.1.213.1.4.8

## Response 200:

  - `200` (unknown)
    Existing patient matched and updated

## Response 200 fields (application/json):

  - `uuid` (string)
    Patient unique identifier.

  - `firstName` (string | null, required)
    Patient first name.

  - `lastName` (string | null, required)
    Patient last name.

  - `languageSpoken` (string)
    Patient language.

  - `createdAt` (string)
    Patient creation date.

  - `updatedAt` (string)
    Patient update date.

  - `synchronizedAt` (string | null)
    Patient synchronization date.

  - `dateOfBirth` (string | null)
    Patient date of birth. Must be strictly before today.

  - `gender` (string | null)
    Patient gender.
    Enum: "female", "male", "unknown", "null"

  - `user` (any)
    Patient author.

  - `user.uuid` (string)
    User unique identifier.

  - `user.firstName` (string | null, required)
    User first name.

  - `user.lastName` (string | null, required)
    User last name.

  - `user.isConventionne` (boolean)
    Whether the practitioner is "conventionne" (national administrative fact, sourced from the Ameli extract). Read-only.

  - `visibilityOption` (string | null)
    Enum: "shared", "private", "null"

  - `email` (string | null)
    Patient email address.

  - `phone` (string | null)
    Patient phone number.
    Example: +33757590893

  - `maidenName` (string | null)
    Patient birth name, when it differs from the current legal name. Helps front-desk identity checks and the social-security link (the NIR is tied to the birth name). Not a dedup key: patient matching uses the NIR, or first name + last name + date of birth.
    Example: Moreau

  - `notes` (string | null)
    Free-text practice notes about the patient record.

  - `medicalAlert` (string | null)
    Critical medical information (allergies, medical risks) meant to be surfaced prominently on the patient record, not buried in notes.
    Example: Allergie pénicilline — risque hémorragique (AVK)

  - `referringPractitioner` (any)
    The internal practitioner designated as this patient's referring practitioner ("praticien référent"). Must belong to the same organization as the patient.

  - `treatingPhysician` (string | null)
    The patient's declared "médecin traitant" (GP registered with health insurance), as free text.
    Example: Dr Martin Schmidt

  - `anonymousCode` (string | null)
    Patient anonymous code.

  - `streetAddress` (string | null)
    Patient street address.

  - `postalCode` (string | null)
    Patient postal code.

  - `city` (string | null)
    Patient city.

  - `recordNumber` (string | null)
    Patient record/folder number from the source software (e.g. Logosw).

  - `height` (integer | null)
    Patient height in centimeters.

  - `weight` (number | null)
    Patient weight in kilograms.

  - `civility` (string | null)
    How the patient is addressed: mr | mrs | dr | pr | none. Null means nobody has declared it — clients fall back to the gender-derived form. Distinct from `gender`: a patient who is a doctor is addressed "Dr" whatever their gender.
    Enum: "mr", "mrs", "dr", "pr", "none", "null"

  - `birthGivenNames` (array | null)
    Civil-status given names in order, the first being the birth first name. Distinct from `firstName`, which stays the name the patient goes by. Populated from the Vitale card when available.
    Example: ["Marie","Claire"]

  - `birthPlaceCode` (string | null)
    INSEE (COG) code of the birthplace, an INS identity trait. Five characters — Corsican codes are 2A/2B and a birth abroad carries a 99xxx country code.
    Example: 75056

  - `insMatricule` (string | null)
    National health identity (INS) matricule. Distinct from `socialSecurityNumber`: the NIR is the number the patient is covered under and may belong to a parent, the INS identifies the patient themselves.
    Example: 269054958815799

  - `insOid` (string | null)
    OID qualifying the INS matricule: 1.2.250.1.213.1.4.8 for a NIR, 1.2.250.1.213.1.4.9 for a NIA (temporary identifier).
    Example: 1.2.250.1.213.1.4.8

  - `insStatus` (string | null)
    INS qualification status: provisional | validated | retrieved | qualified. Only a qualified identity may be carried into an interoperable exchange (DMP, MSSanté, FSE). Read-only: the server derives it from the matricule's provenance — a manually entered matricule reads back as provisional.
    Enum: "provisional", "validated", "retrieved", "qualified", "null"

  - `insSource` (string | null)
    Where the INS came from: manual | vitale | insi | import. Confidence levels — only the INSi teleservice can qualify an identity. Read-only: a matricule written through this API is `manual` by construction.
    Enum: "manual", "vitale", "insi", "import", "null"

  - `insQualifiedAt` (string | null)
    When the identity first became qualified, i.e. when both RNIV determinants were met. Read-only: only the document check and the INSi teleservice can produce a qualification.

  - `insValidatedAt` (string | null)
    When the identity traits were last checked against an identity document. Read-only — set by the validation endpoint.

  - `insValidationDocumentType` (string | null)
    Which kind of high-trust identity document the traits were checked against. Read-only. The document number is never stored — the CNIL forbids it.
    Enum: "national_id_card", "passport", "residence_permit", "family_record_book", "birth_certificate_extract", "electronic_eidas_substantial", "electronic_eidas_high", "null"

  - `insMatriculeType` (string | null)
    What the INS matricule is, read from its OID: `nir` for a definitive identifier, `nia` for a provisional one still awaiting a NIR. Null when the record carries no INS, or an OID outside the two documented namespaces.
    Enum: "nir", "nia", "null"

## Response 200 fields (application/ld+json):

  - `@context` (any)

  - `@context.@vocab` (string, required)

  - `@context.hydra` (string, required)
    Enum: "http://www.w3.org/ns/hydra/core#"

  - `@id` (string, required)

  - `@type` (string, required)

## Response 201:

  - `201` (unknown)
    Patient resource created

## Response 201 fields (application/json):

  - `uuid` (string)
    Patient unique identifier.

  - `firstName` (string | null, required)
    Patient first name.

  - `lastName` (string | null, required)
    Patient last name.

  - `languageSpoken` (string)
    Patient language.

  - `createdAt` (string)
    Patient creation date.

  - `updatedAt` (string)
    Patient update date.

  - `synchronizedAt` (string | null)
    Patient synchronization date.

  - `dateOfBirth` (string | null)
    Patient date of birth. Must be strictly before today.

  - `gender` (string | null)
    Patient gender.
    Enum: "female", "male", "unknown", "null"

  - `user` (any)
    Patient author.

  - `user.uuid` (string)
    User unique identifier.

  - `user.firstName` (string | null, required)
    User first name.

  - `user.lastName` (string | null, required)
    User last name.

  - `user.isConventionne` (boolean)
    Whether the practitioner is "conventionne" (national administrative fact, sourced from the Ameli extract). Read-only.

  - `visibilityOption` (string | null)
    Enum: "shared", "private", "null"

  - `email` (string | null)
    Patient email address.

  - `phone` (string | null)
    Patient phone number.
    Example: +33757590893

  - `maidenName` (string | null)
    Patient birth name, when it differs from the current legal name. Helps front-desk identity checks and the social-security link (the NIR is tied to the birth name). Not a dedup key: patient matching uses the NIR, or first name + last name + date of birth.
    Example: Moreau

  - `notes` (string | null)
    Free-text practice notes about the patient record.

  - `medicalAlert` (string | null)
    Critical medical information (allergies, medical risks) meant to be surfaced prominently on the patient record, not buried in notes.
    Example: Allergie pénicilline — risque hémorragique (AVK)

  - `referringPractitioner` (any)
    The internal practitioner designated as this patient's referring practitioner ("praticien référent"). Must belong to the same organization as the patient.

  - `treatingPhysician` (string | null)
    The patient's declared "médecin traitant" (GP registered with health insurance), as free text.
    Example: Dr Martin Schmidt

  - `anonymousCode` (string | null)
    Patient anonymous code.

  - `streetAddress` (string | null)
    Patient street address.

  - `postalCode` (string | null)
    Patient postal code.

  - `city` (string | null)
    Patient city.

  - `recordNumber` (string | null)
    Patient record/folder number from the source software (e.g. Logosw).

  - `height` (integer | null)
    Patient height in centimeters.

  - `weight` (number | null)
    Patient weight in kilograms.

  - `civility` (string | null)
    How the patient is addressed: mr | mrs | dr | pr | none. Null means nobody has declared it — clients fall back to the gender-derived form. Distinct from `gender`: a patient who is a doctor is addressed "Dr" whatever their gender.
    Enum: "mr", "mrs", "dr", "pr", "none", "null"

  - `birthGivenNames` (array | null)
    Civil-status given names in order, the first being the birth first name. Distinct from `firstName`, which stays the name the patient goes by. Populated from the Vitale card when available.
    Example: ["Marie","Claire"]

  - `birthPlaceCode` (string | null)
    INSEE (COG) code of the birthplace, an INS identity trait. Five characters — Corsican codes are 2A/2B and a birth abroad carries a 99xxx country code.
    Example: 75056

  - `insMatricule` (string | null)
    National health identity (INS) matricule. Distinct from `socialSecurityNumber`: the NIR is the number the patient is covered under and may belong to a parent, the INS identifies the patient themselves.
    Example: 269054958815799

  - `insOid` (string | null)
    OID qualifying the INS matricule: 1.2.250.1.213.1.4.8 for a NIR, 1.2.250.1.213.1.4.9 for a NIA (temporary identifier).
    Example: 1.2.250.1.213.1.4.8

  - `insStatus` (string | null)
    INS qualification status: provisional | validated | retrieved | qualified. Only a qualified identity may be carried into an interoperable exchange (DMP, MSSanté, FSE). Read-only: the server derives it from the matricule's provenance — a manually entered matricule reads back as provisional.
    Enum: "provisional", "validated", "retrieved", "qualified", "null"

  - `insSource` (string | null)
    Where the INS came from: manual | vitale | insi | import. Confidence levels — only the INSi teleservice can qualify an identity. Read-only: a matricule written through this API is `manual` by construction.
    Enum: "manual", "vitale", "insi", "import", "null"

  - `insQualifiedAt` (string | null)
    When the identity first became qualified, i.e. when both RNIV determinants were met. Read-only: only the document check and the INSi teleservice can produce a qualification.

  - `insValidatedAt` (string | null)
    When the identity traits were last checked against an identity document. Read-only — set by the validation endpoint.

  - `insValidationDocumentType` (string | null)
    Which kind of high-trust identity document the traits were checked against. Read-only. The document number is never stored — the CNIL forbids it.
    Enum: "national_id_card", "passport", "residence_permit", "family_record_book", "birth_certificate_extract", "electronic_eidas_substantial", "electronic_eidas_high", "null"

  - `insMatriculeType` (string | null)
    What the INS matricule is, read from its OID: `nir` for a definitive identifier, `nia` for a provisional one still awaiting a NIR. Null when the record carries no INS, or an OID outside the two documented namespaces.
    Enum: "nir", "nia", "null"

## Response 201 fields (application/ld+json):

  - `@context` (any)

  - `@context.@vocab` (string, required)

  - `@context.hydra` (string, required)
    Enum: "http://www.w3.org/ns/hydra/core#"

  - `@id` (string, required)

  - `@type` (string, required)

## Response 400:

  - `400` (unknown)
    Invalid input

## Response 400 fields (application/ld+json):

  - `@context` (any)

  - `@context.@vocab` (string, required)

  - `@context.hydra` (string, required)
    Enum: "http://www.w3.org/ns/hydra/core#"

  - `@id` (string, required)

  - `@type` (string, required)

  - `title` (string | null)
    A short, human-readable summary of the problem.

  - `detail` (string | null)
    A human-readable explanation specific to this occurrence of the problem.

  - `status` (integer | null)

  - `instance` (string | null)
    A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

  - `type` (string)
    A URI reference that identifies the problem type

  - `description` (string | null)

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/ld+json):

  - `@context` (any)

  - `@context.@vocab` (string, required)

  - `@context.hydra` (string, required)
    Enum: "http://www.w3.org/ns/hydra/core#"

  - `@id` (string, required)

  - `@type` (string, required)

  - `title` (string | null)
    A short, human-readable summary of the problem.

  - `detail` (string | null)
    A human-readable explanation specific to this occurrence of the problem.

  - `status` (integer | null)

  - `instance` (string | null)
    A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

  - `type` (string)
    A URI reference that identifies the problem type

  - `description` (string | null)

## Response 422:

  - `422` (unknown)
    An error occurred

## Response 422 fields (application/ld+json):

  - `@context` (any)

  - `@context.@vocab` (string, required)

  - `@context.hydra` (string, required)
    Enum: "http://www.w3.org/ns/hydra/core#"

  - `@id` (string, required)

  - `@type` (string, required)

  - `status` (integer)

  - `violations` (array)

  - `violations.propertyPath` (string, required)
    The property path of the violation

  - `violations.message` (string, required)
    The message associated with the violation

  - `violations.code` (string)
    The code of the violation

  - `violations.hint` (string)
    An extra hint to understand the violation

  - `violations.payload` (object)
    The serialized payload of the violation

  - `detail` (string)

  - `description` (string)

  - `type` (string)

  - `title` (string | null)

  - `instance` (string | null)