External Integration Guide

This page walks through Insyko's capabilities: what each one does, and how it's exposed. Two categories: some capabilities are already exposed as API calls for your own backend (as in the Integration Guide); others are configured through the Insyko back office — the admin system you log into and operate yourselves.

Each capability links to its exact operation in the live API reference (test.api.insyko.com/docs), where you can see the full request/response schema. Anything listed as not available today can be scoped on request.

1. Identity document verification

Accepted document types: passport, national ID card, driver's licence, residence permit. Which are offered to a given applicant is a back-office setting.

Capture: the applicant captures both sides of the document as part of the hosted onboarding session (see Redirect URL to onboarding session). Back-side capture is mandatory for document types that have one; passports only need the photo page.

Requiring two proofs of identity (e.g. "in Czechia, any two of the accepted types") is a back-office flow configuration (§5).

What data you get back

Endpoint: GET /api/v1/onboardings/{onboardingCompletionId} — see Endpoint 2: Get applicant status.

The document comes back under data.identityVerifications:

json

{
  "data": {
    "identityVerifications": [
      {
        "id": 1245,
        "documentType": { "name": "PASSPORT", "value": "passport", "displayValue": "Passport" },
        "documentNumber": "A1234567",
        "dateOfIssue": "2020-01-15",
        "dateOfExpiry": "2030-01-15",
        "issueAuthority": "Department of State",
        "documentFront": { "url": "https://.../document-front.jpg" },
        "documentBack": { "url": "https://.../document-back.jpg" },
        "selfie": { "url": "https://.../selfie.jpg" },
        "completedAt": "2026-06-24T10:00:05Z"
      }
    ]
  }
}

Field naming

Every response field is camelCase (dateOfExpiry, not date_of_expiry) — everywhere in the API, not just here.

The applicant's profile (same response) also carries:

Field	Description
`name`, `surname`	As printed on the document.
`dateOfBirth`	Extracted date of birth.
`personalNumber`	National ID number — see below for Czech/Slovak.
`nationality`	ISO country code.
`gender`	`M`, `F`, or unspecified.
`placeOfBirth`, `surnameAtBirth`	Where present on the document type.
`addresses`	Structured addresses (`type`, `street`, `zipCode`, `city`, `country`) — see the note below on address/document linkage.

Czech & Slovak birth number (rodné číslo): extracted automatically into personalNumber, including the Slovak card layout introduced after 17 December 2024.

Expiration tracking

An opt-in, per-project back-office setting:

Configured via: PUT /api/v1/projects/{projectId}/aml/verification/settings/{amlVerificationSettingsId} — the "reverify on document expiry" setting: notify, notifyBeforeDays, dueDays.

While an applicant is in that window, their profile carries pendingReverification: true and a reverificationDueAt date — check those rather than computing expiry yourself.

To update a document after renewal, without re-running the whole verification:

Endpoint: POST /api/external/v1/identity-verifications/{workflowRunId}

json

{ "document": { "document_number": "B7654321", "date_of_expiry": "2032-01-15" } }

Only the fields you send are changed. Same auth as the rest of your backend calls (API Key + Signature). Note request bodies accept snake_case or camelCase; responses are always camelCase.

Not available today

NFC chip reading (ePassports / eID cards via mobile device) — on our roadmap.
Video-capture mode — on our roadmap.
Per-address document linkage — we don't yet tag an applicant's addresses with which document they came from when they've submitted more than one document with an address.

2. Biometrics & liveness

Biometric checks happen in the same guided session as document capture — a selfie, and optionally a short challenge sequence, each submitted as one step of the onboarding.

Passive liveness: every selfie is checked for spoofing (photo-of-a-photo, screen replay, mask) automatically, no extra action from the applicant.

Active/challenge liveness: an optional sequence — smile, neutral expression, looking in each of four directions. Whether it runs, and which challenges, is configured per workflow; default can be passive-only.

Face-match: the selfie is compared to the document photo, threshold configured per workflow.

What you get back

No raw score — pass/fail feeds into the applicant's overall status rather than being exposed as a number. The selfie photo itself is in data.identityVerifications[].selfie (§1). Outcome:

