---
title: "Start Transaction"
method: POST
path: "/api/v1/start"
tags: ["Start a Transaction"]
---

# Start Transaction

`POST /api/v1/start`

Starts a transaction. For Capture, you begin and end the transaction with a single call to the /start endpoint. For Direct, you begin the transaction with a call to the /start endpoint, and then continue the transaction with subsequent calls to additional endpoints, such as /submit-back, /end, and /get-results.

## Headers

- `signature` string, required — Encrypted Request Body
- `customer-id` string, required — Your provided customer ID.

## Request body

- AppRoutesRoutesMvpV1SwaggerSwaggerDocModelsStartRouteRequest
  - `public_data` object, required — May **not** contain personally identifiable information (PII). A `public_data` object is required even if it is empty, for example, `public_data: {}`.
    - `qr_breakpoint_px` integer — Specifies the pixel measurement at which point a screen width exceeding this value results in a QR code displayed by Capture (instead of the capture process welcome page). For example, if `qr_breakpoint_px` is 700, then a screen larger than 700 pixels results in a QR code to be scanned. Therefore, this value is the breakpoint measurement that specifies whether the customer is using a phone screen or a monitor.
    - `redirect_url` string — A redirect can occur at the completion of the capture process. For example, this redirect URL could load your company's webpage to the end user browser. Use HTTPS in the URL with a fully qualified domain.
    - `error_redirect_url` string — An error redirect can occur if the end user does not complete the capture process, for example, if the end user declines camera access. Another example is if the end user does not complete the capture process in time, as defined by the `ttl` property of the `private_data` object. The default `ttl` value is 10 minutes. After an error, this URL loads in the browser, redirecting the end user. Use HTTPS in the URL with a fully qualified domain.
    - `results_url` string — Postback URL to handle response data from the verification process. Verification results are **not** delivered to the end-user browser. Verification results are posted back to this URL to be viewed by your customer associate. Use HTTPS in the URL with a fully qualified domain. The response header `Content-Type` is `text/plain`.
    - `status_url` string — Capture Only. Postback URL to handle status updates for the Capture experience. This parameter is not available for Direct integrations. Use HTTPS in the URL with a fully qualified domain. The response header `Content-Type` is `text/plain`.
    - `capture_language` 'en-us' | 'fr-ca' | 'es-mx' — Capture Only. Language setting. This property is not available for Direct integrations.
    - `device_validation` boolean — Capture Only. If false, excludes `ipqs` (Device Confidence signal) in the `/get-results` response when either `send_link` or `return_capture_url` is submitted with the `/start` request. If true (or empty), `ipqs` is returned by `/get-results`. If you include `ipqs` in the `signals` array, `ipqs` is returned regardless of the `device_validation` value.
  - `private_data` object, required — May contain personally identifiable information (PII). A `private_data` object is required even if it is empty, for example, `private_data: {}`. If empty, default values are used according to the configuration established by Intellicheck for your account.
    - `document_type` 'na_dl' | 'other' | 'passport' — Identification type. Values: `na_dl`, `passport`, `other`. Select only one. If you specify `na_dl`, then at a minimum, you must include the `idcheck` signal. Likewise, if you select `passport` or `other`, then at a minimum, you must include the `ocr_scan` signal. If these minimum signal requirements are not specified in your request body, then they will be used by default.
    - `location` string — A text field to identify the location where the request is coming from. This is used for reporting purposes. This field should contain the two-letter abbreviation of the state the request is coming from, and optionally if known the city and zip. May capture additional information, such as store number.
    - `purpose` string — A text field that must be used to identify the purpose of the scan, and optionally, a tracking number to correlate the scan to your logs. This is used for both requirements. Purposes may include the following: - Credit Card Payment - Loyalty Account Lookup - Loyalty Credit Payment - Loyalty Signup - Buy Online Pickup In Store - Visitor Management - Age Verification - Credit Card Application - Hotel Guest
    - `return_capture_url` boolean — If true, returns a URL address for the capture session in the form of a capture_url parameter in the response body. If false, no URL address is returned in the response body.
    - `return_images` boolean — If true, returns an `images` object in `get-results` with the following properties: `front`, `back`, and `selfie` as base64-encoded images. The value of `front`, `back`, or `selfie` is `null` if the image was not submitted during the transaction.
    - `send_link` object — Sends a verification link to the customer via SMS or WhatsApp.
      - `type` 'sms' | 'whatsapp' — Delivery method for the verification link. Use `sms` for text message or `whatsapp` for WhatsApp message. Contact Intellicheck to enable WhatsApp for your account.
      - `body` string — Custom message body for SMS delivery. If omitted when `type` is `sms`, the default SMS text message template is used. Ignored when `type` is `whatsapp` because the message body is determined by the configured template.
      - `to` string — Provided phone number. Prefix phone numbers with a plus sign, for example, +1. Do not include separators.
    - `signals` string[] — Array of signals to run for this transaction. Possible values include: - `document_liveness_idrnd` (Doc Liveness) - `idcheck` (Authoritative North America Barcode) - `ocr_match` (Doc Verify) - `ocr_scan` (International Verify) - `selfie` (Face Verify) Leave blank to request all signals to which you are subscribed.
    - `ttl` number — Override of the default minutes to complete. Maximum value is 30.
    - `user_defined` object — A JSON object that will be returned and appended to the results in the private_data object. Requires configuration by Intellicheck.

## Response `200`

