Skip to main content
POST
/
v1
/
request
curl --request POST \
  --url https://api.example.com/v1/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    "user@example.com",
    "+351912345678"
  ],
  "securityLevel": "CONTACT",
  "groupIds": [
    "507f1f77bcf86cd799439011"
  ],
  "resourcesIds": [
    "507f1f77bcf86cd799439012"
  ]
}
'
{
  "credentials": [
    {
      "id": "507f1f77bcf86cd799439011",
      "resourceType": "DOCUMENT",
      "status": "PENDING",
      "name": "Identity Document",
      "internalId": "internal-12345"
    }
  ],
  "id": "507f1f77bcf86cd799439011",
  "subjects": [
    {
      "contact": "user@example.com",
      "did": "did:via:humanos:user-abc123",
      "code": "123456",
      "link": "https://app.humanos.id/link/507f1f77bcf86cd799439011"
    }
  ]
}

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:
["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
​
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
CredentialDto · object[]

Inline JSON credentials to be included in the request

​
signaturePlacements
SignaturePlacementItemDto · object[]

Predefined signature placements for document credentials

​
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

Returns information about the new request, subjects, and credentials

​
credentials
CredentialEntity · object[]
required

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

​
id
string
required

Unique identifier for the request

Example:

"507f1f77bcf86cd799439011"

​
subjects
GenerateSubjectEntity · object[]
required

List of subjects (users) associated with this request