Create Request

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

This endpoint will:

• Create credentials from resources (via group IDs, resource IDs) or inline JSON data
• Associate those credentials with subjects
• Generate and send OTPs via email or SMS

POST /request

Create Request

cURL

curl --request POST \
  --url https://api.humanos.tech/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {
      "contact": "[e-mail]",
      "secondaryContact": "[phone]",
      "docId": "1234567890",
      "language": "pt-PT",
      "signerQuality": "Administrator"
    }
  ],
  "name": "My request",
  "iframe": {
    "pubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
  },
  "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",
      "maxExecutions": 1,
      "description": "Employee NDA signed on 2025-01-01",
      "internalId": "internal-12345",
      "data": "base64 encoded PDF",
      "placements": [
        {
          "contact": "[e-mail]",
          "x": 123,
          "y": 123,
          "width": 123,
          "height": 123,
          "pageIndex": 123,
          "identityType": {}
        }
      ],
      "authorizedAgents": [
        {
          "did": "did:web:humanos.tech:agent:7c1f0a9b3e2d4c5f",
          "keyId": "did:web:humanos.tech:agent:7c1f0a9b3e2d4c5f#key-1",
          "maxAttestationStaleness": 86400
        }
      ]
    }
  ],
  "internalId": "order-123",
  "authorizedDIDs": [
    "did:web:google.com",
    "did:web:google.pt"
  ],
  "webhookEndpoints": [
    "60d5ec49f1a2c8b1f8e4e1a2"
  ]
}
'

201

{
  "id": "507f1f77bcf86cd799439011",
  "credentials": [
    {
      "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
      "name": "Credential Name",
      "internalId": "internal-12345"
    }
  ],
  "subjects": [
    {
      "contact": "[e-mail]",
      "id": "did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8",
      "synthetic": true,
      "code": "<string>",
      "secondaryContact": "[phone]",
      "link": "https://app.humanos.id/link/507f1f77bcf86cd799439011.Ab12Cd34Ef56Gh78"
    }
  ]
}

Headers

Idempotency-Key · string

Optional. A unique value you choose, such as a UUID, that makes retries safe. For 24 hours, a request with the same Idempotency-Key value and the same path parameters, query and body returns the original response instead of running again. Values are scoped to your API key and to this endpoint. A 409 means the first request with this value is still running (this clears within 5 minutes), or the value was already used for a different request. A 503 with Retry-After means nothing ran: retry with the same value after that many seconds.

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-11-02"

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.
Optional fields: name (label for the request), internalId (your own reference), iframe (postMessage/iframe signing config), and authorizedDIDs (extra DIDs granted read + VP create/verify access; the requester DID is always appended).

users · object[] · required

Array of users to be included in the request

Show child attributes

Example:

[
  {
    "contact": "[e-mail]",
    "secondaryContact": "[phone]",
    "docId": "1234567890",
    "language": "pt-PT",
    "signerQuality": "Administrator"
  }
]

name · string

Name to be assigned to the request

Example:

"My request"

iframe · object

IFrame configuration for the request

Show child attributes

Example:

{
  "pubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
}

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

Show child attributes

internalId · string

Internal identifier for the request

Example:

"order-123"

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

webhookEndpoints · string[]

The webhook endpoints this request notifies, by id: exactly these, and [] notifies none. Each must be one of your organization's endpoints.

Omit it to notify your organization's defaults: every endpoint set to receive all requests, plus the endpoints your API key and the request's workflows select.

Maximum array length: 20

Example:

["60d5ec49f1a2c8b1f8e4e1a2"]

Response

201

application/json

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.

Show child attributes

subjects · object[] · required

List of subjects (users) associated with this request

Show child attributes