`globalStatus`	Meaning
`approved`	Passed document + biometric checks (and AML screening, if enabled).
`wating_for_check`	Below auto-approve threshold, routed to manual review.
`rejected`	Failed a configured check.
`pending`	Still in progress.

Not available today

Deepfake detection as a distinct signal — we currently return a failed face-match as one outcome; we don't separate "no match" from "looks synthetic."
On-demand re-verification for high-risk actions (e.g. re-running liveness to authorise an MFA reset) — we don't have a standalone action for this yet. The closest thing we offer today is the document-expiry reverification in §1, which is automatic and tied to expiry, not callable on demand.

3. Data-extraction quality & monitoring

Proactive alerting on extraction-accuracy drops (by country × document type) — we don't have this yet.
Free re-processing of already-submitted applicants after a vendor-side fix — we don't offer this today.
Public status page / changelog for extraction-model updates — we don't publish one.
Address extraction scoped to the actual document holder (not a bank letterhead or other printed address) — our document-recognition engine handles this.

4. Questionnaires & applicant-supplied data

Building a questionnaire (back office)

A questionnaire is a set of typed questions: input, textarea, integer, decimal, radio, checkbox, single_choice_dropdown, multiple_choice_dropdown, yes_no, file_upload, net_promoter_score, matrix (groups sub-questions).

Endpoint: POST /api/v1/projects/{projectId}/questionnaires/{questionnaireId}/questions — questionnaire itself created via POST /api/v1/projects/{projectId}/questionnaires.

A Source-of-Funds question, for example, is a radio question with options:

json

{ "content": "What is your primary source of funds?", "type": "radio", "is_required": true }

Endpoint: POST /api/v1/projects/{projectId}/questionnaires/{questionnaireId}/questions/{questionId}/options

json

{ "content": "Employment income", "requires_input": false }
{ "content": "Other", "requires_input": true }

requiresInput: true is what gives you the free-text "please specify" field — it's a flag on the option, not a separate question.

How applicants answer

A questionnaire is one of the step types in an onboarding, answered the same way as document/ biometric steps:

Endpoint: POST /api/v1/onboardings/{onboardingCompletionId}/steps/{onboardingStepCompletionId}/{action}

Each question can be required or optional (isRequired). A questionnaire already completed is skipped automatically if the applicant re-enters the flow — see §5 for how step resumption works.

Conditional visibility & branching

Conditional visibility — a question can appear only depending on an earlier answer (equals/not-equals/greater-than/less-than, or a specific option selected). We enforce this today; we don't have a self-service endpoint yet to create these rules, so we set them up on our side.
Forbidden answers — a specific answer or option can be flagged to block the applicant from completing the questionnaire. Enforced today; also set up on our side for now.
Scored evaluation bands — options carry points, and a questionnaire can define named bands (e.g. "Low risk" / "High risk") by point total. Point values are configurable via the endpoints above; the bands themselves are set up on our side.
What this doesn't do — answers don't change which document gets requested or which onboarding step runs next. Blocking and classification, above, are the two ways an answer affects the outcome today.

Retroactively applying a new question

A live questionnaire isn't edited in place once it's in use — a new question means creating a new version of the questionnaire. Applicants who already completed the old version aren't affected. To prompt existing applicants for just the new question, the practical approach today is a fresh onboarding session built around a single-question questionnaire — not a bulk "notify everyone" mechanism. If you need something more automatic than that, flag it and we'll scope it.

5. Workflow engine & orchestration

Two distinct things share this name:

Onboarding — the ordered sequence of steps an applicant goes through (identity verification, questionnaire, personal data, bank account, consents, etc.), configured per project. This is the orchestration layer.
Workflow — the identity-verification step's own engine specifically: document/liveness capture and its approve/reject/review conditions. One step type within an onboarding, not the orchestration layer itself.

The onboarding step sequence (back office)

Steps available: identity verification, questionnaire, personal data, phone/email verification, bank account (with or without statement), IBAN, preferred currency, terms & conditions, business data, consents. Which steps, in what order, and required vs. optional is set per project.

"Resuming mid-flow" works at this level regardless of step type: the redirect URL's onboardingStepId starts at any step, and a completed step — document, biometric, questionnaire, or otherwise — is skipped automatically on re-entry.

The identity-verification step's condition engine (back office)

A condition on this step decides approve / reject / manual review, checking:

