Identity API requests¶

Parameters¶

The API system allows you to automate identity document validation through a simple HTTP POST request.

The accepted parameters are listed in the table below:

Parameter	Type	Required	Description
`file`	File	Yes	Identity document 1 page in PDF or image format.
`api_key`	string	Yes	Your API key.
`format`	string	No	Response format: `json` (default) or `xml`.

Example calls in different languages¶

cURL¶

cURL (macOS/Linux)

curl -X POST 'https://api.app.trustdochub.com/api/identity/v1' \
  -F format=json \
  -F "api_key=<YOUR_API_KEY>" \
  -F "file=@/path/to/file.jpg"

Java¶

Java

public String sendIdFileAndGetResults(MultipartFile file) {

WebClient client = WebClient.create();

MultipartBodyBuilder builder = new MultipartBodyBuilder();
builder.part("file", file.getResource());
builder.part("api_key", {{ YOUR_API_KEY }});

return client.post()
.uri(URI.create("https://api.app.trustdochub.com/api/identity/v1"))
.contentType(MediaType.MULTIPART_FORM_DATA)
.body(BodyInserters.fromMultipartData(builder.build()))
.retrieve()
.bodyToMono(String.class)
.block();
}

Python¶

Python

import requests

url = 'https://api.app.trustdochub.com/api/identity/v1'
data = {'api_key': '{{ YOUR_API_KEY }}'}

with open('file.txt', 'rb') as file:
    response = requests.post(url, data=data, files={'file': file})

print(response.text)

Node¶

Node

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

(async () => {
  const form = new FormData();
  form.append('file', fs.createReadStream('<PATH_TO_FILE>')); // ex: ./idcard.jpg
  form.append('api_key', '<YOUR_API_KEY>');
  form.append('format', 'json'); // ou 'xml'

  try {
    const res = await axios.post(
      'https://api.app.trustdochub.com/api/identity/v1',
      form,
      { headers: form.getHeaders(), timeout: 30000 }
    );
    console.log('Response:', res.data);
  } catch (err) {
    if (err.response) {
      console.error('Server error:', err.response.status, err.response.data);
    } else if (err.request) {
      console.error('No response:', err.request);
    } else {
      console.error('Request setup error:', err.message);
    }
  }
})();

PHP¶

PHP

<?php
// Installer: composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$endpoint = 'https://api.app.trustdochub.com/api/identity/v1';
$filePath = '<PATH_TO_FILE>';   // ex: /var/data/idcard.jpg
$apiKey   = '<YOUR_API_KEY>';   // votre clé API

if (!is_file($filePath)) {
  die('Fichier introuvable: ' . $filePath);
}

$client = new Client(['timeout' => 30.0]);

try {
  $response = $client->post($endpoint, [
    'multipart' => [
      [
        'name'     => 'file',
        'contents' => fopen($filePath, 'r'),
        // 'filename' => basename($filePath),           // optionnel
        // 'headers'  => ['Content-Type' => 'image/jpeg'] // optionnel
      ],
      [ 'name' => 'api_key', 'contents' => $apiKey ],
      [ 'name' => 'format',  'contents' => 'json' ]   // ou 'xml'
    ],
    'verify' => true, // laissez à true en prod (certificats SSL)
  ]);

  echo 'HTTP: ' . $response->getStatusCode() . PHP_EOL;
  echo $response->getBody();

} catch (RequestException $e) {
  if ($e->hasResponse()) {
    echo 'Erreur serveur: ' . $e->getResponse()->getStatusCode() . PHP_EOL;
    echo (string) $e->getResponse()->getBody();
  } else {
    echo 'Erreur requête: ' . $e->getMessage();
  }
}

Status codes¶

The following codes are returned by the API:

API response codes¶

Code	Type	Description
`200`	Verification OK	The verification was successful.
`401`	Unauthorized	The API key is not valid.
`402`	Insufficient credits	No verification credits left for the given period.
`422`	Unreadable document	The document could not be recognized or is invalid.

Responses¶

JSON format¶

You can retrieve results in JSON format.

To do so, add the parameter format=json to your request, or simply omit the format parameter.

Below are sample responses depending on the document type:

Passports¶

{
    "documentInfos": {
        "numberOfCharacters": "88",
        "documentType": "PASSPORT",
        "country": "NLD",
        "lastName": "DE BRUIJN",
        "firstNames": [
            "WILLEKE",
            "LISELOTTE"
        ],
        "dateOfBirth": "1965-03-10",
        "gender": "Female",
        "documentNumber": "SPECI2014",
        "nationality": "NLD",
        "personalNumber": "999999990<<<<<",
        "expirationDate": "2024-03-09"
    },
    "documentInfosValidation": {
        "numberOfCharactersValid": true,
        "documentTypeValid": true,
        "lastNameValid": true,
        "dateOfBirthValid": true,
        "genderValid": true,
        "expirationDateValid": true
    },
    "controlKeys": {
        "expirationDateControlKey": true,
        "personalNumberControlKey": true,
        "dateOfBirthControlKey": true,
        "globalControlKey": true,
        "line2ControlKey": true
    }
}