Transaction successfully started. The response body varies based on the integration and request parameters. Here are four common examples:

---
# Direct integration - polling
Your request included only the minimum required properties: `signals` and `document_type`. The `private_data` response object includes a `transaction_id`. Your application must poll the `/get-results` endpoint to retrieve verification results.

---
# Direct integration - webhook
Your request included the optional `results_url`. The `public_data` response echoes back the `results_url`. This approach is the preferred method. Intellicheck sends verification results to your webhook URL when processing completes. No polling is required.

---
# Capture integration - send SMS
Your request included `send_link` with a phone number. The `private_data` response echoes back the `send_link` property. The `capture_url` is returned in `public_data` for reference. Intellicheck sends the `capture_url` link to the end user by way of SMS or WhatsApp.

---
# Capture integration - redirect
Your request included `return_capture_url: True`. The `private_data` response includes a `capture_url` property for reference. Intellicheck redirects the end user browser to the `capture_url` to begin the Capture process.

- AppRoutesRoutesMvpV1SwaggerSwaggerDocModelsStartRouteResponse
  - `public_data` object, required
    - `endpoint` string — The requested endpoint.
    - `version` string — Version of the API.
    - `capture_url` string — The requested URL address for the capture session. Returned here if `return_capture_url: True` in the `private_data` request. This URL is included with the text message specified in the `send_link` request object.
    - `results_url` string — The requested postback URL to handle response data from the verification process. Verification results are **not** delivered to the end-user browser. Verification results are posted back to this URL to be viewed by your customer associate.
    - `redirect_url` string — The requested redirect URL that occurs at the completion of the capture process.
    - `error_redirect_url` string — The requested error redirect URL applied if the end user does not complete the capture process, for example, if the end user declines camera access or if the transaction times out. After an error, this URL loads in the browser, redirecting the end user.
    - `status_url` string — The requested postback URL to handle status updates for the Capture experience.
    - `capture_language` string — The requested language setting.
    - `qr_breakpoint_px` integer — The requested pixel measurement at which point a screen width exceeding this value results in a QR code displayed by Capture (instead of the capture process welcome page).
  - `private_data` object, required
    - `transaction_id` string — ID issued at the beginning of a transaction to associate all subsequent processes within the transaction until ended.
    - `capture_url` string — The requested URL address for the capture session. Returned here if `return_capture_url: True` in the `private_data` request.
    - `signals` string[] — Confirmed list of signals to run.
    - `ttl` number — The requested minutes a user will have to complete the capture process. Defaults to 10 minutes unless overridden.
    - `message` string — A message containing the forced `ttl` value if the requested value is greater than the allowed maximum.
    - `send_link` object — Information about the verification link delivery.
      - `type` string — Delivery method used: `sms` or `whatsapp`.
      - `body` string — Message body for SMS text delivery. For WhatsApp delivery, the message body is determined by the configured template.
      - `to` string — Phone number where the verification link was sent.
    - `capture_expiration_utc` string — A UTC date and time when the transaction expires. Format is mm-dd-yyyy hh:mm:ss. It is calculated based on the current date and time plus the ttl value, which is in minutes.

## Other responses

- `400` — Bad Request - The request contains invalid or malformed data. --- ## Request Errors **Missing required values** - Required values in the header are missing from the request. The `customer_id` and `signature` values are required. **Poorly formed customer id** - The `customer_id` header value is malformed or cannot be parsed. **Bad encoding** - The request body could not be decoded from base64 or parsed as valid JSON. --- ## Field Validation Errors **Poorly formed phone number** - Invalid phone number in the `send_link.to` property. Prefix phone numbers with a plus sign (+) followed by country code (e.g., +15551234567 for US numbers). **Invalid capture_language** - Invalid value in the `capture_language` property in `public_data`. Must be one of: `en-us`, `fr-ca`, or `es-mx`. **Invalid urls** - Invalid URLs in `public_data` properties: `redirect_url`, `error_redirect_url`, `results_url`, or `status_url`. URLs must be properly formatted with valid protocol (https://) and domain. Do not include spaces. **send_link object bad request** - Invalid data in the `send_link` object in `private_data`. The `type` property must be one of: `sms` or `whatsapp`. The `to` property must match the format required by the specified type. **invalid ttl value** - Invalid value in the `ttl` property in `private_data`. Must be a positive integer, greater than 0 but less than or equal to 30, representing minutes to complete. **Purpose field missing from private_data** - Missing `purpose` property in `private_data`. This field is required based on your account configuration and describes the reason for identity verification. **Private body bad request** - One or more fields in `private_data` contain invalid types, missing required fields, forbidden fields, or values outside allowed ranges. **Public body bad request** - One or more fields in `public_data` contain invalid types, missing required fields, forbidden fields, or values outside allowed ranges.
- `401` — Unauthorized - Authentication failed. **Common Causes:** - Invalid HMAC-SHA256 signature - Invalid customer ID - Invalid application credentials
- `404` — Not Found - The requested endpoint does not exist.
- `500` — Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request. **Common Causes:** - Database connection failures - Missing server configuration - Request processing errors - Signal processing errors **Action:** If this error persists, contact Intellicheck support with your transaction ID (if available). The error details are logged on the server for investigation.

---

[API](https://skmtc.dev/intellicheck/apis/idn-direct-api.md) · [All operations](https://skmtc.dev/intellicheck/apis/idn-direct-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/intellicheck/idn-direct-api/revisions/9ce4fb734b46/schema)