Skip to main content
POST
/
user
Create User
curl --request POST \
  --url https://api.example.com/user \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "contacts": [
      "[email protected]",
      "+351912345678"
    ],
    "internalId": "internal-user-123",
    "identity": {
      "fullName": "John Doe",
      "birth": "1990-01-01",
      "docId": "1234567890",
      "countryAlpha3": "PRT"
    }
  },
  {
    "contacts": [
      "+351912345679"
    ],
    "internalId": "internal-user-456"
  }
]
'
[
  {
    "status": 200,
    "message": "Subject created",
    "user": {
      "id": "did:web:humanos.tech:user:013a0628-fd20-4f73-a7d0-785e9f6e79c1",
      "contact": "[email protected]",
      "internalId": "internal-12345"
    }
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.humanos.id/llms.txt

Use this file to discover all available pages before exploring further.

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:

"[email protected]"

​
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:
["[email protected]", "+1234567890"]
​
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.

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

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