Skip to main content
POST
/
request
Create Request
curl --request POST \
  --url https://api.example.com/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    "john.doe@example.com",
    "+1234567890"
  ],
  "name": "My request",
  "securityLevel": "CONTACT",
  "groupIds": [
    "1234567890"
  ],
  "resourcesIds": [
    "1234567890"
  ],
  "credentials": [
    {
      "type": "DOCUMENT",
      "name": "Document 1",
      "scope": "payments.hotel",
      "validFrom": "2025-01-01T00:00:00.000Z",
      "validUntil": "2026-01-01T00:00:00.000Z",
      "description": "Employee NDA signed on 2025-01-01",
      "internalId": "internal-12345",
      "data": [
        "base64 encoded PDF"
      ],
      "placements": [
        {
          "contact": "user@example.com",
          "x": 123,
          "y": 123,
          "width": 123,
          "height": 123,
          "pageIndex": 123,
          "identityType": {}
        }
      ]
    }
  ],
  "language": "ENG",
  "redirectUrl": "https://example.com/callback",
  "internalId": "order-123",
  "pubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
  "authorizedDIDs": [
    "did:web:google.com",
    "did:web:google.pt"
  ],
  "expectedDocIds": [
    {
      "contact": "john.doe@example.com",
      "docId": "1234567890"
    }
  ]
}
'
{
  "id": "507f1f77bcf86cd799439011",
  "credentials": [
    {
      "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
      "name": "Credential Name",
      "internalId": "internal-12345"
    }
  ],
  "subjects": [
    {
      "contact": "user@example.com",
      "id": "did:web:humanos.tech:user:013a0628-fd20-4f73-a7d0-785e9f6e79c1",
      "code": "123456",
      "link": "https://app.humanos.id/link/507f1f77bcf86cd799439011"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.humanos.tech/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

Request body containing contacts (subjects), security level, and credentials to generate
Resources can be specified via groupIds, resourcesIds, or inline credentials array.

​
contacts
string[]
required

Array of contact emails or phone numbers

Example:
["john.doe@example.com", "+1234567890"]
​
name
string

Name to be assigned to the request

Example:

"My request"

​
securityLevel
enum<string>
default:CONTACT

Security level for the request

Available options:
CONTACT,
ORGANIZATION_KYC,
HUMANOS_KYC,
HUMANOS_REVALIDATION
​
groupIds
string[]

Ids of existing group resources to be included in the request

Example:
["1234567890"]
​
resourcesIds
string[]

Ids of existing resources to be included in the request

Example:
["1234567890"]
​
credentials
object[]

Inline JSON credentials to be included in the request

​
language
string

What language to use when sending notifications to the user

Example:

"ENG"

​
redirectUrl
string

URL to redirect the subject after completing the request

Example:

"https://example.com/callback"

​
internalId
string

Internal identifier for the request

Example:

"order-123"

​
pubKey
string

Base64-encoded P-256 SPKI public key to pre-register for postMessage payload encryption.

Example:

"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."

​
authorizedDIDs
string[]

Grants 3 types of access to the request:

  1. READ access to request detail, credentials, and corresponding evidences.

  2. Allows to create Verifiable Presentations (VPs) from mandates associated with this request

  3. Allows to verify Verifiable Presentations (VPs) from mandates associated with this request

By default, the requester DID are automatically appended to this list.

Example:
["did:web:google.com", "did:web:google.pt"]
​
expectedDocIds
string[]

List of known document IDs of the users This will force a KYC verification for each user if none of its Humanos identities match the document ID Will make sure the received identity from the KYC verification matches the document ID, and update the user's Humanos identities if needed

Example:
[
  {
    "contact": "john.doe@example.com",
    "docId": "1234567890"
  }
]

Response

Returns information about the new request, subjects, and credentials

​
id
string
required

Unique identifier for the request

Example:

"507f1f77bcf86cd799439011"

​
credentials
object[]
required

List of credentials created in this request.

​
subjects
object[]
required

List of subjects (users) associated with this request