> ## Documentation Index > Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt > Use this file to discover all available pages before exploring further. # Create User > This endpoint allows organizations to import their existing users' information into Humanos, for better management and control. - Between 1 and 100 users can be created per request. - A user is identified by a Humanos-verified contact (email or phone); if it does not exist, it will be created. - Optionally, additional identity information (KYC) to allow mapping users within your own system. - Optionally, additional contact emails or phone numbers can be provided to allow mapping users within your own system. - Optionally, an internal ID can be provided to allow mapping users within your own system. - Optionally, provide an 'Idempotency-Key' header to safely retry the same request without creating duplicate users. ## OpenAPI ````yaml /versions/2026-07-06.yaml post /user openapi: 3.1.0 info: title: Humanos API description: Humanos API version: '1.0' contact: {} servers: [] security: [] tags: - name: humanosApp description: '' paths: /user: post: tags: - User summary: Create User description: >- This endpoint allows organizations to import their existing users' information into Humanos, for better management and control. - Between 1 and 100 users can be created per request. - A user is identified by a Humanos-verified contact (email or phone); if it does not exist, it will be created. - Optionally, additional identity information (KYC) to allow mapping users within your own system. - Optionally, additional contact emails or phone numbers can be provided to allow mapping users within your own system. - Optionally, an internal ID can be provided to allow mapping users within your own system. - Optionally, provide an 'Idempotency-Key' header to safely retry the same request without creating duplicate users. operationId: user_create parameters: - name: Idempotency-Key in: header description: >- Optional key used to safely retry the same create/initiate request without duplicating side effects. required: false schema: type: string example: a96d14c5-8e60-4f6b-9d80-5c18c0e4202a - $ref: '#/components/parameters/ApiVersion' requestBody: required: true description: >- Array of subjects to create. Each subject represents a user to be imported into Humanos content: application/json: schema: type: array items: $ref: '#/components/schemas/CreateSubjectDto' examples: default: value: - contact: john.doe@example.com internalId: internal-user-123 extraContacts: - jane.doe@example.com - '+351912345678' identity: fullName: John Doe birth: '1990-01-01' docId: '1234567890' fullDocId: '12345678901234' countryAlpha3: PRT gender: M expiresAt: '2026-01-01' issueDate: '2021-01-01' taxNumber: '123456789' healthNumber: '987654321' socialSecurityNumber: '111222333' photo: /9j/4AAQSkZJRgABAQAAAQABAAD/2wBD height: '180' documentType: passport documentDiscriminator: K5V5 placeOfBirth: Lisbon mrzText: >- P- A fully-populated subject (every optional field) plus a minimal one responses: '201': description: >- Returns an array of feedback objects, one for each subject in the request. The order in the response will match the order of of the request body. Possible status codes for each subject: - 201: Subject created or updated - 400: Invalid body payload. Information will be at the message field - 409: Duplicate contact within the request body - 410: This subject (subjectId) has more than one contact in this request body - 500: Unknown error content: application/json: schema: type: array items: $ref: '#/components/schemas/CreateSubjectEntity' '400': description: >- Bad request. This occurs when: no subjects are provided (empty array), subjects provided are not within the allowed limits, or the request body is malformed. content: application/json: schema: type: object properties: statusCode: type: number example: 400 message: type: string example: No subjects provided error: type: string example: Bad Request components: parameters: ApiVersion: name: API-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-07-06' description: >- Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version. schemas: CreateSubjectDto: type: object properties: contact: type: string description: >- The verified contact (email or phone number) that identifies this subject. This becomes a Contact row with a DID — Humanos can OTP it, route webhooks to it, and use it to participate in credential signing flows. See `extraContacts` for non-verified per-issuer metadata strings. example: john.doe@example.com internalId: type: string description: >- Identifier to help you identify the user in your own system. We recommend using a unique value. example: internal-12345 extraContacts: description: >- Array of contact emails or phone numbers. Any update will fully replace the existing extra contacts. These contacts only live within your organization, and are therefore not verified by Humanos. You will not be able to use them to contact the user. example: - john.doe@example.com - '+1234567890' type: array items: type: string identity: description: >- Identity information to be assigned to the user Only mandatory fields are {fullName, birth, docId, countryAlpha3}. Any extra field can be provided for visualization Any update will fully replace the existing identity. This identity only lives within your organization, therefore is not verified by Humanos. example: fullName: John Doe birth: '1990-01-01' docId: '1234567890' countryAlpha3: PRT gender: M expiresAt: '2026-01-01' issueDate: '2021-01-01' taxNumber: '123456789' healthNumber: '123456789' socialSecurityNumber: '987654321' photo: /9j/4AAQSkZJRgABAQAAAQABAAD/2wBD height: '180' documentType: passport documentDiscriminator: K5V5 placeOfBirth: Lisbon mrzText: >- P- HTTP status code indicating the result of the operation for this specific subject: - 201: Success — subject created or updated (the message distinguishes: "Subject created" vs updated) - 400: Invalid body payload. Information will be at the message field - 409: Duplicate contact within the request body - 410: Contact maps to a subject with inconsistent references (the same subject appears through more than one contact in this request) - 500: Unexpected processing error example: 201 enum: - 201 - 400 - 409 - 410 - 500 message: type: string description: Success or error message example: Subject created user: description: >- User information. When the operation fails, only the identifying fields that were submitted (such as contact, internalId, and id) are echoed back. title: SubjectIssuerEntity allOf: - $ref: '#/components/schemas/PartialSubjectEntity' required: - status - message - user IdentityDto: type: object properties: fullName: type: string description: Full name of the person example: John Doe birth: type: string description: Birth date. Must be a valid date in the past (ISO 8601). example: '1990-01-01' format: date docId: type: string description: Document ID number example: '1234567890' fullDocId: type: string description: >- Full document ID (extended version). Must start with docId and contain additional characters. example: '12345678901234' nullable: true countryAlpha3: type: string description: >- 3-letter ISO 3166-1 alpha-3 country code (e.g., PRT, USA, GBR). Must be exactly 3 characters. Spaces will be automatically removed. example: PRT gender: type: object description: Male (M), Female (F), Other (O) example: M nullable: true expiresAt: type: string description: Document expiration date (ISO 8601). example: '2025-01-01' format: date nullable: true issueDate: type: string description: Document issue date (ISO 8601). example: '2010-01-01' format: date nullable: true taxNumber: type: object description: Tax identification number. example: '123456789' nullable: true healthNumber: type: object description: Health insurance number example: '987654321' nullable: true socialSecurityNumber: type: object description: Social security number example: '111222333' nullable: true photo: type: object description: >- Photo of the person, base64-encoded (validated with IsBase64; data URIs and URLs are not accepted). example: /9j/4AAQSkZJRgABAQAAAQABAAD/2wBD nullable: true height: type: object description: Height of the person in centimeters. Will filter numbers only example: '175' nullable: true documentType: type: object description: >- Type of document (e.g., passport, ID card, driver license). Maximum 50 characters. example: passport nullable: true documentDiscriminator: type: object description: Document discriminator example: ZWX1 nullable: true placeOfBirth: type: object description: Place of birth. Maximum 50 characters. example: Lisbon nullable: true mrzText: type: object description: >- Machine Readable Zone (MRZ) text from the document. Maximum 2000 characters. example: P- Additional extra information in JSON format. Maximum 2000 characters. example: '{"notes": "Additional information"}' nullable: true required: - fullName - birth - docId - countryAlpha3 PartialSubjectEntity: type: object properties: id: type: string description: User's VIA identifier example: did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8 contact: type: string description: Verified contact value (email or phone) example: user@example.com internalId: type: string description: >- Identifier to help you identify the user in your own system. We recommend using a unique value. example: internal-12345 ````