Identity import

/v3/identities/import/ brings people you already hold in another system into the identity registry, so their faces are searchable by 1:N on day one — without putting anyone through a verification flow. You supply a unique id, a photo URL, and optionally a name and contact details; we fetch each photo, confirm it holds exactly one readable face, and enrol that face into the tenant's gallery.

This is the migration path for a tenant moving off other software. It is not a verification: an imported identity has no document, no liveness, no decision — only a searchable face and the provenance you recorded for it. For the end-to-end migration walkthrough — pilot batch, CSV columns, what to do with the row report — see Import an existing customer base.

Identity import is opt-in

{ "detail": "feature_not_enabled", "features": ["IDENTITY_IMPORT"] }

The gate is asymmetric on purpose:

Imported faces sit outside the session-driven retention sweep, so deleting the batch is their only disposal route. If revoking the feature also revoked the delete, withdrawing the grant would strand the biometrics it created — so reading and deleting stay available whatever the entitlement says today.

Before you import

How an import runs

Each row is a network fetch plus a face embedding, so the work happens on a worker. POST returns 202 with a batch_id immediately; poll GET for progress and per-row outcomes.

POST /v3/identities/import/  ──▶  202 { batch_id, status: "pending", total }
                                        │
                        worker picks it up (status: "running")
                                        │
         GET /v3/identities/import/{batch_id}/  ──▶  processed / created /
                                        │            updated / skipped / failed
                                        ▼
                              status: "completed" | "failed"

Rows fail individually. One unreachable photo, one group shot, one blank avatar — that row is marked error with a reason and the batch carries on. Only a handful of conditions stop a whole batch (see batch-level errors).

Batch status is pending, running, completed or failed. A failed batch keeps the rows that already landed — those enrolments are real — and the rows it never reached stay pending.

Provenance is required

source_system and consent_reference are not decoration. Every other face in the product traces back to a session where the person stood in front of a camera and accepted the tenant's terms. An import has no session and no terms-acceptance behind it, so these two strings are the only record of where a face came from and on what basis you hold it. Both are stamped onto every identity the import touches (under the identity's metadata.import, alongside the batch id and row number), and both surface in the console: the Past imports list labels each batch with its source_system and shows the consent_reference on hover.

Omitting either is a 400 — source_system_required or consent_reference_required — not a silent default.

Photo URLs: what we will and won't fetch

We download each photo_url from our servers, which means an operator-supplied string turns into an outbound request from inside our network. Every hop is validated, not just the first:

Anything else that goes wrong on the wire — a 404, a timeout, an empty body — is fetch_failed. The message deliberately never echoes the resolved address: an import report that did would be an internal network scanner for anyone who can post rows.

The 15-second timeout is usually the first limit an integrator on slow object storage meets: a cold-storage tier that takes twenty seconds to serve the first byte fails the row with fetch_failed, however healthy the URL looks in a browser. Warm the objects, or serve the import from a hot bucket.

Exactly one readable face

Each photo must contain exactly one detectable face:

• No face → the row fails with no_face_detected.
• More than one face → the row fails with multiple_faces. A group photo would otherwise enrol an arbitrary person under your customer's id, which is worse than not enrolling them at all.
• An embedding of a different width than the tenant's existing gallery → embedding_mismatch. The row would insert fine and then never be findable, so it fails loudly instead.

Endpoints

Start an import

POST /v3/identities/import/
x-api-key: <tenant_api_key>
Content-Type: application/json

Each entry in identities:

curl -X POST https://acme.thirdfactor.ai/v3/identities/import/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_system": "Legacy CRM",
    "consent_reference": "Customer T&C v3 accepted at signup",
    "on_duplicate": "report",
    "identities": [
      {
        "external_user_id": "CUST-00001",
        "full_name": "Aarati Shrestha",
        "photo_url": "https://files.example.com/photos/1.jpg"
      },
      {
        "external_user_id": "CUST-00002",
        "full_name": "Bikash Thapa",
        "photo_url": "https://files.example.com/photos/2.jpg",
        "phone": "+9779800000000"
      }
    ]
  }'

const resp = await fetch("https://acme.thirdfactor.ai/v3/identities/import/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OBSIDIAN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_system: "Legacy CRM",
    consent_reference: "Customer T&C v3 accepted at signup",
    identities: customers.map((c) => ({
      external_user_id: c.id,      // the same id you will send as vendor_data
      full_name: c.name,
      photo_url: c.photoUrl,
    })),
  }),
});
const { batch_id } = await resp.json();  // 202

import requests

resp = requests.post(
    "https://acme.thirdfactor.ai/v3/identities/import/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    json={
        "source_system": "Legacy CRM",
        "consent_reference": "Customer T&C v3 accepted at signup",
        "identities": [
            {
                "external_user_id": c["id"],
                "full_name": c["name"],
                "photo_url": c["photo_url"],
            }
            for c in customers
        ],
    },
)
batch_id = resp.json()["batch_id"]  # 202

{
  "batch_id": "7f1c2a90-4b6d-4e15-9a02-3d8c1b7e5f44",
  "status": "pending",
  "total": 2
}

Errors

Whole-request refusals return { "detail": "<code>", "error": "<sentence>" }.

A row missing external_user_id or photo_url is not a 400. It is accepted into the batch and reported as a failed row (external_user_id_required / photo_url_required), so one malformed line in a 5000-row export doesn't cost you the whole import.

Import status and row report

Polling is how you learn a batch finished. An import fires no webhook and no Connect event — there is no identity_import.* topic to subscribe to — so poll this endpoint until status is completed or failed. Console operators with console_manage_kyc additionally get an in-console notification when one lands (everyone but the operator who started it, who is already watching the progress bar).

