Requêtes de l'API identité¶

Paramètres¶

Le système API vous permet d’automatiser la validation des documents d’identité via une simple requête HTTP POST.

Les paramètres acceptés sont listés dans le tableau ci-dessous :

Paramètre	Type	Obligatoire	Description
`file`	Fichier	Oui	Pièce d’identité 1 page au format PDF ou image.
`api_key`	string	Oui	Votre clé API.
`format`	string	Non	Format de réponse : `json` (défaut) ou `xml`.

Exemples d'appels sur différents langages¶

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¶

Les codes suivants sont retournés par l’API :

Codes de réponse API¶

Code	Type	Description
`200`	Vérification ok	La vérification s’est bien déroulée.
`401`	Non autorisé	La clé API n’est pas correcte.
`402`	Crédits insuffisants	Il n’y a plus de crédits de vérification pour la période donnée.
`422`	Document illisible	Le document n’est pas reconnu ou incorrect.

Réponses¶

Format JSON¶

Vous pouvez obtenir les résultats au format JSON.

Pour cela il suffit d’ajouter le paramètre « format=json » dans votre requête, ou de ne pas ajouter le paramètre « format ».

Voici les réponses possibles en fonction des documents :

Passeports¶

{
    "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
    }
}

Titre de séjour / Permis de séjour¶

(exemple d'un document français)

{
  "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
  }
}

Carte d'identité biométrique¶

(exemple d'une CNI espagnole)

{
  "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
  }
}

Permis de conduire biométrique¶

(exemple d'un permis de conduire français)

{
  "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
  }
}

Format XML¶

Deuxième type de format disponible pour les réponses : le format XML.

Pour cela, il suffit d’ajouter le paramètre « format » « xml » à votre requête.