API reference

FirstPass is a KYC pre-screen: face match, ID reading and a face fingerprint for deduping your own users. It is not certified eKYC and not an identity verification method under Japan's 犯収法. Liveness only runs in hosted sessions.

The examples illustrate responses with synthetic noise images (no real face or document) and document reading not configured. That is why face results show no_face and document reading shows ocr_unavailable; with real photos those fields carry the values described below.

Basics

• Base URL: https://api.firstpass.cloud
• Customer integration endpoints (session creation and polling, direct and granular checks) need Authorization: Bearer YOUR_KEY. Hosted config, submit and help use the session link as a credential; health, demo, signup and website support do not require an API key. Get a key and top up credits in the dashboard.
• The JSON model endpoints documented here need Content-Type: application/json. Without it the body is not parsed and the call fails with 422.
• Images are base64 strings (a data: URL prefix is accepted), JPEG, PNG or WebP, up to 8 MiB of base64 each, including any data URL prefix (hosted scan frames and videos have separate limits).
• HTTP and request-validation errors return {"detail": ...} with the HTTP status (see Errors).

Hosted sessions (recommended)

You open a session and send the applicant to the returned url. On that page they do a live face scan (selfie uploads are disabled; ID uploads are allowed), photograph their ID and, for Level B, add proof of residence, source of funds and declared details. FirstPass runs the check, stores the record in your workspace, and you poll for the result. This is the only flow with server-side liveness checks.

Create a session

curl -X POST https://api.firstpass.cloud/v1/kyc/session \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"level": "A", "applicant_ref": "user_123", "lang": "en"}'

{
  "session_id": "_2L_jByICyPD_528Fk6JB7Y_y6SwJAu3",
  "url": "https://firstpass.cloud/kyc.html?session=_2L_jByICyPD_528Fk6JB7Y_y6SwJAu3&level=A&lang=en",
  "status": "pending"
}

Creating a session costs nothing, but your workspace must have a positive balance and be under its monthly quota (otherwise 402 or 429). The first billable submission costs 1 credit for Level A or 2 for Level B; a positive balance at creation does not guarantee enough credits for B. Retries are free while the session remains charged. After a refund, the next billable submission is charged again. A link expires 24 hours after creation and accepts at most 5 model-valid submissions, including failed liveness and ID-side prechecks. Verified or closed sessions cannot be retried. Creation checks a 300-session hourly threshold per workspace; concurrent requests can exceed it.

Poll a session

Needs the Authorization header. Only the workspace that created the session can read it; any other id returns 404. Polling works even when your balance is 0.

curl https://api.firstpass.cloud/v1/kyc/session/SESSION_ID \
  -H "Authorization: Bearer $KEY"

{
  "session_id": "_2L_jByICyPD_528Fk6JB7Y_y6SwJAu3",
  "status": "pending",
  "level": "A",
  "verdict": null,
  "record_id": null,
  "applicant_ref": "user_123"
}

# Ran locally with the face and OCR engine replaced by synthetic values (no real
# person can be scanned in a test). Billing, storage and this response are the
# real endpoint code. face_embedding is 128 numbers, shortened here.
{
  "session_id": "4WWxCP-EB-khWirnzZNBb61Rat8M9XE9",
  "status": "done",
  "level": "A",
  "verdict": "verified",
  "record_id": 1,
  "applicant_ref": "user_123",
  "result": {
    "outcome": "verified",
    "reason": "ok",
    "face_match": { "faces_a": 1, "faces_b": 1, "similarity": 0.6712, "verdict": "match" },
    "document": {
      "doc_type": "パスポート", "doc_number": "TZ0000000", "name": "TEST APPLICANT",
      "birth_date": "1990-01-01", "expiry_date": "2031-05-14", "expiry_printed": true
    },
    "identity": {
      "level": "A",
      "name": { "input": "Test Applicant", "valid": true },
      "email": { "input": "applicant@example.com", "valid": true, "mx_found": true, "disposable": false },
      "phone": { "input": "+81 90 1234 5678", "valid": true, "e164": "+819012345678", "country": "JP", "type": "mobile" },
      "passed": true
    },
    "face_embedding": [0.0123, 0.0123, ...],
    "liveness_flash": { "result": "pass", "score": 1.0, "signal": 0.0412, "sequence_ok": true,
                        "measured": [{ "color": "R", "fraction": 0.4691, "hit": true }] }
  }
}

