PHP SDK

composer require constaia/constaia-php

<?php
require __DIR__ . '/vendor/autoload.php';

$constaia = new \Constaia\Client(null, [ // null → reads CONSTAIA_API_KEY
    'base_url' => 'https://api.constaia.com', // or CONSTAIA_BASE_URL
    'timeout' => 60,                          // seconds per attempt
    'max_retries' => 2,                       // on 408, 409, 429, 5xx and network errors
    'max_concurrency' => 4,                   // parallel requests in analyzeMany()
    'headers' => [],                          // extra headers on every request
]);

$analysis = $constaia->analyze($path, [
    'expect' => ['es_dni', 'es_nie', 'passport'], // without expect, verdict is null
    'extract' => true,                            // or your own JSON Schema
    'checks' => [
        'not_expired' => true,
        'min_age_years' => 18,
        'holder' => ['full_name' => 'María García López', 'document_number' => '12345678Z'],
    ],
    'storage' => 'none',                          // none | temporary | persistent
    'ttl_hours' => 24,                            // with storage=temporary
    'keep_results' => true,
    'async' => false,                             // true → 202 and webhook
    'export' => ['xlsx'],                         // signed URLs in $analysis->exports
    'metadata' => ['registration_id' => '123'],
    'language' => 'en',                           // es | en | pt | fr

    // Request options (not sent to the API)
    'filename' => 'dni_valid.jpg',
    'idempotency_key' => 'registration-123-id',
    'timeout' => 90,
]);

$analysis->verdict->status;            // "valid" | "invalid" | "review"
$analysis['verdict']['status'];        // same, array style
$analysis->fields->document_number->value;

$analysis->verdictStatus();            // null if you sent no expect
$analysis->isValid();
$analysis->isInvalid();
$analysis->needsReview();
$analysis->isCompleted();              // false if the API answered 202
$analysis->field('birth_date');        // shortcut for fields.birth_date.value

foreach ($analysis->verdict->reasons as $reason) {
    echo $reason->code, ' (', $reason->severity, '): ', $reason->message, PHP_EOL;
}

$analysis->toArray();
json_encode($analysis);                // JsonSerializable

$constaia->lastResponse->status;       // HTTP status of the last call
$constaia->lastResponse->requestId;    // X-Request-Id: quote it when contacting support

// Classify (0.2 credits)
$c = $constaia->classify($input, ['expect' => 'invoice']);
$c->document->type;
$c->candidates[0]->confidence;

// Stored analyses
$constaia->analyses->get('an_01J…');
$page = $constaia->analyses->list([
    'limit' => 50,
    'status' => 'completed',
    'type' => 'es_dni',
    'metadata' => ['registration_id' => '123'],
]);
$constaia->analyses->delete('an_01J…');                          // { id, object, deleted: true }
$bytes = $constaia->analyses->export('an_01J…', 'xlsx');         // bytes
$constaia->analyses->export('an_01J…', 'csv', '/tmp/an.csv');    // saves to disk and returns the path

// Batches (up to 100 documents, always asynchronous)
$batch = $constaia->batches->create([
    'items' => [
        ['file_url' => 'https://example.com/a.pdf'],
        ['file_url' => 'https://example.com/b.pdf', 'options' => ['checks' => ['expected_amount' => 45]]],
    ],
    'options' => ['expect' => 'payment_receipt', 'export' => ['xlsx']],
]);
$batch = $constaia->batches->create([
    'files' => ['/tmp/a.pdf', '/tmp/b.pdf'],                      // multipart files[]
    'options' => ['expect' => 'invoice'],
]);
$constaia->batches->get($batch->id);

// Catalogue
$constaia->documentTypes->list(['language' => 'en']);
$constaia->documentTypes->get('es_dni');

// Webhook endpoints (the secret is only returned on creation)
$endpoint = $constaia->webhookEndpoints->create([
    'url' => 'https://example.com/webhooks/constaia',
    'events' => ['analysis.completed', 'analysis.review_required', 'batch.completed'],
]);
$endpoint->secret; // whsec_…
$constaia->webhookEndpoints->list();
$constaia->webhookEndpoints->get('we_01J…');
$constaia->webhookEndpoints->delete('we_01J…');

// Balance and usage
$constaia->balance();
$constaia->usage(['from' => '2026-09-01', 'to' => '2026-09-30']);

use Constaia\Exception\ConstaiaException;

$results = $constaia->analyzeMany(
    ['ana' => '/tmp/id_ana.jpg', 'luis' => '/tmp/id_luis.jpg'],
    ['expect' => 'es_dni', 'checks' => ['not_expired' => true]],
);

foreach ($results as $who => $result) {
    if ($result instanceof ConstaiaException) {
        echo "$who: error {$result->getErrorCode()}", PHP_EOL;
        continue;
    }
    echo "$who: ", $result->verdictStatus(), PHP_EOL;
}

$page = $constaia->analyses->list(['limit' => 100, 'type' => 'es_dni']);

$page->data();     // array of the current page
$page->hasMore();
$next = $page->nextPage(); // null when there are no more

foreach ($page->autoPagingIterator() as $analysis) {
    echo $analysis->id, ' ', $analysis->verdictStatus(), PHP_EOL;
}

<?php
require __DIR__ . '/vendor/autoload.php';

use Constaia\Exception\SignatureVerificationException;
use Constaia\Webhook;

$payload = file_get_contents('php://input');

try {
    $event = Webhook::verify($payload, $_SERVER, getenv('CONSTAIA_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

switch ($event['type']) {
    case 'analysis.completed':
    case 'analysis.review_required':
        // $event['data'] is the analysis
        break;
    case 'analysis.failed':
    case 'batch.completed':
    case 'credits.low':
        break;
}

http_response_code(204);

use Constaia\Exception;

try {
    $analysis = $constaia->analyze($path, ['expect' => 'es_dni']);
} catch (Exception\InsufficientCreditsException $e) {
    // Alert whoever manages the account and retry later
} catch (Exception\RateLimitException $e) {
    sleep($e->getRetryAfter() ?? 1);
} catch (Exception\InvalidRequestException $e) {
    echo $e->getErrorCode(), ' ', $e->getParam(), ': ', $e->getMessage();
} catch (Exception\ConstaiaException $e) {
    error_log(sprintf('Constaia %s %s (%s)', $e->getHttpStatus(), $e->getErrorCode(), $e->getRequestId()));
}