Document type, document country, nationality, age, gender
Liveness confidence (passive, active), document-to-selfie match, selfie-to-active-liveness match

against a comparison operator — equals, one-of, between, greater/less-than-or-equal.

Endpoint: GET/PUT /api/v1/projects/{projectId}/workflows/{workflowId}/condition-rules

This is also how different applicants take different paths by country or nationality — e.g. route a nationality straight to manual review, or restrict accepted document types.

What this doesn't do

We've kept conditions to the dimensions above — none of them read a questionnaire answer, a named document field (e.g. an address string), or a risk signal, and we don't have a regex or "contains any of these" operator. We also don't have a reusable named "preset" — we set thresholds directly per step. Where a customer has needed logic beyond this, we've built it as custom code for that flow rather than exposing it as a configuration option here.

6. Proof of Address (PoA)

Back office. Bank statements and tax returns have dedicated types; utility bills, government letters, or anything else go through a generic "other" type with a free-text subject.

Endpoint: POST /api/v1/applicants/{applicantId}/document-requests

json

{ "type": "bank_statement", "content": "Please provide the last 3 months of bank statements." }

type can be bank_statement, tax_return, id_card, or other. A document can be attached directly in the same call, or left pending for the applicant to upload.

Re-submitting just the PoA step — resending the request or replacing the document doesn't re-run the rest of verification:

Endpoints: POST /api/v1/applicants/{applicantId}/document-requests/{documentRequestId}/resend, POST /api/v1/applicants/{applicantId}/document-requests/{documentRequestId}/documents

Not available today

PoA age-limit enforcement (configurable max document age in days) — we don't have this setting yet.
Skip PoA if the parsed ID address is already complete — we don't have this rule yet; every PoA request is manual today.

7. AML screening — PEP, sanctions, adverse media

Back office. PEP, sanctions, and terrorism/organised-crime watchlist screening run as one check (topic-based, not separate systems) on workflow completion:

Endpoint: GET /api/v1/applicants/{applicantId}/aml, GET /api/v1/applicants/{applicantId}/aml/screenings for the full hit history.

Adverse media is a separate, distinct check, also back office:

Endpoint: GET/PUT /api/v1/projects/{projectId}/media-screenings/settings, GET/POST /api/v1/applicants/{applicantId}/media-screenings

Ongoing monitoring re-screens approved applicants on a schedule — same settings endpoint as document-expiry tracking (§1), different setting type (periodic_aml_screening): interval in days, with a separate shorter interval for applicants flagged PEP.

Exporting case data: the AML endpoints above return full structured JSON (hits, categories, screening timestamps). There's no PDF report generation.

Risk-flag configuration and country risk specifically are covered in §8, alongside the rest of the risk-signal/review picture.

Not available today

Multi-provider screening — we run one provider (OpenSanctions) today; we don't fan out across multiple providers and merge results yet.
Per-provider fuzzy-match configuration — we don't have this setting yet.
PDF case report / applicant summary — JSON only for now.
Webhook on new watchlist hit for a previously-clean applicant — roadmap; only applicant.created/applicant.updated/applicant.deleted events exist today (see Webhooks).

8. Review outcomes, risk signals, manual review

Risk signals — persistent, applicant-level, separate from any single review's outcome. This is the risk-flag system from §7: 14 predefined reasons today, each enabled with a risk category (standard/elevated/unacceptable) and reason-specific thresholds, extendable if you need a reason we don't have yet.

Endpoint (back office): GET /api/v1/applicants/{applicantId}/aml/flags, POST .../aml/flags/{amlFlagId}/resolve to clear one.
Endpoint (your API Key): push a flag from your own systems via POST /api/external/v1/applicants/{applicantId}/aml/flags.

Rejection reasons — free text on the review action itself, not drawn from a fixed, identifier- based catalogue, and not classified as retry-able vs. final.

Routing to manual review happens two ways: a condition on the identity-verification step (§5) can send an applicant to manual review directly, and raising an AML flag also moves the applicant to manual-review status on its own — a flag isn't just a record, it actively changes the applicant's outcome.

Reviewer dashboard access (back office) is per-project, granular permissions on a user — not just "admin" vs. "member":