Residence permit¶

(example of a French document)

{
  "documentInfos": {
    "numberOfCharacters": "90",
    "documentType": "FR_RESIDENCE_PERMIT",
    "country": "FRA",
    "lastName": "TRAORE",
    "firstNames": [
      "SALIMAH"
    ],
    "dateOfBirth": "1988-01-01",
    "gender": "Female",
    "documentNumber": "3MBMONSFJ",
    "personalNumber": "5903000242",
    "nationality": "SEN",
    "expirationDate": "2030-09-17"
  },
  "documentInfosValidation": {
    "numberOfCharactersValid": true,
    "documentTypeValid": true,
    "countryValid": true,
    "lastNameValid": true,
    "dateOfBirthValid": true,
    "genderValid": true,
    "documentNumberValid": true,
    "personalNumberValid": true,
    "nationalityValid": true,
    "expirationDateValid": true
  },
  "controlKeys": {
    "expirationDateControlKey": true,
    "documentNumberControlKey": true,
    "dateOfBirthControlKey": true,
    "globalControlKey": false
  }
}

Biometric ID card¶

(example of a Spanish ID card)

{
  "documentInfos": {
    "numberOfCharacters": "90",
    "documentType": "ES_BIOMETRIC_ID_CARD",
    "country": "ESP",
    "lastName": "ESPANOLA ESPANOLA",
    "firstNames": [
      "CARMEN"
    ],
    "dateOfBirth": "1980-01-01",
    "gender": "Female",
    "documentNumber": "CAA000000",
    "dniNumber": "99999999R",
    "nationality": "ESP",
    "expirationDate": "2031-06-02"
  },
  "documentInfosValidation": {
    "numberOfCharactersValid": true,
    "documentTypeValid": true,
    "lastNameValid": true,
    "dateOfBirthValid": true,
    "genderValid": true,
    "countryValid": true,
    "documentNumberValid": true,
    "nationalityValid": true,
    "expirationDateValid": true
  },
  "controlKeys": {
    "expirationDateControlKey": true,
    "documentNumberControlKey": true,
    "dateOfBirthControlKey": true,
    "globalControlKey": true
  }
}

Biometric driving licence¶

(example of a French driving licence)

{
  "documentInfos": {
    "numberOfCharacters": "30",
    "documentType": "FR_DRIVING_LICENCE",
    "country": "FRA",
    "lastName": "MARTIN",
    "documentNumber": "13AA00002",
    "expirationDate": "2018-12-31"
  },
  "documentInfosValidation": {
    "numberOfCharactersValid": true,
    "documentTypeValid": true,
    "lastNameValid": true,
    "countryValid": true,
    "documentNumberValid": true,
    "expirationDateValid": true
  },
  "controlKeys": {
    "documentNumberControlKey": true,
    "globalControlKey": true
  }
}

US passport card¶

{
  "documentInfos": {
    "numberOfCharacters": "90",
    "documentType": "US_PASSPORT_CARD",
    "country": "USA",
    "lastName": "BARNES I",
    "firstNames": [
      "ARLO",
      "JAMES"
    ],
    "dateOfBirth": "1994-09-27",
    "gender": "Male",
    "documentNumber": "C13549388",
    "nationality": "USA",
    "expirationDate": "2026-11-21",
    "stateDepDocControlNumber": "792818960"
  },
  "documentInfosValidation": {
    "numberOfCharactersValid": true,
    "documentTypeValid": true,
    "countryValid": true,
    "lastNameValid": true,
    "dateOfBirthValid": true,
    "genderValid": true,
    "documentNumberValid": true,
    "nationalityValid": true,
    "expirationDateValid": true
  },
  "controlKeys": {
    "expirationDateControlKey": true,
    "documentNumberControlKey": true,
    "dateOfBirthControlKey": true,
    "globalControlKey": false
  }
}

US border crossing card¶

{
  "documentInfos": {
    "numberOfCharacters": "90",
    "documentType": "US_BORDER_CROSSING_CARD",
    "country": "USA",
    "lastName": "VIAJERA DE LA FRONTERA",
    "firstNames": [
      "F"
    ],
    "dateOfBirth": "1981-05-05",
    "gender": "Female",
    "documentNumber": "786000118",
    "visaNumber": "MEX004214033",
    "nationality": "MEX",
    "expirationDate": "2018-08-06"
  },
  "documentInfosValidation": {
    "numberOfCharactersValid": true,
    "documentTypeValid": true,
    "countryValid": true,
    "lastNameValid": true,
    "dateOfBirthValid": true,
    "genderValid": true,
    "documentNumberValid": true,
    "nationalityValid": true,
    "expirationDateValid": true
  },
  "controlKeys": {
    "expirationDateControlKey": true,
    "documentNumberControlKey": false,
    "dateOfBirthControlKey": true,
    "globalControlKey": false
  }
}

XML format¶

The second response format available is XML.

To get XML, set the parameter format=xml in your request.