> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import an Existing Verification

> Bring in a verification you already performed elsewhere instead of collecting documents again. POST /cardholders/{id}/kyc/import. Requires cardholders:write scope.

## Overview

If you already verified this person — in a partner verification application, with another provider,
or through your own process — send us that verification instead of putting them through a second
one. Two kinds of evidence are accepted:

| `source` | What you send |
| - | - |
| `SHARED_SESSION` | `shareToken`: a session shared from a partner verification application |
| `EXTERNAL_PROVIDER` | `document`: the verification record itself, with its images |

> [!WARNING]
>
> What you send is **evidence, not a verdict**. Your `decision` is recorded as provenance and shown
> on the cardholder; the cardholder's status is decided by our own screening of the document and
> images, exactly as for any other submission. An import saves a collection round-trip; it does not
> approve a cardholder on your say-so.

## Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `reference` | string | **Yes** | Your own identifier for this verification. Makes a retry safe |
| `source` | string | No | `SHARED_SESSION` or `EXTERNAL_PROVIDER`. Inferred when omitted: a request with `shareToken` is a shared session, one with `document` is a provider record |
| `shareToken` | string | For `SHARED_SESSION` | The token that redeems the shared session. Redeemable **once** |
| `document` | object | For `EXTERNAL_PROVIDER` | The verification record: `documentType`, `documentNumber`, `issuingCountry`, `issuingDate`, `expiryDate`, `frontUrl`, `backUrl`, `selfieUrl` |
| `provider` | string | No | Who performed the verification, in your words. Recorded as given |
| `decision` | string | No | What the source concluded, e.g. `APPROVED`. Recorded as provenance only |
| `verifiedAt` | string | No | When the source verified the person, RFC 3339 |

```bash cURL (provider record) theme={null}
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/kyc/import \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "EXTERNAL_PROVIDER",
    "reference": "kyc-2026-000123",
    "provider": "Our onboarding team",
    "decision": "APPROVED",
    "verifiedAt": "2026-11-02T10:15:00Z",
    "document": {
      "documentType": "PASSPORT",
      "documentNumber": "AB123456",
      "issuingCountry": "KE",
      "issuingDate": "2022-03-01",
      "expiryDate": "2032-02-28",
      "frontUrl": "https://files.example.com/kyc/front.jpg",
      "selfieUrl": "https://files.example.com/kyc/selfie.jpg"
    }
  }'
```

```bash cURL (shared session) theme={null}
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678/kyc/import \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "SHARED_SESSION", "reference": "share-7731", "shareToken": "st_4b1e9c0d" }'
```

## Success Response (201)

The cardholder, with the status our screening reached — or `PENDING` while it is still running, in
which case the decision arrives on your KYC webhook — plus what we recorded about the import:

```json theme={null}
{
  "success": true,
  "status": 201,
  "message": "Verification imported",
  "data": {
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "kycStatus": "PENDING",
    "importedVerification": {
      "source": "EXTERNAL_PROVIDER",
      "provider": "Our onboarding team",
      "reference": "kyc-2026-000123",
      "sourceDecision": "APPROVED",
      "sourceVerifiedAt": "2026-11-02T10:15:00Z",
      "importedAt": "2026-11-09T08:00:00Z"
    }
  }
}
```

The `data` object also carries every other cardholder field, as in
[Get Cardholder](https://docs.fyatu.com/v3.20/api-reference/cardholders/get.md).

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `INVALID_REQUEST` | 400 | `reference` missing; `shareToken` missing for a shared session; `document` missing for a provider record; an invalid or expired share token; a record without a document and its images |
| `CARDHOLDER_NOT_FOUND` | 404 | No such cardholder under your business |
| `KYC_ALREADY_APPROVED` | 409 | The cardholder is already approved |
| `KYC_IMPORT_ALREADY_REDEEMED` | 409 | This share token was already redeemed; its verification arrived the first time |
| `CARDHOLDER_TERMINATED` | 422 | The cardholder is terminated |
| `SERVICE_UNAVAILABLE` | 503 | Shared sessions cannot be accepted right now; send the verification record instead, or retry later |

### In the sandbox

The sandbox redeems shared sessions without a partner: the `shareToken` chooses the outcome.

| `shareToken` | Result |
| - | - |
| `sandbox_invalid` | `400 INVALID_REQUEST`: invalid or expired token |
| `sandbox_redeemed` | `409`: already imported |
| anything else | imported with the sandbox's specimen passport, then decided as any sandbox cardholder is (see the [quickstart](https://docs.fyatu.com/v3.20/documentation/quickstart.md)) |


## OpenAPI

````yaml v3.20/openapi.json POST /cardholders/{id}/kyc/import
openapi: 3.1.0
info:
  title: FYATU CaaS API v3.20
  description: >-
    FYATU Cards-as-a-Service API â€” API key authentication, Cardholder
    lifecycle, Card issuance, Transactions, Webhooks, and Programs.
  version: 3.20.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://sandbox-api.fyatu.com/api/v3.20
    description: 'Public sandbox: free, test money only. Keys from sandbox.fyatu.com'
  - url: https://api.fyatu.com/api/v3.20
    description: >-
      Production. Keys from platform.fyatu.com; the key's environment (LIVE or
      SANDBOX) selects the data
