---
title: "Create a new customer for Flow workflows"
method: POST
path: "/entities/{entityDID}/flow/customers"
tags: ["Flow"]
---

# Create a new customer for Flow workflows

`POST /entities/{entityDID}/flow/customers`

Creates a new customer profile within a Flow workflow context. Customer PII is
encrypted before storage and returned without PII by default. This endpoint
checks for existing customers to prevent duplicates.

**IVMS101 Validation Requirements:**
- For natural persons: `name` object is **required**
- For legal persons: `name` and `nationalIdentification` objects are **required**
- When `nameIdentifier` array is provided, its fields are **required**
- Unknown fields are rejected (strict validation)

## Path parameters

- `entityDID` string, did, required — Decentralized Identifier (DID)

## Request body

- object
  - `customerDid` string, required — Customer identifier (mailto:, tel:, or did:web/did:ethr/did:pkh/did:key/did:jwk/did:keri). When a DID is used, profileData.contactInformation.email is required for OTP.
  - `customerType` 'natural_person' | 'legal_person', required — Type of customer (natural person or legal entity)
  - `profileData` union, required — IVMS101-compliant customer profile data
    - object — Natural person profile
      - `naturalPerson` object, required
        - `name` object, required — Person's name (REQUIRED)
          - `nameIdentifier` object[] — Array of name identifiers (optional, but fields required when present)
            - `primaryIdentifier` string, required — Primary name (e.g., surname) - REQUIRED when nameIdentifier present
            - `secondaryIdentifier` string — Secondary name (e.g., given name)
            - `naturalPersonNameIdentifierType` string, required — Type of name identifier (e.g., LEGL) - REQUIRED when nameIdentifier present
        - `geographicAddress` object[]
        - `nationalIdentification` object
        - `dateAndPlaceOfBirth` object
        - `countryOfResidence` string
    - object — Legal person profile
      - `legalPerson` object, required
        - `name` object, required — Entity's name (REQUIRED)
          - `nameIdentifier` object[] — Array of name identifiers (optional, but fields required when present)
            - `legalPersonName` string, required — Legal entity name - REQUIRED when nameIdentifier present
            - `legalPersonNameIdentifierType` string, required — Type of name identifier - REQUIRED when nameIdentifier present
        - `nationalIdentification` object, required — National identification (REQUIRED for legal persons)
          - `nationalIdentifier` string, required — National identifier value (e.g., registration number) - REQUIRED
          - `nationalIdentifierType` string, required — Type of identifier (e.g., RAID) - REQUIRED
          - `countryOfIssue` string
          - `registrationAuthority` string
        - `geographicAddress` object[]
  - `verificationStatus` 'pending' | 'verified' | 'rejected' | 'expired'
  - `verificationLevel` 'basic' | 'enhanced' | 'premium'

## Response `200`

Customer created successfully

- object
  - `customerDid` string — Customer DID identifier
  - `entityDid` string — Entity DID that owns this customer
  - `customerType` 'natural_person' | 'legal_person' — Type of customer
  - `profileData` object — Encrypted IVMS101 customer profile data (PII encrypted)
  - `verificationStatus` 'pending' | 'verified' | 'rejected' | 'expired' — Customer verification status
  - `verificationLevel` 'basic' | 'enhanced' | 'premium' — Level of verification performed
  - `verifiedAt` string, date-time — When verification was completed
  - `verificationExpiresAt` string, date-time — When verification expires
  - `createdAt` string, date-time — Customer creation timestamp
  - `updatedAt` string, date-time — Customer last update timestamp

## Other responses

- `400` — Bad Request - The server could not process the request due to a client error.
- `401` — Unauthorized - Authentication information is missing or invalid.
- `403` — Forbidden - The server understood the request but refuses to authorize it.
- `404` — Not Found - The requested resource could not be found.
- `409` — Customer already exists
- `500` — Internal Server Error - An unexpected condition was encountered on the server.

---

[API](https://skmtc.net/notabene/apis/notabene-api.md) · [All operations](https://skmtc.net/notabene/apis/notabene-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notabene/notabene-api/versions/70056745a433/schema)