Developer documentation

API Reference#

IdScanly Identity Document Scanning API - v1

The IdScanly API accepts one or more identity document images in a session, processes them asynchronously, and exposes partial and final recognition results through polling or an optional wait-on-upload mode.

Base URL#

https://bck.idscanly.com/api/v1

All examples below use:

BASE_URL="https://bck.idscanly.com/api/v1"
      API_KEY="idscanly_live_replace_me"

Authentication#

Send the API key in the x-api-key header on every request.

x-api-key: idscanly_live_replace_me

curl -H "x-api-key: $API_KEY" "$BASE_URL/stats/today"

Missing, invalid, disabled, or expired keys return:

HTTP/1.1 401 Unauthorized
      Cache-Control: no-store

{
        "error": "Invalid or expired API key",
        "code": "UNAUTHORIZED",
        "requestId": "req-123"
      }

API keys are provisioned by IdScanly. Contact support and provide the partner or application name, technical contact, and intended environment.

Image Requirements#

The server validates actual image content, not only the MIME header. HEIC/HEIF uploads are decoded server-side before preprocessing and OCR.

Recommended capture#

• •Show the entire document - avoid cut-off corners
• •Use sufficient light without glare
• •Keep text reasonably sharp
• •Use the highest practical resolution
• •Upload front and back as separate images in the same session

1. Create a Session#

No request body is required. Returns a session ID and upload URL.

curl -X POST \
        -H "x-api-key: $API_KEY" \
        "$BASE_URL/sessions"

Response 201 Created

{
        "success": true,
        "sessionId": "9c5c6e9c-73b6-4976-a84f-527a98552713",
        "isProcessing": false,
        "status": "waiting_for_images",
        "uploadUrl": "/v1/sessions/9c5c6e9c-73b6-4976-a84f-527a98552713/images",
        "resultUrl": "/v1/sessions/9c5c6e9c-73b6-4976-a84f-527a98552713"
      }

2. Upload an Image#

SESSION_ID="9c5c6e9c-73b6-4976-a84f-527a98552713"
      
      curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@front.jpg" \
        "$BASE_URL/sessions/$SESSION_ID/images"

Optional document crop#

Enable automatic ID detection and cropping with the crop=true query parameter. Accepted values: true, false, 1, 0, yes, no, on, and off. Disabled by default.

curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@front.jpg" \
        "$BASE_URL/sessions/$SESSION_ID/images?crop=true"

Use crop when the ID occupies only part of a larger photograph. Leave disabled when the image is already tightly framed.

Response 202 Accepted

{
        "success": true,
        "imageId": "5f4fc156-c08d-4cd0-b9f6-5112eb13178e",
        "sessionId": "9c5c6e9c-73b6-4976-a84f-527a98552713",
        "status": "queued",
        "cropEnabled": false,
        "resultUrl": "/v1/sessions/9c5c6e9c-73b6-4976-a84f-527a98552713"
      }

202 means accepted for processing. It does not mean recognition has finished.

Optionally wait for the final result#

Add wait=true only when uploading the known final image of a session. The request remains open until every queued or running image in that session finishes. Use view=summary for the compact response.

curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@back.jpg" \
        "$BASE_URL/sessions/$SESSION_ID/images?wait=true&view=summary"

Accepted values are true, false, 1 and 0. Without this option, uploads retain the immediate 202 behavior.

Completed response 200 OK

{
        "success": true,
        "sessionId": "9c5c6e9c-73b6-4976-a84f-527a98552713",
        "status": "finished",
        "isProcessing": false,
        "result": { "fields": { "documentNumber": "123456AB" } },
        "imageId": "5f4fc156-c08d-4cd0-b9f6-5112eb13178e",
        "cropEnabled": false,
        "resultUrl": "/v1/sessions/9c5c6e9c-73b6-4976-a84f-527a98552713",
        "waitTimedOut": false
      }

Upload earlier images asynchronously and do not append more images after starting the final wait request. Wait mode does not seal the session.

Upload a base64 image#

Use the dedicated base64 endpoint when the client cannot send multipart form data.

IMAGE_BASE64="$(base64 -w 0 front.jpg)"
      
      curl -X POST \
        -H "x-api-key: $API_KEY" \
        -H "content-type: application/json" \
        -d "{\"imageBase64\":\"$IMAGE_BASE64\",\"filename\":\"front.jpg\",\"mimeType\":\"image/jpeg\"}" \
        "$BASE_URL/sessions/$SESSION_ID/images/base64"

JSON body

{
        "imageBase64": "/9j/4AAQSkZJRgABAQ...",
        "filename": "front.jpg",
        "mimeType": "image/jpeg"
      }

