---
title: "Create and configure a transaction"
method: POST
path: "/api/transactions"
tags: ["Transaction"]
---

# Create and configure a transaction

`POST /api/transactions`

## Request

- Base URL: `https://verification.trulioo.com`
- URL: `https://verification.trulioo.com/api/transactions`
- Auth: HTTP bearer

Creates a transaction with configuration options for document verification, selfie liveness verification, biometric verification, and optional SDK configuration for client-side capture.

## Headers

- `Accept-Version` string, required

## Request body

- TransactionConfiguration
  - `documentVerification` DocumentVerificationConfig, required: Document verification configuration.
    - `enabled` boolean, required: Enables/disables document verification.
    - `documentsAccepted` object[], required: List of permissible document types combined with issuing countries and (for US/CA where applicable) states/provinces. An empty array accepts all countries and all document types.
      - `documentType` 'DRIVERS_LICENSE' | 'PASSPORT' | 'ID_CARD' | 'RESIDENCE_PERMIT' | 'MILITARY_ID' | 'VISA' | 'HEALTH_CARD' | 'TRAVEL_DOCUMENT' | 'VOTER_ID' | 'TAX_ID': Document type.
      - `documentOrigin` object[]: Allowed issuing countries (ISO 3166-1 alpha-2). For US/CA and certain document types, you may also specify postal state/province codes (e.g., "CA", "NY", "BC"). Provide an empty array to accept all countries.
        - `countryCode` string: Country Code (ISO 3166-1 alpha-2).
        - `jurisdictions` object[]: US/CA only. Two-letter postal subdivision codes (e.g., "FL", "BC"). If omitted or empty, configuration applies at country level.
          - `jurisdictionCode` string
    - `acceptFrontImageOnly` boolean: If true, only the front image is required.
    - `acceptList` string[]: Allowed Trulioo document IDs (overrides territory/type criteria).
    - `denyList` string[]: Denied Trulioo document IDs (overrides territory/type criteria).
  - `selfieVerification` SelfieVerificationConfig, required: Selfie liveness verification configuration.
    - `enabled` boolean, required: Enables/disables selfie liveness verification.
  - `faceMatchVerification` FaceMatchVerificationConfig: Configuration for selfie-only transactions that reuse a prior document verification. When provided, the transaction imports document images from a completed transaction owned by the same organization and performs face match plus selfie liveness using those images and the selfie captured in the following step.
    - `sourceTransactionId` string, uuid: Transaction ID from the same organization that already completed document verification; must not be expired or in ERROR.
  - `matcherConfigs` MatcherConfig[]
    - `matchers` object[]
      - `token` 'FIRST_NAME' | 'MIDDLE_NAME' | 'LAST_NAME' | 'FULL_NAME' | 'DATE_OF_BIRTH' | 'ADDRESS_LINE_1' | 'CITY' | 'STATE_PROVINCE' | 'POSTAL_CODE' | 'COUNTRY' | 'FIRST_LAST_NAME' | 'SECOND_LAST_NAME' | 'SPOUSE_LAST_NAME' | 'BIRTH_LAST_NAME'
      - `precision` 'EXACT_MATCH' | 'HIGH_PARTIAL_MATCH' | 'PARTIAL_MATCH' | 'POOR_MATCH' | 'NO_MATCH'
      - `strategy` object: Controls transliteration, tokenization, and fuzzy matching. Inputs are normalized with diacritic removal before matching.
        - `transliterationMatch` object
          - `enabled` boolean: Apply transliteration before matching.
        - `tokenMatch` object
          - `enabled` boolean: Tokenize strings and compare tokens using threshold logic.
          - `tokenSimilarityThreshold` number, float
        - `basicFuzzyMatch` object
          - `enabled` boolean: Include basic similarity algorithms in final match.
    - `active` boolean: Whether the matcher set is active.
  - `subjectInfo` SubjectInfo: Customer Input Personal Identification Information.
    - `firstName` string
    - `middleName` string
    - `lastName` string
    - `fullName` string
    - `dateOfBirth` string, date
    - `addressLine1` string
    - `stateProvince` string
    - `city` string
    - `postalCode` string
    - `country` string
    - `firstLastName` string
    - `secondLastName` string
    - `birthLastName` string
    - `spouseLastName` string
  - `subjectInfoList` SubjectInfo[]
    - `firstName` string
    - `middleName` string
    - `lastName` string
    - `fullName` string
    - `dateOfBirth` string, date
    - `addressLine1` string
    - `stateProvince` string
    - `city` string
    - `postalCode` string
    - `country` string
    - `firstLastName` string
    - `secondLastName` string
    - `birthLastName` string
    - `spouseLastName` string
  - `biometricVerification` BiometricVerificationConfig: Biometric verification configuration.
    - `enabled` boolean: Enables biometric verification; requires a non-empty uniquePersonIdentifier.
    - `uniquePersonIdentifier` string: Identifier from a prior successful enrolment.
    - `externalUniquePersonIdentifier` string: Optional external identifier associated with the enrolment.
  - `sdk` SDK: SDK configuration for client-side capture and UI settings.
    - `captureDocumentEnabled` boolean: Enable or disable document capture in SDK.
    - `captureSelfieEnabled` boolean: Enable or disable selfie capture in SDK.
    - `countrySelectionEnabled` boolean: Allow country selection in SDK.
    - `jurisdictionSelectionEnabled` boolean: Allow jurisdiction selection in SDK.
    - `documentSelectEnabled` boolean: Allow document type selection in SDK.
    - `additionalConsentRequired` boolean: Require additional consent in SDK workflow.
    - `useDeviceLocale` boolean: Use device locale automatically.
    - `locale` 'ar' | 'bn' | 'bg' | 'zh-HK' | 'zh-Hans-CN' | 'zh-Hant-TW' | 'cs' | 'da' | 'nl-NL' | 'en-GB' | 'en-US' | 'et' | 'fi' | 'fr-CA' | 'fr-FR' | 'de-DE' | 'el' | 'gu' | 'hi' | 'hu' | 'it-IT' | 'ja' | 'kn' | 'ko' | 'lt' | 'ml' | 'mr' | 'no' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'es-MX' | 'sv' | 'ta' | 'te' | 'th' | 'tr' | 'uk' | 'vi': SDK locale code.
    - `theme` Theme
      - `style` 'DEVICE' | 'DARK' | 'LIGHT'
      - `colors` ThemeColors
        - `light` ColorPalette
          - `logoURL` string: URL for custom logo.
          - `primaryButton` string
          - `primaryButtonText` string
        - `dark` ColorPalette
          - `logoURL` string: URL for custom logo.
          - `primaryButton` string
          - `primaryButtonText` string
    - `redirectLink` string, uri: A URL that hosts the Trulioo SDK
    - `presetCountries` string[]: Optional list of ISO 3166-1 alpha-2 country codes to preselect in the SDK's country picker. Codes are normalized to uppercase; unknown codes are ignored.
  - `webhookUrl` string, uri: Callback URL for webhook notifications
  - `clientId` string: Optional client identifier, max length 150 characters
  - `documentLivenessConfig` DocumentLivenessConfig: Configuration for document liveness checks.
    - `screenUsed` object: Screen-used (displayed) detection settings
      - `enabled` boolean: Whether to enable detection
      - `calibration` 'MEDIUM' | 'HIGH': Calibration level for detection
    - `printout` object: Printout detection settings
      - `enabled` boolean: Whether to enable detection
      - `calibration` 'MEDIUM' | 'HIGH': Calibration level for detection
    - `portraitSubstitution` object: Portrait substitution detection settings
      - `enabled` boolean: Whether to enable detection
      - `calibration` 'MEDIUM' | 'HIGH': Calibration level for detection
    - `skipAlreadyCropped` boolean: Skip already-cropped image check

## Response `201`

Transaction created.

- TransactionResponse
  - `transactionId` string, uuid: Unique transaction identifier.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `429`: Too Many Requests (rate limited)
- `500`: Internal Server Error

---

[API](https://skmtc.dev/trulioo/apis/kyc-document-api.md) - [All operations](https://skmtc.dev/trulioo/apis/kyc-document-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trulioo/apis/kyc-document-api/revisions/53a65736c9f8?raw)