security:
  - BearerAuth: []
tags:
  - name: Meta
    description: Liveness, account info, and supported event types
  - name: Account
    description: Account-level balance and funding status
  - name: Programs
    description: Read card program configuration
  - name: Cardholders
    description: Create and manage cardholder profiles
  - name: Cards
    description: Issue, fund, freeze, and terminate virtual cards
  - name: Transactions
    description: Read-only card transaction history
  - name: Webhooks
    description: Manage webhook endpoints for real-time event delivery
  - name: Products
    description: Read card product configurations
paths:
  /cardholders/{id}/kyc/import:
    post:
      tags:
        - Cardholders
      summary: Import an existing verification
      description: >-
        Takes in a verification you already performed elsewhere instead of
        collecting the documents again: either a **shared session** from a
        partner verification application (`shareToken`), or the **verification
        record** from another provider or your own process (`document`).


        What you send is evidence, not a verdict. Your `decision` is recorded as
        provenance; the cardholder's status is decided by our own screening of
        the document and images, exactly as for any other submission. The
        response carries the status that screening reached, or `PENDING` when it
        is still running (the decision then arrives on your webhook).


        `reference` is required and makes a retry safe. A share token can be
        redeemed once.
      operationId: importCardholderVerification
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Cardholder ID
          example: chl_01HXYZ1234ABCDEF5678
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reference
              properties:
                source:
                  type: string
                  enum:
                    - SHARED_SESSION
                    - EXTERNAL_PROVIDER
                  description: >-
                    Inferred when omitted: a request with `shareToken` is
                    SHARED_SESSION, one with `document` is EXTERNAL_PROVIDER
                reference:
                  type: string
                  description: Your own identifier for this verification. Required
                provider:
                  type: string
                  description: >-
                    Who performed the verification, in your words. Recorded as
                    given
                decision:
                  type: string
                  description: >-
                    What the source concluded (e.g. APPROVED, DECLINED).
                    Recorded as provenance, never used as our verdict
                verifiedAt:
                  type: string
                  format: date-time
                  description: When the source verified the person, RFC 3339
                shareToken:
                  type: string
                  description: SHARED_SESSION only. Redeemable once
                document:
                  $ref: '#/components/schemas/KycDocument'
                  description: EXTERNAL_PROVIDER only. Required for that source
            examples:
              externalProvider:
                summary: A record from another provider
                value:
                  source: EXTERNAL_PROVIDER
                  reference: kyc-2026-000123
                  provider: Our onboarding team
                  decision: APPROVED
                  verifiedAt: '2026-11-02T10:15:00Z'
                  document:
                    documentType: PASSPORT
                    documentNumber: AB123456
                    issuingCountry: KE
                    issuingDate: '2022-03-01'
                    expiryDate: '2032-02-28'
                    frontUrl: https://files.example.com/kyc/front.jpg
                    selfieUrl: https://files.example.com/kyc/selfie.jpg
              sharedSession:
                summary: A shared session
                value:
                  source: SHARED_SESSION
                  reference: share-7731
                  shareToken: st_4b1e9c0d
      responses:
        '201':
          description: Verification imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  status:
                    type: integer
                  message:
                    type: string
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Cardholder'
                      - type: object
                        properties:
                          importedVerification:
                            type: object
                            properties:
                              source:
                                type: string
                              provider:
                                type: string
                              reference:
                                type: string
                              sourceDecision:
                                type: string
                              sourceVerifiedAt:
                                type: string
                              sessionId:
                                type: string
                              importedAt:
                                type: string
                                format: date-time
                              importedBy:
                                type: string
        '400':
          description: reference is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 400
                message: reference is required
                error:
                  code: INVALID_REQUEST
                  detail: reference is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Cardholder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 404
                message: Cardholder not found
                error:
                  code: CARDHOLDER_NOT_FOUND
                  detail: Cardholder not found
        '409':
          description: This verification has already been imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 409
                message: This verification has already been imported
                error:
                  code: KYC_IMPORT_ALREADY_REDEEMED
                  detail: This verification has already been imported
        '422':
          description: Cardholder is terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 422
                message: Cardholder is terminated
                error:
                  code: CARDHOLDER_TERMINATED
                  detail: Cardholder is terminated
        '503':
          description: Shared verification sessions cannot be accepted right now
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 503
                message: Shared verification sessions cannot be accepted right now
                error:
                  code: SERVICE_UNAVAILABLE
                  detail: Shared verification sessions cannot be accepted right now