imageBase64 may also be a data URL. When a data URL is used, mimeType is optional. The response is the same 202 Accepted payload returned by multipart uploads. Base64 uploads also support wait=true&view=summary.

Add more images#

Upload each additional image (e.g. back of the document) in a separate request using the same session ID. Do not create a separate session for each side of the same document.

curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@back.jpg" \
        "$BASE_URL/sessions/$SESSION_ID/images"

Upload without explicit session creation#

A compatibility endpoint that creates a session automatically:

# Creates a new session automatically
      curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@front.jpg" \
        "$BASE_URL/session-images"
      
      # Append to an existing session
      curl -X POST \
        -H "x-api-key: $API_KEY" \
        -F "image=@back.jpg" \
        "$BASE_URL/session-images?sessionId=$SESSION_ID"

For new integrations, the explicit POST /sessions → POST /sessions/{sessionId}/images workflow is preferred.

The same compatibility behavior is available for base64 uploads. Both compatibility endpoints accept wait=true; use it only on the final image:

curl -X POST \
        -H "x-api-key: $API_KEY" \
        -H "content-type: application/json" \
        -d "{\"imageBase64\":\"$IMAGE_BASE64\",\"filename\":\"front.jpg\",\"mimeType\":\"image/jpeg\"}" \
        "$BASE_URL/session-images/base64"

3. Poll Results#

curl \
        -H "x-api-key: $API_KEY" \
        "$BASE_URL/sessions/$SESSION_ID?view=summary"

Example response (still processing)

{
        "success": true,
        "sessionId": "22222222-2222-4222-8222-222222222222",
        "status": "processing",
        "isProcessing": true,
        "summary": null,
        "result": null,
        "images": [
          {
            "imageId": "11111111-1111-4111-8111-111111111111",
            "status": "running",
            "sourceName": "example-front.jpg",
            "fieldCount": 0,
            "avgConfidence": 0,
            "mrzFound": false,
            "hasExternalResult": false,
            "externalResultUpdatedAt": null,
            "error": null,
            "updatedAt": "2026-09-05T10:00:00.000Z",
            "completedAt": null
          }
        ],
        "createdAt": "2026-09-05T10:00:00.000Z",
        "updatedAt": "2026-09-05T10:00:00.000Z",
        "completedAt": null
      }

Full diagnostic view#

Omitting ?view=summary returns the full response including per-image OCR blocks, candidates, recognition layer details, preprocessing timings and logs. Use only for controlled diagnostics.

Session Status Values#

Image status values#

Response JSON reference#

Read this reference alongside the endpoint examples. It distinguishes the response envelope, the merged document result, and image-level diagnostic data; these objects have different meanings even when their property names overlap.

{
  "success": true,
  "sessionId": "22222222-2222-4222-8222-222222222222",
  "status": "processing",
  "isProcessing": true,
  "summary": null,
  "result": null,
  "images": [
    {
      "imageId": "11111111-1111-4111-8111-111111111111",
      "status": "running",
      "sourceName": "example-front.jpg",
      "fieldCount": 0,
      "avgConfidence": 0,
      "mrzFound": false,
      "hasExternalResult": false,
      "externalResultUpdatedAt": null,
      "error": null,
      "updatedAt": "2026-09-05T10:00:00.000Z",
      "completedAt": null
    }
  ],
  "createdAt": "2026-09-05T10:00:00.000Z",
  "updatedAt": "2026-09-05T10:00:00.000Z",
  "completedAt": null
}