• status is pending, done or expired (a link nobody finished within 24 hours).
• The top-level verdict is the overall outcome (verified, review, rejected, or erased after an erasure request). The face-only verdict is result.face_match.verdict.
• result appears once the session is done. Level B adds proof_of_residence, source_of_funds and edd (POR/SOF keys are omitted when their values are null) (see Level B). Images are not returned; view them in the dashboard. Level B residence and funds document images are the exception: they are not in the dashboard, exports or API, only authorised FirstPass staff reviewing records can view them through the staff page (access is logged). They become inaccessible after 90 days; startup or the next expiry job overwrites the encrypted images. The fields read from them stay in the result.
• liveness_flash.result is pass, fail, inconclusive or not_measured. sequence_ok is optional (absent on the not_measured early return) and says whether the flash frames came in the colour order this session issued (null if none was issued). A clear reading in the wrong order is a fail with fail_reason: "sequence" and changes an otherwise verified check to review (flash_sequence_review); a wrong reflection pattern is fail_reason: "reflectance" (flash_review). Existing rejection or review reasons take priority; flash downgrades only an otherwise verified result.

Outcomes and reasons

A hosted check ends as verified, review or rejected. Review cases are yours to decide: The service requesting verification is responsible for decisions and applicant follow-up; no reviewer assignment or response is guaranteed. FirstPass staff access to proof images supports operations and is not an applicant-review service. If you need original proofs for your own review, arrange collection with the applicant through your own process. verified needs a matching face, an accepted in-date ID (residence card, driver's license, My Number card, passport, or another country's national ID card), valid name, email and phone (format/MX/disposable-domain checks, not mailbox delivery or a name-to-ID comparison), and a passing screen-flash reading. A national ID explicitly marked expiry_printed: false does not require an expiry date. Earlier face/ID/identity reasons take priority; Level B missing-document and cross-check reasons apply only after preceding checks pass.

Direct Level A and B

If you capture images yourself, post them directly. These calls run no liveness check: they accept any selfie image, including an uploaded photo. They also return no overall outcome: you get the face verdict, the document fields and the identity checks, and decide yourself.

ID images must show the photo side. When no face is found anywhere on the ID image (face_match.faces_b is 0), it is most likely the back of the card: the record keeps the fields read from it but not the image, and you should ask the applicant to photograph the front. The same applies to /v1/face/compare (image_b) and /v1/document/ocr.

Level A

1 credit. Body: name, email, phone, selfie, document (required), region (default country for the phone number, default "JP").

curl -X POST https://api.firstpass.cloud/v1/kyc/a \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @kyc_a.json
# kyc_a.json: {"name": "Test Applicant", "email": "applicant@example.com",
#   "phone": "090-1234-5678", "region": "JP", "selfie": "BASE64_JPEG", "document": "BASE64_JPEG"}

{
  "level": "A",
  "identity": {
    "level": "A",
    "name": { "input": "Test Applicant", "valid": true },
    "email": { "input": "applicant@example.com", "valid": true, "mx_found": true, "disposable": false },
    "phone": { "input": "090-1234-5678", "valid": true, "e164": "+819012345678", "country": "JP", "type": "mobile" },
    "passed": true
  },
  "face_match": { "faces_a": 0, "faces_b": 0, "similarity": null, "verdict": "no_face" },
  "document": { "ocr_unavailable": true },
  "face_embedding": null
}

With real photos, face_match.verdict is match, uncertain, mismatch or no_face, similarity is 1 minus the face distance, document holds doc_type, doc_number, name, birth_date, expiry_date and expiry_printed (or is null when the image is not a readable ID), and face_embedding is the selfie's 128-number fingerprint for deduping within your own platform. When OCR classifies an image as a My Number card, doc_number is cleared and sensitive-number filtering is applied to OCR text fields. This is not a guarantee against misclassification; submit only the photo side and mask sensitive numbers before upload.

Level B

2 credits per call, even if the optional proofs are omitted. The official hosted B page requires both proofs and all declared fields before submission; the direct API accepts the following optional fields in addition to Level A: por_document, sof_document (images), birth_date (YYYY-MM-DD), nationality, address, occupation, pep (true/false), funds_source, annual_income.

• The residence and funds documents are optional here; when left out, proof_of_residence and source_of_funds are null.
• Cross-checks only run when the data is there: birth_date_matches_id needs a birth date and a readable ID birth date; address_matches_por needs an address and a readable proof of residence.
• Occupation, PEP status, source of funds and income are recorded as declared and are not verified. There is no sanctions or PEP screening.

curl -X POST https://api.firstpass.cloud/v1/kyc/b \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @kyc_b.json
# kyc_b.json: the Level A fields plus "birth_date": "1990-01-01", "address": "Tokyo",
#   "occupation": "engineer", "pep": false, "funds_source": "salary", "annual_income": "3m_6m"

