Skip to main content
POST
/
v1
/
user
Create User
curl --request POST \
  --url https://api.example.com/v1/user \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "contact": "user@example.com",
    "internalId": "internal-user-123",
    "identity": {
      "fullName": "John Doe",
      "birth": "1990-01-01",
      "docId": "1234567890",
      "countryAlpha3": "PRT"
    }
  },
  {
    "contact": "+351912345678",
    "internalId": "internal-user-456"
  }
]
'
[
  {
    "status": 200,
    "data": {
      "userId": "507f1f77bcf86cd799439011",
      "internalId": "internal-user-12345",
      "did": {
        "id": "507f1f77bcf86cd799439012",
        "did": "did:via:humanos:user-123",
        "active": true,
        "revoked": false
      }
    }
  }
]

Body

application/json

Array of subjects to create. Each subject represents a user to be imported into Humanos. Minimum 1 subject, maximum 100 subjects per request. Each subject must have at least a contact (email or phone).

​
contact
string
required

Contact information for the user. Must be a valid email address or phone number (e.g., "user@example.com" or "+351912345678"). Spaces will be automatically removed from the contact value. This is the only required field.

Example:

"user@example.com"

​
identity
object

Optional identity information (KYC data) for the user. When provided, all identity fields will be validated. Required fields if identity is provided: fullName, birth, docId, countryAlpha3.

​
internalId
string

Optional internal identifier that allows organizations to map users within their own database. This ID is stored and can be used to reference the user in subsequent API calls. Useful for maintaining a link between your internal user records and the Humanos user records.

Example:

"internal-user-12345"

Response

Request processed successfully. Returns an array of feedback objects, one for each subject in the request. The order of feedback items matches the order of subjects in the request. Each feedback contains a status code and optional data with user information.

​
status
enum<number>
required

HTTP status code indicating the result of the operation for this specific subject. Status codes: 200 (success), 400 (invalid contact), 401 (invalid identity), 402 (invalid country), 407 (duplicate contact in request), 408 (duplicate identity in request), 409 (identity already exists for another user).

Available options:
200,
400,
401,
402,
407,
408,
409
Example:

200

​
data
object

Response data containing user information if the operation was successful (status 200), or null if there was an error. When status is 200, this object contains userId, internalId (if provided), and the DID information.

Example:
{
  "userId": "507f1f77bcf86cd799439011",
  "internalId": "internal-user-12345",
  "did": {
    "id": "507f1f77bcf86cd799439012",
    "did": "did:via:humanos:user-123",
    "active": true,
    "revoked": false
  }
}