Post a decisioned KYC verification result performed by an external identity provider.
Post a decisioned KYC verification result performed by an external identity provider. Fluz validates the payload, creates a verification record and updates the user’s KYC status according to the result. Requires the VERIFY_KYC scope on a user access token.Use this mutation when your platform runs its own KYC and pushes the outcome to Fluz. To have Fluz run the verification instead, use verifyUserInformation or verifyUserPrefillInformation.
Send this mutation to the dedicated secure ingestion endpoint, not the standard API host. This endpoint securely tokenizes PII data like person.ssn in transit. A request whose SSN or other PII data arrive untokenized is rejected. Always pass the arguments as GraphQL variables; values inlined into the query document cannot be tokenized.
Idempotency. Submissions are idempotent on externalVerificationId: replaying the same identifier returns the original result and writes nothing. A re-decisioned verification must be submitted with a new identifier.
Only decisioned results.decision must be PASSED or FAILED — do not send pending or undecisioned verifications.
KYC status transitions. A PASSED result moves an unverified user to PASS (US address) or PASS_INTERNATIONAL (non-US address). If the user is already verified, the verification is still recorded for audit but the status is never changed — the response message notes that the existing status was preserved. A FAILED result is recorded and leaves the status untouched.
Photo URLs must be HTTPS and remain fetchable for at least 24 hours after delivery — Fluz fetches and stores the images.
The provider’s globally unique identifier for this verification attempt (for
example a Persona inquiry id). This is the idempotency key — one attempt, one
id, forever.
Full US SSN, digits with optional dashes. Required together with
ssnLast4 when verifications.ssn is present. Sent in clear over TLS to
the secure endpoint, where it is tokenized in transit — it never reaches
Fluz systems and is never stored in clear. Never send a masked or partial
value.
The person’s verified legal address: streetLine1 (no PO Boxes), optional
streetLine2, city, subdivision (state/province code, required for US
addresses), postalCode (for US, the 5-digit ZIP), and countryCode (ISO
3166-1 alpha-2 — drives PASS vs PASS_INTERNATIONAL).
The provider verifications backing the decision. At least one of document,
ssn, or database is required. Presence is semantic: a ssn section means
the SSN was validated against an authoritative source; person.ssn without a
ssn section means the SSN was merely collected.
Government-id documentary verification: verificationId (provider id of
this resource), status (PASSED or FAILED), documentClass
(DRIVER_LICENSE, PASSPORT, or GOVERNMENT_ID), documentNumber
(stored only as a hash), issuingCountryCode (ISO 3166-1 alpha-2),
optional issuingSubdivision, issueDate, expirationDate,
confidenceScore (0–100), address (as extracted from the document),
photos (front required when present, optional back and selfie —
HTTPS URLs), checks, and documentData.
SSN verification against an authoritative source: verificationId,
status, source (for example TIN_DATABASE, ECBSV, CREDIT_BUREAU),
optional checks and ssnData. Requires person.ssn and
person.ssnLast4 to carry the verified value.
Database verification of personal data against public or private sources,
without a document or SSN: verificationId, status, optional checks
and databaseData.
Each section accepts a checks array of individual check outcomes: name
(a stable snake_case identifier, consistent across submissions — for
example id_expired_detection), status (PASSED, FAILED, or
NOT_APPLICABLE), and optional reasons. Fluz records all outcomes for
audit and records FAILED check names as decline codes.
Freeform provider context for audit (template ids, partner reference ids,
original provider identifiers). Must not contain clear PII beyond what the
typed fields already carry.