GET /v3/identities/import/{batch_id}/
x-api-key: <tenant_api_key>

curl -s "https://acme.thirdfactor.ai/v3/identities/import/$BATCH_ID/?status=error&page_size=200" \
  -H "x-api-key: $OBSIDIAN_API_KEY"

async function waitForImport(batchId) {
  for (;;) {
    const resp = await fetch(
      `https://acme.thirdfactor.ai/v3/identities/import/${batchId}/`,
      { headers: { "x-api-key": process.env.OBSIDIAN_API_KEY } },
    );
    const batch = await resp.json();
    if (batch.status === "completed" || batch.status === "failed") return batch;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

import time, requests

while True:
    batch = requests.get(
        f"https://acme.thirdfactor.ai/v3/identities/import/{batch_id}/",
        headers={"x-api-key": OBSIDIAN_API_KEY},
    ).json()
    if batch["status"] in ("completed", "failed"):
        break
    time.sleep(5)

failed = requests.get(
    f"https://acme.thirdfactor.ai/v3/identities/import/{batch_id}/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
    params={"status": "error", "page_size": 200},
).json()["rows"]

{
  "batch_id": "7f1c2a90-4b6d-4e15-9a02-3d8c1b7e5f44",
  "status": "completed",
  "source_system": "Legacy CRM",
  "total": 2,
  "processed": 2,
  "created": 1,
  "updated": 0,
  "skipped": 0,
  "failed": 1,
  "error": "",
  "created_at": "2026-09-16T04:10:00Z",
  "finished_at": "2026-09-16T04:10:37Z",
  "rows": [
    {
      "row": 1,
      "external_user_id": "CUST-00001",
      "status": "created",
      "detail": "",
      "message": "",
      "individual_id": "3c9a1e77-2b40-4d8f-9a11-6e5c4b3a2d10",
      "matches": []
    },
    {
      "row": 2,
      "external_user_id": "CUST-00002",
      "status": "error",
      "detail": "no_face_detected",
      "message": "No face could be read in this photo.",
      "individual_id": null,
      "matches": []
    }
  ],
  "row_count": 2,
  "page": 1,
  "page_size": 50
}

Row statuses

Row detail slugs

detail is a stable machine slug; message is the same reason as a sentence you can show an operator.

Batch-level errors

These stop the whole batch. Rows already enrolled are kept; untouched rows stay pending and come back in the report as work still to do.

Errors

A batch_id that isn't a UUID never reaches this view at all — the route only matches a UUID — so it comes back as a plain routing 404 with no detail code. Branch on the status, not the body, when you can't trust the id.

Duplicate handling

With on_duplicate: "report" (the default) each row is searched against the tenant's existing gallery and against faces enrolled earlier in the same batch — so the same person appearing twice in one file is reported on the second row. Hits are recorded on the row and never acted on:

"matches": [
  {
    "individual_id": "9b2c7d10-5e41-4f88-a0c3-1d2e3f4a5b6c",
    "score": 0.9312,
    "external_user_id": "CUST-00088",
    "full_name": "Aarati Shrestha"
  }
]

The threshold is the tenant's own duplicate threshold — the same one live verifications use — so "duplicate" means the same thing in an import report as it does mid-flow. An identity is never reported as a duplicate of itself: the row's own external_user_id is resolved first and excluded from the search.

score is a face-embedding cosine in 0..1. Treat a hit as a candidate for review, not a verdict.

Merging into existing identities

When a row's external_user_id already exists for the tenant, the import enrols the face onto that identity (status updated) and fills blank contact fields only. An import never overwrites a name, email, phone or country that came off a verified document. The imported photo becomes the identity's primary face only when it has no primary face already — a real selfie always outranks an import.

Billing

Identity import is metered under the IDENTITY_IMPORT key, per enrolled record — one debit per row that created or updated an identity, posted to the credit ledger with reason: "tool_usage". Rows that error or are skipped cost nothing.

Two behaviours worth designing around:

• Each row's debit is keyed on (batch, row), so a redelivered or retried batch replays rather than charges twice.
• If the balance runs out mid-batch the import stops — status: "failed", error: "insufficient_credits" — rather than enrolling the rest for free. The rows it never reached stay pending; top up and re-import those.

Retention and deletion

That is deliberate, not an oversight: a gallery that quietly aged itself out would stop answering 1:N searches with no warning.

DELETE /v3/identities/import/{batch_id}/
x-api-key: <tenant_api_key>

Deleting a batch removes:

• every face photo the import enrolled (file and record) — which is what made those people searchable; and
• identities the import created, but only while they are still nothing but an import. The moment someone has verified through a session, or another face or document exists on the identity, it is no longer the import's to delete.

Identities the import merely updated are never touched — they predate it.

curl -X DELETE "https://acme.thirdfactor.ai/v3/identities/import/$BATCH_ID/" \
  -H "x-api-key: $OBSIDIAN_API_KEY"

resp = requests.delete(
    f"https://acme.thirdfactor.ai/v3/identities/import/{batch_id}/",
    headers={"x-api-key": OBSIDIAN_API_KEY},
)
removed = resp.json()  # {"ok": true, "photos_removed": …, "identities_removed": …}

{
  "ok": true,
  "photos_removed": 4821,
  "identities_removed": 4796
}

Errors

Deletion does not require the IDENTITY_IMPORT entitlement to still be granted, for the reason above: withdrawing the feature must never strand the biometrics it created.

Import vs. a session

Common pitfalls

FAQ

Related