Skip to main content
POST
/
request
Create Request
curl --request POST \
  --url https://api.example.com/request \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    {
      "contact": "[email protected]",
      "secondaryContact": "+351912345678",
      "docId": "1234567890"
    }
  ],
  "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": "[email protected]",
          "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": "[email protected]",
            "secondaryContact": "+351912345678",
            "docId": "1234567890"
        }
    ],
    "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": "[email protected]",
                    "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: '[email protected]',
        secondaryContact: '+351912345678',
        docId: '1234567890'
      }
    ],
    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: '[email protected]',
            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' => '[email protected]',
                'secondaryContact' => '+351912345678',
                'docId' => '1234567890'
        ]
    ],
    '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' => '[email protected]',
                                                                '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\": \"[email protected]\",\n      \"secondaryContact\": \"+351912345678\",\n      \"docId\": \"1234567890\"\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\": \"[email protected]\",\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\": \"[email protected]\",\n      \"secondaryContact\": \"+351912345678\",\n      \"docId\": \"1234567890\"\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\": \"[email protected]\",\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\": \"[email protected]\",\n      \"secondaryContact\": \"+351912345678\",\n      \"docId\": \"1234567890\"\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\": \"[email protected]\",\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
{
  "id": "507f1f77bcf86cd799439011",
  "credentials": [
    {
      "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
      "name": "Credential Name",
      "internalId": "internal-12345"
    }
  ],
  "subjects": [
    {
      "contact": "[email protected]",
      "id": "did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8",
      "secondaryContact": "+351912345678",
      "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"
}

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.

​
users
object[]
required

Array of users to be included in the request

Example:
[
  {
    "contact": "[email protected]",
    "secondaryContact": "+351912345678",
    "docId": "1234567890"
  }
]
​
name
string

Name to be assigned to the request

Example:

"My request"

​
iframe
object

IFrame configuration for the request

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

​
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

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