{
  "status": "partial_or_complete",
  "isComplete": true,
  "imageCount": 1,
  "successfulImageCount": 1,
  "failedImageCount": 0,
  "fieldCount": 8,
  "runtime": {
    "startedAt": "2026-09-05T10:00:00.000Z",
    "finishedAt": "2026-09-05T10:00:02.400Z",
    "durationMs": 2400
  },
  "fields": {
    "documentType": "passport",
    "documentCountry": "GBR",
    "documentNumber": "000123456",
    "surname": "SMITH",
    "givenNames": "JANE",
    "fullName": "SMITH JANE",
    "dateOfBirth": "1990-04-12",
    "dateOfExpiry": "2030-04-12",
    "displayName": "JANE SMITH",
    "nameOrder": "given_surname"
  },
  "fieldConfidences": {
    "documentType": 0.97,
    "documentCountry": 0.97,
    "documentNumber": 0.97,
    "surname": 0.97,
    "givenNames": 0.97,
    "fullName": 0.97,
    "dateOfBirth": 0.97,
    "dateOfExpiry": 0.97,
    "displayName": 0.97,
    "nameOrder": 0.97
  },
  "fieldSources": {
    "documentType": {
      "value": "passport",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "documentCountry": {
      "value": "GBR",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "documentNumber": {
      "value": "000123456",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "surname": {
      "value": "SMITH",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "givenNames": {
      "value": "JANE",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "fullName": {
      "value": "SMITH JANE",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "dateOfBirth": {
      "value": "1990-04-12",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "dateOfExpiry": {
      "value": "2030-04-12",
      "source": "ocr_fields",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "displayName": {
      "value": "JANE SMITH",
      "source": "name_display",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    },
    "nameOrder": {
      "value": "given_surname",
      "source": "country_name_order",
      "imageId": "11111111-1111-4111-8111-111111111111",
      "confidence": 0.97
    }
  },
  "documents": [
    {
      "type": "passport",
      "country": "GBR",
      "signals": [
        "session-field-merge"
      ],
      "confidence": 0.97
    }
  ],
  "mrz": [],
  "images": [
    {
      "imageId": "11111111-1111-4111-8111-111111111111",
      "status": "done",
      "runtimeMs": 2400,
      "flags": [],
      "extractorCoverage": null,
      "avgConfidence": 0.97,
      "fieldCount": 8,
      "mrzFound": false,
      "captureFeedback": {
        "status": "ok",
        "items": []
      },
      "readSuccess": true,
      "readFailureReason": null,
      "error": null
    }
  ],
  "captureFeedback": {
    "status": "ok",
    "items": []
  },
  "flags": [],
  "requiresReview": false,
  "reviewReasons": [],
  "identityConflict": {
    "detected": false,
    "mergeAllowed": true,
    "images": []
  }
}

Merged Result#

The merged result is available under summary.fields or result.fields in both views. These contain the same merged data.

Available field names#

fields is extensible rather than a fixed schema. These names are currently produced by document classification, MRZ parsing, extraction, or final session merge.

Normalized dates use YYYY-MM-DD when evidence is sufficient. Country fields normally use uppercase ISO 3166-1 alpha-3 codes. Keep identifiers as strings because leading zeros are significant. visibleDates is an array of unassigned normalized date candidates. displayName and nameOrder are derived and do not increase fieldCount.

Capture Feedback#

result.captureFeedback reports capture and readability problems in a stable, machine-readable form. It is also present in summary.captureFeedback. Per-image details are available under result.images[].captureFeedback.

Example#

{
        "status": "warning",
        "items": [
          {
            "code": "image_blurry",
            "severity": "warning",
            "status": "unresolved",
            "message": "The image may be too blurry to read reliably.",
            "messageKey": "capture.image_blurry",
            "suggestedAction": "Hold the camera steady, move closer, and take another photo.",
            "evidence": {
              "laplacianVariance": 189.77,
              "avgConfidence": 0.699
            },
            "imageIds": ["3e3c7eff-aee5-47fd-aa1b-9f8d40af83ae"]
          }
        ]
      }

Status values#

Item properties#

Issue codes#

Suggested actions#

Default English values of suggestedAction are listed below. This field contains guidance text, not an action code. Automatically corrected issues return JSON null, so no user action is needed. Use the issue code for application logic and localization; do not match the English text.

When document_data_page_required is returned, ask the user to open the passport on the photo and personal-data page and capture that page instead. In multi-image sessions, aggregate missing_required_fields is suppressed when another image recovered all missing fields. Branch on code, status, and severity, not numeric evidence thresholds.

Statistics#

Daily API stats#

Returns statistics for the current UTC day. The request itself is included in apiRequests.total.

Weekly API stats#

Returns statistics from Monday through the current day in UTC.

Monthly API stats#

Returns statistics from the first day of the current month through the current day in UTC.

Statistics response#

All three endpoints use the same response shape. Country, document type, and failure-reason breakdowns contain at most the ten most frequent values in the selected period.

{
        "period": "month",
        "fromDate": "2026-08-01",
        "toDate": "2026-08-29",
        "apiRequests": {
          "total": 18540
        },
        "sessions": {
          "created": 4120,
          "completed": 4055,
          "withReadableResult": 3920,
          "withoutReadableResult": 135
        },
        "images": {
          "uploaded": 6890,
          "processed": 6844,
          "readSuccessful": 6530,
          "readFailed": 314,
          "processingErrors": 21,
          "readSuccessRate": 95.41
        },
        "performance": {
          "averageProcessingTimeMs": 2840
        },
        "quality": {
          "averageFieldCount": 7.4,
          "averageConfidence": 0.91
        },
        "failureReasons": [
          { "reason": "document_not_found", "count": 82 },
          { "reason": "required_fields_missing", "count": 64 }
        ],
        "documentTypes": [
          {
            "documentType": "identity_card",
            "count": 3560,
            "readSuccessful": 3420,
            "readFailed": 140
          }
        ],
        "countries": [
          {
            "country": "POL",
            "count": 1240,
            "readSuccessful": 1190,
            "readFailed": 50
          }
        ]
      }

Statistics field meanings#

Creation, upload, processing, and completion are counted on the UTC date when each event occurs. A session created before the selected period may therefore be counted as completed inside the period. Statistics are read from daily aggregates rather than scanning individual image records.

Session and uploaded-image counters are collected from the statistics-rollup deployment onward; historical sessions are not scanned or estimated automatically.

Error Responses#

Unknown session 404 Not Found#

{ "error": "Session not found" }

A session created by one API key is not visible to another API key.

Invalid upload 400 Bad Request#

{
        "error": "Uploaded file is not a valid supported image",
        "code": "INVALID_UPLOAD",
        "requestId": "req-124"
      }

File too large 413 Payload Too Large#

{
        "error": "request file too large",
        "code": "PAYLOAD_TOO_LARGE",
        "requestId": "req-125"
      }

Session image limit 400 Bad Request#

{
        "error": "Session image limit reached (10)",
        "code": "INVALID_UPLOAD",
        "requestId": "req-126"
      }

JavaScript Example#

Run this example on your backend with the front and back image buffers. Keep the API key secret. Use the partial callback to forward available fields to your UI; a late partial response is ignored once the final upload response arrives.

// Server-side example. Supply frontBuffer and backBuffer from your own backend.
// Keep the API key secret; configure client/proxy timeouts for at least 310 seconds.
const baseUrl = 'https://bck.idscanly.com/api/v1';
const headers = { 'x-api-key': process.env.IDSCANLY_API_KEY };

async function scanDocument(frontBuffer, backBuffer, onPartial = () => {}) {
  // 1. Create one session for all sides and retakes of this document.
  const created = await fetch(`${baseUrl}/sessions`, {
    method: 'POST', headers,
  }).then(readJson);
  const sessionUrl = `${baseUrl}/sessions/${created.sessionId}`;

  // 2. Upload the first photo immediately. The 202 response is an acknowledgement.
  await upload(frontBuffer, 'front.jpg', false);
  // Add any retakes or other sides here with wait=false, in this same session.

  // 3. Upload the known final photo and wait for all queued/running images.
  let finalResponseReceived = false;
  const finalUpload = upload(backBuffer, 'back.jpg', true).then((snapshot) => {
    finalResponseReceived = true;
    return snapshot;
  });

  // 4. Read partial data once while the last upload is waiting.
  // The GET may return no fields yet. Its failure does not cancel the upload.
  void fetch(`${sessionUrl}?view=summary`, { headers }).then(readJson)
    .then((snapshot) => {
      if (!finalResponseReceived && snapshot.result) {
        onPartial(snapshot.result.fields);
      }
    }).catch(() => { /* Optional partial preview unavailable. */ });

  let session = await finalUpload;
  // 5. After a wait timeout (202, waitTimedOut: true), poll as fallback.
  while (session.isProcessing) {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    session = await fetch(`${sessionUrl}?view=summary`, { headers }).then(readJson);
  }
  if (session.status === 'failed' || !session.result) {
    throw new Error('No usable session result; review or recapture the document.');
  }
  return session;

  function upload(buffer, filename, wait) {
    const form = new FormData();
    form.append('image', new Blob([buffer], { type: 'image/jpeg' }), filename);
    return fetch(`${sessionUrl}/images?wait=${wait}&view=summary`, {
      method: 'POST', headers, body: form,
    }).then(readJson);
  }
}

const session = await scanDocument(frontBuffer, backBuffer, (fields) => {
  // Forward partial fields to your application's UI over your own secure channel.
});
// Before accepting session.result.fields, check required fields, confidence,
// requiresReview and identityConflict. A completed request can still need review.

async function readJson(response) {
  const payload = await response.json();
  if (!response.ok) throw new Error(payload.error || `HTTP ${response.status}`);
  return payload;
}

For HEIC images, adapt the upload helper to use the original filename and MIME type:

form.append(
        'image',
        new Blob([heicBuffer], { type: 'image/heic' }),
        'front.heic'
      );

Privacy Notes#

Send images over encrypted HTTPS. IdScanly processes document images without retaining them or the extracted personal data, and does not write processing log files. Only broad, aggregate document statistics, such as country and type, are retained. Diagnostic fields in an API response describe processing results; they are not log files.

Identity document images and extracted fields are sensitive personal data. API responses include Cache-Control: no-store, but clients must also:

• •Avoid browser caching of responses
• •Encrypt data in transit and at rest
• •Avoid placing fields in URLs
• •Avoid logging full response bodies
• •Delete local temporary files promptly
• •Restrict access to diagnostic responses
• •Comply with applicable privacy and retention requirements