> ## Documentation Index > Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt > Use this file to discover all available pages before exploring further. # 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 ## OpenAPI ````yaml /versions/2026-07-06.yaml post /request openapi: 3.1.0 info: title: Humanos API description: Humanos API version: '1.0' contact: {} servers: [] security: [] tags: - name: humanosApp description: '' paths: /request: post: tags: - Requests summary: Create Request description: >- 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 operationId: requests_create parameters: - name: Idempotency-Key in: header description: >- Optional key used to safely retry the same create/initiate request without duplicating side effects. required: false schema: type: string example: a96d14c5-8e60-4f6b-9d80-5c18c0e4202a - $ref: '#/components/parameters/ApiVersion' requestBody: required: true description: >- 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). content: application/json: schema: $ref: '#/components/schemas/GenerateRequestDto' responses: '201': description: Returns information about the new request, subjects, and credentials content: application/json: schema: $ref: '#/components/schemas/GenerateRequestEntity' '400': description: |- Bad request. This can occur when: - (1) Some resource or group ids were not found - (2) Maximum credentials exceeded - (3) Some contacts were not found - (4) Other validation errors. content: application/json: schema: type: object properties: statusCode: type: number example: 404 message: type: string example: Failed to generate credentials request error: type: string example: Not Found '402': description: >- Payment required. The issuer does not have enough credits to create this request. content: application/json: schema: type: object properties: statusCode: type: number example: 402 message: type: string example: >- Insufficient credits for this action. Please top up your balance. error: type: string example: Unknown Error '409': description: >- Concurrent request conflict. Two requests for the same contact raced on subject/contact creation and the write could not be committed after the server retried. This is transient — safe to retry the identical request. content: application/json: schema: type: object properties: statusCode: type: number example: 409 message: type: string example: Try again later error: type: string example: Unknown Error components: parameters: ApiVersion: name: API-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-07-06' description: >- 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. schemas: GenerateRequestDto: type: object properties: name: type: string description: Name to be assigned to the request example: My request users: description: Array of users to be included in the request example: - contact: john.doe@example.com secondaryContact: '+351912345678' docId: '1234567890' language: ENG signerQuality: Administrator type: array items: $ref: '#/components/schemas/GenerateRequestUserDto' iframe: description: IFrame configuration for the request example: pubKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE... allOf: - $ref: '#/components/schemas/GenerateRequestIFrameDto' securityLevel: type: string description: Security level for the request enum: - CONTACT - ORGANIZATION_KYC - HUMANOS_KYC - HUMANOS_REVALIDATION default: CONTACT groupIds: description: Ids of existing group resources to be included in the request example: - '1234567890' type: array items: type: string resourcesIds: description: Ids of existing resources to be included in the request example: - '1234567890' type: array items: type: string credentials: description: Inline JSON credentials to be included in the request type: array items: $ref: '#/components/schemas/CredentialDto' internalId: type: string description: Internal identifier for the request example: order-123 authorizedDIDs: description: >- 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 type: array items: type: string required: - users GenerateRequestEntity: type: object properties: id: type: string description: Unique identifier for the request example: 507f1f77bcf86cd799439011 credentials: description: List of credentials created in this request. type: array items: $ref: '#/components/schemas/GenerateCredentialEntity' subjects: description: List of subjects (users) associated with this request type: array items: $ref: '#/components/schemas/GenerateSubjectEntity' required: - id - credentials - subjects GenerateRequestUserDto: type: object properties: contact: type: string description: Contact email or phone number example: john.doe@example.com secondaryContact: type: string description: >- Secondary contact email or phone number. When present, first contact will receive the OTP code and the secondary contact will receive the link to complete the request. example: '+351912345678' docId: type: string description: >- Known document ID of the user, expected to be returned by the KYC verification example: '1234567890' language: type: string description: >- Language for OTP notifications. Defaults to the contact phone nationality, or ENG. enum: - ENG - PRT - SPA - FRA signerQuality: type: string description: >- Signer quality for this request. Free text; if omitted for an existing member, the member quality is propagated. example: Administrator required: - contact GenerateRequestIFrameDto: type: object properties: pubKey: type: string description: >- Base64-encoded P-256 SPKI public key to pre-register for postMessage payload encryption. example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE... cookie: description: >- Trusted browser session config — skip the OTP for high-frequency approvals (HUM-6). allOf: - $ref: '#/components/schemas/GenerateRequestIFrameCookieDto' required: - pubKey CredentialDto: type: object properties: scope: type: string description: >- The scope of a credential is used to identify the context of the credential example: payments.hotel validFrom: format: date-time type: string description: >- The date from which the credential becomes valid. Must be now or later. Defaults to now if omitted. example: '2025-01-01T00:00:00.000Z' validUntil: format: date-time type: string description: The expiration date for the credential example: '2026-01-01T00:00:00.000Z' type: type: string description: >- The type of the credential, can help categorize credentials. General methods should use the type JSON - Type JSON is recommended for general use. - Type DOCUMENT should include the following unhidden fields: { label: "display name", type: "pdf" } - Type CONSENT should include the following unhidden fields: { label: "display name", type: "url" }, { label: "text", type: "string" } - Type POLICY is for action-bound credentials. Provide an 'action' (actionUrn + userParams) and omit 'data'. enum: - DOCUMENT - CONSENT - JSON - POLICY example: DOCUMENT name: type: string description: Name of the credential example: Document 1 description: type: string description: Optional description for the credential example: Employee NDA signed on 2025-01-01 internalId: type: string description: >- Identifier to help you identify the credential in your own system. We recommend using a unique value. example: internal-12345 data: description: Data associated with the credential oneOf: - type: string title: DOCUMENT description: Base64-encoded PDF document string. example: base64 encoded PDF - type: object title: CONSENT description: Consent object containing text and optional URL. example: text: I consent to the terms and conditions url: https://example.com/terms properties: text: type: string url: type: string required: - text additionalProperties: false placements: description: Predefined signature placements for document credentials type: array items: $ref: '#/components/schemas/CredentialPlacementDto' action: description: >- Reference to the action (and its userParams) bound to this credential allOf: - $ref: '#/components/schemas/ActionDto' required: - type - name GenerateCredentialEntity: type: object properties: id: type: string description: URN of the credential. example: urn:via:credential:550e8400-e29b-41d4-a716-446655440000 name: type: string description: Human-readable name of the credential; null when unset. example: Credential Name internalId: type: string description: >- Identifier to help you identify the credential in your own system. We recommend using a unique value. example: internal-12345 required: - id GenerateSubjectEntity: type: object properties: contact: type: string description: Verified contact value (email or phone) example: user@example.com id: type: string description: User's VIA identifier example: did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8 secondaryContact: type: string description: >- Secondary contact (phone or email) used in 2FA mode to receive the signing link. example: '+351912345678' link: type: string description: >- Signing link for the subject. Only present when the issuer is configured to receive the link in the response instead of Humanos delivering the OTP. example: >- https://app.humanos.id/link/507f1f77bcf86cd799439011.Ab12Cd34Ef56Gh78 required: - contact - id GenerateRequestIFrameCookieDto: type: object properties: allow: type: boolean description: >- Opt into a trusted browser session for this request (HUM-6): when true, a valid session cookie lets the subject skip the OTP on future approvals. Default false. default: false duration: type: number description: >- Trusted-session lifespan in seconds. Used ONLY when `allow` is true (ignored otherwise — no error). Clamped to [3600 (1h), 86400 (24h)]; default 3600. example: 3600 CredentialPlacementDto: type: object properties: contact: type: string description: Contact email or phone matching contacts[] example: user@example.com type: type: string description: Placement type enum: - SIGNATURE - INITIALS - IDENTITY_FIELD - OPEN_TEXT - NUMERIC - DATE - CHECKBOX identityType: type: object description: Identity field type (for IDENTITY_FIELD type) x: type: number description: X position (0-100%) 'y': type: number description: Y position (0-100%) width: type: number description: Width (0-100%) height: type: number description: Height (0-100%) pageIndex: type: number description: 0-based page index required: - contact - type - x - 'y' - width - height - pageIndex ActionDto: type: object properties: id: type: string description: The unique identifier of the action example: urn:via:action:507f1f77bcf86cd799439011 userParams: type: object description: Issuer-pinned values for the action's declared userParams example: maxAmount: 500 currency: EUR required: - id - userParams ````