Create

Create a new credential request for one or more subjects (users).

This endpoint will:

• Create credentials from resources or inline JSON data
• Associate credentials with subjects
• Generate and send OTPs for approval via email or SMS

Request details:

• Resources can be specified via group IDs, resource IDs, or as inline JSON credentials
• Maximum 30 credentials per request
• Maximum 20 contacts per request
• OTPs are automatically sent to all subjects after creation

POST /request

cURL

withResources

curl --request POST \ --url https://api.example.com/request \ --header 'Content-Type: application/json' \ --data ' { "contacts": [ "[e-mail]", "[phone]" ], "securityLevel": "CONTACT", "groupIds": [ "507f1f77bcf86cd799439011" ], "resourcesIds": [ "507f1f77bcf86cd799439012" ] } '

201

{
  "credentials": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Identity Document",
      "internalId": "internal-12345"
    }
  ],
  "id": "507f1f77bcf86cd799439011",
  "subjects": [
    {
      "contact": "[e-mail]",
      "did": "did:via:humanos:user-abc123",
      "code": "123456",
      "link": "https://app.humanos.id/link/507f1f77bcf86cd799439011"
    }
  ]
}

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

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

contacts · string[] · required

Array of contact emails or phone numbers

Example:

["[e-mail]", "[phone]"]

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

allowDuplicates · boolean · default: false

Whether filters or allows credentials with the exact same data to be requested. This applies to both duplicate resourceIds passed in the body or associated with groupIds provided.

Example:

true

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

Show child attributes

signaturePlacements · object[]

Predefined signature placements for document credentials

Show child attributes

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"

Response

201

application/json

Returns information about the new request, subjects, and credentials

credentials · object[] · required

List of credentials created in this request. Each credential is associated with one or more subjects.

Show child attributes

id · string · required

Unique identifier for the request

Example:

"507f1f77bcf86cd799439011"

subjects · object[] · required

List of subjects (users) associated with this request

Show child attributes