Endpoint: PUT /api/v1/companies/{companyId}/projects/{projectId}/users/assign-permission/{userId}

Permissions: viewWorkflows, editWorkflows, createWorkflows, manageAML, addUsers, manageUsers.

Audit trail, exportable per applicant, back office:

Endpoint: GET /api/v1/applicants/{applicantId}/revisions (also /revisions/table for a paginated view)

Not available today

Reviewer comments (moderator-facing + applicant-visible) as part of the review payload — we don't return this yet.
Machine-readable rejection-reasons catalogue with stable identifiers — our reasons are free text today, not an enumerated list.

9. SDK & applicant-facing UX

Web SDK: two integration modes — the redirect flow used throughout this guide, and a richer attempt-based API for a custom-built embedded UI (ask if you want to go that route instead).

Theming (back office; colours and fonts, no logo yet):

Endpoint: GET/PUT /api/v1/projects/{projectId}/whitelabel

Fields: container background, QR code colours, primary/secondary text colour+font+size, button text/background colour+font+size. We don't have a logo field yet.

Languages: we have en, sk, cs, ro active today. We don't expose an endpoint to fetch/update individual translation strings yet — additional languages are a localization task we handle on our side, not something you configure via API.

Skipping our consent screen: consent capture is just one step type among several in the onboarding sequence (§5) — omit it from your configured sequence if you're capturing consent yourselves.

10. API, webhooks, data download

Sandbox — a full test onboarding without touching production data:

Endpoint: POST /api/v1/onboardings/testing/{testingHash}

Versioning: every route in this guide sits under an explicit /v1/ (or /external/v1/) prefix.

This spec, published: this guide plus the live reference at test.api.insyko.com/docs is that OpenAPI spec.

Not available today

Fetch an applicant by your own external ID — today it's only by our numeric applicantId; we don't have an externalId field on the applicant record to look up by yours instead.
Dedicated per-document image download endpoint — we already return document/selfie images as URLs on the applicant record (§1); we don't have a separate download-by-document-id call.
Applicant-summary PDF via API — we don't have a PDF export endpoint yet.
Reset-applicant / reset-single-step / change-current-step / applicant-timeline APIs — we haven't built any of these yet.
Full per-applicant regulatory export bundle (all binaries + data + screening output + timeline as one atomic download, e.g. for MiCA) — on our roadmap.

11. Out-of-band actions & post-approval operations

Post-approval document update — covered in §1: update a document's data after the applicant's already approved, without re-running verification.

Standalone liveness re-check to authorise an action like an MFA reset — we don't offer this as its own action yet; same gap as noted in §2.

External Integration Guide ​

1. Identity document verification ​

What data you get back ​

Expiration tracking ​

Not available today ​

2. Biometrics & liveness ​

What you get back ​

Not available today ​

3. Data-extraction quality & monitoring ​

4. Questionnaires & applicant-supplied data ​

Building a questionnaire (back office) ​

How applicants answer ​

Conditional visibility & branching ​

Retroactively applying a new question ​

5. Workflow engine & orchestration ​

The onboarding step sequence (back office) ​

The identity-verification step's condition engine (back office) ​

What this doesn't do ​

6. Proof of Address (PoA) ​

Not available today ​

7. AML screening — PEP, sanctions, adverse media ​

Not available today ​

8. Review outcomes, risk signals, manual review ​

Not available today ​

9. SDK & applicant-facing UX ​

10. API, webhooks, data download ​

Not available today ​

11. Out-of-band actions & post-approval operations ​

External Integration Guide

1. Identity document verification

What data you get back

Expiration tracking

Not available today

2. Biometrics & liveness

What you get back

Not available today

3. Data-extraction quality & monitoring

4. Questionnaires & applicant-supplied data

Building a questionnaire (back office)

How applicants answer

Conditional visibility & branching

Retroactively applying a new question

5. Workflow engine & orchestration

The onboarding step sequence (back office)

The identity-verification step's condition engine (back office)

What this doesn't do

6. Proof of Address (PoA)

Not available today

7. AML screening — PEP, sanctions, adverse media

Not available today

8. Review outcomes, risk signals, manual review

Not available today

9. SDK & applicant-facing UX

10. API, webhooks, data download

Not available today

11. Out-of-band actions & post-approval operations