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, the people this user can sign on behalf of (represents), named later on Create Request with users[].onBehalfOf.
• Optionally, provide an ‘Idempotency-Key’ header to safely retry the same request without creating duplicate users.

POST /user

Create User

cURL

curl --request POST \
  --url https://api.humanos.tech/user \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "contact": "[e-mail]",
    "internalId": "internal-user-123",
    "extraContacts": [
      "[e-mail]",
      "[phone]"
    ],
    "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<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02",
      "extra": "{\"department\":\"Engineering\",\"employeeId\":\"E-4471\"}"
    },
    "represents": [
      {
        "fullName": "Tomás Doe",
        "birth": "2015-06-10",
        "docId": "87654321",
        "countryAlpha3": "PRT",
        "healthNumber": "123456789",
        "internalId": "patient-0042"
      }
    ]
  },
  {
    "contact": "[phone]",
    "internalId": "internal-user-456"
  }
]
'

201

[
  {
    "status": 201,
    "message": "Subject created",
    "user": {
      "id": "did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8",
      "contact": "[e-mail]",
      "internalId": "internal-12345"
    }
  }
]

Headers

Idempotency-Key · string

Optional. A unique value you choose, such as a UUID, that makes retries safe. For 24 hours, a request with the same Idempotency-Key value and the same path parameters, query and body returns the original response instead of running again. Values are scoped to your API key and to this endpoint. A 409 means the first request with this value is still running (this clears within 5 minutes), or the value was already used for a different request. A 503 with Retry-After means nothing ran: retry with the same value after that many seconds.

Example:

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

API-Version · string

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.

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

Example:

"2026-11-02"

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. 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:

["[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": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD",
  "height": "180",
  "documentType": "passport",
  "documentDiscriminator": "K5V5",
  "placeOfBirth": "Lisbon",
  "mrzText": "P<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02"
}

represents · object[]

People this user can sign on behalf of (e.g. a parent signing for a child). Same fields and mandatory fields as identity, plus an optional internalId. At most 10 per user.

Entries are matched by docId: a matching entry is replaced, a new one is added, and entries not sent are kept. Name one on Create Request with users[].onBehalfOf.docId to fill the document's identity fields with that person's identity. The credential webhook returns it in onBehalfOf.

These identities only live within your organization, are not verified by Humanos, and never change the user's identity status.

Show child attributes

Example:

[
  {
    "fullName": "Tomás Doe",
    "birth": "2015-06-10",
    "docId": "87654321",
    "countryAlpha3": "PRT",
    "healthNumber": "123456789",
    "internalId": "patient-0042"
  }
]

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:

• 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

status · enum<number> · required

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

Available options: 201, 400, 409, 410, 500

Example:

201

message · string · required

Success or error message

Example:

"Subject created"

user · SubjectIssuerEntity · object · required

User information. When the operation fails, only the identifying fields that were submitted (such as contact, internalId, and id) are echoed back.

Show child attributes