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.example.com/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {
      "contact": "[e-mail]",
      "secondaryContact": "[phone]",
      "docId": "1234567890",
      "language": "ENG",
      "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",
      "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": {}
        }
      ]
    }
  ],
  "internalId": "order-123",
  "authorizedDIDs": [
    "did:web:google.com",
    "did:web:google.pt"
  ]
}
'

import requests

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

payload = {
    "users": [
        {
            "contact": "[e-mail]",
            "secondaryContact": "[phone]",
            "docId": "1234567890",
            "language": "ENG",
            "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",
            "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": {}
                }
            ]
        }
    ],
    "internalId": "order-123",
    "authorizedDIDs": ["did:web:google.com", "did:web:google.pt"]
}
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({
    users: [
      {
        contact: '[e-mail]',
        secondaryContact: '[phone]',
        docId: '1234567890',
        language: 'ENG',
        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',
        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: {}
          }
        ]
      }
    ],
    internalId: 'order-123',
    authorizedDIDs: ['did:web:google.com', 'did:web:google.pt']
  })
};

fetch('https://api.example.com/request', 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/request",
  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([
    'users' => [
        [
                'contact' => '[e-mail]',
                'secondaryContact' => '[phone]',
                'docId' => '1234567890',
                'language' => 'ENG',
                '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',
                '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' => [
                                                                                                                                
                                                                ]
                                ]
                ]
        ]
    ],
    'internalId' => 'order-123',
    'authorizedDIDs' => [
        'did:web:google.com',
        'did:web:google.pt'
    ]
  ]),
  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/request"

	payload := strings.NewReader("{\n  \"users\": [\n    {\n      \"contact\": \"[e-mail]\",\n      \"secondaryContact\": \"[phone]\",\n      \"docId\": \"1234567890\",\n      \"language\": \"ENG\",\n      \"signerQuality\": \"Administrator\"\n    }\n  ],\n  \"name\": \"My request\",\n  \"iframe\": {\n    \"pubKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\"\n  },\n  \"securityLevel\": \"CONTACT\",\n  \"groupIds\": [\n    \"1234567890\"\n  ],\n  \"resourcesIds\": [\n    \"1234567890\"\n  ],\n  \"credentials\": [\n    {\n      \"type\": \"DOCUMENT\",\n      \"name\": \"Document 1\",\n      \"scope\": \"payments.hotel\",\n      \"validFrom\": \"2025-01-01T00:00:00.000Z\",\n      \"validUntil\": \"2026-01-01T00:00:00.000Z\",\n      \"description\": \"Employee NDA signed on 2025-01-01\",\n      \"internalId\": \"internal-12345\",\n      \"data\": \"base64 encoded PDF\",\n      \"placements\": [\n        {\n          \"contact\": \"[e-mail]\",\n          \"x\": 123,\n          \"y\": 123,\n          \"width\": 123,\n          \"height\": 123,\n          \"pageIndex\": 123,\n          \"identityType\": {}\n        }\n      ]\n    }\n  ],\n  \"internalId\": \"order-123\",\n  \"authorizedDIDs\": [\n    \"did:web:google.com\",\n    \"did:web:google.pt\"\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/request")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    {\n      \"contact\": \"[e-mail]\",\n      \"secondaryContact\": \"[phone]\",\n      \"docId\": \"1234567890\",\n      \"language\": \"ENG\",\n      \"signerQuality\": \"Administrator\"\n    }\n  ],\n  \"name\": \"My request\",\n  \"iframe\": {\n    \"pubKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\"\n  },\n  \"securityLevel\": \"CONTACT\",\n  \"groupIds\": [\n    \"1234567890\"\n  ],\n  \"resourcesIds\": [\n    \"1234567890\"\n  ],\n  \"credentials\": [\n    {\n      \"type\": \"DOCUMENT\",\n      \"name\": \"Document 1\",\n      \"scope\": \"payments.hotel\",\n      \"validFrom\": \"2025-01-01T00:00:00.000Z\",\n      \"validUntil\": \"2026-01-01T00:00:00.000Z\",\n      \"description\": \"Employee NDA signed on 2025-01-01\",\n      \"internalId\": \"internal-12345\",\n      \"data\": \"base64 encoded PDF\",\n      \"placements\": [\n        {\n          \"contact\": \"[e-mail]\",\n          \"x\": 123,\n          \"y\": 123,\n          \"width\": 123,\n          \"height\": 123,\n          \"pageIndex\": 123,\n          \"identityType\": {}\n        }\n      ]\n    }\n  ],\n  \"internalId\": \"order-123\",\n  \"authorizedDIDs\": [\n    \"did:web:google.com\",\n    \"did:web:google.pt\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"users\": [\n    {\n      \"contact\": \"[e-mail]\",\n      \"secondaryContact\": \"[phone]\",\n      \"docId\": \"1234567890\",\n      \"language\": \"ENG\",\n      \"signerQuality\": \"Administrator\"\n    }\n  ],\n  \"name\": \"My request\",\n  \"iframe\": {\n    \"pubKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\"\n  },\n  \"securityLevel\": \"CONTACT\",\n  \"groupIds\": [\n    \"1234567890\"\n  ],\n  \"resourcesIds\": [\n    \"1234567890\"\n  ],\n  \"credentials\": [\n    {\n      \"type\": \"DOCUMENT\",\n      \"name\": \"Document 1\",\n      \"scope\": \"payments.hotel\",\n      \"validFrom\": \"2025-01-01T00:00:00.000Z\",\n      \"validUntil\": \"2026-01-01T00:00:00.000Z\",\n      \"description\": \"Employee NDA signed on 2025-01-01\",\n      \"internalId\": \"internal-12345\",\n      \"data\": \"base64 encoded PDF\",\n      \"placements\": [\n        {\n          \"contact\": \"[e-mail]\",\n          \"x\": 123,\n          \"y\": 123,\n          \"width\": 123,\n          \"height\": 123,\n          \"pageIndex\": 123,\n          \"identityType\": {}\n        }\n      ]\n    }\n  ],\n  \"internalId\": \"order-123\",\n  \"authorizedDIDs\": [\n    \"did:web:google.com\",\n    \"did:web:google.pt\"\n  ]\n}"

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

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",
      "secondaryContact": "[phone]",
      "link": "https://app.humanos.id/link/507f1f77bcf86cd799439011.Ab12Cd34Ef56Gh78"
    }
  ]
}

{
  "statusCode": 404,
  "message": "Failed to generate credentials request",
  "error": "Not Found"
}

{
  "statusCode": 402,
  "message": "Insufficient credits for this action. Please top up your balance.",
  "error": "Unknown Error"
}

{
  "statusCode": 409,
  "message": "Try again later",
  "error": "Unknown Error"
}

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

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": "ENG",
    "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"]

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