{
  "level": "B",
  "identity": { ...same shape as Level A..., "passed": true },
  "face_match": { "faces_a": 0, "faces_b": 0, "similarity": null, "verdict": "no_face" },
  "document": { "ocr_unavailable": true },
  "face_embedding": null,
  "proof_of_residence": null,
  "source_of_funds": null,
  "edd": {
    "birth_date": "1990-01-01",
    "nationality": null,
    "address": "Tokyo",
    "declared": { "occupation": "engineer", "pep": false, "funds_source": "salary", "annual_income": "3m_6m" },
    "cross_checks": {}
  }
}

When read, proof_of_residence is {doc_kind, name, address, issue_date, issuer, recent} (recent is true only for issue dates from today minus 90 days through today, inclusive, by JST calendar day; future dates return recent: false and an additional reason: "por_future_date") and source_of_funds is {doc_kind, name, issuer, amount, period}.

Granular endpoints

Single steps for composing your own flow. 1 credit each. None of them runs liveness.

Face compare

Body: image_a (selfie), image_b (ID photo). Stored as a record.

curl -X POST https://api.firstpass.cloud/v1/face/compare \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_a": "BASE64_JPEG", "image_b": "BASE64_JPEG"}'

{"faces_a": 0, "faces_b": 0, "similarity": null, "verdict": "no_face"}

Face fingerprint

Body: image. Returns the face count and the largest face's 128-number embedding (or null). Not stored.

curl -X POST https://api.firstpass.cloud/v1/face/embed \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "BASE64_JPEG"}'

{"faces": 0, "embedding": null}

ID document reading

Body: image. Returns {doc_type, doc_number, name, birth_date, expiry_date, expiry_printed}. Stored as a record. An image that is not a readable ID returns 422; a reader outage returns 502. Neither is charged.

curl -X POST https://api.firstpass.cloud/v1/document/ocr \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "BASE64_JPEG"}'

{"detail": "ocr unavailable. not charged, retry later"}

Proof-of-residence reading

Body: image. Returns {doc_kind, name, address, issue_date, issuer, recent}. Not stored. A null OCR result returns 422 and a reader outage returns 502, both refunded. Unknown, unreadable or unrecognized document kinds also return 422, refund the charge and record usage with ok=0. A readable but future-dated proof still costs 1 credit and returns recent: false with reason: "por_future_date".

curl -X POST https://api.firstpass.cloud/v1/document/por \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "BASE64_JPEG"}'

{"detail": "ocr unavailable. not charged, retry later"}

Name, email and phone check

Body: name, email, phone, region (default "JP"). Checks the name, the email format, mail server (MX) and disposable domains, and parses the phone number. Charged whenever it returns 200. Not stored.

curl -X POST https://api.firstpass.cloud/v1/identity/basic \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Applicant", "email": "applicant@example.com", "phone": "090-1234-5678", "region": "JP"}'

{
  "level": "A",
  "name": { "input": "Test Applicant", "valid": true },
  "email": { "input": "applicant@example.com", "valid": true, "mx_found": true, "disposable": false },
  "phone": { "input": "090-1234-5678", "valid": true, "e164": "+819012345678", "country": "JP", "type": "mobile" },
  "passed": true
}

Credits

1 credit = $0.10, prepaid. Credits are taken before the check runs. Direct A/B calls are billed per call, including no-face or unreadable-ID results unless OCR is unavailable. Their engine exceptions, OCR outages and handled record-save failures are refunded, but errors in image preparation or final settlement are not all covered: an arbitrary 500 does not guarantee a refund. Hosted submissions refund their new charge on processing or storage failure and release the charge claim; after a refund the next billable submission is charged again. A free retry has no new charge to refund. Unreadable POR within direct or hosted Level B still costs the overall 2 credits; hosted B goes to review/documents_unreadable. A future-dated POR goes to review/edd_review in hosted B, without an automatic rejection. Direct B returns the fields for the customer to decide.

Errors

HTTP and model-validation errors use {"detail": ...}. Model-validation 422 responses contain a list; business 422 responses contain a string or object. Unhandled 500 errors do not guarantee JSON or a refund.

What is stored

Stored records are encrypted, visible only in your own dashboard (and to our authorised operations staff), and never matched across customers. Except for Level B proof images (90 days), they have no automatic deletion period, and storage cannot be switched off. Our operations staff erase a record on request: email hello@firstpass.cloud. Details in the privacy policy.

Health

Public, no key. 200 when the service can reach its database and load the face model, 503 with "ok": false when it cannot. ocr says whether document reading is configured.

curl https://api.firstpass.cloud/health

{"ok": true, "db": "ok", "ocr": "missing", "face_model": "ok"}