Skip to main content
POST
/
user
Create User
curl --request POST \
  --url https://api.example.com/user \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "contacts": [
      "user@example.com",
      "+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": {
      "contacts": [
        "user@example.com"
      ],
      "internalId": "internal-user-123",
      "did": "did:web:humanos.tech:user-abc123"
    }
  }
]

Headers

​
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

​
contacts
string[]
required

Array of contacts (emails or phone numbers) for the user

Example:
["user@example.com", "+351912345678"]
​
internalId
string

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

Example:

"internal-12345"

​
identity
object

Identity information to be assigned to the user

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.

​
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
SubjectEntity · object
required

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