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, 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.example.com/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\"}"
    }
  },
  {
    "contact": "[phone]",
    "internalId": "internal-user-456"
  }
]
'

import requests

url = "https://api.example.com/user"

payload = [
    {
        "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\"}"
        }
    },
    {
        "contact": "[phone]",
        "internalId": "internal-user-456"
    }
]
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      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"}'
      }
    },
    {contact: '[phone]', internalId: 'internal-user-456'}
  ])
};

fetch('https://api.example.com/user', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/user",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        '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"}'
        ]
    ],
    [
        'contact' => '[phone]',
        'internalId' => 'internal-user-456'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/user"

	payload := strings.NewReader("[\n  {\n    \"contact\": \"[e-mail]\",\n    \"internalId\": \"internal-user-123\",\n    \"extraContacts\": [\n      \"[e-mail]\",\n      \"[phone]\"\n    ],\n    \"identity\": {\n      \"fullName\": \"John Doe\",\n      \"birth\": \"1990-01-01\",\n      \"docId\": \"1234567890\",\n      \"fullDocId\": \"12345678901234\",\n      \"countryAlpha3\": \"PRT\",\n      \"gender\": \"M\",\n      \"expiresAt\": \"2026-01-01\",\n      \"issueDate\": \"2021-01-01\",\n      \"taxNumber\": \"123456789\",\n      \"healthNumber\": \"987654321\",\n      \"socialSecurityNumber\": \"111222333\",\n      \"photo\": \"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD\",\n      \"height\": \"180\",\n      \"documentType\": \"passport\",\n      \"documentDiscriminator\": \"K5V5\",\n      \"placeOfBirth\": \"Lisbon\",\n      \"mrzText\": \"P<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02\",\n      \"extra\": \"{\\\"department\\\":\\\"Engineering\\\",\\\"employeeId\\\":\\\"E-4471\\\"}\"\n    }\n  },\n  {\n    \"contact\": \"[phone]\",\n    \"internalId\": \"internal-user-456\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/user")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"contact\": \"[e-mail]\",\n    \"internalId\": \"internal-user-123\",\n    \"extraContacts\": [\n      \"[e-mail]\",\n      \"[phone]\"\n    ],\n    \"identity\": {\n      \"fullName\": \"John Doe\",\n      \"birth\": \"1990-01-01\",\n      \"docId\": \"1234567890\",\n      \"fullDocId\": \"12345678901234\",\n      \"countryAlpha3\": \"PRT\",\n      \"gender\": \"M\",\n      \"expiresAt\": \"2026-01-01\",\n      \"issueDate\": \"2021-01-01\",\n      \"taxNumber\": \"123456789\",\n      \"healthNumber\": \"987654321\",\n      \"socialSecurityNumber\": \"111222333\",\n      \"photo\": \"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD\",\n      \"height\": \"180\",\n      \"documentType\": \"passport\",\n      \"documentDiscriminator\": \"K5V5\",\n      \"placeOfBirth\": \"Lisbon\",\n      \"mrzText\": \"P<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02\",\n      \"extra\": \"{\\\"department\\\":\\\"Engineering\\\",\\\"employeeId\\\":\\\"E-4471\\\"}\"\n    }\n  },\n  {\n    \"contact\": \"[phone]\",\n    \"internalId\": \"internal-user-456\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/user")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"contact\": \"[e-mail]\",\n    \"internalId\": \"internal-user-123\",\n    \"extraContacts\": [\n      \"[e-mail]\",\n      \"[phone]\"\n    ],\n    \"identity\": {\n      \"fullName\": \"John Doe\",\n      \"birth\": \"1990-01-01\",\n      \"docId\": \"1234567890\",\n      \"fullDocId\": \"12345678901234\",\n      \"countryAlpha3\": \"PRT\",\n      \"gender\": \"M\",\n      \"expiresAt\": \"2026-01-01\",\n      \"issueDate\": \"2021-01-01\",\n      \"taxNumber\": \"123456789\",\n      \"healthNumber\": \"987654321\",\n      \"socialSecurityNumber\": \"111222333\",\n      \"photo\": \"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD\",\n      \"height\": \"180\",\n      \"documentType\": \"passport\",\n      \"documentDiscriminator\": \"K5V5\",\n      \"placeOfBirth\": \"Lisbon\",\n      \"mrzText\": \"P<PRTDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<1234567890PRT9001019M2601012<<<<<<<<<<<<<<02\",\n      \"extra\": \"{\\\"department\\\":\\\"Engineering\\\",\\\"employeeId\\\":\\\"E-4471\\\"}\"\n    }\n  },\n  {\n    \"contact\": \"[phone]\",\n    \"internalId\": \"internal-user-456\"\n  }\n]"

response = http.request(request)
puts response.read_body

201

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

{
  "statusCode": 400,
  "message": "No subjects provided",
  "error": "Bad Request"
}

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 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-07-06"

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"
}

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