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

# Import a shared identity

> Import a partner’s existing verification with consent and an idempotency key.

See [reusable identity onboarding](https://docs.stableyard.fi/concepts/individual-kyc.md#reuse-a-partners-existing-didit-verification) for consent, review and retry requirements.


## OpenAPI

````yaml openapi.json POST /v2/accounts/{accountId}/kyc/imports
openapi: 3.1.0
info:
  title: Stableyard Partner API
  version: 2.0.0
  x-stableyard-api-version: '2026-09-09'
  x-stableyard-supported-api-versions:
    - '2026-09-09'
  summary: Backend API for UPAs, Payments, activity, and optional financial products.
  description: >

    Use this API from a trusted partner backend with an app ID and app secret.


    ## Recommended integration


    1. Call `GET /v2/partners/config` to verify credentials and discover enabled
    capabilities.

    2. Create a UPA only when your product needs a persistent Stableyard
    account.

    3. Create a receive or send Payment with `POST /v2/payments`.

    4. Redirect a payer to the returned `paymentUrl` or pass the Payment
    credentials to an official Stableyard interface SDK.

    5. Process signed webhooks and fetch the Payment by ID for reconciliation.


    Checkout execution and account-bound browser endpoints are documented in the
    separate Interfaces & SDKs reference.
  x-stableyard-documentation-surface: partner
servers:
  - url: https://prod-api.stableyard.fi
    description: Production
  - url: https://staging-api-v2.stableyard.fi
    description: Sandbox
security: []
tags:
  - name: Authentication
    x-displayName: API authentication
    description: Verify your app ID and app secret before calling UPA APIs.
  - name: Accounts
    x-displayName: UPA Accounts
    description: Create Universal Payment Accounts and manage account settings.
  - name: Deposit Addresses
    description: Create reusable receive addresses and verify inbound deposits.
  - name: Identity & KYC
    description: >-
      Verify the UPA email and run identity verification. Managed vaults and
      fiat payment rails use this same verified UPA identity.
  - name: Vaults
    description: >-
      Create policy-controlled stablecoin vaults and manage policy updates for
      accounts.
  - name: Payments
    description: >-
      Create escrow-first payments, issue partner-authenticated send
      instructions or executions, power public checkout, and reconcile
      collection through final account settlement.
  - name: Balances & Transactions
    description: >-
      Read Stableyard-posted financial activity. Balances are ledger projections
      of activity Stableyard processed; they are not live balances of externally
      controlled wallets.
paths:
  /v2/accounts/{accountId}/kyc/imports:
    post:
      tags:
        - Identity & KYC
      summary: Import an existing shared identity verification
      description: >-
        Server-to-server, Individual UPA only. Requires v2:kyc, active app
        policy, verified UPA email and explicit consent. Review-first by
        default; caller cannot select trust mode. The share token is write-only
        and never stored. Identical Idempotency-Key/input returns the same
        operation; changed inputs conflict. Ambiguous outcomes are held for
        operator reconciliation and never blindly resubmitted. Approval requires
        approved person-bound AML checks, explicit compliance evidence/consent
        review and policy freshness limits. Missing checks remain blocked even
        when the source decision was approved. Consume verification.eligibility
        before using fiat rails; import success alone is not payment readiness.
      operationId: importAccountIdentity
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: Stableyard-Version
          in: header
          required: false
          schema:
            type: string
            enum:
              - '2026-09-09'
          description: >-
            Optional contract-version assertion. Omit it to use the app
            environment's pinned version. A different supported version is
            accepted only after that environment is explicitly migrated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportAccountIdentityRequest'
            examples:
              example:
                summary: Import an existing shared identity verification request
                value:
                  shareToken: >-
                    eyJhbGciOiJIUzI1NiJ9.eyJzZXNzaW9uX2lkIjoiMTExMTExMTEtMTExMS00MTExLTgxMTEtMTExMTExMTExMTExIiwic2Vzc2lvbl9raW5kIjoidXNlciIsImZyb21fYXBwbGljYXRpb25faWQiOiIyMjIyMjIyMi0yMjIyLTQyMjItODIyMi0yMjIyMjIyMjIyMjIiLCJmb3JfYXBwbGljYXRpb25faWQiOiIzMzMzMzMzMy0zMzMzLTQzMzMtODMzMy0zMzMzMzMzMzMzMzMiLCJpYXQiOjAsImV4cCI6MX0.synthetic_invalid_signature
                  consent:
                    accepted: true
                    version: v1
                    reference: consent_receipt_123
      responses:
        '200':
          description: Durable import and current verification state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityImportResponse'
              examples:
                example:
                  summary: Import an existing shared identity verification 200 response
                  value:
                    import:
                      id: kyc_import_123
                      status: submitting
                      nextAction:
                        type: none
                    verification:
                      id: kyc_123
                      accountId: acct_123
                      status: not_started
                      verificationUrl: https://example.com
                      eligibility:
                        status: eligible
                        verifiedAt: '2026-08-28T10:00:00.000Z'
                        validUntil: '2026-08-28T10:00:00.000Z'
                        revokedAt: '2026-08-28T10:00:00.000Z'
                        reasonCode: identity_eligibility_invalid
                      nextAction:
                        type: none
                      createdAt: '2026-08-28T10:00:00.000Z'
                      updatedAt: '2026-08-28T10:00:00.000Z'
        '400':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 400 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '401':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 401 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '403':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 403 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '404':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 404 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '409':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 409 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '422':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 422 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '502':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 502 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
        '503':
          description: Validation, access, consent, conflict, or provider failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  summary: Read this app's identity reuse policy 503 response
                  value:
                    error:
                      code: bad_request
                      message: The request is invalid
                      details: example
      security:
        - partnerBasicAuth: []
components:
  schemas:
    ImportAccountIdentityRequest:
      type: object
      additionalProperties: false
      required:
        - shareToken
        - consent
      properties:
        shareToken:
          type: string
          minLength: 100
          maxLength: 8192
          pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
          writeOnly: true
          example: >-
            eyJhbGciOiJIUzI1NiJ9.eyJzZXNzaW9uX2lkIjoiMTExMTExMTEtMTExMS00MTExLTgxMTEtMTExMTExMTExMTExIiwic2Vzc2lvbl9raW5kIjoidXNlciIsImZyb21fYXBwbGljYXRpb25faWQiOiIyMjIyMjIyMi0yMjIyLTQyMjItODIyMi0yMjIyMjIyMjIyMjIiLCJmb3JfYXBwbGljYXRpb25faWQiOiIzMzMzMzMzMy0zMzMzLTQzMzMtODMzMy0zMzMzMzMzMzMzMzMiLCJpYXQiOjAsImV4cCI6MX0.synthetic_invalid_signature
          description: >-
            Short-lived token minted for Stableyard's receiving identity
            application. Example is deliberately invalid.
        consent:
          type: object
          additionalProperties: false
          required:
            - accepted
            - version
            - reference
          properties:
            accepted:
              type: boolean
              const: true
            version:
              type: string
              minLength: 1
              maxLength: 64
              pattern: ^[A-Za-z0-9_.:-]+$
              example: v1
            reference:
              type: string
              minLength: 1
              maxLength: 128
              pattern: ^[A-Za-z0-9_.:-]+$
              example: consent_receipt_123
    IdentityImportResponse:
      type: object
      additionalProperties: false
      required:
        - import
        - verification
      properties:
        import:
          type: object
          additionalProperties: false
          required:
            - id
            - status
            - nextAction
          properties:
            id:
              type: string
              pattern: ^kyc_import_[a-zA-Z0-9_-]+$
              example: kyc_import_123
            status:
              type: string
              enum:
                - submitting
                - imported
                - requires_reconciliation
                - rejected
            nextAction:
              type: object
              additionalProperties: false
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - none
                    - wait
                    - contact_support
        verification:
          $ref: '#/components/schemas/KycVerification'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              minLength: 1
              maxLength: 128
              example: bad_request
            message:
              type: string
              minLength: 1
              maxLength: 1000
              example: The request is invalid
            details: {}
    KycVerification:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - status
        - eligibility
        - nextAction
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^kyc_[A-Za-z0-9_-]+$
          example: kyc_123
        accountId:
          type: string
          pattern: ^acct_[A-Za-z0-9_-]+$
          example: acct_123
        status:
          type: string
          enum:
            - not_started
            - pending
            - in_progress
            - approved
            - rejected
            - expired
            - requires_review
        verificationUrl:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            Hosted verification URL to send to the account holder while action
            is required.
        eligibility:
          type: object
          additionalProperties: false
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - eligible
                - expired
                - revoked
                - requires_review
                - not_eligible
              description: >-
                Current Stableyard identity eligibility. Regulated operations
                recheck this value at execution time.
            verifiedAt:
              type: string
              format: date-time
            validUntil:
              type: string
              format: date-time
            revokedAt:
              type: string
              format: date-time
            reasonCode:
              type: string
              maxLength: 128
              description: >-
                Why the account is no longer eligible.
                `verification_validity_elapsed`: the verification passed its
                validity period. `operator_revoked`: Stableyard revoked it.
                `identity_eligibility_invalid`: the verification outcome no
                longer supports eligibility. Treat any other value as
                `identity_eligibility_invalid`.
              x-known-values:
                - identity_eligibility_invalid
                - verification_validity_elapsed
                - operator_revoked
              example: identity_eligibility_invalid
        nextAction:
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - none
                - start_verification
                - complete_verification
                - refresh_verification
                - contact_support
        completedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  securitySchemes:
    partnerBasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth. Username is the Stableyard app ID. Password is the app
        secret. The optional Stableyard-Version request header must match the
        environment pin.

````

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