​
Document Verification API - Detailed Documentation

The Document Verification API enables the submission and verification of identification documents through a multi-step journey or a single-step process. It also includes optional checks for age verification and disability assessment.

​
API Playground:

You can try the openJourney endpoint here.

​
Endpoints Overview

  1. Document Verification with Journey Build-Up:
    • Open a verification journey.
    • Upload document images (front, back, selfie).
    • Initiate document verification.
  2. Single-Step Verification:
    • Upload all images in a single request.
    • Get instant verification results.
  3. Age and Disability Check:
    • Verify user eligibility based on age or disability percentage.
  4. Error Handling & Codes:
    • Standardized error messages for seamless integration.

​
Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.
  • Tokens are valid for 60 minutes and must be refreshed after expiration.
  • Refer to the Authentication for detailed steps on obtaining a token.
  • Include the token in the Authorization header as follows:
Authorization: Bearer YOUR_ACCESS_TOKEN

​
API Base URL

https://api-umbrella.io/api/services

​
1. Document Verification with Journey Build-Up

​
Description

This section covers the multi-step approach, where you first open a journey, then upload documents in steps, and finally call the verification endpoint(s).

​
1.1 Open Journey

​
Endpoint

POST /openJourney

​
Description

Starts a new verification journey where the customer can submit documents in steps.

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

None required (optional metadata can be included).

​
Response Structure

​
Example Response

{
    "journeyId": "uniqueJourneyIdentifier",
    "passThroughData": {}
}

​
1.2 Add Image

​
Endpoint

POST /addImage

​
Description

After opening a journey, you can upload an image representing the front/back of an ID or a selfie. Adds an image (front, back, or selfie) to the ongoing journey. Images can be submitted as base64-encoded strings or as file uploads.

​
Request Body Parameters

​
Example Request

{
    "journeyId": "uniqueJourneyIdentifier",
    "imageName": "uploadedFileName",
    "imageSide": "front", // or "back", "selfie"
    "storeOnly": true, // or false if classification is needed
    "imageData": "base64EncodedImagestring", // or use multipart/form-data
    "passThroughData": { "userId": "12345" }
}

​
Example Request with Multiple Images

[
  {
    "imageName": "frontImage.jpg",
    "imageSide": "front",
    "imageData": "base64EncodedFrontImage"
  },
  {
    "imageName": "backImage.jpg",
    "imageSide": "back",
    "imageData": "base64EncodedBackImage"
  },
  {
    "imageName": "selfieImage.jpg",
    "imageSide": "selfie",
    "imageData": "base64EncodedSelfieImage"
  }
]

​
1.3 Verify

​
Endpoint

POST /verify

​
Description

Once you’ve uploaded all relevant images, you can call this endpoint to verify them. Initiates the verification of all images submitted in this journey. Returns a detailed verification result (see response structure below).

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

​
Response Structure

​
Example Request

{
    "journeyId": "uniqueJourneyIdentifier"
}

​
Example Response

{
    "journeyId": "uniqueJourneyIdentifier",
    "status": "verificationComplete",
    "identitySubject": {
        "type": "person",
        "fullName": "Max Mustermann",
        "nameStructure": {
            "firstName": "Max",
            "lastName": "Mustermann",
            "nativeFullName": "Max Mustermann"
        },
        "gender": "M",
        "nationality": "DE",
        "dob": "1990/01/01",
        "addressSingleLine": "123 Main St, City, Country",
        "email": "max.mustermann@example.com",
        "mobileNumber": "+1234567890"
    },
    "authoritativeData": {
        "identityDocument": {
            "type": "passport",
            "idNumber": "123456789",
            "issuingCountry": "DE",
            "expeditor": "BH Neunkirchen",
            "expirationDate": "2030/01/01",
            "verificationChannel": "optical"
        }
    },
    "proofOfWork": {
        "type": "image",
        "titleOfProof": "IDFront",
        "timestampOfProof": "2024/08/01T10:00:00Z"
    },
    "auditTrail": {
        "workId": "abc123",
        "workStatus": "PASS",
        "workStartTst": "2024/08/01T10:00:00Z",
        "workEndTst": "2024/08/01T10:01:00Z",
        "workResult": "Verification successful"
    },
    "fraudAlerts": {
        "fraudAlertDetail": [],
        "aggregateFraudAlertScore": 0
    },
    "croppedImages": {
        "front": "base64EncodedFrontImage",
        "portrait": "base64EncodedPortraitImage",
        "signature": "base64EncodedSignatureImage",
        "back": "base64EncodedBackImage",
        "selfie": "base64EncodedSelfieImage"
    }
}

