Verify by External Provider

If your platform already runs KYC with its own identity provider, your customers should not have to verify twice. Submit the decisioned result to Fluz with postKycVerification. Unlike the other API methods, Fluz does not screen the identity itself here — the decision is yours. Fluz only validates and records it, and moves the customer’s status accordingly.

Prerequisites

An external KYC program approved by Fluz for your application. Talk to your account manager before building against this method.
The VERIFY_KYC scope enabled on your application by Fluz. See Required scope.
A user access token generated for the customer being verified, including VERIFY_KYC in its scopes.
The dedicated secure ingestion endpoint for your environment, provided during onboarding.

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.

Staging: https://secure.transactional-graph.staging.fluzapp.com/api/v1/graphql
Production: provided during onboarding

How it works

The postKycVerification mutation is synchronous. You submit the verified identity and the provider verifications backing your decision, and Fluz returns APPROVED, DECLINED, DUPLICATE, or ERROR in the response body. There is no customer-facing step. A few behaviors are specific to this method:

Only decisioned results. decision must be PASSED or FAILED. Do not send pending or undecisioned verifications.
Idempotency. Submissions are idempotent on externalVerificationId — your provider’s unique id for the attempt. Replaying an id returns the original result and writes nothing; a re-decisioned verification must be submitted with a new id.
Status transitions. A PASSED result moves an unverified customer to verified. If the customer is already verified — by any method — the verification is still recorded for audit, but their status is never changed; the response message notes that the existing status was preserved. A FAILED result is recorded and leaves the status untouched.
No attempt limit. Because you are reporting results rather than requesting screening, this method has no attempt limit and does not count against the limits on Verify by SSN or KYC Autofill.

Request

The customer is identified by the user access token in the Authorization header — person.userId and your application identity are filled in by Fluz, and any submitted values are overwritten.

Field	Type	Required	Description
`schemaVersion`	String	Yes	Version of the payload contract. Currently `"1.0"`.
`externalVerificationProvider`	String	Yes	`IDOLOGY`, `OSCILAR`, `PERSONA`, or `CUSTOM`.
`externalVerificationId`	String	Yes	Your provider’s globally unique id for this attempt — the idempotency key.
`decision`	String	Yes	`PASSED` or `FAILED`.
`decisionReason`	String	No	Human-readable reason or rule that produced the decision.
`decisionedAt`	String	No	ISO 8601 timestamp of the decision. Defaults to the time of ingestion.
`person`	JSON	Yes	The verified identity as established by the provider.
`verifications`	JSON	Yes	The provider verifications backing the decision — at least one of `document`, `ssn`, or `database`.
`externalProviderData`	JSON	No	Freeform provider context for audit.

See postKycVerification for the full field reference, including the person and verifications object shapes.

Example

import { GraphQLClient, gql } from 'graphql-request';

const API_URL =
  'https://secure.transactional-graph.staging.fluzapp.com/api/v1/graphql';

const POST_KYC_VERIFICATION = gql`
  mutation postKycVerification(
    $schemaVersion: String!
    $externalVerificationProvider: String!
    $externalVerificationId: String!
    $decision: String!
    $decisionReason: String
    $person: JSON!
    $verifications: JSON!
  ) {
    postKycVerification(
      schemaVersion: $schemaVersion
      externalVerificationProvider: $externalVerificationProvider
      externalVerificationId: $externalVerificationId
      decision: $decision
      decisionReason: $decisionReason
      person: $person
      verifications: $verifications
    ) {
      status
      verificationId
      message
    }
  }
`;

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

const response = await client.request(POST_KYC_VERIFICATION, {
  schemaVersion: '1.0',
  externalVerificationProvider: 'PERSONA',
  externalVerificationId: 'inq_gCf28LrXY9wrxDoZbnbEqTrn',
  decision: 'PASSED',
  decisionReason: 'All checks passed',
  person: {
    firstName: 'JANE Q',
    lastName: 'SAMPLE',
    dateOfBirth: '1990-01-01',
    ssn: '900-98-7654',
    ssnLast4: '7654',
    address: {
      streetLine1: '123 EXAMPLE STREET',
      city: 'SAMPLETOWN',
      subdivision: 'CA',
      postalCode: '90001',
      countryCode: 'US',
    },
  },
  verifications: {
    document: {
      verificationId: 'ver_p8qmKydzkQwyLKbaAJRvADi9',
      status: 'PASSED',
      documentClass: 'DRIVER_LICENSE',
      documentNumber: 'X90000000000001',
      issuingCountryCode: 'US',
      photos: { front: 'https://files.provider.example/front.jpg' },
      checks: [{ name: 'id_expired_detection', status: 'PASSED' }],
    },
    ssn: {
      verificationId: 'ver_tin_snW2CvL2x4kTdZjbmGBjqcuV',
      status: 'PASSED',
      source: 'TIN_DATABASE',
    },
  },
});

console.log(response);

Response

{
  "data": {
    "postKycVerification": {
      "status": "APPROVED",
      "verificationId": "4b99e8c5-4201-45fd-a5dc-1c3b88e4f6c7",
      "message": "User verification successful"
    }
  }
}

Handling the response

Status	What to do
`APPROVED`	The verification was recorded. If the customer was not yet verified, they now are; if they were already verified, `message` notes that the existing status was preserved.
`DECLINED`	The `FAILED` result was recorded. The customer’s status is unchanged.
`DUPLICATE`	The verification was recorded, but the SSN or document number matches another Fluz customer. The account is placed under review — investigate on your side before proceeding. Fluz does not disclose which customer matched.
`ERROR`	Inspect `message` — most commonly a payload that failed contract validation. Nothing was recorded.

Testing

Test against the staging endpoint with fabricated identities — because the decision is yours, there are no provider test-identity requirements as with the other methods. Use SSNs in the 900-XX-XXXX range (never issued), generate a fresh externalVerificationId per attempt (replaying an id returns the original result rather than exercising a new one), and make sure any photo URLs you send are fetchable — Fluz retrieves and stores the images.

​How it works

​Request

​Example

​Handling the response

​Testing

How it works

Request

Example

Handling the response

Testing