Create User

This endpoint allows organizations to import their existing users information into Humanos, for better management and control.

• Multiple users can be created in a call.
• A user is identified by a Humanos verified contact (email or phone), if doesn’t exist 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.

POST /user

Create User

cURL

curl --request POST \
  --url https://api.example.com/user \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "contacts": [
      "[e-mail]",
      "[phone]"
    ],
    "internalId": "internal-user-123",
    "identity": {
      "fullName": "John Doe",
      "birth": "1990-01-01",
      "docId": "1234567890",
      "countryAlpha3": "PRT"
    }
  },
  {
    "contacts": [
      "[phone]"
    ],
    "internalId": "internal-user-456"
  }
]
'

201

[
  {
    "status": 200,
    "message": "Subject created",
    "user": {
      "id": "did:web:humanos.tech:user:013a0628-fd20-4f73-a7d0-785e9f6e79c1",
      "contact": "[e-mail]",
      "internalId": "internal-12345"
    }
  }
]

Headers

Idempotency-Key · string

Optional key used to safely retry the same create/initiate request without duplicating side effects.

Example:

"a96d14c5-8e60-4f6b-9d80-5c18c0e4202a"

API-Version · string

Pin responses to a specific API version (YYYY-MM-DD). When omitted, defaults to the version stored in your issuer config or today's date.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-03-03"

Body

application/json

Array of subjects to create. Each subject represents a user to be imported into Humanos

contact · string · required

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:

"[e-mail]"

internalId · string

Identifier to help you identify the user in your own system. We recommend using a unique value.

Example:

"internal-12345"

extraContacts · string[]

Array of contact emails or phone numbers. Any update will fully replace the existing extra contacts. This contacts only live within your organization, therefore are not verified by Humanos. You will not be able to use it to contact the user.

Example:

["[e-mail]", "[phone]"]

identity · object

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.

Show child attributes

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": "https://example.com/photo.jpg",
  "height": "180",
  "documentType": "passport",
  "documentDiscriminator": "K5V5",
  "placeOfBirth": "Lisbon",
  "mrzText": "P<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02"
}

Response

201

application/json

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:

• 200: Subject created
• 201: Subject 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 then one contact in this request body
• 500: Unknown error

status · enum<number> · required

HTTP status code indicating the result of the operation for this specific subject:

• 200: Success
• 201: Success, but nothing was updated
• 400: Invalid body payload. Information will be at the message field
• 402: Invalid identity due to invalid countryAlpha3
• 407: This call contained this contact more than once
• 408: This call contained this identity more than once
• 409: Duplicate Identity
• 410: Duplicate Identity. This user already has an identity with this countryAlpha3

Available options: 200, 201, 400, 402, 407, 408, 409, 410

Example:

200

message · string · required

Success or error message

Example:

"Subject created"

user · SubjectIssuerEntity · object · required

User information. Will just contain the contact if the operation fails

Show child attributes