​
1.4 Verify with Age and Disability Check

​
Endpoint

POST /verify/age

​
Description

Performs an optional age/disability verification after documents are submitted. Checks if the user meets certain age or disability thresholds. Note: ageFrom and ageTo are mutually exclusive—do not use both in the same request.

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

​
Response Structure

​
Example Request

{
    "journeyId": "uniqueJourneyIdentifier",
    "ageFrom": 21,
    "ageTo": 65,
    "minDisabilityPercentage": 50
}

​
Example Response

{
    "journeyId": "uniqueJourneyIdentifier",
    "status": "ageAndDisabilityVerificationComplete",
    "ageResult": "yes", // or "no"
    "disabilityResult": "eligible" // or "not eligible"
}

​
2. Single-Step Verification

​
Description

This section describes the single-step approach, bypassing the journey creation. You must provide all images in one request.

​
2.1 Verify in One Step

​
Endpoint

POST /verify/single

​
Description

Bypasses the journey build-up and processes all images in one request. No feedback is provided if pages are missing—all must be submitted at once.

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

​
Response Structure

​
Example Request

{
  "images": [
    {
      "imageName": "frontImage.jpg",
      "imageSide": "front",
      "imageData": "base64EncodedFrontImage"
    },
    {
      "imageName": "backImage.jpg",
      "imageSide": "back",
      "imageData": "base64EncodedBackImage"
    }
  ]
}

​
3. Error Handling & Codes

Below is how the Document Verification API handles errors. This section is divided into:
  1. General HTTP Status Codes - which apply across all endpoints.
  2. Generic Error Response Structure - the standard JSON format returned in error cases.
  3. Endpoint-Specific Error Scenarios - a reference table detailing common error codes for each endpoint.

​
3.1 General HTTP Status Codes

HTTP StatusMeaningDescription
200OKRequest succeeded. See response body for details.
400Bad RequestThe request was invalid or missing required parameters.
401UnauthorizedAuthentication failed or the user lacks valid credentials.
403ForbiddenThe user does not have permission to perform this operation.
404Not FoundResource or endpoint not found.
422Unprocessable EntityThe request is understood, but cannot be processed (e.g., malformed base64 or missing data).
429Too Many RequestsRate limit exceeded.
500Internal Server ErrorA generic server-side error occurred.

​
3.2 Generic Error Response Structure

When an error occurs (i.e., a 4xx or 5xx status code), the API returns a JSON body with the following format:

​
Response Structure

​
Example Response

{
    "errorCode": "invalidImageData",
    "errorMessage": "The imageSide must be one of [front, back, selfie].",
    "details": {
      "field": "imageSide"
    }
}
  • errorCode is particularly useful for programmatic checks in client applications.
  • errorMessage should help developers quickly understand what went wrong.
  • details can be omitted if no extra info is needed.

​
3.3 Endpoint-Specific Error Scenarios

Each endpoint may have unique validation or domain-specific constraints. The table below summarizes common error codes per endpoint. All error responses conform to the Generic Error Response Structure above.
EndpointError CodeHTTP StatusError MessageDescription
/openJourneyjourneyAlreadyExists400A journey already exists for this user/session.Occurs if the client tries to open a new journey while one is still active.
/addImageinvalidImageData400Base64 string is malformed or missing.Triggered if imageData is not valid base64 or is absent.
journeyNotFound404No active journey with the given journeyId.The provided journeyId does not exist or has already been closed.
/verifyjourneyNotFound404No active journey with the given journeyId.Attempted verification on an invalid or missing journeyId.
missingImages422Required images (front/back/selfie) were not all provided.Verification could not be completed because essential images are missing.
/verify/agemutuallyExclusive400ageFrom and ageTo cannot both be specified.The request included both ageFrom and ageTo, which is not allowed.
journeyNotFound404No active journey with the given journeyId.As above.
/verify/singlemissingImages422Not all necessary images (front/back) were provided.Single-step verification requires all images in a single request.
invalidImageData400Base64 string is malformed or missing.Same as above, but specifically applies to single-step scenarios.

​
3.4 Handling Errors

  1. Check the HTTP status code returned from the API.
  2. Parse the JSON if the status code indicates an error (4xx or 5xx).
  3. Use errorCode to determine the type of error (e.g., JOURNEY_NOT_FOUND), and handle it in your client application (e.g., show a specific user message).
  4. Look at errorMessage for a human-readable explanation of the issue.
  5. Examine details if present, to get more granular context (e.g., which field triggered the error).