components:
  schemas:
    KycDocument:
      type: object
      description: >-
        Identity document details for verification. Optional on create;
        patchable at any time and not locked after approval. Accepted as a whole
        — a partial document is refused rather than stored and ignored. Images
        are copied to our own storage on receipt.
      properties:
        documentType:
          type: string
          enum:
            - PASSPORT
            - NATIONAL_ID
            - DRIVERS_LICENSE
            - RESIDENCE_PERMIT
          example: PASSPORT
        documentNumber:
          type: string
          example: AB123456
        issuingCountry:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        issuingDate:
          type: string
          description: Date of issue, formatted 1994-12-31.
          example: '2019-03-04'
        expiryDate:
          type: string
          description: >-
            Date of expiry, formatted 1994-12-31. Must be in the future and
            after issuingDate.
          example: '2029-03-03'
        frontUrl:
          type: string
          format: uri
          example: https://storage.example.com/doc-front.jpg
        backUrl:
          type: string
          format: uri
          nullable: true
          description: Not required for passports
          example: null
        selfieUrl:
          type: string
          format: uri
          example: https://storage.example.com/selfie.jpg
    Cardholder:
      type: object
      properties:
        cardholderId:
          type: string
          example: chl_01HXYZ1234ABCDEF5678
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Smith
        email:
          type: string
          format: email
          example: john.smith@example.com
        phone:
          type: string
          nullable: true
          example: '+12025551234'
        dateOfBirth:
          type: string
          format: date
          example: '1990-05-15'
        nationality:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        gender:
          type: string
          enum:
            - MALE
            - FEMALE
            - M
            - F
          description: >-
            Cardholder gender. Required for verification on programmes that need
            a verified cardholder — an identity check cannot be run without it.
          example: MALE
        address:
          $ref: '#/components/schemas/Address'
        kycDocument:
          $ref: '#/components/schemas/KycDocumentResponse'
          nullable: true
        externalId:
          type: string
          nullable: true
          example: usr_123456
        metadata:
          type: object
          nullable: true
          example:
            plan: premium
        status:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
            - TERMINATED
          example: ACTIVE
        kycStatus:
          type: string
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          example: APPROVED
        kycVerifiedAt:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-10T14:23:00Z'
        kycRejectionReason:
          type: string
          nullable: true
          description: Only present when kycStatus is REJECTED
          example: null
        totalCards:
          type: integer
          example: 2
        suspendedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        terminatedAt:
          type: string
          format: date-time
          nullable: true
          description: Only present when status is TERMINATED
          example: null
        createdAt:
          type: string
          format: date-time
          example: '2026-05-01T09:00:00Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-05-10T14:23:00Z'
        programEligibility:
          type: array
          description: >-
            Whether this cardholder can be issued a card, per BIN and summarised
            per programme. A programme is eligible when at least one of its BINs
            is. Returned when a single cardholder is read.
          items:
            type: object
            properties:
              programCode:
                type: string
                example: FYT-USD-02
              programName:
                type: string
                example: USD Global Tier 2
              eligible:
                type: boolean
                example: false
                description: >-
                  Whether any BIN on this programme can issue for this
                  cardholder right now.
              requiresVerification:
                type: boolean
                description: >-
                  Whether any BIN on this programme needs a verified cardholder.
                  A summary: it does not by itself close the programme.
                example: true
              reason:
                type: string
                description: Present only when not eligible; says what to do.
              bins:
                type: array
                description: >-
                  Every issuable BIN on this programme, each with its own
                  answer. The BIN is where the decision is made.
                items:
                  type: object
                  properties:
                    binCode:
                      type: string
                      example: SGVISAV01
                    binName:
                      type: string
                      example: Virtual Card - Singapore BIN
                    bin:
                      type: string
                      description: >-
                        The BIN number, as printed on cards issued from it.
                        Absent where the registry has no number recorded.
                      example: '49372410'
                    issuingCountry:
                      type: string
                      description: ISO 3166-1 alpha-2 country the BIN issues from.
                      example: SG
                    scheme:
                      type: string
                      enum:
                        - VISA
                        - MASTERCARD
                    formFactor:
                      type: string
                      enum:
                        - VIRTUAL
                        - PHYSICAL
                    requiresVerification:
                      type: boolean
                      description: Whether this BIN needs a verified cardholder.
                    eligible:
                      type: boolean
                      description: Whether a card can be issued from this BIN right now.
                    reason:
                      type: string
                      description: Present only when not eligible; says what to do.
                    verificationStatus:
                      type: string
                      enum:
                        - NOT_SUBMITTED
                        - IN_REVIEW
                        - REJECTED
                        - VERIFIED
                      description: >-
                        Where this BIN's own verification stands. A cardholder
                        is registered per BIN, so two BINs can be in different
                        states at once. Absent on a BIN whose issuer keeps no
                        cardholder record of its own: there the cardholder's
                        kycStatus decides, and it must be APPROVED.
                      example: NOT_SUBMITTED
                    canSubmit:
                      type: boolean
                      description: >-
                        Whether submitting this cardholder to this BIN now would
                        do anything. Absent once verified, and while your own
                        verification has not concluded.
                      example: true
                    verificationMessage:
                      type: string
                      description: >-
                        What came back about this cardholder on this BIN - why a
                        review failed. Absent when nothing was said.
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 422
        message:
          type: string
          example: Human readable message
        error:
          $ref: '#/components/schemas/ErrorBody'
        meta:
          $ref: '#/components/schemas/Meta'
    Address:
      type: object
      properties:
        address:
          type: string
          example: 123 Main Street, Apt 4B
        city:
          type: string
          example: Newark
        state:
          type: string
          nullable: true
          example: Delaware
        postalCode:
          type: string
          nullable: true
          example: '19701'
        country:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
      required:
        - address
        - city
        - country
    KycDocumentResponse:
      type: object
      description: >-
        The identity document as it is RETURNED, which is not the same shape it
        is sent in. Changed on 2026-10-19: frontUrl, backUrl and selfieUrl are
        no longer returned, and documentNumber comes back masked to its last
        four characters. A profile fetch should not be a way to open somebody's
        passport — anything holding one of your tokens could page the cardholder
        list and keep a link to every identity image in it. For a DELETED
        cardholder the whole object is null: their documents stop being
        reachable to anyone, including through our own admin tools.
      properties:
        documentType:
          type: string
          enum:
            - PASSPORT
            - NATIONAL_ID
            - DRIVERS_LICENSE
            - RESIDENCE_PERMIT
          example: PASSPORT
        documentNumber:
          type: string
          description: >-
            Masked to the last four characters. Enough to reconcile against your
            own record; not enough to impersonate its holder.
          example: ••••3456
        issuingCountry:
          type: string
          description: ISO 3166-1 alpha-2
          example: US
        issuingDate:
          type: string
          example: '2019-03-04'
        expiryDate:
          type: string
          example: '2029-03-03'
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        detail:
          type: string
          example: dateOfBirth must be in YYYY-MM-DD format
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6a7b8c9d0e1f2
        platform:
          type: string
          example: Fyatu CaaS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-22T15:00:00Z'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: API key missing
              value:
                success: false
                status: 401
                message: API key is required
                error:
                  code: AUTH_TOKEN_MISSING
                  detail: API key is required
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
            invalid:
              summary: API key invalid
              value:
                success: false
                status: 401
                message: Invalid API key
                error:
                  code: AUTH_TOKEN_INVALID
                  detail: Invalid API key
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
        <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.