Hercle
REST
POST/api/v1/end-users/{endUserId}/documents

Upload End User Document

Uploads an identity verification document for an end user. IDENTITY_VERIFICATION is the only accepted document type; any other type is rejected with 400.

Auth:Bearer <api_key>
Tags:Banking

Request

cURL
curl -X POST https://publicapi.sandbox.hercle.financial/api/v1/end-users/{endUserId}/documents \
  -H "Authorization: Bearer eyJhb..." \
  -H "Content-Type: multipart/form-data" \
  -F "type=IDENTITY_VERIFICATION" \
  -F "description=Front page of passport" \
  -F "file=@/path/to/document.pdf"

Path Parameters

NameTypeRequiredDescription
endUserIdstringYesUnique identifier of the end user (individual or business)
Example: 550e8400-e29b-41d4-a716-446655440000

Headers

NameTypeRequiredDescription
AuthorizationstringYesBearer API_KEY
Example: Bearer your_api_key_here
Content-TypestringYesmultipart/form-data
Example: multipart/form-data

Request Body

Schema

FieldTypeDescriptionRequired
typestring
Type of document being uploaded
Allowed values:
IDENTITY_VERIFICATION
Yes
descriptionstringOptional description of the documentNo
fileunknownYes

Example

{
  "type": "IDENTITY_VERIFICATION",
  "description": "Front page of passport",
  "file": "(binary)"
}

Response

Success Response Schema

FieldTypeDescription
requestIdstringUnique request identifier (UUID)
hercleDocumentIdstringHercle document identifier (UUID)
frDocumentIdstringDocument identifier at the banking provider. Empty string when frSyncStatus is FAILED
frSyncStatusstringSynchronization status with the banking provider: SYNCED or FAILED. On FAILED, errorMessage holds the reason and frDocumentId is an empty string
errorMessagestring | nullError message when the synchronization failed, or null

Upload Document Response Object

Response containing document identifiers and sync status

FieldTypeDescription
requestIdstringUnique request identifier (UUID)
hercleDocumentIdstringHercle document identifier (UUID)
frDocumentIdstringDocument identifier at the banking provider. Empty string when frSyncStatus is FAILED
frSyncStatusstringSynchronization status with the banking provider: SYNCED or FAILED. On FAILED, errorMessage holds the reason and frDocumentId is an empty string
errorMessagestring | nullError message when the synchronization failed, or null

Responses

Document successfully uploaded

200 application/json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "hercleDocumentId": "c8a3e6f1-2b7d-4f90-9e15-6a4d0b3c7f28",
  "frDocumentId": "fr_doc_456",
  "frSyncStatus": "SYNCED",
  "errorMessage": null
}

API Tester

Test this endpoint directly against the sandbox environment

Get your API key from Hercle Sandbox

Unique identifier of the end user (individual or business)

https://publicapi.sandbox.hercle.financial/api/v1/end-users/{endUserId}/documents