# API Documentation The Veratad IDresponse API is accessible via RESTful HTTPS JSON requests exposing solutions that are used for verification processes. ![](/files/-MC8glewdB5wUQG4OGr7) ## What services are available? Veratad offers many services to verify your customer's age and identity. These services include age and identity verification through trusted and verified data source matching, knowledge based authentication to quiz your customer on their identity, identity document scanning and management, phone/email verification and validation and one-time password delivery via SMS and call. {% hint style="success" %} If you are having trouble deciding which service to use for your business the best place to start is a consultation with your Veratad Professional Services Team Member. They will be happy to discuss your business objectives and guide you in the right service direction. If you do not know your team member just drop an email to ****. {% endhint %} ## AgeMatch Age verification service that matches customer attributes against trusted and verified data sources to determine their age. {% content-ref url="/pages/JlgW5supfEp1Qam2GgG6" %} [United States](/agematch/united-states) {% endcontent-ref %} {% content-ref url="/pages/mdPGNnnOpkOofnWXhXA5" %} [International](/agematch/agematch-international) {% endcontent-ref %} {% content-ref url="/pages/SR1upzMHwwUQcxus6GUc" %} [With KBA Quiz](/agematch/with-kba) {% endcontent-ref %} ## IDMatch Identity verification service that matches customer input data against trusted and verified data sources. {% content-ref url="/pages/-LrjPMxtyC9PG5UzN9lW" %} [United States](/identity-verification/idmatch-us) {% endcontent-ref %} {% content-ref url="/pages/-M8zvJxLngbridA6Heff" %} [With KBA Escalation](/identity-verification/idmatch-us/idmatch-escalation) {% endcontent-ref %} {% content-ref url="/pages/-MCDaFXvMJ8Rb3ApPQfn" %} [COPPA Compliance](/identity-verification/idmatch-us/coppa-compliance) {% endcontent-ref %} {% content-ref url="/pages/-LrkFKRaSQek27pX1A9s" %} [KYC/CIP Compliance](/identity-verification/idmatch-us/kyc-cip-compliance) {% endcontent-ref %} ## What's the difference between AgeMatch and IDMatch? This is a common question and one that your Veratad Professional Services team member can help you answer. See this link below for a more in depth explanation of Veratad Services. {% content-ref url="/pages/-MCCmKlj-1VIesSanClX" %} [Understanding Veratad Services](/knowledge-base/understanding-veratad-services) {% endcontent-ref %} ## IDMatch+ Identity verification with a knowledge based authentication quiz based on trusted and verified data sources. {% content-ref url="/pages/-LrjPVJ4laByqRWomWqD" %} [United States](/knowledge-based-authentication/unitedstates) {% endcontent-ref %} ## DCAMS DCAMS (Document Capture and Management System) is Veratad's full suite of tools that will allow you to scan, store, match a selfie and manually review identity documents. {% content-ref url="/pages/-Lrp6hWlfIEweqQzGQ8X" %} [Document Capture and Management Services](/id-document-verification/overview) {% endcontent-ref %} ## PhoneMatch Phone verification service that allows you to verify, validate and send OTP via SMS and call for phone numbers. {% content-ref url="/pages/-MB4Ew4X\_rvHXg2mYOZK" %} [Verification and Validation](/phone-verification-and-validation/verification-and-validation) {% endcontent-ref %} {% content-ref url="/pages/-MB4FMiDOL6QPQceRvuf" %} [One Time Passwords](/phone-verification-and-validation/one-time-passwords) {% endcontent-ref %} {% content-ref url="/pages/-MB4FWErABQ-YL5b7JLi" %} [Message Delivery](/phone-verification-and-validation/message-delivery) {% endcontent-ref %} ## EmailMatch Email address verification and validation services that allow you to verify, validate email addresses. {% content-ref url="/pages/-LrjPvXlqXipTTL4nWUw" %} [Email Validation](/email-verification-and-validation/validate) {% endcontent-ref %} ## Best Practices {% hint style="success" %} Check out Veratad Best Practices for helpful hints and guidance for a successful integration. {% endhint %} {% content-ref url="/pages/-LrQBoLnrReiWXivpPun" %} [Best Practices](/knowledge-base/best-practices) {% endcontent-ref %} # Authentication This is how we authenticate your request. API queries for all services will be authenticated by including your username and password in the body of the POST request. ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "AgeMatch5.0", "reference": "12345 {A UNIQUE ID}", "rules": "AgeMatch5_0_RuleSet_YOB_SSN", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` {% hint style="info" %} If you do not have your API credentials please contact your company administrator or send an email to **** {% endhint %} # Testing Details on how to test the system ## How does testing work? Each Veratad service comes with a target attribute called `test_key`. This attribute tells the system that the transaction is for testing purposes. Once the system knows that it is a test it will drop the live data and other verification sources and use a fake database with known data values. ## Do I need to change my endpoint? No. The endpoint, service name and user credentials all stay the same when testing. ## Is testing free? Yes. Whenever the `test_key` attribute is sent with a valid value then those transactions are not billable. {% hint style="danger" %} It is important to follow the testing instructions when integrating. Transactions that are not sent as test are billable to your company. {% endhint %} ## Do services have different test cases and methods? Yes. Check your specific service documentation for exact testing instructions. In some cases the responses are canned, and so, regardless of input you will receive a known response. This is not true of all services, and so, in some cases when you send the key the system will run it through the normal verification checks so you can manipulate responses based on your target inputs. ## Are there any services that I am unable to test? Yes. Services like PhoneMatch5.0.SMS where you need to send an OTP to a real phone is impossible to test without using the live service. Please consult with your Veratad representative on this as they will allot you a certain amount of free live transactions for testing. # API Methods These pages document the REST endpoints available for VX integrations. {% content-ref url="/pages/knoeQwuMQc7H0FomA9w0" %} [Create Session](/vx/api-methods/create-session) {% endcontent-ref %} {% content-ref url="/pages/pHykSBNd1M7mA7lx3ueQ" %} [Get Session Result](/vx/api-methods/get-session-result) {% endcontent-ref %} {% content-ref url="/pages/pkpY8TMVFE3wehlliQwC" %} [Webhook](/vx/api-methods/webhook) {% endcontent-ref %} # Create Session ## Overview The VX API provides a comprehensive solution for creating and managing verification sessions. This guide covers: 1. **Authentication** - Obtain a bearer token for authorization. 2. **Create Session** - Generate a verification session link. 3. **iFrame Integration** (optional) - Embed the verification link and handle post message events. *** ## Authentication To interact with the VX API, you must first obtain a Bearer token. This token will authenticate your application for all subsequent requests. ### Endpoint **POST** `https://auth.dcams.app/oauth/token` ### Request Body ```bash curl -X POST https://auth.dcams.app/oauth/token \ -H "Content-Type: application/json" \ -d '{ "client_id": "{{client_id}}", "client_secret": "{{client_secret}}", "audience": "dcams.app", "grant_type": "client_credentials" }' ``` ### Request Details * **client\_id**: Provided by your administrator, this identifies your application. * **client\_secret**: A secret key provided by your administrator for authenticating your application. * **audience**: Specifies the target API, which should be `"dcams.app"`. * **grant\_type**: Always set to `"client_credentials"` for this type of request. ### Responses {% tabs %} {% tab title="200 OK" %} ```json { "access_token": "eyJhb...", "expires_in": 3600, "token_type": "Bearer" } ``` {% endtab %} {% tab title="401 Unauthorized" %} ```json { "error": "access_denied", "error_description": "Unauthorized" } ``` {% endtab %} {% tab title="403 Forbidden" %} ```json { "error": "access_denied", "error_description": "Service not enabled within domain: dcams.ap" } ``` {% endtab %} {% endtabs %} *** ## Create Session After obtaining the Bearer token, you can create a verification session. This session will return a link that the user can use to complete the verification process. ### Endpoint **POST** `https://vx.dcams.app/api/session/create_session` ### Headers * **Authorization**: `Bearer {{access_token}}` (where `{{access_token}}` is the token obtained from the Authentication step) ### Required Fields * **email**: The user's email address. This field is used as the primary identifier of a user, but the email address does not need to be real or working as we will never send the user an email. * **age**: The user's age, which must be in the format `"21+"` (with the plus sign to indicate "age to check and over"). NOTE: "21" is just the example, please use any value that fits your use case. ### Optional Fields {% hint style="info" %} When sending `route_id`, `settings_id` and/or `brand_id` as empty fielfds the default value for each that is associated with the`client_id` will always be used. {% endhint %} * **route\_id**: The route ID to use for this session. If not provided, the default route associated with the `client_id` will be used. * **settings\_id**: Specifies the settings for the session. If not provided, default settings associated with the `client_id` will be used. * **brand\_id**: Specifies the brand for the session. If not provided, a default brand associated with the `client_id` will be used. * **styles**: Customize the appearance of the VX experience. See [Styles](/vx/styles) for a full list of options. * **webhook.endpoint**: Provide the HTTPS endpoint that should receive VX webhook callbacks for this session. Make sure the endpoint is reachable from the public internet. * There are several more optional fields in the full example below. {% hint style="info" %} Webhook deliveries can be protected with either Basic Authentication credentials or an HMAC signature header. Coordinate with your Veratad representative to receive the credentials or signing secret, and validate every webhook before processing it. {% endhint %} ### Request (Simple Example) ```bash curl -X POST https://vx.dcams.app/api/session/create_session \ -H "Authorization: Bearer {{access_token}}" \ -H "Content-Type: application/json" \ -d '{ "email": "test05@veratad.com", "age": "21+" }' ``` ### Request Body (Complete Example with All Optional Fields) For detailed styling options, see [Styles](/vx/styles). ```json { "email": "test05@veratad.com", "age": "21+", "route_id": "p8a7b9c2-4d5e-4b7d-8e2a-4f6c9d8b1e2a", "settings_id": "s9d8f6c7-4b7d-8e2a-f8a7-4c5e9d8b1e2a", "brand_id": "o7e2a8f6-4b7d-9e2a-7f8a-6c4e5b8d1f2a", "settings": { "test_mode": true, "block": false, "isCloseButtonShown": true, "shouldShowContinueOnDesktop": false, "isReactNative": true, "isFooterShown": false }, "webhook": { "endpoint": "https://example.com" }, "fn": "John", "ln": "Doe", "addr": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "phone": "201-555-1234", "dob": "20000101", "ssn": "123-45-6789", "reference": "Ref123", "additionalData": { "key_1": "value_1", "key_2": "value_2" }, "language": "en", "styles": { "colors": { "custom-green": [ "#B3ECE7", "#8FE3DB", "#6BDACF", "#47D1C3", "#23C8B7", "#11BFA5", "#0AA58D", "#008B75", "#006E5D", "#005145" ] }, "primaryColor": "custom-green", "primaryShade": 5, "colorScheme": "light | dark", "logo_url": "https://example.com/logo.png", "defaultRadius": "xs | sm | md | lg | xl | string | number", "button": { "radius": "xs | sm | md | lg | xl | string | number" }, "components": { "button": { "color": "#000000" }, "paper": { "backgroundColor": "#FF0000" } }, "assets": { "icons": { "handoff.header.main": { "alt": "Brand", "url": "https://example.com/images/logo.svg", "srcset": { "2x": "https://example.com/images/logo@2x.svg", "3x": "https://example.com/images/logo@3x.svg" }, "width": 100, "height": 100 } } }, "global": { "backgroundColor": "#000000", "typography": { "font": { "family": "SpaceGrotesk", "normal": { "url": "https://example.com/fonts/SpaceGrotesk-Regular.ttf", "format": "truetype" } } } } }, "resultMessages": { "success": { "verificationSuccessTitle": "Verification Success", "verificationSuccessSubTitle": "You have been verified" }, "failure": { "verificationFailureTitle": "Verification Failure", "verificationFailureSubTitle": "You have not been verified" }, "error": { "verificationErrorTitle": "System Error", "verificationErrorSubTitle": "Please contact customer service", "verificationErrorTokenTitle": "Token Error", "verificationErrorTokenSubTitle": "The token provided is not valid. Please check and try again.", "verificationErrorAlreadyVerifiedTitle": "Already Verified", "verificationErrorAlreadyVerifiedSubTitle": "You have already been verified. Please contact customer support.", "verificationErrorPendingTitle": "Pending Verification", "verificationErrorPendingSubTitle": "Your verification is currently pending. Please wait for further instructions.", "verificationErrorVelocityTitle": "Too Many Attempts", "verificationErrorVelocitySubTitle": "You have exceeded the number of verification attempts. Please try again later." } } } ``` ### Responses {% tabs %} {% tab title="200 OK" %} ```json { "message": "Success", "detail": "Session created successfully", "expires_in": 3600, "request_id": "54bba0ca-c5c7-442d-8c6d-3cf286ccaf23", "link": "https://vx-fe.dcams.app/54bba0ca-c5c7-442d-8c6d-3cf286ccaf23" } ``` {% endtab %} {% tab title="400 Bad Request" %} 
{
    "message": "Bad JSON format",
    "detail": "Please check your JSON and try again",
}
{% endtab %} {% tab title="401 Unauthorized" %} ```json { "message": "Unauthorized", "detail": "Missing a required input" } ``` {% endtab %} {% tab title="403 Forbidden" %} ```json { "message": "Forbidden", "detail": "Invalid API Key or missing token", } { "message": "Already Verified", // this error only occurs if block setting is active "detail": "This user has a status of pass" } ``` {% endtab %} {% tab title="423 Locked" %} ```json { "message": "Pending Review", // this only occurs if the VX app is a human review "detail": "The user has a manual review of an ID document in process" } ``` {% endtab %} {% tab title="429 Too Many Requests" %} ```json { "message": "Too many requests", detail: "You have exceeded the amount of requests", } { "message": "Too many attempts", //this is enforced by email and visitor_id by default. In the case of creatng a session link at this time we will not have the visitor_id, and so, it will be based on email only. "detail": "This user has exceeded the amount of verification sessions" } ``` {% endtab %} {% tab title="500 Internal Server Error" %} ``` { "message": "Internal Server Error", "detail": "{{The reason for error if known}}" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **PRO TIP:** Use the `request_id` to link the session back to your database through either a webhook or a poll request. Additionally, always use the returned link value, as the domain may change at any time. {% endhint %} {% hint style="warning" %} You are limited to 1,000 requests per minute to the create session endpoint. If you require a larger throughput please contact our support team. {% endhint %} *** # Get Session Result `GET` `/api/session/result/:request_id` This endpoint retrieves the session result associated with a specific `request_id`. The session result contains detailed information about the verification process for a user, including personal details, status, and additional metadata. **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer ` | **Response** {% tabs %} {% tab title="200" %} ```json { "fn": "John", "ln": "Doe", "addr": "", "city": "", "state": "", "zip": "", "dob": "19900101", "email": "johndoe@example.com", "phone": "123-456-7890", "reference": "", "status": "PASS", "request_id": "19fe3b9e-384e-41d1-bded-8de9ef3abacb", "additionalData": { "customKey": "customValue" }, "dcams_plus": { "document_data": {}, "output": { "vpin": {} }, "api_processing_error": false, "service": "PhoneMatch5.0.Smart2FA.SMS", "confirmation": 180603431, "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [ "OUT-OF-BAND SUCCESSFUL" ] }, "storage": { "success": null }, "journey": { "stops": [ { "timestamp": "2024-08-19 20:56:25.223174", "type": "NEW REGISTRATION", "source": "", "status": "", "action": "", "detail": "" }, { "timestamp": "2024-08-19 20:56:41.280685", "type": "Data Service", "source": "PhoneMatch5.0.Smart2FA.SMS", "status": "PENDING", "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED" }, { "timestamp": "2024-08-19 20:56:57.448256", "type": "Data Service", "source": "PhoneMatch5.0.Smart2FA.SMS", "status": "PASS", "action": "PASS", "detail": "ALL CHECKS PASSED" } ], "duration": "00h 00m 32s" }, "documents": null } ``` {% endtab %} {% tab title="202" %} ```json { "message": "IN PROGRESS", "detail": "Session result not found, but user started the process." } ``` {% endtab %} {% tab title="404" %} 
{
    "message": "NOT FOUND",
    "detail": "Session result not found, user did not start the process or your request_id is invalid."
}
{% endtab %} {% tab title="500" %} ```json { "message": "INTERNAL SERVER ERROR", "detail": "An unexpected error occurred while processing your request." } ``` {% endtab %} {% endtabs %} # Webhook VX will fire a webhook to your defined endpoint after each components execution through the journey. {% hint style="info" %} When you create the VX session, set the `webhook.endpoint` value to the HTTPS address that should receive callbacks so status updates are delivered to the correct destination. {% endhint %} `POST` `[YOUR_ENDPOINT]` ## Payload {% code lineNumbers="true" %} ```json { "fn": "Avery", "ln": "Langley", "addr": "742 Evergreen Terrace", "city": "Springfield", "state": "IL", "zip": "62704", "dob": "19840224", "ssn": "", "email": "avery.langley@examplemail.com", "phone": "3125550198", "reference": "", "status": "PENDING", "request_id": "e7a5f0d4-1234-5678-9abc-def012345678", "additionalData": { "customKey": "customValue" }, "dcams_plus": { "document_data": {}, "output": { "vpin": {}, "age_estimate": "", "spoof_score": "" }, "api_processing_error": false, "service": "PhoneMatch5.0.Smart2FA.SMS", "confirmation": 206978022, "action": "FAIL", "detail": "FAILED OUT-OF-BAND CHECK", "issues": [] }, "storage": { "success": null }, "journey": { "stops": [ { "timestamp": "2025-10-04 22:17:55.122089", "type": "NEW REGISTRATION", "source": "", "status": "", "action": "", "detail": "" }, { "timestamp": "2025-10-04 22:18:50.543719", "type": "Data Service", "source": "PhoneMatch5.0.Smart2FA.SMS", "status": "PENDING", "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED" }, { "timestamp": "2025-10-04 22:19:09.127088", "type": "Data Service", "source": "PhoneMatch5.0.Smart2FA.SMS", "status": "PENDING", "action": "FAIL", "detail": "FAILED OUT-OF-BAND CHECK" } ], "duration": "00h 01m 14s" }, "documents": null } ``` {% endcode %} ## Field Reference The top-level PII fields returned in the webhook payload reflect the most recent values for the user. They represent the latest data either originally provided when creating the session or modified during the journey and echoed back in the webhook. All `dcams_plus.*` values correspond to the most recent verification transaction. | Field | Type | Description | | --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `fn` | String | Latest first name value recorded for the user during the session. | | `ln` | String | Latest last name value recorded for the user during the session. | | `addr` | String | Latest street address associated with the user. | | `city` | String | Latest city portion of the provided address. | | `state` | String | Latest two-character state or province code. | | `zip` | String | Latest postal code for the provided address. | | `dob` | String | Latest date of birth in `YYYYMMDD` format. | | `ssn` | String | Latest Social Security Number value captured (blank in this example). | | `email` | String | Latest email captured for the verification session. | | `phone` | String | Latest primary phone number associated with the user. | | `reference` | String | Latest optional value supplied by the client to correlate the session. | | `status` | String | Overall session status when the webhook fires. Possible values: `PASS`, `FAIL`, or `PENDING`. | | `request_id` | String | Session identifier returned when the session was originally created (also referred to as the request ID). | | `additionalData` | Object | Optional object of client-defined metadata echoed back from the session. | | `dcams_plus.document_data` | Object | Parsed document attributes returned when document checks run. | | `dcams_plus.output` | Object | Additional outputs such as vPIN results, age estimate, and spoof score. | | `dcams_plus.api_processing_error` | Boolean | Indicates whether the downstream service returned an error. | | `dcams_plus.service` | String | Name of the service that processed the verification step. | | `dcams_plus.confirmation` | Number | Confirmation code returned by the downstream service. | | `dcams_plus.action` | String | Action outcome from the service (for example `PASS`, `FAIL`, or `REVIEW`). | | `dcams_plus.detail` | String | Additional detail describing the outcome. | | `dcams_plus.issues` | Array | Array of human-readable issues, if any. | | `storage.success` | Boolean \| null | Indicates whether the transaction was persisted to long-term storage. | | `journey.stops` | Array | Chronological list of steps taken within the journey. | | `journey.duration` | String | Total time elapsed for the journey. | | `documents` | Object \| null | Container for document artifacts when they are returned. | ## Securing the Webhook VX supports securing webhook deliveries with either Basic Authentication credentials or an HMAC signature header. Your Veratad representative will work with you to enable the preferred option and share the necessary secrets. Always validate the credential or signature before accepting the payload. # Styles The `styles` object customizes the look and feel of the VX verification experience. Use it in the Create Session request to override default UI settings. ## Colors Defines custom color palettes. Each key (e.g., `custom-green`) maps to an array of ten hexadecimal color values representing the shades for that color. ## primaryColor Specifies which color key from `colors` is used as the primary theme color. ## primaryShade Selects the shade index (0–9) from the primary color palette. ## colorScheme Sets the overall color scheme, either `"light"` or `"dark"`. ## logo\_url URL of a logo image displayed in the interface. ## defaultRadius Default border radius applied to components. Accepts preset values (`xs`, `sm`, `md`, `lg`, `xl`) or a custom string/number. ## button.radius Overrides the border radius specifically for buttons. Supports the same values as `defaultRadius`. ## components.button.color Hex value for the text color of primary filled buttons. ## assets.icons.handoff.header.main Defines a custom icon for the handoff header: * **alt** – alternative text for the image. * **url** – fallback image URL. * **srcset** – provides higher‑resolution sources for `"2x"` and `"3x"` displays. * **width** and **height** – dimensions in pixels. Icons must fit within a 100 × 100 space, though smaller sizes are allowed. ## global.typography.font Controls the font used across the experience: * **family** – name of the font family. * **normal.url** – URL to the font file. Any font type is accepted; the example uses a TTF file for demonstration. * **normal.format** – format of the font file, such as `"truetype"`. # Device fingerprinting and user tracking VX uses device fingerprinting to link sessions back to the same device, even when a person rotates emails, phone numbers, or other personally identifiable information. By monitoring how often a fingerprint requests a new verification session or successfully completes a journey, you can block suspicious behaviour such as rapid account creation attempts or repeat verifications from the same device. ## How VX uses the fingerprint VX administrators can create rate limits and trust policies that: * Stop a device after it exceeds the allowed number of verification attempts—successful or failed—within defined time windows. * Flag returning devices that have already been approved to prevent duplicate account creation. * Require additional checks for devices that repeatedly abandon, restart, or replay journeys in short succession. These controls allow you to enforce fair usage rules even if an individual changes their contact information between attempts. ## Device and network signals Beyond core session limiting, VX surfaces a broad set of device and network telemetry that you can reference when writing custom rules. Commonly used indicators are summarised below. | Signal | What it tells you | | -------------------------------------------- | ------------------------------------------------------------------------------------------- | | Device fingerprint ID | Stable identifier that links sessions from the same device. | | Confidence score | Likelihood that the fingerprint accurately represents a unique device. | | First/last seen timestamps | When the device was first and most recently observed globally and within your subscription. | | Browser & OS details | Reported browser, operating system, version, and user agent. | | IP geolocation | Country, city, timezone, and accuracy radius of the originating IP. | | Autonomous system & network | ASN and network owner for the IP address. | | Datacenter detection | Indicates whether traffic originates from a datacenter. | | VPN, proxy, or TOR usage | Flags anonymising services and provides confidence levels. | | Incognito/private mode | Detects privacy-focused browsing modes. | | Bot detection (BotD) | Classifies whether automated tooling is present. | | Emulator, virtual machine, or rooted devices | Highlights non-standard or tampered device environments. | | Tampering & anti-detect signals | Detects anomalies, anti-detect browsers, or debugging tools. | | Frida & developer tools | Indicates dynamic instrumentation or developer console access. | | Factory reset & cloned app checks | Surfaces recently reset or cloned mobile applications. | | Raw device attributes | Technical attributes such as fonts, canvas data, audio, and hardware characteristics. | | Velocity metrics | Counts of unique IPs, countries, events, and linked IDs over rolling intervals. | | High activity indicator | Highlights unusually high interaction volumes for the device. | | Location spoofing | Detects discrepancies between reported and derived location data. | | Proximity data | Provides proximity ID and confidence for co-located devices. | | IP blocklist & attack sources | Flags addresses with spam or attack history. | ## Implementing custom rules Your VX implementation team will work with you during client setup to codify the rules that align with your fraud risk appetite. They can incorporate any of the above signals alongside your internal policies to deliver the right mix of automated blocks, step-up challenges, and manual reviews. The example below illustrates the breadth of telemetry available when a user is in-session. This data stays within VX—none of the raw attributes are shared with clients. Instead, VX uses the signals internally so your team can craft granular policies that extend beyond default verification and velocity checks. ```json { "linked_id": "somelinkedId", "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", "url": "https://www.example.com/login?hope{this{works[!", "ip_address": "61.127.217.15", "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....", "browser_details": { "browser_name": "Chrome", "browser_major_version": "74", "browser_full_version": "74.0.3729", "os": "Windows", "os_version": "7", "device": "Other" }, "identification": { "visitor_id": "Ibk1527CUFmcnjLwIs4A9", "confidence": { "score": 0.97, "version": "1.1" }, "visitor_found": false, "first_seen_at": 1708102555327, "last_seen_at": 1708102555327 }, "supplementary_id_high_recall": { "visitor_id": "3HNey93AkBW6CRbxV6xP", "visitor_found": true, "confidence": { "score": 0.97, "version": "1.1" }, "first_seen_at": 1708102555327, "last_seen_at": 1708102555327 }, "bot": "not_detected", "root_apps": false, "emulator": false, "ip_info": { "v4": { "address": "94.142.239.124", "geolocation": { "accuracy_radius": 20, "latitude": 50.05, "longitude": 14.4, "postal_code": "150 00", "timezone": "Europe/Prague", "city_name": "Prague", "country_code": "CZ", "country_name": "Czechia", "continent_code": "EU", "continent_name": "Europe", "subdivisions": [ { "iso_code": "10", "name": "Hlavni mesto Praha" } ] }, "asn": "7922", "asn_name": "COMCAST-7922", "asn_network": "73.136.0.0/13", "datacenter_result": true, "datacenter_name": "DediPath" }, "v6": { "address": "2001:db8:3333:4444:5555:6666:7777:8888", "geolocation": { "accuracy_radius": 5, "latitude": 49.982, "longitude": 36.2566, "postal_code": "10112", "timezone": "Europe/Berlin", "city_name": "Berlin", "country_code": "DE", "country_name": "Germany", "continent_code": "EU", "continent_name": "Europe", "subdivisions": [ { "iso_code": "BE", "name": "Land Berlin" } ] }, "asn": "6805", "asn_name": "Telefonica Germany", "asn_network": "2a02:3100::/24", "datacenter_result": false, "datacenter_name": "" } }, "ip_blocklist": { "email_spam": false, "attack_source": false, "tor_node": false }, "proxy": true, "proxy_confidence": "low", "proxy_details": { "proxy_type": "residential", "last_seen_at": 1708102555327 }, "vpn": false, "vpn_confidence": "high", "vpn_origin_timezone": "Europe/Berlin", "vpn_origin_country": "unknown", "vpn_methods": { "timezone_mismatch": false, "public_vpn": false, "auxiliary_mobile": false, "os_mismatch": false, "relay": false }, "incognito": false, "tampering": false, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false }, "cloned_app": false, "factory_reset_timestamp": 0, "jailbroken": false, "frida": false, "privacy_settings": false, "virtual_machine": false, "location_spoofing": false, "velocity": { "distinct_ip": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 }, "distinct_country": { "5_minutes": 1, "1_hour": 2, "24_hours": 2 }, "events": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "ip_events": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "distinct_ip_by_linked_id": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "distinct_visitor_id_by_linked_id": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 } }, "developer_tools": false, "mitm_attack": false, "sdk": { "platform": "js", "version": "3.11.10" }, "replayed": false } ``` # Integration Options Veratad VX (Verification Experience) allows you to seamlessly embed your user's verification journey direct into your application. ## What is VX? Veratad VX (Verification Experience) allows you to seamlessly embed your user's verification journey direct into your application. ## Integration Methods ### SDK The SDK options give your business a future proof way to integrate verification journeys. ### API Access VX Journeys to display in your own UI/UX via the Run Journey API set. ## Device fingerprinting and user tracking Learn how VX uses device fingerprints and network telemetry to prevent repeat fraud in the [Device fingerprinting and user tracking](/vx/device-fingerprinting) guide. # Web SDK The VX Web SDK unlocks the power of VX for your application. This allows you to set up your verification process one time while empowering you to dynamically change the user's Verification Experience. ## What are the steps for getting set up? ### 1. Create Token In order for the document scan/upload process to work you must submit a token within the parameters of the `veratadModal`. ```javascript veratadModal = new veratad.modal({ token: "8dfe0180-5389-46d4-a28c-b74061d8e7c3", }); ``` To get a token you must make an API call with your Veratad username and password. See link below for more details. {% content-ref url="/pages/5IKrCvKQ8dX1saUTzLFS" %} [Create Token](/vx/overview/createtoken) {% endcontent-ref %} {% hint style="warning" %} Tokens are only valid for 6 hours. It is recommended that you get a new token on each iFrame build. {% endhint %} ### 2. Include CSS, JS and iFrame {% tabs %} {% tab title="CSS" %} ```markup ``` {% endtab %} {% tab title="JS" %} ``` ``` {% endtab %} {% tab title="iFrame" %} ``` ``` {% endtab %} {% endtabs %} ## Full Example {% hint style="info" %} This example includes all parameters, functions and methods. {% endhint %} ```markup ``` ## Functions | Name | Description | | ------------------------ | --------------------------------------------------------------------------------------------- | | onOpen() | Triggers when the modal is first opened on the page or with the `open()` method | | onClose() | Triggers when the modal is closed by the user or with the `close()` method | | onSuccess() | The document was successfully scanned or successfully uploaded if DCAMS+ is not active | | onFailure() | The document failed the scan process or was not uploaded successfully if DCAMS+ is not active | | onEmail() | The user has requested that they get an email with a link to scan. | | onQr() | The user pushed the "done" button after QR scanning. | | onError() | A general processing error occurred during the scan or upload process. | | onErrorToken() | An invalid token was supplied | | onErrorPending() | The user's document is currently in a `PENDING` state and they cannot submit a new document | | onErrorAlreadyVerified() | The user is in a `PASS` state already | | onErrorVelocity() | The user has already processed 3 attempts within a 24 hour period | ## Methods | Name | Description | | --------- | ----------------------------------------------------------------- | | open() | Open the modal. i.e. `veratadModal.open();` | | close() | Close the modal i.e. `veratadModal.close();` | | destroy() | Destroy the modal and all variables i.e. `veratadModal.destroy()` | ## Parameters | Parameter | Required | Type | Description | | ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | international | optional | boolean | If the upload should be treated as a non-US document. Default is `false` | | fn | required | string | The customer's first name | | ln | required | string | The customer's last name | | addr | required | string | The customer's street address | | city | required | string | The customer's city | | state | required | string | The customer's state | | zip | required | string | The customer's zip code | | dob | required | string |

The customer's Date of Birth

(YYYYMMDD format)

| | phone | optional | string |

The customer's phone number formatted as any of the below:

(555) 555-5555
555-555-5555
5555555555

| | | | | | | email | required | string | The customer's email address | | reference | optional | string | An arbitrary value that will be returned with the callback | | token | required | string | The token for the iFrame session | | styleToken | optional | string | You can create a style ID in the admin dashboard. Once created enter the value in this parameter to customize the iFrame style. | | qr | optional | boolean | If set to "true" then the user will be given a prompt to scan a QR code when they select the "Use My Phone" option when on desktop. | | additionalData | optional | object | Any additional data you would like sent back with the callback POST. This can be set with any key => value pairs. | | resultMessages | optional | object | See `resultMessages` section below for more explanation. | | language | optional | string |

If no language is specified then the system will default to English. All languages from the Google Translate API are supported. Click here to view.

The value should be the ISO-639-1 Code.

| | email\_fallback | optional | boolean | The system will default to "true". If this is set to 'false" the user will never be given the option to send an email if they are having trouble with the QR. In order for this to work the "QR" attribute also needs to be set to "true". | | bypassDesktopIntro | optional | boolean | The system will default to "false". If you set this attribute to "true" then the user will go direct to either the QR or Email link flow depending on your QR settings. | ### resultMessages These are the messages displayed to the end user in the iFrame. {% hint style="info" %} **NOTE:** If you do not want the user to be messaged in the iFrame you can simply run the `veratadModal.close()` after one of the function callbacks. That said, If you do not customize these messages then your users that get an email link sent to them will see the defaults on the page. {% endhint %} {% tabs %} {% tab title="Success" %} **The user has passed verification or successfully uploaded if DCAMS+ is not active, but storage is active.** | parameter | default message | | --------------------------- | ---------------------------- | | verificationSuccessTitle | Verification Success | | verificationSuccessSubTitle | You have passed verification | | {% endtab %} | | {% tab title="Failure" %} **The user did not PASS DCAMS+ verification or the image was not uploaded.** | parameter | default message | | --------------------------- | -------------------------------------- | | verificationFailureTitle | Verification Failed | | verificationFailureSubTitle | Your document is pending manual review | | {% endtab %} | | {% tab title="Error" %} **Something went wrong and no verification was processed. There are 4 error states:** 1. **Token** - the token provided in the iFrame is not valid 2. **Already Verified** - the user (based on email) has already `PASSED` verification 3. **Pending** - the user (based on email) is currently in a `PENDING` state of verification 4. **Velocity** - The user has exceeded the `velocity_threshold` | parameter | default message | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | verificationErrorTokenTitle | Bad or Expired Token | | verificationErrorTokenSubTitle | This document scan instance is using a bad or expired token. Please contact customer service. | | verificationErrorAlreadyVerifiedTitle | You Are Already Verified | | verificationErrorAlreadyVerifiedSubTitle | You have already passed this process and are not able to upload a new document at this time. Please call Customer Service. | | verificationErrorPendingTitle | Your Document is Currently Pending Manual Review | | verificationErrorPendingSubTitle | Your document is currently pending manual review and you may not provide another document at this time. Please call Customer Service. | | verificationErrorVelocityTitle | Too Many Attempts | | verificationErrorVelocitySubTitle | You have exceeded the amount of verification attempts. Please call Customer Service. | | {% endtab %} | | | {% endtabs %} | | ## Callback Once a document is uploaded, the callback will fire. The callback will also fire on subsequent status updates. The `email` or `reference` values can be used to associate the upload on Veratad's side to a customer/order on your side. {% hint style="danger" %} You should always use the backend callback POST to get the official status of the customer/order. The frontend callback in the JS should only be used to message and route your customer on the frontend. {% endhint %} #### Set up your callback endpoint Click the link to create your callback endpoint {% content-ref url="/pages/-M2nn0UW7N5Dq3I1u1Cw" %} [Broken mention](broken://pages/-M2nn0UW7N5Dq3I1u1Cw) {% endcontent-ref %} ### Example ```javascript POST {The URL you setup} ``` #### Body ```javascript { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19880521", "email": "test@veratad.com", "reference": "12345-test", "status": "PENDING", "additionalData": { "value_1": "test1", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808-0000", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN }, "confirmation": 92480850, "action": "REVIEW", "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"], "detail": "TRANSACTION REQUIRES FURTHER ATTENTION" }, "storage": { "success": false } } ``` #### Body (When Image Return is Active) There is a setting when a company is not using the Veratad storage system to have the document images returned via the callback. If this setting is active then the callback body will be as follows. ```javascript { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19880521", "email": "test@veratad.com", "reference": "12345-test", "status": "PENDING", "additionalData": { "value_1": "test1", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808-0000", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN }, "confirmation": 92480850, "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"], "detail": "TRANSACTION REQUIRES FURTHER ATTENTION" }, "storage": { "success": false }, "documents": { "front": "BASE 64 Encoded Image String", "back": "BASE 64 Encoded Image String" } } ``` #### Possible Status Values | status | description | | ------- | ------------------------------------ | | PASS | The document has passed verification | | PENDING | The document is under manual review | | FAIL | The document has failed verification | # Create Token The Create Token process is designed to generate a unique token to be used in the frontend of the iFrame solution in order to identify your site and settings to Veratad. ## Create Token `POST` `https://vx-be.idresponse.com/token/create` This endpoint creates your token with associated settings to access a document iFrame session. #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | ---------------------------------------------------- | | user\* | string | Your Veratad API username | | pass\* | string | Your Veratad API Password | | journey\_id | String | The VX journey ID to be loaded with this token | | settings\_id | String | The settings profile ID to be loaded with this token | | branding\_id | String | The branding ID to be loaded with this token | {% tabs %} {% tab title="200 Token successfully created." %} ``` { "result": "Success", "message": "Token created successfully", "token": "393d50f9-2703-4100-9e4b-dfd8e4fda493", "age": "21+", "rules": "DCAMS5_0_RuleSet_NAME_DOB", "store_on": "FAIL", "company_name_for_email": "Company ABC", "email_logo_link": "https://yourcompany.com/logo.png", "email_logo_height": "50", "email_logo_width": "80", "dcams_manual_rules": "DCAMS5_0_Manual_Review_RuleSet_NAME_DOB" } ``` {% endtab %} {% tab title="400 Missing a required input" %} ``` { "result": "Error", "message": "Missing a required input", "token": "" } { "result": "Error", "message": "Invalid age submitted. Must conform to age+ like 21+", "token": "" } { "result": "Error", "message": "Invalid ruleset submitted. Please check the documentation", "token": "" } { "result": "Error", "message": "Invalid store_on value. Must be PASS, FAIL or ALL", "token": "" } ``` {% endtab %} {% tab title="401 Username or password is incorrect." %} ``` { "result": "Error", "message": "Either your username or password is incorrect", "token": "" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **IMPORTANT:** The token is only good for 6 hours. It is recommended that you generate a new token on each iFrame request. {% endhint %} ## Request Body ```json { "user": "USERNAME | API KEY", "pass": "PASSWORD", "journey_id": "SET | DEFAULT", "settings_id": "SET | DEFAULT", "branding_id": "SET | DEFAULT" } ``` # User Status This method allows you to fetch the user's status. ## Retrieve User Status `POST` `https://vx-be.idresponse.com/user/status` This endpoint allows you to get the status of the user. #### Request Body | Name | Type | Description | | ----- | ------ | ------------------------ | | user | string | Veratad API Username | | pass | string | Veratad API Password | | email | string | The user's email address | {% tabs %} {% tab title="200 User found" %} ```javascript { "fn": "TIM", "ln": "SMITH", "addr": "123 MAIN ST", "city": "STRATFORD", "state": "CT", "zip": "06614", "dob": "19870203", "email": "test15847@veratad.com", "reference": "12344", "status": "PENDING", "additionalData": { "value_1": "rangers", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "STEVE", "LastName": "JONES", "MiddleName": "JIM", "Address": "123 MAIN ST", "City": "STRATFORD", "State": "CT", "Zip": "06614", "DateOfBirth": "19630203", "Height": "5-03", "Sex": "M", "EyeColor": "BRO", "DocumentNumber": "D485995948833", "IssueDate": "20190812", "ExpirationDate": "20230203" }, "confirmation": 93239228, "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [ "LAST NAME DOES NOT MATCH DOCUMENT", "DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT" ] }, "documents": null, "found": true } ``` {% endtab %} {% tab title="400 Missing a required input" %} ``` { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Bad login" %} ``` { "result": "Error", "message": "Either your username or password is incorrect", } ``` {% endtab %} {% tab title="404 User not found" %} ```javascript { "fn": null, "ln": null, "addr": null, "city": null, "state": null, "zip": null, "dob": null, "email": null, "reference": null, "status": null, "additionalData": false, "dcams_plus": { "document_data": false, "confirmation": 0, "action": null, "detail": null, "issues": false }, "documents": null, "found": false } ``` {% endtab %} {% endtabs %} #### Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "email": "test15847@veratad.com" } ``` {% hint style="info" %} **NOTE:** After 2 hours certain elements will be purged. This includes: * fn * ln * addr * city * state * zio * dob * dcams\_plus.document\_data This does not apply if you have storage active. {% endhint %} # Generate Link ## Generate Link `POST` `https://vx-be.idresponse.com/link/generate` This endpoint allows you generate a direct link to an iFrame instance and send the user an email if desired. #### Request Body | Name | Type | Description | | --------------------------------------------- | ------- | -------------------------------------------------------- | | options\* | object | The object where you place certain options | | send\_email\* | boolean | Set to true if you want the link to be sent via an email | {% tabs %} {% tab title="200 Link successfully generated" %} ```javascript { "action": "PASS", "detail": "Link Generated", "link": "https://frontend.dcams.app?request_id=c9c40f18-2c30-43ef-a879-5a82f1c4uf76", "email_sent": true, "error_message": "", "error_description": "" } ``` {% endtab %} {% endtabs %} ## Sample Request Body {% hint style="info" %} You must provide a valid token when making this API call. So, make sure you retrieve your token first and then set it here. {% endhint %} ```json { "options": { "send_email": true }, "reference": "CHECKLY TEST", "token": "{{TOKEN}}", "fn": "Tom", "ln": "Canfarotta", "addr": "707 HAWLEY LANE", "city": "STRATFORD", "state": "CT", "zip": "06614", "phone": "2015106000", "dob": "19820821", "email": "user_email@gmail.com", "email_fallback": false, "language": "", "country": "US", "bypassDesktopIntro": false, "qr": true, "additionalData": "{\"value_1\":\"test1\",\"value_2\":\"test2\"}", "styleToken": "", "resultMessages": { "success": { "verificationSuccessTitle": "", "verificationSuccessSubTitle": "" }, "failure": { "verificationFailureTitle": "", "verificationFailureSubTitle": "" }, "error": { "verificationErrorTokenTitle": "", "verificationErrorTokenSubTitle": "", "verificationErrorAlreadyVerifiedTitle": "", "verificationErrorAlreadyVerifiedSubTitle": "", "verificationErrorPendingTitle": "", "verificationErrorPendingSubTitle": "", "verificationErrorVelocityTitle": "", "verificationErrorVelocitySubTitle": "" } } } ``` ## Responses | Description | Value | | ------------------ | ------------------------------------------------------------------------------------------------------------ | | action |

PASS - the link was generated

ERROR - the link was not generated (see below for all error types

| | detail | A description of the action result | | link | The URL value to provide the end user | | email\_sent | Will be set to true or false | | error\_message | The overall error message | | error\_description | A description of the error that occurred | # Canned Responses The iFrame allows you to get a canned response when using the below last name values in your iFrame build. {% hint style="warning" %} **NOTE:** This will only work if your site has testing\_mode active. Talk to your Veratad representative about activating this feature. {% endhint %} {% hint style="info" %} If you do not send one of the below last name values then the frame will treat the transaction as if it were live. {% endhint %} ## Available Cases Here is an example with one of the canned response last names: ```javascript $(function(){ veratadModal = new veratad.modal({ region: "United States", region_select: true, fn: "John", ln: "dcamspluspass", // set the last name to one of the value below. addr: "123 Main St", city: "Stratford", state: "CT", zip: "12345", dob: "19880212", email: "test51598@veratad.com", reference: "tery745f", token: token, }) }); ``` Here are the possible values and description: | Last Name | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dcamspluspass | This will result in a instant scan pass - no manual review | | dcamsplusfail | This will result in an instant scan failure - no manual review | | dcamsplusfailmanualpass | This will result in an instant scan failure, trigger manual review and manual review will PASS. The manual review response will be delayed by about 90 seconds. | | dcamsplusfailmanualfail | This will result in an instant scan failure, trigger manual review and manual review will FAIL The manual review response will be delayed by about 90 seconds. | | dcamspluspassselfiematch | This will result in an auto scan pass and a request for a selfie. Once selfie is submitted it will match and the transaction will PASS. | | dcamspluspassselfienomatch | This will result in an auto scan pass and a request for a selfie. Once selfie is submitted it will NOT match and the transaction will FAIL. | {% hint style="info" %} The cases for `dcamsplusfailmanualpass` and `dcamsplusfailmanualfail` will only work if you have Veratad manual review active. {% endhint %} # iFrame Integration ## Embedding the Verification iFrame You can optionally embed the verification link returned in the response within an iFrame on your website. The iFrame will post messages to the parent window based on specific events that occur during the verification process. ## iFrame Example ```html ``` {% hint style="info" %} When displaying this iFrame on a mobile device, set both `width` and `height` to `100%` and include the `allowfullscreen` attribute so the verification experience can expand properly. {% endhint %} ## Listening for Post Messages To listen for events sent from the iFrame to the parent window, you can add an event listener for the `message` event. The VX iFrame posts updates such as `PASS`, `FAIL`, `ALREADY VERIFIED`, `ERROR`, `LINK EXPIRED`, `BOT DETECTED`, and `CLOSE` (when the user dismisses the experience). *** ### Sample Implementation ```javascript // Listen for messages from the iframe/webview window.addEventListener('message', function(event) { // Optional: Verify the origin for security // if (event.origin !== 'https://vx-fe.dcams.app') return; const message = event.data; switch (message) { case 'PASS': console.log('Verification successful!'); // Handle successful verification // e.g., redirect user, show success message, etc. break; case 'FAIL': console.log('Verification failed'); // Handle failed verification // e.g., show error message, allow retry, etc. break; case 'ALREADY VERIFIED': console.log('User already verified'); // Handle already verified case // e.g., skip verification flow, show appropriate message break; case 'ERROR': console.log('A system error occurred in the verification experience'); // Handle general system errors // e.g., prompt to retry, log error, etc. break; case 'LINK EXPIRED': console.log('Verification link has expired'); // Handle expired links // e.g., request a new verification session, notify user, etc. break; case 'BOT DETECTED': console.log('Potential automated activity detected'); // Handle bot detection events // e.g., block the session, add additional checks, etc. break; case 'CLOSE': console.log('User closed the verification experience'); // Handle closure // e.g., prompt to retry later or navigate away break; default: console.log('Unknown message received:', message); // Handle any other messages or ignore break; } }); ``` # United States Age verification via trusted and verified data sources in the United States. ## AgeMatch5.0 `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target meets your age requirement. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action** and a **detail**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (AgeMatch5.0) | | rules | string | See rules explanation below | | reference | string | A unique identifier for your customer | | target\* | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age\* | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "confirmation": 71483084, "reference": "12345", "service": "AgeMatch5.0", "timestamp": "2019-10-17 14:29:48", "company": "Company, LLC", "user": "ws@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Service Testing Use the `test_key` attribute to test the service. When the `test_key` is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "AgeMatch5.0", "reference": "12345 {A UNIQUE ID}", "rules": "AgeMatch5_0_RuleSet_YOB_SSN", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | ------------------ | -------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | AGE NOT VERIFIED | Target found, but no DOB information available | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | FAIL | AGE NOT SUBMITTED | No age to check was provided in the query | | FAIL | POSSIBLE MINOR | Target found, but a minor age detected | | PASS | ALL CHECKS PASSED | Target was found is not deceased and meets the age requirement | ## Rules AgeMatch will process with the default base ruleset unless a different rule set is specified in the query. {% hint style="info" %} The base rule set will return a PASS when: * A match is found * The target is not deceased * The target meets the minimum age requirement {% endhint %} ## Additional Rule Sets The following are additional matching rule sets. Each set is the above base default rule set plus additional matching requirements of the input elements. | Ruleset Name | Description | | -------------------------------------------- | ------------------------------------------------------- | | AgeMatch5\_0\_RuleSet\_YOB | Base + Year of Birth Must Match | | AgeMatch5\_0\_RuleSet\_YOB\_SSN | Base + Year of Birth and SSN Must Match | | AgeMatch5\_0\_RuleSet\_DOB | Base + Full Date of Birth Must Match | | AgeMatch5\_0\_RuleSet\_DOB\_SSN | Base + Full DOB and SSN Must Match | | AgeMatch5\_0\_RuleSet\_ADDR | Base + Address Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_YOB | Base + Address and Year of Birth Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_YOB\_SSN | Base + Address, Year of Birth and SSN Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_DOB\_SSN\_PHONE | Base + Address and Date of Birth Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_YOB\_SSN\_PHONE | Base + Address, Year of Birth, SSN and Phone Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_DOB\_PHONE | Base + Address, Date of Birth and Phone Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_YOB\_PHONE | Base + Address, Year of Birth and Phone Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_SSN\_PHONE | Base + Address, SSN and Phone Must Match | | AgeMatch5\_0\_RuleSet\_ADDR\_PHONE | Base + Address and Phone Must Match | | AgeMatch5\_0\_RuleSet\_YOB\_SSN\_PHONE | Base + Year of Birth, SSN and Phone Must Match | | AgeMatch5\_0\_RuleSet\_DOB\_SSN\_PHONE | Base + Date of Birth, SSN and Phone Must Match | | AgeMatch5\_0\_RuleSet\_YOB\_PHONE | Base + Year of Birth and Phone Must Match | | AgeMatch5\_0\_RuleSet\_DOB\_PHONE | Base + Date of Birth and Phone Must Match | | AgeMatch5\_0\_RuleSet\_SSN\_PHONE | Base + SSN and Phone Must Match | | AgeMatch5\_0\_RuleSet\_PHONE | Base + Phone Must Match | # United States (DMV) Age and Identity verification via state DMV databases in the United States. ## AgeMatch5.0.DMV `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided attributes that match the document. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string |

The service name

(AgeMatch5.0.DMV)

| | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | age\* | string |

The age to check

(must be sent like "age+" i.e. "18+", "21+" etc.)

| | document | object | The data from the document | | fn\* | string | The target's document first name | | mn | string | The target's document middle name | | ln\* | string | The target's document last name | | suffix | string | The target's document name suffix | | addr\* | string |

The target's document street address

(line 1 and line 2)

| | city | string | the target's document city | | state | string | The target's document state | | zip\* | string | The target's document zip | | dob | string |

The target's document Date of Birth

(YYYYMMDD format)

| | number | string | The target's document ID number | | expiration | string | The target's document expiration date | | issue | string | The target's document issue date | | height | string |

The target's document height

(provided in feet and inches i.e. 5 feet 10 inches is presented as "510")

| | weight | string | The target's document weight | | eye\_color | string | The target's document eye color | | gender | string |

The target's document gender

m = male
f = female

| | category | string |

The target's document category

1 = Driver License
2 = Driver Permit
3 = ID Card

(if none is supplied then Driver License will be assumed)

| {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "company": "Company, LLC", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "AgeMatch5.0.DMV", "timestamp": "2020-01-01 17:56:14", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "DOB CHECK FAILED", "LAST NAME CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Service testing is done with the live data source. Veratad will provide you with an amount of free transactions for testing purposes. {% endhint %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "AgeMatch5.0.DMV", "reference": "12345 {A UNIQUE ID}", "target":{ "document":{ "fn":"Barbara", "mn":"Anne", "ln": "Miller", "suffix": "JR", "addr": "123 Main St APT 6", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "height": "502", "weight": "120", "eye_color": "blue", "gender": "f", "number": "D0415 73071 06822", "expiration": "20220412", "issue": "20170412", "category": "1" } "age": "21+" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | FAIL | NO MATCH | No match found with document ID number | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found, but at least one identity attribute provided does not match. This will also populate the "issues" object with a list of the identity attributes that did not match. See full list below. | | PASS | ALL CHECKS PASSED | Target was found and has passed all verification checks | | PASS | VERIFICATION EXISTS | If Veratad storage is active then an already verified customer will PASS without the search at the data source | ## Issues Responses When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. | Issue | Description | | ----------------------------- | --------------------------------------------------------------------------------------- | | FIRST NAME CHECK FAILED | The first name provided does not match data associated with document number | | MIDDLE NAME CHECK FAILED | The middle name provided does not match data associated with document number | | LAST NAME CHECK FAILED | The last name provided does not match data associated with document number | | NAME SUFFIX CHECK FAILED | The name suffix provided does not match data associated with document number | | ADDRESS CHECK FAILED | The address provided does not match data associated with document number | | ADDRESS POD CHECK FAILED | The address point of delivery does not match data associated with document number | | CITY CHECK FAILED | The city provided does not match data associated with document number | | STATE CHECK FAILED | The state provided does not match data associated with document number | | ZIP CHECK FAILED | The zip provided does not match data associated with document number | | DATE OF BIRTH CHECK FAILED | The Date of Birth provided does not match data associated with document number | | ID EXPIRATION CHECK FAILED | The ID expiration date provided does not match data associated with the document number | | ID ISSUE CHECK FAILED | The ID issue date provided does not match data associated with the document number | | GENDER CHECK FAILED | The gender provided does not match data associated with the document number | | EYE COLOR CHECK FAILED | The eye color provided does not match data associated with the document number | | WEIGHT CHECK FAILED | The weight provided does not match data associated with the document number | | HEIGHT CHECK FAILED | The height provided does not match data associated with the document number | | AGE CHECK FAILED | The Date of Birth provided is under the age requirement | | CURRENT DOCUMENT CHECK FAILED | The expiration date provided is in the past | ## Rules AgeMatch5.0.DMV will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * There are no issues {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target's identity attributes do not all match {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found {% endhint %} # International Age verification via trusted and verified data sources in countries outside of the United States. ## What countries are covered? Click this link to see what countries are covered for the AgeMatch International Service. {% content-ref url="/pages/-MB4GiWHjlo1WNC2Z-3n" %} [Data Coverage](/coverage/international) {% endcontent-ref %} ## AgeMatch5.0.{CountryName} `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target meets your age requirement. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action** and a **detail**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service nameAgeMatch5.0.{CountryName}The "CountryName" should match the value in the international coverage section. | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr1 | string | The target's house number or name, plus street | | addr2 | string | the target's apt, flat or floor | | addr3 | string | The target's further address details | | addr4 | string | The target's further address details | | addr5 | string | The target's city | | addr6 | string | The target's locality (e.g. county) | | addr7 | string | The target's state or UK county | | zip\* | string | The target's zip/postal code | | dob | string | The target's Date of Birth (YYYYMMDD format) | | international\_id | string | The target's international id number.This is sometimes required. Check the international coverage page for more details. | | phone | string | The target's phone number | | age\* | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "confirmation": 71483084, "reference": "12345", "service": "AgeMatch5.0", "timestamp": "2019-10-17 14:29:48", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} When setting the service name you must view the data coverage section (linked above) and use the country name for your query. Therefore, in the majority of cases the service name will be something like: **AgeMatch5.0.Canada** But in certain cases where a country name has spaces i.e. the United Kingdom the service name will be like: **AgeMatch5.0.UK** You will find all of the countries where there is an exception in the data coverage section of the documentation. {% endhint %} ## Sample Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "AgeMatch5.0.{CountryName}", "reference": "12345", "target":{ "fn":"Barbara", "ln": "Miller", "addr1": "123 Main St", "addr2": "TORONTO", "addr3": "ON", "zip": "M4B 1B3", "dob": "19740821", "international_id": "854125698", "phone": "2015106000", "age": "21+", "test_key": "international_pass" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | --------------------------- | ---------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | AGE NOT VERIFIED | Target found, but no DOB information available or the DOB did not match | | FAIL | POSSIBLE MINOR | Input DOB is under the age to check | | FAIL | SERVICE CANNOT BE COMPLETED | The underlying data sources are having a processing issue. Resubmit this query at a later time | | PASS | ALL CHECKS PASSED | Target was found and meets the age requirement | ## Service Testing When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. Here are available test cases for the international service: | test key | description | | ------------------------------------------ | --------------------------------------------------------- | | international\_pass | Will return a `PASS - ALL CHECKS PASSED` result | | international\_fail\_no\_match | Will return a `FAIL - NO MATCH` result | | international\_fail\_age\_not\_verified | Will return a `FAIL - AGE NOT VERIFIED` result | | international\_fail\_possible\_minor | Will return a `FAIL - POSSIBLE MINOR` result | | international\_fail\_cannot\_be\_completed | Will return a `FAIL - SERVICE CANNOT BE COMPELTED` result | {% hint style="info" %} The above are all "canned responses", so the target input will not matter if a valid test key is provided. {% endhint %} ## Rules AgeMatch International will process with the following rules by default {% hint style="info" %} The base ruleset will return a PASS when: * A match is found * The target meets the minimum age requirement {% endhint %} {% hint style="warning" %} The base ruleset will return a FAIL when: * No Match Found * The target's age has not been verified * The service can not be completed {% endhint %} # With KBA Quiz Age verification via trusted and verified data sources in the United States. This service will also return a KBA quiz for verification. ## AgeMatch5.0.KBA `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes and to receive the quiz to present. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. If any of the provided identity attributes provided did not match you will know during this initial call. \ \ Then present the quiz to the user and take their answers and populate them in the **template** object provided and make a second POST request to get the final result with quiz score. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatchPLUS5.0.MULTI) | | reference | string | A unique identifier for your customer | | target\* | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age\* | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "questions": { "questions": [ { "prompt": "With which of the following states are you or have you been associated?", "type": "state", "id": "state1", "answers": [ { "text": "VERMONT" }, { "text": "NORTH DAKOTA" }, { "text": "SOUTH DAKOTA" }, { "text": "WISCONSIN" }, { "text": "None of the above" } ] }, { "prompt": "Which of the following addresses are in Green Bay?", "type": "address", "id": "address3", "answers": [ { "text": "11 157 STREET" }, { "text": "170 WEAVER ST" }, { "text": "87 EAST BROADWAY BLVD" }, { "text": "6 PRICE ROAD" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following zip codes are you or have you been associated?", "type": "zip5", "id": "zip52", "answers": [ { "text": "54420" }, { "text": "54155" }, { "text": "54551" }, { "text": "54807" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following cities are you or have you been associated?", "type": "city", "id": "city0", "answers": [ { "text": "STREETSBORO" }, { "text": "SAINT JOHN" }, { "text": "FORT MORGAN" }, { "text": "WEST ALLIS" }, { "text": "None of the above" } ] } ] } }, "meta": { "confirmation": 21185214, "reference": "12345", "service": "AgeMatch5.0.KBA", "timestamp": "2017-08-08 14:25:02", "company": "Veratad Technologies, LLC", "user": "user@veratad.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "questions": { "url": "/process/continue", "template": { "token": "2nypwsj51mzhjvm7cr1hbyaabqm67qcc", "answers": { "zip52": [], "state1": [], "address3": [], "city0": [] } }, "instructions": "Add the text of the answers into the empty list for the appropriate question (case sensitive)." } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% endhint %} {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Sample Request Body {% hint style="info" %} This is the initial query to get the quiz. See below example of how to submit the answers for final scoring and evaluation. {% endhint %} ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "AgeMatch5.0.KBA", "rules": "A_RULESET_ID", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Request with Quiz Answers Once your user has answered the questions, send those answers back to the system for scoring and a final evaluation. ## Submit Answers `POST` `https://production.idresponse.com/process/continue` Sending a POST request with the below body will give you the final evaluation of the quiz and other identity attributes. #### Request Body | Name | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------------- | | token | string | The token that was returned in the initial response that relates to this specific quiz. | | answers | object | The answers object should include each question asked and the user's answer. | {% tabs %} {% tab title="200 The result of the question and identity evaluation. " %} ```javascript { "final": { "template": { "token": "euwd6q5a8b4c0vwc0zy0s6ms1mjh5p0s" }, "url": "/process/status" }, "output": { "answers": { "asked": 4, "correct": 0 } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "QUESTION CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body - Quiz Score ```javascript { "answers": { "state3": ["NEW YORK"], "mothers_maiden0": ["None of the above"], "phone1": ["(206) 393-4478"], "county2": ["FAIRFIELD"] }, "token": "1bauxkpczhdiyy3vqm15ais8ue12u7zw" } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | AGE NOT VERIFIED | Target found, but no DOB information available | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | FAIL | POSSIBLE MINOR | Target found, but a minor age detected | | FAIL | QUESTION CHECK FAILED | The user did not answers at least 3/4 questions correct. | | FAIL | QUIZ NOT GENERABLE | The target did not have enough data to generate a quiz. | | PENDING | MORE INFORMATION IS REQUIRED | Target was found is not deceased and meets the age requirement, but they have not yet answered the quiz. | | PASS | ALL CHECKS PASSED | Target was found is not deceased, passed the verification quiz and meets the age requirement | ## Rules AgeMatch with KBA will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target meets the age requirement * The user has answered at least 3/4 questions correct {% endhint %} {% hint style="info" %} The base ruleset will return a PENDING when: * A match found * The target is not deceased * The age requirement is met * Questions are returned, but not answered yet {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found or * The target is deceased or * The target does not meet the minimum age requirement In this case no questions will be provided. {% endhint %} ## API Processing Error Returns {% hint style="info" %} Each token is only valid for 300 seconds with this service. See the error responses to get information on what happens if a token is bad or expired. {% endhint %} {% content-ref url="/pages/-LrjFxJ4Wv\_iErI2\_I7V" %} [Error Returns](/api-processing-errors/error-returns) {% endcontent-ref %} # Selfie Age Estimation ## AgeMatch 5.0 Estimate API The AgeMatch 5.0 Estimate API provides an estimate of the age based on a provided selfie. ### POST /process/comprehensive/gateway Submits a request to estimate the age of a person based on a selfie image. #### Request | Field | Type | Description | Required | | --------- | ------ | -------------------------------------- | -------- | | user | string | Your Veratad username | Yes | | pass | string | Your Veratad password | Yes | | service | string | The service identifier | Yes | | reference | string | A unique reference for the transaction | No | | rules | string | Additional rules for the transaction | No | | target | object | The target information | Yes | **Target Object** | Field | Type | Description | Required | | ------ | ------ | ------------------------- | -------- | | selfie | string | Base64 encoded face image | Yes | | age | string | The age to check against | Yes | **Example Request** ```json { "user": "username", "pass": "password", "service": "AgeMatch5.0.Estimate", "reference": "12345", "rules": "", "target": { "selfie": "base 64 encoded face image", "age": "21+" } } ``` #### Response The response will contain metadata about the request, output details, and the result of the age estimation. **Response Object** | Field | Type | Description | | ------ | ------ | -------------------------------------------- | | meta | object | Contains metadata related to the transaction | | output | object | Contains the output of the age estimate | | result | object | Contains the result of the age verification | **Meta Object** | Field | Type | Description | | ------------ | ------ | ----------------------------------- | | confirmation | number | Confirmation number for the request | | timestamp | string | Timestamp of the transaction | | reference | string | Reference of the original request | | user | string | Your Veratad username | | company | string | Your company name | | service | string | The service identifier | **Selfie Object** | Field | Type | Description | | ------------- | ------ | ------------------- | | age\_estimate | string | Estimated age range | **Result Object** | Field | Type | Description | | ------ | ------ | ------------------------------------- | | action | string | The action taken, either PASS or FAIL | | detail | string | Details of the action | | issues | array | An array of issues if any | **Example Response** ```json { "meta": { "confirmation": 160567642, "timestamp": "2023-11-07 13:23:55", "reference": "12345", "user": "root@veratad.com", "company": "Veratad Technologies, LLC", "service": "AgeMatch5.0.Estimate.ROC" }, "output": { "images": { "selfie": { "age_estimate": "27-31" } } }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` # United States Identity verification via trusted and verified data sources in the United States. ## IDMatch5.0 `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatch5.0", "timestamp": "2017-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "SSN CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% endhint %} {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatch5.0", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the "issues" object with a list of the identity attributes that did not match. See full list below. | | PASS | ALL CHECKS PASSED | Target was found, is not deceased and has passed all verification checks | ## Issues Responses {% hint style="info" %} When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. {% endhint %} | Issue | Description | | --------------------------- | ------------------------------------------------------ | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DATE OF BIRTH CHECK FAILED | The Date of Birth provided does not match any on file | | YEAR OF BIRTH CHECK FAILED | The Year of Birth provided does not match any on file | | MONTH OF BIRTH CHECK FAILED | The Month of Birth provided does not match any on file | | DAY OF BIRTH CHECK FAILED | The Day of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not match any on file | | PHONE CHECK FAILED | The phone number provided does not match any on file | | EMAIL CHECK FAILED | The email address provided does not match any on file | | AGE CHECK FAILED | The target does not meet the age attribute provided | | POSSIBLE MINOR | The target is detected as a minor | ## Rules IDMatch will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target has provided all valid identity attributes {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target is not deceased * The target's identity attributes do not all match {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found * The target is deceased {% endhint %} # With KBA Escalation Identity verification via trusted and verified data sources in the United States. WIth a conditional escalation to a KBA quiz. ## IDMatch5.0.Escalate `POST` `https://production.idresponse.com/process/escalate/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 1-3 seconds with a **result** object that includes **action, detail** and **issues**. This service differs from the base IDMatch5.0 in that it will return a KBA quiz conditionally. See the rule set below to find out when a quiz will be returned. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript //PASS - no quiz Returned { "meta": { "company": "Company, LLC", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatch5.0.Escalate", "timestamp": "2017-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } //FAIL - no quiz returned { "meta": { "company": "Company, LLC", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatch5.0.Escalate", "timestamp": "2017-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "FAIL", "detail": "NO MATCH", "issues": [] } } //PENDING - quiz returned { "output": { "questions": { "questions": [ { "prompt": "With which of the following states are you or have you been associated?", "type": "state", "id": "state2", "answers": [ { "text": "WISCONSIN" }, { "text": "WASHINGTON, D.C." }, { "text": "NEW YORK" }, { "text": "WEST VIRGINIA" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following counties are you or have you been associated?", "type": "county", "id": "county0", "answers": [ { "text": "COCHRAN" }, { "text": "PLATTE" }, { "text": "DIVIDE" }, { "text": "ROSCOMMON" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following zip codes are you or have you been associated?", "type": "zip5", "id": "zip53", "answers": [ { "text": "19465" }, { "text": "37356" }, { "text": "66375" }, { "text": "66401" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following cities are you or have you been associated?", "type": "city", "id": "city1", "answers": [ { "text": "FILLMORE" }, { "text": "SCHENECTADY" }, { "text": "OKMULGEE" }, { "text": "BOCA RATON" }, { "text": "None of the above" } ] } ] } }, "meta": { "confirmation": 94186314, "reference": "", "service": "IDMatch5.0.Escalate", "timestamp": "2020-06-04 11:31:35", "company": "Veratad Technologies, LLC", "user": "ws@veratad.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [ "YOB CHECK FAILED", "DOB CHECK FAILED" ] }, "continuations": { "questions": { "url": "/process/continue", "template": { "token": "p7lx6svy7s0dku6vxa9l8yemk1tnwlsj", "answers": { "zip53": [], "state2": [], "city1": [], "county0": [] } }, "instructions": "Add the text of the answers into the empty list for the appropriate question (case sensitive)." } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% endhint %} {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatch5.0.Escalate", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Request with Quiz Answers Once your user has answered the questions, send those answers back to the system for scoring and a final evaluation. ## Submit Answers `POST` `https://production.idresponse.com/process/continue` Sending a POST request with the below body will give you the final evaluation of the quiz and other identity attributes. #### Request Body | Name | Type | Description | | ------- | ------ | --------------------------------------------- | | token | string | The token returned during the initial request | | answers | object | The answers the user selected during the quiz | {% tabs %} {% tab title="200 " %} ``` { "final": { "template": { "token": "euwd6q5a8b4c0vwc0zy0s6ms1mjh5p0s" }, "url": "/process/status" }, "output": { "answers": { "asked": 4, "correct": 0 } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "QUESTION CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **NOTE:** The token is only valid for 90 seconds by default. So, your user has 90 seconds to answer the quiz. {% endhint %} ## Sample Request for Answer Scoring ```javascript { "answers": { "state3": ["NEW YORK"], "mothers_maiden0": ["None of the above"], "phone1": ["(206) 393-4478"], "county2": ["FAIRFIELD"] }, "token": "1bauxkpczhdiyy3vqm15ais8ue12u7zw" } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the "issues" object with a list of the identity attributes that did not match. See full list below. | | PENDING | MORE INFORMATION IS REQUIRED | Target is found and not deceased, but has provided some inaccurate identity attributes. This means that a quiz was returned and the transaction is waiting for the answers to be submitted. | | PASS | ALL CHECKS PASSED | Target was found, is not deceased and has passed all verification checks | ## Issues Responses {% hint style="info" %} When a transaction returns as REVIEW or PENDING then there will be a list of issues. This list can include any of the below values. {% endhint %} | Issue | Description | | --------------------------- | ----------------------------------------------------------- | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DATE OF BIRTH CHECK FAILED | The Date of Birth provided does not match any on file | | YEAR OF BIRTH CHECK FAILED | The Year of Birth provided does not match any on file | | MONTH OF BIRTH CHECK FAILED | The Month of Birth provided does not match any on file | | DAY OF BIRTH CHECK FAILED | The Day of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not match any on file | | PHONE CHECK FAILED | The phone number provided does not match any on file | | EMAIL CHECK FAILED | The email address provided does not match any on file | | AGE CHECK FAILED | The target does not meet the age attribute provided | | POSSIBLE MINOR | The target is detected as a minor | | QUESTION CHECK FAILED | The target did not answer at least 3/4 questions correctly. | ## Rules IDMatch5.0.Escalate will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target has provided all valid identity attributes * No quiz returned {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target is not deceased * The target's identity attributes do not all match or the quiz was answered incorrectly * This action will only appear on the final result * No quiz will be returned {% endhint %} {% hint style="info" %} The base ruleset will return a PENDING when: * A match is found * the target is not deceased * The target's identity attributes do not all match * A quiz will be returned {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found * The target is deceased * A quiz will not be returned {% endhint %} # KYC/CIP Compliance Identity verification via trusted and verified data sources in the United States with watchlist screening included. ## IDMatchCOMPLY5.1 `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatchCOMPLY5.1", "timestamp": "2020-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "SSN CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOMPLY5.1", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the "issues" object with a list of the identity attributes that did not match. See full list below. | | PASS | ALL CHECKS PASSED |

Target was found, is not deceased and has passed all verification checks.

A PASS will still occur if the only issue is ADDRESS DISCREPANCY

| ## Issues Responses When a transaction returns as `REVIEW` then there will be a list of issues. This list can include any of the below values. | Issue | Description | | -------------------------- | --------------------------------------------------------------------- | | ADDRESS CHECK FAILED | The address provided does not match any on file | | ADDRESS DISCREPANCY | The address provided is a partial match to one of the addresses found | | YEAR OF BIRTH CHECK FAILED | The Year of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not match any on file | | NAME FOUND ON WATCHLIST | The target has been found on a watchlist | ### Example for PASS with an issue {% hint style="info" %} This service is slightly different from other services in that it can return one issue with a `PASS` action. This issue is `ADDRESS DISCREPANCY` and it will only return as `PASS` if there are no other issues present. {% endhint %} ```javascript { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatchCOMPLY5.1", "timestamp": "2017-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [ "ADDRESS DISCREPANCY" ] } } ``` ## Rules IDMatch+COMPLY will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target has provided all valid identity attributes or the only issue is `ADDRESS DISCREPANCY` {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target is not deceased * The target's identity attributes do not all match {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found * The target is deceased {% endhint %} ## Service Testing {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% endhint %} {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} # COPPA Compliance Identity verification via trusted and verified data sources in the United States specifically designed for COPPA compliance. ## Overview The **COPPA Compliance** service verifies that a target is a real, identifiable **adult** so you can obtain **Verifiable Parental Consent (VPC)** under the Children's Online Privacy Protection Act (COPPA). Before a child can use your service, COPPA requires you to confirm that the person providing consent is the parent or guardian — an adult — and this service performs that adult identity verification against trusted and verified data sources. Under the **FTC Safe Harbor Guidelines**, a transaction passes only when we can: * **Locate** the target in trusted and verified data sources * Confirm the target is **not deceased** * Confirm the target is **18 or older** * Confirm the target has provided an **accurate SSN variable** You send the target's identity attributes in a single **HTTPS POST** request and receive a synchronous response in **2–3 seconds** containing a `result` object with `action`, `detail`, and `issues` fields. ## SSN variable Every request must include the target's SSN in **one** of three formats: | Format | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Full 9 SSN** | The complete nine-digit SSN. | | **Last 4 SSN** | The last four digits of the SSN. | | **IDR Calc** | Veratad's patented process — the user sums at least two digits of their SSN to prove they know it, without collecting sensitive PII. See [IDR Calc](#idr-calc) below. | ## Service variants This service is available in two variants. Both share the same **endpoint, response objects, rulesets, and testing process**; they differ only in the identity attributes you must send. | Variant | Locates the target using | | ------------------------------ | -------------------------------------------------------------- | | **IDMatchCOPPA5.0** | Name + address + SSN variable (the base service) | | **IDMatchCOPPA5.0.NO.ADDRESS** | Name + SSN variable + either Date of Birth **or** phone number | {% hint style="info" %} **PRO TIP:** The more data you send, the higher your success rate. The required inputs are the minimum needed to run a transaction, but sending everything you collect helps us locate the adult in the data sources and return a `PASS`. Add optional attributes beyond the minimum — for example, include the target's `dob` with the base **IDMatchCOPPA5.0** service, or both `phone` and `dob` with the **IDMatchCOPPA5.0.NO.ADDRESS** variant — to maximize your match rate. {% endhint %} *** ## Endpoint Both variants are served from the same endpoint: **POST** `https://production.idresponse.com/process/5/gateway` The service name you send in the request body (`service`) determines which variant runs. *** ## IDMatchCOPPA5.0 (base service) Locates the target by **name and address**, then validates the SSN variable. ### Request {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://production.idresponse.com/process/5/gateway \ -H "Content-Type: application/json" \ -d '{ "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOPPA5.0", "reference": "12345 {A UNIQUE ID}", "target": { "fn": "Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "5698", "age": "18+", "test_key": "general_identity" } }' ``` {% endtab %} {% tab title="JSON" %} ```json { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOPPA5.0", "reference": "12345 {A UNIQUE ID}", "target": { "fn": "Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "5698", "age": "18+", "test_key": "general_identity" } } ``` {% endtab %} {% endtabs %} ### Body parameters | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (`IDMatchCOPPA5.0`) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | string | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | The target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (`YYYYMMDD` format) | | ssn\* | string | The target's SSN (Full 9, Last 4, or IDR Calc). See [IDR Calc](#idr-calc). | | phone | string | The target's phone number | | email | string | The target's email address | | age\* | string | The age to check (sent as `"age+"` — e.g. `"18+"`, `"21+"`) | | test\_key | string | The test key value that you are using to test | \* Required. ### Responses {% tabs %} {% tab title="200 PASS" %} ```json { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatchCOPPA5.0", "timestamp": "2020-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% tab title="200 REVIEW" %} ```json { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatchCOPPA5.0", "timestamp": "2020-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "SSN CHECK FAILED" ] } } ``` {% endtab %} {% tab title="200 FAIL" %} ```json { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "IDMatchCOPPA5.0", "timestamp": "2020-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "FAIL", "detail": "TARGET IS UNDERAGE", "issues": [] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **PRO TIP:** Send a unique `reference` value with each request so you can reconcile the synchronous response back to the customer record in your own system. {% endhint %} *** ## IDMatchCOPPA5.0.NO.ADDRESS A variant of the base service for cases where you cannot collect the target's street address. Instead of locating the target by address, it uses the SSN variable together with **either** a Date of Birth **or** a phone number. Everything else — the endpoint, response objects, rulesets, and testing process — is identical to the base **IDMatchCOPPA5.0** service. Only the required inputs differ, as described below. {% hint style="info" %} **Required inputs for this variant:** * First name (`fn`) * Last name (`ln`) * SSN variable (`ssn` — Full 9, Last 4, or IDR Calc) * **At least one** of the following: * Date of Birth (`dob`) * Phone number (`phone`) You do **not** need to send `addr`, `city`, `state`, or `zip` with this variant. {% endhint %} ### Request {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://production.idresponse.com/process/5/gateway \ -H "Content-Type: application/json" \ -d '{ "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOPPA5.0.NO.ADDRESS", "reference": "12345 {A UNIQUE ID}", "target": { "fn": "Barbara", "ln": "Miller", "dob": "19740821", "ssn": "5698", "age": "18+", "test_key": "general_identity" } }' ``` {% endtab %} {% tab title="JSON" %} ```json { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOPPA5.0.NO.ADDRESS", "reference": "12345 {A UNIQUE ID}", "target": { "fn": "Barbara", "ln": "Miller", "dob": "19740821", "ssn": "5698", "age": "18+", "test_key": "general_identity" } } ``` {% endtab %} {% endtabs %} ### Body parameters | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (`IDMatchCOPPA5.0.NO.ADDRESS`) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | string | The target's last name | | ssn\* | string | The target's SSN (Full 9, Last 4, or IDR Calc). See [IDR Calc](#idr-calc). | | dob† | string | The target's Date of Birth (`YYYYMMDD` format). Required if `phone` is not sent. | | phone† | string | The target's phone number. Required if `dob` is not sent. | | email | string | The target's email address | | age\* | string | The age to check (sent as `"age+"` — e.g. `"18+"`, `"21+"`) | | test\_key | string | The test key value that you are using to test | \* Required. † You must send **at least one** of `dob` or `phone`. ### Responses Response objects are identical to the base service. See [Response reference](#response-reference) for all possible `action`, `detail`, and `issues` values. *** ## Response reference {% hint style="warning" %} **`REVIEW` does not mean `PASS`.** Only a `PASS` action confirms a verified adult. If a transaction returns anything other than `PASS` — including `REVIEW` or `FAIL` — treat the target as **not verified** and do **not** consider them verified for COPPA VPC (Verifiable Parental Consent) purposes. {% endhint %} ### Action and detail The following are all values that will be returned in the `result` object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | FAIL | MINOR SUBMITTED | The DOB submitted for the target is under 18 | | FAIL | TARGET IS UNDERAGE | The target's DOB was found on file and is under 18 | | FAIL | POSSIBLE MINOR | Multiple DOBs are on file, at least one is under 18, and we could not determine which one belongs to the target | | FAIL | AGE NOT VERIFIED | No DOB was on file for this individual, so we could not verify their age | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. For this service, the only issue will be `SSN CHECK FAILED`. | | PASS | ALL CHECKS PASSED | Target was found, is not deceased, and has passed all verification checks | ### Issues When a transaction returns `REVIEW`, the response includes a list of issues. This list can contain any of the values below. | Issue | Description | | ---------------- | ------------------------------------------- | | SSN CHECK FAILED | The SSN provided does not match any on file | *** ## Rules Both variants process with the same default base ruleset: {% hint style="success" %} The base ruleset will return a **PASS** when: * A match is found * The target is not deceased * The target is 18+ * The target has provided an accurate SSN value {% endhint %} {% hint style="warning" %} The base ruleset will return a **REVIEW** when: * A match is found * The target is not deceased * The target is 18+ * The target did not provide an accurate SSN value {% endhint %} {% hint style="danger" %} The base ruleset will return a **FAIL** when: * A match is not found * The target is deceased * The target could not be confirmed as 18+ {% endhint %} *** ## IDR Calc IDR Calc is Veratad's patented process that lets the user sum at least two digits of their SSN to prove they know it, without collecting sensitive PII. Instead of sending an `ssn` value, send the `dcalc_mask` and `dcalc_answer` attributes. ```json { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOPPA5.0", "reference": "12345 {A UNIQUE ID}", "target": { "fn": "Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "dcalc_mask": "100000001", "dcalc_answer": "16", "age": "18+", "test_key": "general_identity" } } ``` | Attribute | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | dcalc\_mask | Tells the system which digits you asked the customer to sum. Place a `1` in each position you summed and a `0` in every other position. | | dcalc\_answer | The sum the user entered. | *** ## Testing Use the `test_key` attribute to test the service. When `test_key` is provided, the system automatically bypasses the live data sources and queries the testing database instead. These transactions are free of charge — to access live data, do not send this attribute. {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} # International Identity verification via trusted and verified data sources in countries outside of the United States. ## What countries are covered? Click this link to see what countries are covered for the IDMatch International Service. {% content-ref url="/pages/-MB4GiWHjlo1WNC2Z-3n" %} [Data Coverage](/coverage/international) {% endcontent-ref %} ## IDMatch5.0.{CountryName} `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action** and a **detail**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name IDMatch5.0.{CountryName}The "CountryName" should match the value in the international coverage section. | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr1 | string | The target's house number or name, plus street | | addr2 | string | the target's apt, flat or floor | | addr3 | string | The target's further address details | | addr4 | string | The target's further address details | | addr5 | string | The target's city | | addr6 | string | The target's locality (e.g. county) | | addr7 | string | The target's state or UK county | | zip\* | string | The target's zip/postal code | | dob | string | The target's Date of Birth (YYYYMMDD format) | | international\_id | string | The target's international id number.This is sometimes required. Check the international coverage page for more details. | | phone | string | The target's phone number | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "confirmation": 71483084, "reference": "12345", "service": "IDMatch5.0.{CountryName}", "timestamp": "2019-10-17 14:29:48", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} When setting the service name you must view the data coverage section (linked above) and use the country name for your query. Therefore, in the majority of cases the service name will be something like: **IDMatch5.0.Canada** But in certain cases where a country name has spaces i.e. the United Kingdom the service name will be like: **IDMatch5.0.UK** You will find all of the countries where there is an exception in the data coverage section of the documentation. {% endhint %} ## Sample Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "IDMatch5.0.{CountryName}", "reference": "12345", "target":{ "fn":"Barbara", "ln": "Miller", "addr1": "123 Main St", "addr2": "TORONTO", "addr3": "ON", "zip": "M4B 1B3", "dob": "19740821", "international_id": "854125698", "phone": "2015106000", "age": "21+", "test_key": "international_pass" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | SERVICE CANNOT BE COMPLETED | The underlying data sources are having a processing issue. Resubmit this query at a later time | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | The service was completed and a match was found, but not all of the identity attributes matched. See the issues array for the elements that did not match. | | PASS | ALL CHECKS PASSED | The service was complete, the target was found and all identity attributes provided matched. | ## Issues Responses When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. | Issue | Description | | ----------------------------- | ----------------------------------------------------- | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DATE OF BIRTH CHECK FAILED | The Date of Birth provided does not match any on file | | INTERNATIONAL ID CHECK FAILED | The SSN provided does not match any on file | | PHONE CHECK FAILED | The phone number provided does not match any on file | | EMAIL CHECK FAILED | The email address provided does not match any on file | | AGE CHECK FAILED | The target does not meet the age attribute provided | | POSSIBLE MINOR | The target is detected as a minor | ## Service Testing When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. Here are available test cases for the international service: | test key | description | | ------------------------------------------ | ---------------------------------------------------------------------------------- | | international\_pass | Will return a `PASS - ALL CHECKS PASSED` result | | international\_fail\_no\_match | Will return a `FAIL - NO MATCH` result | | international\_review | Will return a `REVIEW` result. The issues array will include all issues available. | | international\_fail\_cannot\_be\_completed | Will return a `FAIL - SERVICE CANNOT BE COMPELTED` result | {% hint style="info" %} The above are all "canned responses", so the target input will not matter if a valid test key is provided. {% endhint %} ## Rules IDMatch International will process with the following rules by default {% hint style="info" %} The base rule set will return a PASS when: * The service was completed * A match is found * The target meets has provided all valid identity attributes {% endhint %} {% hint style="warning" %} The base rule set will return a REVIEW when: * The service was completed * A match was found * The target has not provided all accurate identity attributes In this case a list of issues will be returned to indicate which attributes did not match {% endhint %} {% hint style="danger" %} The base rule set will return a FAIL when: * The service could not be completed * No match found {% endhint %} # United States Identity verification via trusted and verified data sources in the United States. This service will also return a KBA quiz for verification. ## IDMatchPLUS5.0.MULTI `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes and to receive the quiz to present. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. If any of the provided identity attributes provided did not match you will know during this initial call.\ \ Then present the quiz to the user and take their answers and populate them in the **template** object provided and make a second POST request to get the final result with quiz score. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatchPLUS5.0.MULTI) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "questions": { "questions": [ { "prompt": "With which of the following states are you or have you been associated?", "type": "state", "id": "state1", "answers": [ { "text": "VERMONT" }, { "text": "NORTH DAKOTA" }, { "text": "SOUTH DAKOTA" }, { "text": "WISCONSIN" }, { "text": "None of the above" } ] }, { "prompt": "Which of the following addresses are in Green Bay?", "type": "address", "id": "address3", "answers": [ { "text": "11 157 STREET" }, { "text": "170 WEAVER ST" }, { "text": "87 EAST BROADWAY BLVD" }, { "text": "6 PRICE ROAD" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following zip codes are you or have you been associated?", "type": "zip5", "id": "zip52", "answers": [ { "text": "54420" }, { "text": "54155" }, { "text": "54551" }, { "text": "54807" }, { "text": "None of the above" } ] }, { "prompt": "With which of the following cities are you or have you been associated?", "type": "city", "id": "city0", "answers": [ { "text": "STREETSBORO" }, { "text": "SAINT JOHN" }, { "text": "FORT MORGAN" }, { "text": "WEST ALLIS" }, { "text": "None of the above" } ] } ] } }, "meta": { "confirmation": 21185214, "reference": "12345", "service": "IDMatchPLUS5.0.MULTI", "timestamp": "2017-08-08 14:25:02", "company": "Veratad Technologies, LLC", "user": "user@veratad.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "questions": { "url": "/process/continue", "template": { "token": "2nypwsj51mzhjvm7cr1hbyaabqm67qcc", "answers": { "zip52": [], "state1": [], "address3": [], "city0": [] } }, "instructions": "Add the text of the answers into the empty list for the appropriate question (case sensitive)." } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below. {% endhint %} {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Sample Request Body {% hint style="info" %} This is the initial query to get the quiz. See below example of how to submit the answers for final scoring and evaluation. {% endhint %} ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchPLUS5.0.MULTI", "rules": "A_RULESET_ID", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` ## Request with Quiz Answers Once your user has answered the questions, send those answers back to the system for scoring and a final evaluation. ## Submit Answers `POST` `https://production.idresponse.com/process/continue` Sending a POST request with the below body will give you the final evaluation of the quiz and other identity attributes. #### Request Body | Name | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------------- | | token | string | The token that was returned in the initial response that relates to this specific quiz. | | answers | object | The answers object should include each question asked and the user's answer. | {% tabs %} {% tab title="200 The result of the question and identity evaluation. " %} ```javascript { "final": { "template": { "token": "euwd6q5a8b4c0vwc0zy0s6ms1mjh5p0s" }, "url": "/process/status" }, "output": { "answers": { "asked": 4, "correct": 0 } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "QUESTION CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body - Quiz Score ```javascript { "answers": { "state3": ["NEW YORK"], "mothers_maiden0": ["None of the above"], "phone1": ["(206) 393-4478"], "county2": ["FAIRFIELD"] }, "token": "1bauxkpczhdiyy3vqm15ais8ue12u7zw" } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | AGE NOT VERIFIED | Target found, but no DOB information available | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | FAIL | POSSIBLE MINOR | Target found, but a minor age detected | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the "issues" object with a list of the identity attributes that did not match. See full list below. | | PENDING | MORE INFORMATION IS REQUIRED | Target was found is not deceased and meets the age requirement, but they have not yet answered the quiz. | | PASS | ALL CHECKS PASSED | Target was found is not deceased and meets the age requirement | ## Issues Responses {% hint style="info" %} When a transaction returns as REVIEW or PENDING then there will be a list of issues. This list can include any of the below values. {% endhint %} | Issue | Description | | --------------------------- | ------------------------------------------------------------------------ | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DATE OF BIRTH CHECK FAILED | The Date of Birth provided does not match any on file | | YEAR OF BIRTH CHECK FAILED | The Year of Birth provided does not match any on file | | MONTH OF BIRTH CHECK FAILED | The Month of Birth provided does not match any on file | | DAY OF BIRTH CHECK FAILED | The Day of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not match any on file | | MULTIPLE SSNS FOUND | The identity located has more than one SSN associated | | PHONE CHECK FAILED | The Phone Number provided does not match any on file | | EMAIL CHECK FAILED | The Email Address provided does not match any on file | | AGE CHECK FAILED | The target does not meet the minimum age requirement | | POSSIBLE MINOR | A DOB detected that indicates the user may be under your age requirement | | QUESTION CHECK FAILED | The user did not answer at least 3/4 questions correct | ## Rules IDMatch+PLUS will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target has provided all valid identity attributes * The user has answered at least 3/4 questions correct {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target is not deceased * The target's identity attributes do not all match or they failed the quiz {% endhint %} {% hint style="info" %} The base ruleset will return a PENDING when: * A match found * The target is not deceased * Questions are returned, but not answered yet {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found or * The target is deceased In this case no questions will be provided. {% endhint %} ## API Processing Error Returns {% hint style="info" %} Each token is only valid for 90 seconds with this service. See the error responses to get information on what happens if a token is bad or expired. {% endhint %} {% content-ref url="/pages/-LrjFxJ4Wv\_iErI2\_I7V" %} [Error Returns](/api-processing-errors/error-returns) {% endcontent-ref %} # Fraud Score IDMatch+Predict Fraud Score assesses the overall risk of an applicant for a new account. ## IDMatchPredict5.0.FraudScore `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target is a potential fraud risk. You will receive a synchronous response in under 1 second with a **result** object that includes an **action** and a **detail**. #### Request Body | Name | Type | Description | | ------------------------------------------------------------ | ------ | ------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatchPredict5.0.FraudScore) | | rules | string | See rules explanation below | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | account.id\* | string | The target's unique account ID | | account.registration\_time\* | string | The target's account registration timeYYYY-MM-DD HH:MM | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | ip\_address\* | string | The target's IP address (v4 or v6) | | phone\* | string | The target's phone number | | email\_address\* | string | The target's email address | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "signals": { "phone": { "is_valid": true, "line_type": "LANDLINE", "is_matched_with_name": false, "country_code": "US", "carrier": "VERIZON" }, "ip_address": { "distance_to_phone": 15, "date_last_seen": "2021-10-06", "is_risky": false, "distance_to_address": "" }, "email": { "date_first_seen": "2008-04-29", "is_valid": true, "is_matched_with_name": true }, "identity": { "risk_score": 58.2, "network_score": 0.401 }, "address": { "is_valid": false, "is_matched_with_name": null } } }, "meta": { "confirmation": 117360891, "reference": "", "service": "IDMatchPredict5.0.FraudScore", "timestamp": "2021-10-06 19:23:45", "company": "Veratad Technologies, LLC", "user": "root@veratad.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "RISK SCORE GREATER THAN 40 AND LESS THAN 80" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchPredict5.0.FraudScore", "reference": "12345 {A UNIQUE ID}", "rules": "", "target": { "fn": "Barbara", "ln": "Miller", "email_address": "bmiller@veratad.com", "ip_address": "2600:100c:b21d:431e:2ac:edaf:20ef:9fd5", "account": { "id": "587156", "registration_time": "2021-07-22 21:45" }, "addr": "123 Main St", "city": "Dallas", "state": "Tx", "zip": "75215", "phone": "2015106000", "test_key": "predict_fraudscore_review" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------- | | FAIL | RISKY CUSTOMER | Identity risk score, network score, IP risk score, and email age all exceed their respective thresholds | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | See the full list of possible issues below | | PASS | ALL CHECKS PASSED | Identity risk score, network score, IP risk score, and email age all within their respective thresholds | ## Issues | Issue | Description | | --------------------------------------------------- | -------------------------------------------------------------- | | RISK SCORE GREATER THAN OR EQUAL TO X SCORE | The identity risk score greater than or equal to X score | | IP RISK SCORE GREATER THAN OR EQUAL TO X SCORE | The IP risk score is greater than or equal to X score | | NETWORK RISK SCORE GREATER THAN OR EQUAL TO X SCORE | The Identity network score is greater than or equal to X score | | EMAIL IS LESS THAN X DAY(S) OLD | The days since email first seen date is less than X days | ## Rules IDMatchPredict5.0.FraudScore will process with the default base ruleset unless a different rule set is specified in the query. {% hint style="success" %} The base ruleset will return a PASS when: * Identity risk score < 50 * IP risk score < 60 * Identity network score < 60 * Days since email first seen date >= 100 days {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * Identity risk score >= 50 * IP risk score >= 60 * Identity network score >= 60 * Days since email first seen date < 100 days {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * Identity risk score >= 50 AND IP risk score >= 60 AND Identity network score >= 60 AND days since email first seen date < 100 days {% endhint %} ## Testing When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. Here are available test cases for the fraud score service. | Key | Description | | --------------------------- | ------------------------------------------------------------------------------ | | predict\_fraudscore\_pass | The action will always return as `PASS` regardless of the target attributes. | | predict\_fraudscore\_review | The action will always return as `REVIEW` regardless of the target attributes. | | predict\_fraudscore\_fail | The action will always return as `FAIL` regardless of the target attributes. | # Verification and Validation You can verify that a target is associated with a phone number or that a phne number itself is valid. ![](/files/-MC8b5C0wVskHrYIT3md) ## Verification Authoritatively connect a user's phone number to their identity using trusted and verified data sources in the United States. {% content-ref url="/pages/-LrtMK5rlt2D9Clsp-Ov" %} [Phone Verification](/phone-verification-and-validation/verification-and-validation/phone-verification) {% endcontent-ref %} ## Validation Validate a phone number and receive phone details on return. {% content-ref url="/pages/-LrtMwBDV1j5rj5XoFHt" %} [Phone Validation](/phone-verification-and-validation/verification-and-validation/phone-validation) {% endcontent-ref %} # Smart 2FA ## What is Smart 2FA? Exclusively from Veratad, Smart 2FA℠ finally introduces two-factor authentication to customer onboarding. By combining the best of identity verification and two-factor, Smart 2FA delivers **the highest level** of surety that your customers are who they say they are. ## **This service is asynchronous** This service may include two requests: 1. **Initial Request:** with this request you will start the session by sending the target. Once started the first thing that will happen is the user will receive the OTP either through call or SMS. You will get a session token in return to send back in the secondary request with the user's OTP entry. 2. **Secondary Request:** with this request you will send the entered OTP to be scored. If successful the verification process will also occur and the final result is returned. ## SMS or Call You are able to send the OTP via SMS or Call by adjusting the service name on initial request. The service name will either be: `PhoneMatch5.0.Smart2FA.SMS` `PhoneMatch5.0.Smart2FA.Call` ## Initial Request Parameters and example response `POST` `https://production.idresponse.com/process/comprehensive/gateway` #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ---------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (PhoneMatch5.0.Smart2FA.SMS or PhoneMatch5.0.Smart2FA.Call) | | reference | string | A unique identifier for your customer | | target\* | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone\* | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | options | object | The OTP options | {% tabs %} {% tab title="200: OK When the OTP has been delivered successfully " %} ```javascript { "output": { "outofband": {}, "rescue": {} }, "meta": { "confirmation": 127334139, "reference": "195599", "service": "PhoneMatch5.0.Smart2FA.SMS", "timestamp": "2022-03-08 09:39:38", "company": "Company, LLC", "user": "company@veratad.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "outofband": { "url": "/process/continue", "hint": "Enter the six-digit code", "prompt": "One Time Passcode", "template": { "token": "umge9844g0j5d6sebq08qif9isr0xzzl", "codematch": { "key": null } }, "instructions": "A code has been delivered to the provided number. Please resubmit the code to complete the transaction." } } } ``` {% endtab %} {% tab title="200: OK When the OTP was not delivered" %} ```javascript { "output": { "outofband": {}, "rescue": {} }, "meta": { "confirmation": 127334300, "reference": "195599", "service": "PhoneMatch5.0.Smart2FA.SMS", "timestamp": "2022-03-08 09:45:51", "company": "Veratad Technologies, LLC", "user": "root@veratad.com" }, "result": { "action": "FAIL", "detail": "FAILED TO SEND TO NUMBER", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Initial Request Body Example ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "PhoneMatch5.0.Smart2FA.SMS", "reference": "12345 {A UNIQUE ID}", "options": { "outofband": { "message": "Hello {fn}, your one-time password is {pin}", // this is the SMS message that will be delivered to the user "do_not_send_to_types": ["landline"] // you can block "landlines" for the SMS service here } }, "target":{ "fn":"Barbara", "ln": "Miller", "phone": "2015106000" } } ``` ## Initial Request Action and Detail Responses | Action | Detail | Description | | ------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | VOIP NOT ALLOWED | The phone line type was detected as VOIP | | FAIL | SUPPRESSED SENDING CODE | The phone line type discovered was found in the `do_not_send_to_types` array in the options block on request | | FAIL | FAILED TO SEND TO NUMBER | An issue occurred during OTP delivery and the code was never received by the user | | FAIL | DATA CHECK FAILED | The phone number is invalid | | PENDING | MORE INFORMATION IS REQUIRED | The line type is not VOIP, the number is valid and the OTP was delivered to the user. The transaction is now waiting for the secondary request to complete. | ## Secondary request parameters and responses `POST` `https://production.idresponse.com/process/continue` Return the OTP entered and the token that you received on the Initial response to complete the transaction #### Request Body | Name | Type | Description | | ----------------------------------------------- | ------ | -------------------------------------------------- | | token\* | string | The session token returned on the initial response | | codematch:key\* | string | The OTP value entered by the user | {% tabs %} {% tab title="200: OK PASS " %} ```javascript {{ "final": { "template": { "token": "631bg2jx4s7fjwceitituf9nw52yn6i7" }, "url": "/process/status" }, "meta": { "company": "Veratad Technologies, LLC", "confirmation": 127335232, "reference": "195599", "service": "PhoneMatch5.0.Smart2FA.SMS", "timestamp": "2022-03-08 10:17:55", "user": "user@company.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [ "OUT-OF-BAND SUCCESSFUL" ] } } ``` {% endtab %} {% tab title="200: OK REVIEW" %} ```javascript { "final": { "template": { "token": "631bg2jx4s7fjwceitituf9nw52yn6i7" }, "url": "/process/status" }, "meta": { "company": "Veratad Technologies, LLC", "confirmation": 127335232, "reference": "195599", "service": "PhoneMatch5.0.Smart2FA.SMS", "timestamp": "2022-03-08 10:17:55", "user": "user@veratad.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "OUT-OF-BAND SUCCESSFUL", "ADDRESS CHECK FAILED" ] } } ``` {% endtab %} {% tab title="200: OK FAIL" %} ```javascript { "final": { "template": { "token": "631bg2jx4s7fjwceitituf9nw52yn6i7" }, "url": "/process/status" }, "meta": { "company": "Veratad Technologies, LLC", "confirmation": 127335372, "reference": "195599", "service": "PhoneMatch5.0.Smart2FA.SMS", "timestamp": "2022-03-08 10:21:28", "user": "user@veratad.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "FAIL", "detail": "NO MATCH", "issues": [ "OUT-OF-BAND SUCCESSFUL" ] } } ``` {% endtab %} {% endtabs %} ## Secondary Request Sample Body ```json { "token": "631bg2jx4s7fjwceitituf9nw52yn6i7", "codematch": { "key": 12345 } } ``` ## Secondary Request Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | FAIL | FAILED OUT-OF-BAND CHECK | The OTP entered did not match what was sent to the user | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the `issues`object with a list of the identity attributes that did not match. See full list below | | PASS | ALL CHECKS PASSED | Target was found is not deceased and all submitted target attributes match | ## Issues Responses When a transaction returns as `REVIEW` then there will be a list of issues. This list can include any of the below values. | Issue | Description | | -------------------- | ----------------------------------------------------- | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DOB CHECK FAILED | The Date of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not math any on file | | PHONE CHECK FAILED | The phone number provided does not match any on file | | EMAIL CHECK FAILED | The email address provided does not match any on file | | AGE CHECK FAILED | The age found does not meet the age submitted | ## Rules PhoneMatch+Smart2FA will process with the default ruleset. Which is as follows: {% hint style="success" %} The ruleset will return a PASS when: * All OTP checks have passed * A match is found * The target is not deceased * The target has provided all valid identity attributes including phone number {% endhint %} {% hint style="warning" %} The ruleset will return a REVIEW when: * A match is found * The target is not deceased * The OTP was delivered * The OTP matched * The target's identity attributes do not all match This result will also return an array of issues to notify you of exactly which target attributes provided did not match. {% endhint %} {% hint style="danger" %} The ruleset will return a FAIL when: * A match is not found * The target is deceased * The phone line type is not acceptable * The OTP is not able to be delivered * The OTP entered does not match the OTP sent {% endhint %} {% hint style="info" %} The ruleset will return PENDING when: * The service is waiting for the next API call with session token {% endhint %} ## Service Testing Since this service requires a successful OTP process you must use real data and have access to the phone number provided. You will be allotted 250 free transactions for development purposes. # Phone Verification Authoritatively connect a user's phone number to their identity using trusted and verified data sources. ## What's the difference between this service and IDMatch? In short, the main differences between this service and IDMatch are: * **The Goals -** this service knows that your main objective is matching a phone number to a target. Therefore, this service will continue to search sources until that goal can either be confirmed or denied. * **The Required Inputs -** this service only requires a first name, last name and phone number on input to process, but can accept all other target attributes and will attempt to match anything sent in the request. * **The Data Sources -** this service uses additional phone number specific data sources to increase your success rate. ## Can I verify a user to their phone number outside of the United States? Yes. There are many countries outside of the US where Veratad has access to phone information. Please see the country coverage below: {% content-ref url="/pages/-MB4GiWHjlo1WNC2Z-3n" %} [Data Coverage](/coverage/international) {% endcontent-ref %} {% hint style="success" %} Using this service coupled with **PhoneMatch5.0.SMS** and/or **PhoneMatch5.0.Call** is a great way to verify that the number belongs to your customer and that they have possession of the device to increase identity verification confidence. {% endhint %} ## PhoneMatch5.0 `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (PhoneMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone\* | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "company": "Company ABC, Inc.", "confirmation": "21201890", "reference": "12345 {A UNIQUE ID}", "service": "PhoneMatch5.0", "timestamp": "2017-08-08 17:56:14", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "PHONE CHECK FAILED" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "IDMatch5.0", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "phone": "2015106000", "test_key": "general_identity" } } ``` ## Service Testing Use the `test_key` attribute to test the service. When the `test_key` is provided the system will dynamically drop the live data sources and use the testing database. {% content-ref url="/pages/-Lrp-fueX5LNIL3YLyzR" %} [Test Cases](/testing-1/additional-test-cases) {% endcontent-ref %} ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | NO MATCH | No matching identity found in the data sources | | FAIL | TARGET IS DECEASED | Target found as a deceased identity | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the `issues`object with a list of the identity attributes that did not match. See full list below | | PASS | ALL CHECKS PASSED | Target was found is not deceased and all submitted target attributes match | ## Issues Responses When a transaction returns as `REVIEW` then there will be a list of issues. This list can include any of the below values. | Issue | Description | | -------------------- | ----------------------------------------------------- | | ADDRESS CHECK FAILED | The address provided does not match any on file | | DOB CHECK FAILED | The Date of Birth provided does not match any on file | | SSN CHECK FAILED | The SSN provided does not math any on file | | PHONE CHECK FAILED | The phone number provided does not match any on file | | EMAIL CHECK FAILED | The email address provided does not match any on file | | AGE CHECK FAILED | The age found does not meet the age submitted | ## Rules PhoneMatch will process with the default base ruleset. Which is as follows: {% hint style="success" %} The base ruleset will return a PASS when: * A match is found * The target is not deceased * The target has provided all valid identity attributes {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * A match is found * The target is not deceased * The target's identity attributes do not all match This result will also return an array of issues to notify you of exactly which target attributes provided did not match. {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * A match is not found or * The target is deceased {% endhint %} # Phone Validation Validate a phone number and receive phone details on return. ## PhoneMatch5.0.Validate `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided a valid number and other details about the number. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your Account's API password | | service\* | string | The service name (PhoneMatch5.0.Validate) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | phone\* | string | The target's phone number (see formats below) | | invalid\_phonelinetypes | array | Set which line types should FAIL the check (see below for input values) | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "data": { "PhoneNumber": [ { "countrycode": "US", "countrycallingcode": "1", "country": "United States", "phonelinetype": "Mobile", "carrier": "Verizon Wireless", "phonenumber": "2015106000" } ] } }, "meta": { "confirmation": 71785534, "reference": null, "service": "PhoneMatch5.0.Validate", "timestamp": "2019-10-25 14:09:12", "company": "Company, LLC", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "PhoneMatch5.0.Validate", "reference": "12345", "target": { "phone": "2015106000", "invalid_phonelinetypes": ["voip"] } } ``` ## How should the number be formatted? The number should be a string with the country code followed by the number. #### US Example ``` 12015106000 ``` #### International Example ``` 442015412653 ``` {% hint style="info" %} If you send the number with any characters that is fine. They will be stripped out. So, `1 (201) 510-6000` is also valid. {% endhint %} ## Invalid Phone Number Types On input you can set which line types should return a `FAIL` - `PHONE TYPE CHECK FAILED`. For example, the above would fail if the number was detected as voip. Use any of the line types described below in the output data section. ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------ | ----------------------- | ------------------------------------------------------ | | FAIL | PHONE CHECK FAILED | The phone number is not valid | | FAIL | PHONE TYPE CHECK FAILED | The phone number type is in the exclusion list | | PASS | ALL CHECKS PASSED | The phone number is valid and the type is not excluded | ## Output Data {% hint style="info" %} The phone validation returns information to your application about the number. Below are the return values. {% endhint %} | Parameter | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | countrycode | The ISO-3166 alpha-2 country code of the address. | | countrycallingcode | The country code of the phone number. | | country | The country name of the location associated to the phone number. | | phonelinetype |

The line type of the phone number.

  • Landline - Traditional wired phone line.
  • VOIP - VOIP-based fixed and nonfixed line phones.
  • Mobile - Wireless phone line.
  • Voicemail - Voicemail-only service.
  • TollFree - Callee pays for call.
  • Premium - Caller pays a premium for the call–e.g. 976 area code.
  • Other - Anything that does not match the previous categories.
| | carrier | The company that provides voice and/or data services for the phone number. Carriers are returned at the MVNO level. | | phonenumber | The phone number in E.164 or local format. The default country calling code is +1 (USA). | ## Rules PhoneMatch+Validate will process with the default base ruleset. Here are the rules: {% hint style="success" %} The base ruleset will return a PASS when: * The phone number is valid * The phone number type is not on the exclusion list {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The phone number is not valid * The phone number type is on the exclusion list {% endhint %} ## API Processing Error Returns {% content-ref url="/pages/-LrjFxJ4Wv\_iErI2\_I7V" %} [Error Returns](/api-processing-errors/error-returns) {% endcontent-ref %} # One Time Passwords Send OTP (One-Time Passwords) to users via SMS and Call ![](/files/-MC7sySD9ZNawoyBMNxf) ## OTP (One-Time Password) Delivery Methods {% hint style="info" %} **NOTE:** When reviewing the API documentation for both methods notice that they are almost identical except for the service name and and the option to edit the message sent. So, really only one integration is required with minor logic to adjust to either call or SMS. {% endhint %} There are two methods to send an OTP to a user's phone. Click below to view documentation {% content-ref url="/pages/-LrtNBwpOkNk4AGCUMix" %} [SMS](/phone-verification-and-validation/one-time-passwords/sms-otp) {% endcontent-ref %} {% content-ref url="/pages/-LrtN\_Mq-G8CSd1xZ5vu" %} [Call](/phone-verification-and-validation/one-time-passwords/call-otp) {% endcontent-ref %} # SMS Validate a user's number and send a one time password via SMS to their phone to verify they have possession. ## This service is asynchronous The PhoneMatch OTP delivery services are asynchronous which means you will make an initial call to send the OTP and receive a response and a second call to validate the user's OTP entry against what was sent. 1. **Initial Request -** Send the phone number with other options via the Initial Request Instructions below and when successful you will receive a response with a template that includes a token value. 2. **OTP Validation Request -** Send the template returned in the initial request including the token and the user's OTP entry back to the system for final match result. {% hint style="info" %} As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines. {% endhint %} ## PhoneMatch5.0.SMS (initial request) `POST` `https://production.idresponse.com/process/comprehensive/gateway` Initial request details #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | phone\* | string | The target's street address (line 1 and line 2) | | options | object | the target's city | | outofband | object | The target's state | | message | string |

The sms message content. Use {} to enter a target attribute and the OTP value

i.e. Hello {fn}, your one-time password is {pin}

| | do\_not\_send\_to\_types | array |

A list of line types that the message will not be delivered. Possible values are:

mobile
landline
voip

| {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "outofband": {} }, "meta": { "confirmation": 57984073, "reference": "12345", "service": "PhoneMatch5.0.SMS", "timestamp": "2019-01-07 12:35:09", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "outofband": { "url": "/process/continue", "template": { "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1", "codematch": { "key": null } }, "instructions": "A code has been delivered to the provided number. Please resubmit the code to complete the transaction." } } } ``` {% endtab %} {% endtabs %} ## Sample Initial Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "PhoneMatch5.0.SMS", "reference": "12345", "options": { "outofband": { "message": "Hello {fn}, your one-time password is {pin}", "do_not_send_to_types": ["voip", "mobile", "landline"], "country": { "blacklist": ["ISO2 Country Code"], //countries you do not want to send codes "whitelist": ["ISO2 Country Code"] //countries you only want to send codes } } }, "target": { "fn": "John", "ln": "Smith", "phone": "2015106000" } } ``` ## Action and Detail Responses Initial Request The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | SUPPRESSED SENDING CODE | The phone line type was detected as one of the line types passed in the options object in the `do_not_send_to_types` array | | FAIL | FAILED TO SEND TO NUMBER | An issue occurred during password delivery and it never reached the user | | FAIL | DATA CHECK FAILED | The phone number is invalid and the code could not be sent | | PENDING | TRANSACTION REQUIRES FURTHER ATTENTION | The line type is not in the `do_not_send_to_types` array, the number is valid and the SMS was sent to the user. The transaction is now waiting for submission of the OTP for final matching | ## PhoneMatch5.0.SMS (OTP validation request) `POST` `https://production.idresponse.com/process/continue` OTP validation request details #### Request Body | Name | Type | Description | | --------- | ------ | --------------------------------------------------------- | | token | string | The token returned in the initial request response | | codematch | object | An object that contains the key with the user's OTP entry | | key | string | The user's OTP entry | {% tabs %} {% tab title="200 OTP match completed and response returned" %} ```javascript { "final": { "template": { "token": "1x6mvu6b4kuwonduqw8b1nsj7jpxgaza" }, "url": "\/process\/status" }, "meta": { "company": "Veratad Technologies, LLC", "confirmation": 96197373, "reference": null, "service": "PhoneMatch5.0.SMS", "timestamp": "2020-07-10 10:46:08", "user": "root@veratad.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample OTP Validation Request Body ```javascript { "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1", "codematch": { "key": "12345" } } ``` ## Action and Detail Response OTP Validation Request | Action | Detail | Description | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | FAILED OUT-OF-BAND CHECK | The number is valid, the line type was not found in the `do_not_send_to_types` array, the OTP was successfully sent, the user entered the OTP and the OTP entered DID NOT match the OTP sent. | | PASS | ALL CHECKS PASSED | The number is valid, the line type was not found in the `do_not_send_to_types` array, the OTP was successfully sent, the user entered the OTP and the OTP entered matched the OTP sent. | ## Rules PhoneMatch+SMS will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The OTP was sent successfully * The user OTP entry matched the OTP sent {% endhint %} {% hint style="warning" %} The base ruleset will return a PENDING when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The OTP was sent successfully * The transaction is waiting for submission of the user's OTP entry {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The phone number is not valid * The phone line type is found in the `do_not_send_to_types` array * The OTP was not sent successfully * The user OTP entry did not match the OTP sent {% endhint %} # Call Validate a user's number and send a one time password via call to their phone to verify they have possession. ## This service is asynchronous The PhoneMatch OTP delivery services are asynchronous which means you will make an initial call to send the OTP and receive a response and a second call to validate the user's OTP entry against what was sent. 1. **Initial Request -** Send the phone number with other options via the Initial Request Instructions below and when successful you will receive a response with a template that includes a token value. 2. **OTP Validation Request -** Send the template returned in the initial request including the token and the user's OTP entry back to the system for final match result. {% hint style="info" %} As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines. {% endhint %} ## PhoneMatch5.0.Call (initial request) `POST` `https://production.idresponse.com/process/comprehensive/gateway` Initial request details #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (PhoneMatch5.0.Call) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | phone\* | string | The target's street address (line 1 and line 2) | | options | object | the target's city | | outofband | object | The target's state | | do\_not\_send\_to\_types | array | A list of line types that the message will not be delivered. Possible values are:mobile landline voip | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "outofband": {} }, "meta": { "confirmation": 57984073, "reference": "12345", "service": "PhoneMatch5.0.Call", "timestamp": "2019-01-07 12:35:09", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "outofband": { "url": "/process/continue", "template": { "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1", "codematch": { "key": null } }, "instructions": "A code has been delivered to the provided number. Please resubmit the code to complete the transaction." } } } ``` {% endtab %} {% endtabs %} ## Sample Initial Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "PhoneMatch5.0.Call", "reference": "12345", "options": { "outofband": { "do_not_send_to_types": ["voip", "mobile", "landline"], "country": { "blacklist": ["ISO2 Country Code"], //countires you do not want to send codes "whitelist": ["ISO2 Country Code"] //countires you only want to send codes } } }, "target": { "fn": "John", "ln": "Smith", "phone": "2015106000" } } ``` ## Action and Detail Responses Initial Request The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | SUPPRESSED SENDING CODE | The phone line type was detected as one of the line types passed in the options object in the `do_not_send_to_types` array | | FAIL | FAILED TO SEND TO NUMBER | An issue occurred during password delivery and it never reached the user | | FAIL | DATA CHECK FAILED | The phone number is invalid and the code could not be sent | | PENDING | TRANSACTION REQUIRES FURTHER ATTENTION | The line type is not in the `do_not_send_to_types` array, the number is valid and the SMS was sent to the user. The transaction is now waiting for submission of the OTP for final matching | ## PhoneMatch5.0.Call (OTP validation request) `POST` `https://production.idresponse.com/process/continue` OTP validation request details #### Request Body | Name | Type | Description | | --------- | ------ | --------------------------------------------------------- | | token | string | The token returned in the initial request response | | codematch | object | An object that contains the key with the user's OTP entry | | key | string | The user's OTP entry | {% tabs %} {% tab title="200 OTP match completed and response returned" %} ```javascript { "final": { "template": { "token": "1x6mvu6b4kuwonduqw8b1nsj7jpxgaza" }, "url": "\/process\/status" }, "meta": { "company": "Veratad Technologies, LLC", "confirmation": 96197373, "reference": null, "service": "PhoneMatch5.0.SMS", "timestamp": "2020-07-10 10:46:08", "user": "root@veratad.com" }, "output": { "codematch": { "key_matched": true } }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample OTP Validation Request Body ```javascript { "token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1", "codematch": { "key": "12345" } } ``` ## Action and Detail Response OTP Validation Request | Action | Detail | Description | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | FAILED OUT-OF-BAND CHECK | The number is valid, the line type was not found in the `do_not_send_to_types` array, the OTP was successfully sent, the user entered the OTP and the OTP entered DID NOT match the OTP sent. | | PASS | ALL CHECKS PASSED | The number is valid, the line type was not found in the `do_not_send_to_types` array, the OTP was successfully sent, the user entered the OTP and the OTP entered matched the OTP sent. | ## Rules PhoneMatch+SMS will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The OTP was sent successfully * The user OTP entry matched the OTP sent {% endhint %} {% hint style="warning" %} The base ruleset will return a PENDING when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The OTP was sent successfully * The transaction is waiting for submission of the user's OTP entry {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The phone number is not valid * The phone line type is found in the `do_not_send_to_types` array * The OTP was not sent successfully * The user OTP entry did not match the OTP sent {% endhint %} # Message Delivery With IDR5 you are able to send a pre recorded message to a user's phone number and receive a result that will let you know if the message was delivered. ## Dialer The PhoneMatch+Dialer service will deliver a message to your users. Please click below for the documentation. {% content-ref url="/pages/-MC8\_\_1Ktt8Xo1R9TQdG" %} [Dialer](/phone-verification-and-validation/message-delivery/dialer) {% endcontent-ref %} # Dialer Send a pre-recorded message to a user's phone number and receive a result that will let you know if the message was delivered. ## This service is asynchronous This service includes two POST request: * **Initial request -** defines which message to send and to what phone number. This request will also return a template with a unique token that should be submitted in the status request. * **Status Request -** a request with the template and token from the initial request to retrieve the status of the call. ## You must provide the audio file Provide your Veratad representative with the audio file you want to be delivered. You can have as many audio files as necessary. Once you have provided the audio file then Veratad will provide you with that files unique name which you will send as part of the initial request in the `message` attribute. Please see the section below called "***What types of audio files are acceptable"*** for a full list of file types. {% hint style="info" %} As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines. {% endhint %} ## PhoneMatch5.0.Dialer (initial request) `POST` `https://production.idresponse.com/process/comprehensive/gateway` Initial request details #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (IDMatch5.0) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | phone\* | string | The target's phone number | | options | object | The transaction options | | outofband | object | The dialer specific options | | message | string | The audio file name provided to you by Veratad after you have provided Veratad with the audio file. (see below for acceptable audio file types) | | do\_not\_send\_to\_types | array |

A list of line types that the message will not be delivered. Possible values are:mobile
landline
voip

| {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "outofband": {} }, "meta": { "confirmation": 66834975, "reference": "Unique Identifier", "service": "PhoneMatch5.0.Dialer", "timestamp": "2019-07-09 09:57:45", "company": "Company ABC, Inc", "user": "user@company.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "outofband": { "url": "/process/continue", "template": { "dialer": { "return": "status" }, "token": "ssskwryi5u5t222kd3sqjey4axsnonl8" }, "instructions": "A phone call has been placed. Please resubmit to determine the status of said call" } } } ``` {% endtab %} {% endtabs %} ## Sample Initial Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "PhoneMatch5.0.Dialer", "reference": "12345", "options": { "outofband": { "message": "test.message", "do_not_send_to_types": ["voip", "mobile", "landline"] } }, "target": { "phone": "2015106000" } } ``` ## Action and Detail Responses Initial Request The following are all values that will be returned in the result object of the response. | Action | Detail | Description | | ------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | SUPPRESSED SENDING CODE | The phone line type was detected as one of the line types passed in the options object in the `do_not_send_to_types` array | | FAIL | FAILED TO SEND TO NUMBER | An issue occurred during password delivery and it never reached the user | | FAIL | DATA CHECK FAILED | The phone number is invalid and the code could not be sent | | PENDING | TRANSACTION REQUIRES FURTHER ATTENTION | The line type is not in the `do_not_send_to_types` array, the number is valid and the message was sent to the user. You may now send a subsequent request to get the status. | ## PhoneMatch5.0.Dialer (message status request) `POST` `https://production.idresponse.com/process/continue` OTP validation request details #### Request Body | Name | Type | Description | | ------ | ------ | -------------------------------------------------- | | token | string | The token returned in the initial request response | | dialer | object | An object that contains the return value | | return | string | The value to return | {% tabs %} {% tab title="200 OTP match completed and response returned" %} ```javascript { "continuations": { "outofband": { "instructions": "A phone call has been placed. Please resubmit to determine the status of said call", "template": { "dialer": { "return": "status" }, "token": "ej809ouee0ci516cspuauva5m8q3cy2o" }, "url": "\/process\/continue" } }, "meta": { "company": "Company ABC, Inc", "confirmation": 96399016, "reference": null, "service": "PhoneMatch5.0.Dialer", "timestamp": "2020-07-14 10:33:14", "user": "user@company.com" }, "output": [], "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample OTP Validation Request Body ```javascript { "dialer": { "return": "status" }, "token": "ssskwryi5u5t222kd3sqjey4axsnonl8" } ``` ## Action and Detail Response Status Request | Action | Detail | Description | | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | FAIL | MESSAGE COULD NOT BE DELIVERED | Something went wrong and the message was never delivered to the customer. | | PENDING | MORE INFORMATION IS REQUIRED | The call is still in progress. Take the template returned and submit again. | | PASS | ALL CHECKS PASSED | The number is valid, the line type was not found in the `do_not_send_to_types` array, the message was successfully sent and was delivered. | ## Rules PhoneMatch+Dialer will process with the default base ruleset: {% hint style="success" %} The base ruleset will return a PASS when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The message was sent successfully {% endhint %} {% hint style="warning" %} The base ruleset will return a PENDING when: * The phone number is valid * The phone line type is not found in the `do_not_send_to_types` array * The message was sent * The transaction is waiting for you to check the status {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The phone number is not valid * The phone line type is found in the `do_not_send_to_types` array * The message was not sent successfully {% endhint %} ## What types of audio files are acceptable? You must provide Veratad with the audio file that you want delivered. Once you have provided this file Veratad will supply you with the files name in the system for you to populate the `message` attribute in your initial request. Here are all of the acceptable file types: | MIME type | Description | | ------------ | ----------------------------- | | audio/mpeg | mpeg layer 3 audio | | audio/wav | wav format audio | | audio/wave | wav format audio | | audio/x-wav | wav format audio | | audio/aiff | audio interchange file format | | audio/x-aifc | audio interchange file format | | audio/x-aiff | audio interchange file format | | audio/x-gsm | GSM audio format | | audio/gsm | GSM audio format | | audio/ulaw | u-law audio format | # Email Validation Email validation and risk profiling. ## EmailMatch5.0.Validate `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided a valid and non high risk email address. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (EmailMatch5.0.Validate) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | email | string | The target's email address | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "confirmation": 68651625, "reference": null, "service": "EmailMatch5.0", "timestamp": "2019-10-25 13:48:21", "company": "Company, LLC", "user": "user@company.com" }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "EMAIL DELIVERY UNKNOWN" ] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "EmailMatch5.0.Validate", "target": { "email": "test@veratad.com" } } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------ | -------------------------------------- | -------------------------------------------------------- | | FAIL | EMAIL DELIVERY CHECK FAILED | The email address is not deliverable | | FAIL | EMAIL RISK CHECK FAILED | The email address risk is high | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | The email has one of the below issues | | PASS | ALL CHECKS PASSED | The email address is deliverable and there are no issues | ## Issues Responses {% hint style="info" %} When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. {% endhint %} | Issue | Description | | --------------------- | ---------------------------------------------------------------------------- | | EMAIL RISK IS MEDIUM | The email address has been detected as deliverable, but with medium risk | | EMAIL RISK IS UNKNOWN | The email address has been detected as deliverable, but with an unknown risk | ## Rules EmailMatch+Validate will process with the default base ruleset. Here are the rules: {% hint style="success" %} The base ruleset will return a PASS when: * The email address is deliverable * The email address is low risk {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * The email address is deliverable * The email address has medium risk * The email address has an unknown risk {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The email address is not deliverable * The email address is high risk {% endhint %} ## API Processing Error Returns {% content-ref url="/pages/-LrjFxJ4Wv\_iErI2\_I7V" %} [Error Returns](/api-processing-errors/error-returns) {% endcontent-ref %} # Document Capture and Management Services The DCAMS platform has two methods of integration and three major product families. All products are designed to validate, verify, store and manually review ID documents ![](/files/-MB0pHxIrR7O10a2Vli2) ## Integration Methods ### 1. API You may integrate any service below by directly connecting with one of the DCAMS API endpoints. ### 2. iFrame With the iFrame, we’ve tried to make it as easy as possible to get up and running with DCAMS. The iFrame is built to allow you to scan, review and store identity documents. ## Products ### DCAMS DCAMS is the storage system for identity documents. This system will allow you to securely store customer identity documents and allow your internal teams to review uploaded documents. The system is available via API endpoints or through a backend management system. ### DCAMS+ DCAMS+ is an API service to scan and verify identity documents. There are two services within this product: * **DCAMSPLUS5.0** - this ID document scanning service will validate an identity document and match customer information to the document scanned. * **DCAMSPLUS5.0.Enhanced** - The enhanced service will do everything that the base service can do, but will also verify the identity document through security checks, match a selfie against the document and offers better coverage of non US based documents. ### DCAMS+Manual DCAMS+Manual is a service that includes the human review of an identity document. {% content-ref url="/pages/-Lrp6wM9eshXsnrjjxXR" %} [Manual Review](/id-document-verification/overview/id-document-manual-review) {% endcontent-ref %} # Scanning Basic Instantly scan an identity document for validation purposes. You can also match your customer to the document and have the document details returned to your application. ## What is the difference between basic and enhanced? Please see the table below for a list of features to decide which option fits your business best. | Feature | basic | enhanced | | ---------------------------------------- | ----- | -------- | | Data Extraction | yes | yes | | Expiration Check | yes | yes | | Age Check | yes | yes | | Target Data Matching | yes | yes | | Automatically Recognizes Document Type | no | yes | | Automatically Recognizes Document Region | no | yes | | Enhanced Security Checks | no | yes | | Selfie Matching | no | yes | | Expanded International Coverage | no | yes | ## DCAMSPLUS5.0 `POST` `https://docs.idresponse.com/process/comprehensive/gateway` Send a POST request with target parameters along with the document image(s) to receive the verification result. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (DCAMSPLUS5.0) | | rules | string | The rule set name (if left empty then the base rule set will be used) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn | string | The target's first name | | ln | object | The target's last name | | addr | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | license | object | The target's document images and other parameters.*This is not required if you send the passport object* | | front\* | string | The target's front document image | | back | string | The target's back document image | | state | string | The document's state.Only applicable for US documents. If included it can speed up processing times. | | region | string |

The document's region. If this is left empty then United States will be assumed. To verify a document outside of the United States you must include this attribute. Acceptable values are:Asia
Australia
Africa
Canada
Europe
Oceania
South America
United States

| | passport | object | The target's passport image.*Only required if you are not sending the license object* | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "documents": { //this is the test case data in the system. So, when you use the test_key dcams_pass this si what will be returned. "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE", // other values are PASSPORT, IDENTITY CARD and UNKNOWN "Confidence": 100 } }, "meta": { "confirmation": 96095474, "reference": "12345", "service": "DCAMSPLUS5.0", "timestamp": "2020-07-08 14:49:19", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "DCAMSPLUS5.0", "reference": "12345", "rules": "additional matching rules", "target": { "license": { // this object will accept any identity document except a passport i.e. driving license or identity card. "front": "base64 encoded image file", "back": "base64 encoded image file", "state": "CT", "region": "United States" }, "passport":{ "front": "base64 encoded image file" }, "age": "21+", "fn": "John", "ln": "Smith", "dob": "19870621", "test_key": "dcams_pass" } } ``` {% hint style="info" %} If you send both the `license` and `passport` objects the system will prefer the `license` and ignore the `passport.`If you want to verify a passport please remove the `license` object and only send the `passport` object. {% endhint %} ## Test Keys Use the `test_key` attribute to test the service. When the `test_key` is provided the system will return a known canned response (regardless of the image submitted) and these transactions are free of charge. | test\_key | description | | -------------------- | ---------------------------------- | | dcams\_pass | Will return a `PASS` action result | | dcams\_fail\_expired | Will return a `FAIL` action result | {% hint style="info" %} If you are using one of the matching rule sets and want to force a REVIEW then use the `dcams_pass` case and change the input target attributes to something other than the target returned. For example, the test case's first name is LOUISA, so to get a `FIRST NAME DOES NOT MATCH THE DOCUMENT` issue just change the target's first name to something other than LOUISA. {% endhint %} ## Action and Detail Responses The following are all values that will be returned in the result object of the response. | action | detail | description | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | FAIL | NOT A VALID DOCUMENT | We can not detect the image as a valid identity document | | FAIL | DOCUMENT NOT VERIFIED | We have detected an identity document, but the confidence level is below the threshold | | FAIL | DOCUMENT IS EXPIRED | The document's expiration date is in the past | | FAIL | DOCUMENT AGE CHECK FAILED | The Date of Birth on the document does not meet the minimum age requirement | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | One of the matching rules was not met (this only happens when using an additional rule set) | | PASS | ALL CHECKS PASSED | The document is valid, is not expired, the Date of Birth meets the minimum age requirement and additional matching rules all passed. | ## Issues Responses {% hint style="info" %} When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. For this service the REVIEW action will only return if you are not using the base rule set. {% endhint %} | Issue | Description | | -------------------------------------- | -------------------------------------------------------------------------------- | | FIRST NAME DOES NOT MATCH THE DOCUMENT | The target's first name does not match the first name discovered on the document | | LAST NAME DOES NOT MATCH THE DOCUMENT | The target's last name does not match the last name discovered on the document | | DOB DOES NOT MATCH THE DOCUMENT | The target's DOB does not match the DOB discovered on the document | | ADDRESS DOES NOT MATCH THE DOCUMENT | The target's address does not match the address discovered on the document | | STATE DOES NOT MATCH THE DOCUMENT | The target's state does not match the state discovered on the document | ## Rules DCAMSPLUS5.0 will process with the default base ruleset unless a below rule set value is supplied: {% hint style="success" %} The base ruleset will return a PASS when: * The document is valid * The document is not expired * The Date of Birth on the document meets the age requirement {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * The base rule set is not used * One or more of the target attributes do not match the document. {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The document is not valid * The document is expired * The Date of Birth on the document does not meet the age requirement {% endhint %} ## Additional Rule Sets You can set a new rule set. | Rule Set Name | Description | | ------------------------------------ | -------------------------------------------------------------------------------- | | DCAMS5\_0\_RuleSet\_NAME\_DOB | Base Ruleset + Name and DOB on target must match the document | | DCAMS5\_0\_RuleSet\_NAME | Base Ruleset + Name on target must match the document | | DCAMS5\_0\_RuleSet\_NAME\_ADDR | Base Ruleset + Name and Address on target must match the document | | DCAMS5\_0\_RuleSet\_NAME\_STATE | Base Ruleset + Name and State on target must match the document | | DCAMS5\_0\_RuleSet\_NAME\_STATE\_DOB | Base Ruleset + Name, State and Date of Birth on target must match the document | | DCAMS5\_0\_RuleSet\_NAME\_ADDR\_DOB | Base Ruleset + Name, Address and Date of Birth on target must match the document | {% hint style="success" %} If you do not see a rule set that you would like to use -- please just ask. We can always create a new rule set for your business purpose. {% endhint %} ## Helpful Information * The total payload may not exceed 10 MB in size. * The minimum image size is 400 pixels on each side of the document * For the best results ensure: * The image is not blurry * There is no glare * The document takes up at least 80% of the image * The edges are not cut off * The document is on a flat surface # Scanning Enhanced Instantly scan an identity document for verification purposes. ## What is the difference between basic and enhanced? Veratad offers two levels of document scanning service `basic` and `enhanced`. Please see the table below for a list of features to decide which service level fits your business best. | Feature | basic | enhanced | | ---------------------------------------- | ----- | -------- | | Data Extraction | yes | yes | | Expiration Check | yes | yes | | Age Check | yes | yes | | Target Data Matching | yes | yes | | Automatically Recognizes Document Type | no | yes | | Automatically Recognizes Document Region | no | yes | | Enhanced Security Checks | no | yes | | Selfie Matching | no | yes | | Expanded International Coverage | no | yes | ## DCAMSPLUS5.0.Enhanced `POST` `https://docs.idresponse.com/process/comprehensive/gateway` Send a POST request with target parameters along with the document image(s) to receive the verification result. #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name DCAMSPLUS5.0.Enhanced or DCAMSPLUS5.0.Enhanced.Selfie | | rules | string | The rule set name (if left empty then the base rule set will be used) | | reference | string | A unique identifier for your customer | | target\* | object | The individual being sent for verification | | fn | string | The target's first name | | ln | object | The target's last name | | addr | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | document\* | object | The target's document image which contains the front attribute | | front\* | string | The target's front document image | | age\* | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | | back | String | The target's back document image | | selfie | String | The target's captured selfie for matching. You must use the "Selfie" service name for service to attempt a match. | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "documents": { "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808-0000", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN } }, "meta": { "confirmation": 97147321, "reference": "12345", "service": "DCAMSPLUS5.0.Enhanced", "timestamp": "2020-07-27 13:11:55", "company": "Company ABC, INC", "user": "user@company.com" }, "result": { "action": "PASS", "detail": "ALL CHECKS PASSED", "issues": [] } } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "DCAMSPLUS5.0.Enhanced", "reference": "12345", "rules": "DCAMS5_0_Enhanced_RuleSet_NAME_DOB", "target": { "document": { // this object will accept any identity document i.e. driving license, identity card or passport. "front": "base64 encoded image ", "back": "base64 encoded image" // the back is an optional field "selfie": "base64 encoded image" // only when using DCAMSPLUS5.0.Enahcned.Selfie as the service }, "age": "21+", "fn": "John", "ln": "Smith", "dob": "19870621", "test_key": "dcams_enhanced_pass" } } ``` ## Action and Detail Responses The following are all values that will be returned in the result object of the initial response. | action | detail | description | | ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAIL | SERVICE CANNOT BE COMPLETED | There was some type of processing error. Please resubmit this query again | | FAIL | NOT A VALID DOCUMENT | Can not detect the image as a valid identity document | | FAIL | DOCUMENT NOT VERIFIED | The image had been detected as an identity document, but authentication checks have failed. | | FAIL | DOCUMENT IS EXPIRED | The document's expiration date is in the past | | FAIL | DOCUMENT AGE CHECK FAILED | The document's Date of Birth does not meet the minimum age requirement | | FAIL | SELFIE MATCH FAILED | The selfie provided did not match the face on the ID document | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | One of the matching rules was not met (this only happens when using an additional rule set). See issues below for all values possible. | | PASS | ALL CHECKS PASSED | The document is valid and verified, is not expired, the Date of Birth meets the minimum age requirement and additional matching rules all passed. Also, this transaction does not require any further images to be provided. | ## Issues Responses When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. For this service the REVIEW action will only return if you are not using the base rule set. | Issue | Description | | -------------------------------------- | -------------------------------------------------------------------------------- | | FIRST NAME DOES NOT MATCH THE DOCUMENT | The target's first name does not match the first name discovered on the document | | LAST NAME DOES NOT MATCH THE DOCUMENT | The target's last name does not match the last name discovered on the document | | DOB DOES NOT MATCH THE DOCUMENT | The target's DOB does not match the DOB discovered on the document | | ADDRESS DOES NOT MATCH THE DOCUMENT | The target's address does not match the address discovered on the document | | STATE DOES NOT MATCH THE DOCUMENT | The target's state does not match the state discovered on the document | ## Base Rule Set DCAMSPLUS5.0.Enhanced will process with the default base ruleset unless a below rule set value is supplied: {% hint style="success" %} The base ruleset will return a PASS when: * The document has passed all verification checks * The document is not expired * The Date of Birth on the document meets the age requirement {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * The base rule set is not used * One or more of the target attributes do not match the document. {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The document is not valid * The document is expired * The Date of Birth on the document does not meet the age requirement * The service could not be completed {% endhint %} ## Additional Rule Sets You can set a new rule set. | Rule Set Name | Description | | ---------------------------------------------- | -------------------------------------------------------------------------------- | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME\_DOB | Base Ruleset + Name and DOB on target must match the document | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME | Base Ruleset + Name on target must match the document | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME\_ADDR | Base Ruleset + Name and Address on target must match the document | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME\_STATE | Base Ruleset + Name and State on target must match the document | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME\_STATE\_DOB | Base Ruleset + Name, State and Date of Birth on target must match the document | | DCAMS5\_0\_Enhanced\_RuleSet\_NAME\_ADDR\_DOB | Base Ruleset + Name, Address and Date of Birth on target must match the document | {% hint style="success" %} If you do not see a rule set that you would like to use -- please just ask. We can always create a new rule set for your business purpose. {% endhint %} ## Test Keys Use the `test_key` attribute to test the service. When the `test_key` is provided the system will return a known canned response (regardless of the image submitted) and these transactions are free of charge. | test\_key | description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | dcams\_enhanced\_pass | Will return a `PASS` action result | | dcams\_enhanced\_fail\_age | Will return a `FAIL` action result with a `DOCUMENT AGE CHECK FAILED` detail on the initial query | | dcams\_enhanced\_fail\_not\_valid | Will return a `FAIL` action result with a `DOCUMENT NOT VALID` detail on the initial query | | dcams\_enhanced\_fail\_expired | Will return a `FAIL` action result with a `DCOUMENT IS EXPIRED` detail on the initial query | | dcams\_enhanced\_fail\_not\_verified | Will return a `FAIL` action result with a `DOCUMENT NOT VERIFIED` detail | | dcams\_enhanced\_facematched | Should be used with the selfie query to get a face match success response. Use any failure key above to get the fail response. | {% hint style="info" %} If you are using one of the matching rule sets and want to force a REVIEW then use the `dcams_enhanced_pass` case and change the input target attributes to something other than the target returned. For example, the test case's first name is LOUISA, so to get a `FIRST NAME DOES NOT MATCH THE DOCUMENT` issue just change the target's first name to something other than LOUISA. {% endhint %} ## Helpful Information * The total payload may not exceed 10 MB in size. * The minimum image size is 400 pixels on each side of the document * For the best results ensure: * The image is not blurry * There is no glare * The document takes up at least 80% of the image * The edges are not cut off * The document is on a flat surface # Manual Review Register a document with the Veratad Manual Review Team and then poll for the status. ## This service is asynchronous The manual review service includes two requests: * **Initial Request -** make an HTTPS POST request with the below body parameters to register the document with the Veratad Manual Review Team. The response for this request will include polling instructions with a unique token for the request. {% hint style="info" %} **NOTE:** The total payload of the initial request can not be greater than 10mb in size. {% endhint %} * **Polling Request -** make an HTTPS POST request with the template returned from the initial request to find the user's final status. The majority of manual reviews will take 90 seconds to complete, but this is not guaranteed, so continue to poll until you receive the final status. ![](/files/-MC8ug2M0nK9-9CFNDe-) ## DCAMSPLUS5.0.Manual (Initial Request) `POST` `https://docs.idresponse.com/process/comprehensive/gateway` This is the initial request. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------- | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (DCAMSPLUS5.0.Manual) | | rules | string | The rule set name (if left empty then the base rule set will be used) | | reference | string | A unique identifier for your customer | | target | object | The individual being sent for verification | | fn | string | The target's first name | | ln | object | The target's last name | | addr | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip | string | The target's zip | | dob | string | The target's Date of Birth (YYYYMMDD format) | | license | object | The target's document images | | front\* | string | The target's front document image | | back | string | The target's back document image | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "output": { "input": { "DriversLicense": "{}", "FirstName": "John", "LastName": "Smith", "Age": "21+", "DateOfBirth": "19870621", "TestKey": "dcams_manual_review_completed" }, "documents": [] }, "meta": { "confirmation": 95742258, "reference": "12345", "service": "DCAMSPLUS5.0.Manual", "timestamp": "2020-07-02 10:29:33", "company": "Company ABC, Inc.", "user": "user@company.com" }, "result": { "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [] }, "continuations": { "polling": { "url": "\/process\/continue", "template": { "polled": { "status": "PROCESSING", // on initial request the status will either be PROCESSING when the action is PENDING or ERROR when the action is FAIL "test_key": "", "expiry": "2020-07-03 10:29:35" }, "token": "37a0dvjedoyiovnwyhixf49cxm9a45la" }, "instructions": "Please submit template at 2.0 second intervals until polling is complete." } } } ``` {% endtab %} {% endtabs %} ## Sample Initial Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "service": "DCAMSPLUS5.0.Manual", "reference": "12345", "rules": "additional matching rules", "target": { "license": { // this object will accept any identity document i.e. driving license, identity card or passport. "front": "base64 encoded image file", "back": "base64 encoded image file" }, "age": "21+", "fn": "John", "ln": "Smith", "dob": "19870621", "test_key": "dcams_manual_review_completed" } } ``` ## Test Key Initial Submission Scenarios {% hint style="info" %} Use the `test_key` attribute to test the service. When the `test_key` is provided the system will return a known canned response (regardless of the image provided) and these transactions are free of charge. {% endhint %} | test\_key | description | | --------------------------------- | ------------------------------------------------------------------------------------- | | dcams\_manual\_review\_completed | Returns a document output when sending `template` to `process/continue` | | dcams\_manual\_review\_processing | Will only return a `processing` state when sending `template` to `process/continue` | | dcams\_manual\_review\_error | Will return an `error` state and `FAIL` when sending `template` to `process/continue` | ## Action and Detail Responses For the Initial Request {% hint style="info" %} The following are all values that will be returned in the result object of the initial response. {% endhint %} | Action | Detail | Description | | ------- | ---------------------------- | -------------------------------------------------------------------------------------------------- | | PENDING | MORE INFORMATION IS REQUIRED | The document was accepted and is currently going through manual review process. | | FAIL | SERVICE CANNOT BE COMPLETED | There was an issue with the submitted document and it cannot go through the manual review process. | ## Possible Status Responses {% hint style="info" %} On the initial request the status will always be PROCESSING or ERROR. You will only see COMPLETED during a polling request. {% endhint %} | status | description | | ---------- | ----------------------------------- | | COMPLETED | The manual review is complete | | PROCESSING | The manual review is processing | | ERROR | The manual review resulted in error | ## DCAMSPLUS5.0.Manual (Polling Request) `POST` `https://docs.idresponse.com/process/continue` This is the polling request. #### Request Body | Name | Type | Description | | -------------------------------------- | ------ | --------------------------------------------------------------------------- | | user\* | string | Your Veratad API username | | pass\* | string | Your Veratad API password | | polled | object | The polled object that was returned in the template of the initial response | | status | string | The status returned in the template of the initial response | | test\_key | string | The test\_key that you want to use during the polling request. | | expiry | string | The expiry returned in the template of the initial response | | token | string | The token returned in the template of the initial response. | {% tabs %} {% tab title="200 " %} ```javascript { "final": { // this object should be ignored. Please continue to send poll requests to the above URL in the same fashion as the first request until you get a completed result. "template": { "token": "37a0dvjedoyiovnwyhixf49cxm9a45la" }, "url": "\/process\/status" }, "meta": { "company": "Company ABC, Inc.", "confirmation": 95743502, "reference": "12345", "service": "DCAMSPLUS5.0.Manual", "timestamp": "2020-07-02 10:39:37", "user": "user@company.com" }, "output": { "documents": { //this is the test case data in the DB. "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "Confidence": 100, "DateOfBirth": "19720629", "DocumentNumber": "003009381", "ExpirationDate": "20300329", "FirstName": "LOUISA ANNA", "IssueDate": "20140714", "LastName": "SAMPLE", "MiddleName": "", "State": "LA", "Zip": "70806-0000", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN }, "input": { "Age": "21+", "DateOfBirth": "19870621", "DriversLicense": "{}", "FirstName": "John", "LastName": "Smith", "TestKey": "dcams_manual_review_completed" }, "polled": { "instructions": "Poll request has completed.", "status": "COMPLETED" } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": ["LAST NAME DOES NOT MATCH DOCUMENT", "DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"] } } ``` {% endtab %} {% endtabs %} ## Sample Polling Request Body ```javascript { "user": "user@company.com", "pass": "PASSWORD", "polled": { "status": "PROCESSING", "test_key": "dcams_manual_review_pass", "expiry": "2020-07-03 10:29:35" }, "token": "37a0dvjedoyiovnwyhixf49cxm9a45la" } ``` ## Test Key Polling Response Scenarios | test\_key | description | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | | dcams\_manual\_review\_pass | When submitted the polling action will be PASS | | dcams\_manual\_review\_fail\_expired | When submitted the polling action will be FAIL and detail will be DOCUMENT IS EXPIRED | | dcams\_manual\_review\_fail\_age | When submitted the polling action will be FAIL and detail will be DOCUMENT AGE CHECK FAILED | | dcams\_manual\_review\_fail\_not\_valid | When submitted the polling action will be FAIL and detail will be NOT A VALID DOCUMENT | | dcams\_manual\_review\_fail\_not\_verified | When submitted the polling action will be FAIL and detail will be DOCUMENT NOT VERIFIED | {% hint style="info" %} If you are using one of the additional rule sets and want to get a REVIEW then just send the `dcams_manual_review_pass` key and change one of the target attributes to something that does not match the test case returned. {% endhint %} ## Action and Detail Responses for the Polling Request | action | detail | description | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | FAIL | NOT A VALID DOCUMENT | The document is not valid or visible or is cut off | | FAIL | DOCUMENT IS EXPIRED | The expiration date on the document is in the past | | FAIL | DOCUMENT NOT VERIFIED | The document is not verified | | FAIL | DOCUMENT AGE CHECK FAILED | The Date of Birth on the document does not meet the minimum age requirement | | REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | One of the matching rules was not met (this only happens when using an additional rule set) | | PASS | ALL CHECKS PASSED | The document is valid, is not expired, the Date of Birth meets the minimum age requirement and additional matching rules all passed. | ## Issues Responses for the Polling Request {% hint style="info" %} When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values. For this service the REVIEW action will only return if you are not using the base rule set. {% endhint %} | Issue | Description | | -------------------------------------- | -------------------------------------------------------------------------------- | | FIRST NAME DOES NOT MATCH THE DOCUMENT | The target's first name does not match the first name discovered on the document | | LAST NAME DOES NOT MATCH THE DOCUMENT | The target's last name does not match the last name discovered on the document | | DOB DOES NOT MATCH THE DOCUMENT | The target's DOB does not match the DOB discovered on the document | ## Rules DCAMSPLUS5.0.Manual will process with the default base ruleset unless a rule set value is supplied: {% hint style="success" %} The base ruleset will return a PASS when: * The document is valid * The document is not expired * The Date of Birth on the document meets the age requirement {% endhint %} {% hint style="warning" %} The base ruleset will return a REVIEW when: * The base rule set it not used * One or more of the target attributes do not match the document. {% endhint %} {% hint style="danger" %} The base ruleset will return a FAIL when: * The document is not valid * The document is expired * The Date of Birth on the document does not meet the age requirement {% endhint %} ## Additional Rule Sets You can set a new rule set. | Rule Set Name | Description | | --------------------------------------------- | ------------------------------------------------------------- | | DCAMS5\_0\_Manual\_Review\_RuleSet\_NAME\_DOB | Base Ruleset + Name and DOB on target must match the document | | DCAMS5\_0\_Manual\_Review\_RuleSet\_NAME | Base Ruleset + Name on target must match the document | # Storage Store identity documents for your team to review and manually approve. There are multiple endpoints that can be used to store a customer, update a customer or get customer details from the storage system programmatically. {% content-ref url="/pages/-MC8Z7PiArYsnBBynVpX" %} [Create or Update a Customer](/id-document-verification/overview/id-document-storage/create-or-update-customer) {% endcontent-ref %} {% content-ref url="/pages/-Lrp9JBLUvew-9oqXM-G" %} [Get Customer Status](/id-document-verification/overview/id-document-storage/getcustomerstatus) {% endcontent-ref %} {% content-ref url="/pages/-MB0Yjurl37bcypqPEwx" %} [Get Customer Document Images](/id-document-verification/overview/id-document-storage/get-customer-document-images) {% endcontent-ref %} {% content-ref url="/pages/-MB0vV3KtxTxQN0lGDKC" %} [Update Customer Status](/id-document-verification/overview/id-document-storage/update-customer-status) {% endcontent-ref %} {% hint style="info" %} The storage system also offers a UI for your reps, so if you do not want to build your own please ask your Veratad representative for access. {% endhint %} # Create or Update a Customer Create a new customer or update an existing customer within the storage system. ## createOrUpdateCustomer `POST` `https://dcams.app/v3/stable/api/storage` Send all of the required fields below and the method will detect whether a create or update is necessary and will signal in the return which one occurred. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------- | | user\* | string | Your Veratad API Username | | pass\* | string | Your Veratad API Password | | service\* | string | The service name "createOrUpdateCustomer" | | reference | string | A value to be stored in the referecne field | | target | object | The target of the query | | email | string | The user's email address | | fn | string | The user's first name | | ln | string | The user's last name | | addr | string | The user's street address | | city | string | The user's city | | state | string | The user's state | | zip | string | The user's zip | | dob | string | The user's Date of Birth (YYYYMMDD) | | phone | string | The user's phone number | | documents | object | The document images | | front\* | string | The front document image | | back | string | The back document image | {% tabs %} {% tab title="200 The customer was found" %} ```javascript { "result": "Success", "reference": "888888812", "customer_link": "https://register.veratad.com/admin/customers.php?a=edit&id=727657", "status": "PASS", "type": "updateCustomer" // possible values "updateCustomer" or "createCustomer" "target": { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19700101", "email": "jsmith@veratad.com", "phone": "2015106000" } } ``` {% endtab %} {% tab title="400 The email was not a valid email address" %} ```javascript { "result": "Error", "message": "The email address is invalid" } //or { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Either a bad username or password" %} ```javascript { "result": "Error", "message": "Either your username or password is incorrect" } ``` {% endtab %} {% tab title="404 The customer was not found" %} ```javascript { "result": "Error", "message": "The email address was not found" } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "createOrUpdateCustomer", "reference": "888888812" "target": { "email": "jsmith@veratad.com", "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19700101", "phone": "2015106000", "documents": { "front": "base64 encoded image", "back": "base64 encoded image" } } } ``` ## Response Fields {% hint style="info" %} The response will include all of the target attributes stored within the system for this user, except their document images, and the following varying fields. {% endhint %} | attribute | values | | --------- | --------------------------------------------------------------------------- | | result |

Success

Error

| | status |

PASS

PENDING

FAIL

| | type |

updateCustomer

createCustomer

| # Get Customer Status Once a customer is registered with the document storage system you can get their status and other details stored in the system without their document images by making this API call. ## getStatus `POST` `https://dcams.app/v3/stable/api/storage` This endpoint allows you to get the status of a customer account already registered in the system. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------ | | user\* | string | Your Veratad API Username | | pass\* | string | Your Veratad API Password | | service\* | string | The service name "getStatus" | | target | object | The target of the query | | email | string | The user's email address for status lookup | {% tabs %} {% tab title="200 The customer was found" %} ```javascript { "result": "Success", "reference": "888888812", "status": "PASS", "target": { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19700101", "email": "test@veratad.com", "phone": "2015106000" } } ``` {% endtab %} {% tab title="400 The email was not a valid email address" %} ```javascript { "result": "Error", "message": "The email address is invalid" } //or { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Either a bad username or password" %} ```javascript { "result": "Error", "message": "Either your username or password is incorrect" } ``` {% endtab %} {% tab title="404 The customer was not found" %} ```javascript { "result": "Error", "message": "The email address was not found" } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "getStatus", "target": { "email": "test@veratad.com" } } ``` ## Response Fields {% hint style="info" %} The response will include all of the target attributes stored within the system for this user and the following varying fields. {% endhint %} | attribute | values | | --------- | --------------------------------------------------------------------------- | | result |

Success

Error

| | status |

PASS

PENDING

FAIL

| # Get Customer Document Images Once a customer is registered with the document storage system you can get their status and other details stored in the system including their document images by making this API call. ## getDocumentImages `POST` `https://dcams.app/v3/stable/api/storage` This endpoint allows you to get the status of a customer account already registered in the system including their document images. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------ | | user\* | string | Your Veratad API Username | | pass\* | string | Your Veratad API Password | | service\* | string | The service name "getDocumentImages" | | target | object | The target of the query | | email | string | The user's email address for status lookup | {% tabs %} {% tab title="200 The customer was found" %} ```javascript { "result": "Success", "reference": "888888812", "status": "PASS", "target": { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19700101", "email": "test@veratad.com", "phone": "2015106000" "documents": { "front": "base64 encoded string of image", "back": "base64 encoded string of image" } } } ``` {% endtab %} {% tab title="400 The email was not a valid email address" %} ```javascript { "result": "Error", "message": "The email address is invalid" } //or { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Either a bad username or password" %} ```javascript { "result": "Error", "message": "Either your username or password is incorrect" } ``` {% endtab %} {% tab title="404 The customer was not found" %} ```javascript { "result": "Error", "message": "The email address was not found" } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "getDocumentImages", "target": { "email": "test@veratad.com" } } ``` ## Response Fields {% hint style="info" %} The response will include all of the target attributes stored within the system for this user, including their document images, and the following varying fields. {% endhint %} | attribute | values | | --------- | --------------------------------------------------------------------------- | | result |

Success

Error

| | status |

PASS

PENDING

FAIL

| # Update Customer Status Once a customer is registered with the document storage system you can update their status stored in the system by making this API call. ## updateStatus `POST` `https://dcams.app/v3/stable/api/storage` This endpoint allows you to update the status of a customer account already registered in the system. #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------ | | user\* | string | Your Veratad API Username | | pass\* | string | Your Veratad API Password | | service\* | string | The service name "getStatus" | | target | object | The target of the query | | email | string | The user's email address for status lookup | | status | string | The status for update | {% tabs %} {% tab title="200 The customer was found" %} ```javascript { "result": "Success", "reference": "888888812", "target": { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19700101", "email": "test@veratad.com", "phone": "2015106000", "status": "PASS" } } ``` {% endtab %} {% tab title="400 The email was not a valid email address" %} ```javascript { "result": "Error", "message": "The email address is invalid" } //or { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Either a bad username or password" %} ```javascript { "result": "Error", "message": "Either your username or password is incorrect" } ``` {% endtab %} {% tab title="404 The customer was not found" %} ```javascript { "result": "Error", "message": "The email address was not found" } ``` {% endtab %} {% endtabs %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "updateStatus", "target": { "email": "test@veratad.com", "status": "PASS" } } ``` ## Request Fields | attribute | values | | --------- | --------------------------------------------------------------------------- | | status |

PASS

PENDING

FAIL

| ## Response Fields {% hint style="info" %} The response will include all of the target attributes stored within the system for this user and the following varying fields. {% endhint %} | attribute | values | | --------- | --------------------------------------------------------------------------- | | result |

Success

Error

| | status |

PASS

PENDING

FAIL

| # iFrame With this iFrame guide, we’ve tried to make it as easy as possible to get up and running with DCAMS. The iFrame is built to allow you to scan, review and store identity documents. ## What are the steps for getting set up? ### 1. Create Token In order for the document scan/upload process to work you must submit a token within the parameters of the `veratadModal`. ```javascript veratadModal = new veratad.modal({ token: "8dfe0180-5389-46d4-a28c-b74061d8e7c3", }); ``` To get a token you must make an API call with your Veratad username and password. See link below for more details. {% hint style="warning" %} Tokens are only valid for 6 hours. It is recommended that you get a new token on each iFrame build. {% endhint %} ### 2. Include CSS, JS and iFrame {% tabs %} {% tab title="CSS" %} ```markup ``` {% endtab %} {% tab title="JS" %} ``` ``` {% endtab %} {% tab title="iFrame" %} ``` ``` {% endtab %} {% endtabs %} ### 3. Set-up a Webhook URL Use the admin to set your endpoint, authentication and see IP addresses.. ## Full Example {% hint style="info" %} This example includes all parameters, functions and methods. {% endhint %} ```markup ``` ## Functions | Name | Description | | ------------------------ | --------------------------------------------------------------------------------------------- | | onOpen() | Triggers when the modal is first opened on the page or with the `open()` method | | onClose() | Triggers when the modal is closed by the user or with the `close()` method | | onSuccess() | The document was successfully scanned or successfully uploaded if DCAMS+ is not active | | onFailure() | The document failed the scan process or was not uploaded successfully if DCAMS+ is not active | | onEmail() | The user has requested that they get an email with a link to scan. | | onQr() | The user pushed the "done" button after QR scanning. | | onError() | A general processing error occurred during the scan or upload process. | | onErrorToken() | An invalid token was supplied | | onErrorPending() | The user's document is currently in a `PENDING` state and they cannot submit a new document | | onErrorAlreadyVerified() | The user is in a `PASS` state already | | onErrorVelocity() | The user has already processed 3 attempts within a 24 hour period | ## Methods | Name | Description | | --------- | ----------------------------------------------------------------- | | open() | Open the modal. i.e. `veratadModal.open();` | | close() | Close the modal i.e. `veratadModal.close();` | | destroy() | Destroy the modal and all variables i.e. `veratadModal.destroy()` | ## Parameters | Parameter | Required | Type | Description | | ---------------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | fn | required | string | The customer's first name | | ln | required | string | The customer's last name | | addr | optional | string | The customer's street address | | city | optional | string | The customer's city | | state | optional | string | The customer's state | | zip | optional | string | The customer's zip code | | dob | optional | string |

The customer's Date of Birth

(YYYYMMDD format)

| | email | required | string | The customer's email address | | phone | optional | string | 10 digits no chars | | reference | optional | string | An arbitrary value that will be returned with the callback | | token | required | string | The token for the iFrame session | | styleToken | optional | string | You can create a style ID in the admin dashboard. Once created enter the value in this parameter to customize the iFrame style. | | desktopToMobileHandoff | optional | object |

There are two boolean values:

isActive which will make the QR code the first thing a user sees on Desktop.

continueIsAnOption if set to true then the user will have the option to bypass the QR and continue on desktop

Both are false by default

| | additionalData | optional | object | Any additional data you would like sent back with the callback POST. This can be set with any key => value pairs. | | resultMessages | optional | object | See `resultMessages` section below for more explanation. | | language | optional | string |

If no language is specified then the system will default to English. All languages from the Google Translate API are supported. Click here to view.

The value should be the ISO-639-1 Code.

| ### resultMessages These are the messages displayed to the end user in the iFrame. {% hint style="info" %} **NOTE:** If you do not want the user to be messaged in the iFrame you can simply run the `veratadModal.close()` after one of the function callbacks. That said, If you do not customize these messages then your users that get an email link sent to them will see the defaults on the page. {% endhint %} {% tabs %} {% tab title="Success" %} **The user has passed verification or successfully uploaded if DCAMS+ is not active, but storage is active.** | parameter | default message | | --------------------------- | ---------------------------- | | verificationSuccessTitle | Verification Success | | verificationSuccessSubTitle | You have passed verification | | {% endtab %} | | {% tab title="Failure" %} **The user did not PASS DCAMS+ verification or the image was not uploaded.** | parameter | default message | | --------------------------- | -------------------------------------- | | verificationFailureTitle | Verification Failed | | verificationFailureSubTitle | Your document is pending manual review | | {% endtab %} | | {% tab title="Error" %} **Something went wrong and no verification was processed. There are 4 error states:** 1. **Token** - the token provided in the iFrame is not valid 2. **Already Verified** - the user (based on email) has already `PASSED` verification 3. **Pending** - the user (based on email) is currently in a `PENDING` state of verification 4. **Velocity** - The user has exceeded the `velocity_threshold` | parameter | default message | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | verificationErrorTokenTitle | Bad or Expired Token | | verificationErrorTokenSubTitle | This document scan instance is using a bad or expired token. Please contact customer service. | | verificationErrorAlreadyVerifiedTitle | You Are Already Verified | | verificationErrorAlreadyVerifiedSubTitle | You have already passed this process and are not able to upload a new document at this time. Please call Customer Service. | | verificationErrorPendingTitle | Your Document is Currently Pending Manual Review | | verificationErrorPendingSubTitle | Your document is currently pending manual review and you may not provide another document at this time. Please call Customer Service. | | verificationErrorVelocityTitle | Too Many Attempts | | verificationErrorVelocitySubTitle | You have exceeded the amount of verification attempts. Please call Customer Service. | | {% endtab %} | | | {% endtabs %} | | ## Webhook Once a customer's status changes then the webhook will be invoked. The `email additional_data` or `reference` values can be used to associate the journey on Veratad's side to a customer/order on your side. {% hint style="danger" %} You should always use the backend webhook POST to get the official status of the customer/order. The frontend callback in the JS should only be used to message and route your customer on the frontend. {% endhint %} ### Example ```javascript POST {The URL you setup} ``` #### Body ```javascript { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19880521", "email": "test@veratad.com", "reference": "12345-test", "status": "PENDING", "additionalData": { "value_1": "test1", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808-0000", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN }, "confirmation": 92480850, "action": "REVIEW", "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"], "detail": "TRANSACTION REQUIRES FURTHER ATTENTION" }, "storage": { "success": false } } ``` #### Body (When Image Return is Active) There is a setting when a company is not using the Veratad storage system to have the document images returned via the callback. If this setting is active then the callback body will be as follows. ```javascript { "fn": "John", "ln": "Smith", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19880521", "email": "test@veratad.com", "reference": "12345-test", "status": "PENDING", "additionalData": { "value_1": "test1", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "LOUISA", "LastName": "SAMPLE", "MiddleName": "ANNA", "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000", "Address": "109 S FOSTER RD", "City": "BATON ROUGE", "State": "LA", "Zip": "70808-0000", "DateOfBirth": "19720629", "Height": "5-08", "Sex": "F", "EyeColor": "BRN", "DocumentNumber": "003009381", "IssueDate": "20140714", "ExpirationDate": "20300629", "CountryCode": "USA", // (ISO Alpha 2 or 3) "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN }, "confirmation": 92480850, "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"], "detail": "TRANSACTION REQUIRES FURTHER ATTENTION" }, "storage": { "success": false }, "documents": { "front": "BASE 64 Encoded Image String", "back": "BASE 64 Encoded Image String" } } ``` #### Possible Status Values | status | description | | ------- | ------------------------------------ | | PASS | The document has passed verification | | PENDING | The document is under manual review | | FAIL | The document has failed verification | # Canned Responses The iFrame allows you to get a canned response when using the below last name values in your iFrame build. {% hint style="warning" %} **NOTE:** This will only work if your site has testing\_mode active. Talk to your Veratad representative about activating this feature. {% endhint %} {% hint style="info" %} If you do not send one of the below last name values then the frame will treat the transaction as if it were live. {% endhint %} ## Available Cases Here is an example with one of the canned response last names: ```javascript $(function(){ veratadModal = new veratad.modal({ region: "United States", region_select: true, fn: "John", ln: "dcamspluspass", // set the last name to one of the value below. addr: "123 Main St", city: "Stratford", state: "CT", zip: "12345", dob: "19880212", email: "test51598@veratad.com", reference: "tery745f", token: token, }) }); ``` Here are the possible values and description: | Last Name | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dcamspluspass | This will result in a instant scan pass - no manual review | | dcamsplusfail | This will result in an instant scan failure - no manual review | | dcamsplusfailmanualpass | This will result in an instant scan failure, trigger manual review and manual review will PASS. The manual review response will be delayed by about 90 seconds. | | dcamsplusfailmanualfail | This will result in an instant scan failure, trigger manual review and manual review will FAIL The manual review response will be delayed by about 90 seconds. | | dcamspluspassselfiematch | This will result in an auto scan pass and a request for a selfie. Once selfie is submitted it will match and the transaction will PASS. | | dcamspluspassselfienomatch | This will result in an auto scan pass and a request for a selfie. Once selfie is submitted it will NOT match and the transaction will FAIL. | {% hint style="info" %} The cases for `dcamsplusfailmanualpass` and `dcamsplusfailmanualfail` will only work if you have Veratad manual review active. {% endhint %} # Create Token The Create Token process is designed to generate a unique token to be used in the frontend of the iFrame solution in order to identify your site and settings to Veratad. ## Create Token `POST` `https://dcams.app/v3/stable/token/create` This endpoint creates your token with associated settings to access a document iFrame session. #### Request Body | Name | Type | Required | Description | | ------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | user | string | true | Your Veratad API username | | pass | string | true | Your Veratad API Password | | age | string | true | The age you want to check.This needs to be sent with a "+" at the end like "21+". In that example you are checking that the user is 21 and above. | | rules | string | false | The DCAMS+ and DCAMS+Review data matching rules. See below for values. | | company\_name\_for\_email | string | false | Use this to change the company name that appears in the email sent to the customer. | | email\_logo\_link | string | false | Set a link to a logo image to be placed on the top of the email to the customer | | email\_logo\_height | string | false | Set the logo height in px | | email\_logo\_width | string | false | Set the logo width in px | | store\_on | string | false |

If DCAMS Storage is active in your account you can decide what DCAMS+ Scan result you want to store. Acceptable values are:

PASS
FAIL
ALL

If you do not specify this value the document will not be stored.

| | redirect\_uri | string | false | The URL that you would like a user returned to in a redirect or handoff flow. | {% tabs %} {% tab title="200 Token successfully created." %} ``` { "result": "Success", "message": "Token created successfully", "token": "393d50f9-2703-4100-9e4b-dfd8e4fda493", "age": "21+", "rules": "DCAMS5_0_RuleSet_NAME_DOB", "store_on": "FAIL", "company_name_for_email": "Company ABC", "email_logo_link": "https://yourcompany.com/logo.png", "email_logo_height": "50", "email_logo_width": "80", "dcams_manual_rules": "DCAMS5_0_Manual_Review_RuleSet_NAME_DOB", "redirect_uri": "https://example.com/return?req=123" } ``` {% endtab %} {% tab title="400 Missing a required input" %} ``` { "result": "Error", "message": "Missing a required input", "token": "" } { "result": "Error", "message": "Invalid age submitted. Must conform to age+ like 21+", "token": "" } { "result": "Error", "message": "Invalid ruleset submitted. Please check the documentation", "token": "" } { "result": "Error", "message": "Invalid store_on value. Must be PASS, FAIL or ALL", "token": "" } ``` {% endtab %} {% tab title="401 Username or password is incorrect." %} ``` { "result": "Error", "message": "Either your username or password is incorrect", "token": "" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **IMPORTANT:** The token is only good for 6 hours. It is recommended that you generate a new token on each iFrame request. {% endhint %} ## Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "age": "21+", "rules": "DCAMS5_0_RuleSet_NAME_DOB", "store_on": "FAIL", "company_name_for_email": "Company ABC", "email_logo_link": "https://yourcompany.com/logo.png", "email_logo_height": "50", "email_logo_width": "80", "dcams_manual_rules": "DCAMS5_0_Manual_Review_RuleSet_NAME_DOB", "redirect_uri": "https://example.com/return?req=123" } ``` ## DCAMS+ & DCAMS+REVIEW Matching Rules When processing a scan or a manual review you can define what elements from your customer parameters must match the information found on the document provided. {% hint style="info" %} **EXAMPLE** If you send `DCAMS5_0_RuleSet_NAME_DOB` this means that the Name and Date of Birth from your customer's parameters must match the Name and Date of Birth found on the document. {% endhint %} {% hint style="warning" %} If you leave this value empty then **NO** matching rules will be used. {% endhint %} Here are the available DCAMS+ rule sets: * DCAMS5\_0\_RuleSet\_NAME\_DOB * DCAMS5\_0\_RuleSet\_NAME * DCAMS5\_0\_RuleSet\_NAME\_ADDR * DCAMS5\_0\_RuleSet\_NAME\_STATE * DCAMS5\_0\_RuleSet\_NAME\_STATE\_DOB * DCAMS5\_0\_RuleSet\_NAME\_ADDR\_DOB Here are the available DCAMS+REVIEW rule sets: * DCAMS5\_0\_Manual\_Review\_RuleSet\_NAME\_DOB * DCAMS5\_0\_Manual\_Review\_RuleSet\_NAME # View Callback The View Callback method is designed for you to view your current callback without having to change the value. ## View Callback `POST` `https://dcams.app/v3/stable/callback/view` This endpoint allows you to view your current callback URL. #### Request Body | Name | Type | Description | | ---- | ------ | ------------------------- | | user | string | Your Veratad API Username | | pass | string | Your Veratad API Password | {% tabs %} {% tab title="200 Callback successfully retrieved." %} ```javascript { "result": "Success", "message": "Here is your current callback", "current_callback": "https://verataddev.com/callback" } ``` {% endtab %} {% tab title="400 Missing a required input" %} ``` { "result": "Error", "message": "Missing a required input", "callback": "" } ``` {% endtab %} {% tab title="401 You have supplied a bad username or password" %} ``` { "result": "Error", "message": "Either your username or password is incorrect", "current_callback": "" } ``` {% endtab %} {% endtabs %} ## Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD" } ``` # User Status This method allows you to fetch the user's status. ## Retrieve User Status `POST` `https://dcams.app/v3/stable/user/status` This endpoint allows you to get the status of the user. #### Request Body | Name | Type | Description | | ----- | ------ | ------------------------ | | user | string | Veratad API Username | | pass | string | Veratad API Password | | email | string | The user's email address | {% tabs %} {% tab title="200 User found" %} ```javascript { "fn": "TIM", "ln": "SMITH", "addr": "123 MAIN ST", "city": "STRATFORD", "state": "CT", "zip": "06614", "dob": "19870203", "email": "test15847@veratad.com", "reference": "12344", "status": "PENDING", "additionalData": { "value_1": "rangers", "value_2": "test2" }, "dcams_plus": { "document_data": { "FirstName": "STEVE", "LastName": "JONES", "MiddleName": "JIM", "Address": "123 MAIN ST", "City": "STRATFORD", "State": "CT", "Zip": "06614", "DateOfBirth": "19630203", "Height": "5-03", "Sex": "M", "EyeColor": "BRO", "DocumentNumber": "D485995948833", "IssueDate": "20190812", "ExpirationDate": "20230203" }, "confirmation": 93239228, "action": "PENDING", "detail": "MORE INFORMATION IS REQUIRED", "issues": [ "LAST NAME DOES NOT MATCH DOCUMENT", "DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT" ] }, "documents": null, "found": true } ``` {% endtab %} {% tab title="400 Missing a required input" %} ``` { "result": "Error", "message": "Missing a required input" } ``` {% endtab %} {% tab title="401 Bad login" %} ``` { "result": "Error", "message": "Either your username or password is incorrect", } ``` {% endtab %} {% tab title="404 User not found" %} ```javascript { "fn": null, "ln": null, "addr": null, "city": null, "state": null, "zip": null, "dob": null, "email": null, "reference": null, "status": null, "additionalData": false, "dcams_plus": { "document_data": false, "confirmation": 0, "action": null, "detail": null, "issues": false }, "documents": null, "found": false } ``` {% endtab %} {% endtabs %} #### Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "email": "test15847@veratad.com" } ``` {% hint style="info" %} **NOTE:** After 2 hours certain elements will be purged. This includes: * fn * ln * addr * city * state * zio * dob * dcams\_plus.document\_data This does not apply if you have storage active. {% endhint %} # Generate Link The iFrame has the capacity to handle an end-user through a direct link. Through this API call you can retrieve a link for a user or send the link in an email if desired. ## Generate Link `POST` `https://dcams.appv3/stable/link/generate` This endpoint allows you generate a direct link to an iFrame instance and send the user an email if desired. #### Request Body | Name | Type | Description | | ----------- | ------- | -------------------------------------------------------- | | options | object | The object where you place certain options | | send\_email | boolean | Set to true if you want the link to be sent via an email | {% tabs %} {% tab title="200 Link successfully generated" %} ```javascript { "action": "PASS", "detail": "Link Generated", "link": "https://frontend.dcams.app?request_id=c9c40f18-2c30-43ef-a879-5a82f1c4uf76", "email_sent": true, "error_message": "", "error_description": "" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} The other body parameters can be found in the iFrame instructions. All of the fields below are the same fields that you would set when creating an iFrame instance via the JS code. {% endhint %} ## Sample Request Body {% hint style="info" %} You must provide a valid token when making this API call. So, make sure you retrieve your token first and then set it here. {% endhint %} ```javascript { "additionalData": "{\"value_1\":\"test1\",\"value_2\":\"test2\"}", "addr": "123 Main Street", "city": "Stratford", "dob": "19880621", "email": "test@veratad.com", "language": "es", "fn": "Steve", "ln": "Smith", "reference": "12345-test", "international": "false", "state": "CT", "styleToken": "", "token": "e55da960-29cd-4f6c-8546-239f0c9a5456", "verificationErrorAlreadyVerifiedSubTitle": "", "verificationErrorAlreadyVerifiedTitle": "", "verificationErrorPendingSubTitle": "", "verificationErrorPendingTitle": "", "verificationErrorTokenSubTitle": "", "verificationErrorTokenTitle": "", "verificationErrorVelocitySubTitle": "", "verificationErrorVelocityTitle": "", "verificationFailureSubTitle": "", "verificationFailureTitle": "", "verificationSuccessSubTitle": "", "verificationSuccessTitle": "", "zip": "06614", "options": { "send_email": true } } ``` ## Responses | Description | Value | | ------------------ | ------------------------------------------------------------------------------------------------------------ | | action |

PASS - the link was generated

ERROR - the link was not generated (see below for all error types

| | detail | A description of the action result | | link | The URL value to provide the end user | | email\_sent | Will be set to true or false | | error\_message | The overall error message | | error\_description | A description of the error that occurred | # Swift SDK This SDK is for use with Veratad identity document and biometric verification processes on iOS and iPadOS. (macOS support coming soon) ## Introduction In order to use this SDK, you will need a valid set of credentials. If you are already a Veratad customer, please contact your account manager to get started. ## Minimum Requirements ### Operating System Requirements: * iOS 13.5 or later * iPadOS 13.5 or later * macOS 15.5 coming soon ### IDE Requirements: * Xcode 11 or later ## Features ### Verify Identity Documents in an Instant Companies that do business online need a way to protect themselves from fraud, liability and regulatory penalties. And while data validation and other methods are often effective, sometimes they’re not enough. Veratad’s **D-CAMS℠ and D-CAMS+℠ solutions** let you capture, manage and verify identity documents in seconds, with or without human intervention. ### Robust ID Document Verification For businesses that require higher confidence levels or flexibility, Veratad’s document verification solutions provide secure and cost-effective document reads in an instant. Customers easily upload pictures of their relevant documents as part of your app's onboarding flow. The images are uploaded to a secure portal where they can be reviewed and stored to maintain an audit trail for compliance purposes. ### Reduce Rejected Transactions Sometimes you can’t verify a valid customer’s identity with a traditional database. Veratad’s document capture provides a more robust method to verify customers that fail against other methods. This enables you to onboard more customers and reject fewer legitimate transactions. ### Automated Document Validation Manual document review drives up costs. Veratad’s automated document verification solutions verify document validity and subject identity in an instant. They also minimize the amount of manual intervention. This speeds up transactions, mitigates costs and provides a seamless user experience. ## Implementation 1. Import *Veratad SDK for Swift* as a Swift Package Dependency from within Xcode. This will make available a library named *VeratadSwiftSDK*. 2. *Veratad SDK for Swift* requires an additional plist file to be added to your bundle named Veratad.plist (case-sensitive). This file is used to store your Veratad credentials (user and password) as well as your sandbox or production preferences. | Key | Value | | ----------- | ---------------------------------------------- | | user | Veratad Username | | pass | Veratad Password | | environment | "sandbox" or "production" (no quotation marks) | 1. Create a SwiftUI View similar to this example: > **import** SwiftUI **import** VeratadSwiftSDK ... **struct** ContentView: View {     **var** veratad = VeratadSdk(displayName: "My Bank", journey: .frontBackSelfie)     **var** body: **some** View {             VStack(alignment: .center, spacing: 30) {                     Spacer()                     **self**.veratad.veratadButton()                     Spacer()             }     } ... } 2. That's it! ## Change Log ### Version 1.0 * Initial release of Veratad SDK for Swift ## License The license granted to each *Veratad SDK for Swift* customer allows the user to install the SDK on a development computer and use the SDK for development of an end user application, by integrating certain Veratad redistributable libraries and files into the end user application using the SDK sample code and documentation. The basic rules for the development licenses are as follows: * **License Needed for Each Application Developed.** A copy of *Veratad SDK for Swift* must be licensed for each application that is developed. For example, if three (3) separate applications are developed, three (3) *Veratad SDK for Swift* Development Licenses need to be purchased. (Discounts are available for additional development licenses.) * **End User Applications Only.** *Veratad SDK for Swift* may only be used to develop an "end user" application. An end user application is an application for business or personal use that may not be copied or redistributed by the user or used to develop software. *Veratad SDK for Swift* may not be used in a developer oriented product, such as a development toolkit or a product that contains an API. If a customer wishes to use *Veratad SDK for Swift* in connection with the development of an application that is not an "end user" application, the customer may be able to obtain a customized license from Veratad. # Android SDK This SDK is for use with Veratad identity document and biometric verification processes on Android. In order to use this SDK, you will need a valid set of credentials. If you are already a Veratad customer, please contact your account manager to get started. ## Minimum Requirements ### Operating System Requirements: * Android 9 or later (API Level 28) * Make sure your app has migrated to AndroidX ## Features ### Verify Identity Documents in an Instant Companies that do business online need a way to protect themselves from fraud, liability and regulatory penalties. And while data validation and other methods are often effective, sometimes they’re not enough. Veratad’s **D-CAMS℠ and D-CAMS+℠ solutions** let you capture, manage and verify identity documents in seconds, with or without human intervention. ### Robust ID Document Verification For businesses that require higher confidence levels or flexibility, Veratad’s document verification solutions provide secure and cost-effective document reads in an instant. Customers easily upload pictures of their relevant documents as part of your app's onboarding flow. The images are uploaded to a secure portal where they can be reviewed and stored to maintain an audit trail for compliance purposes. ### Reduce Rejected Transactions Sometimes you can’t verify a valid customer’s identity with a traditional database. Veratad’s document capture provides a more robust method to verify customers that fail against other methods. This enables you to onboard more customers and reject fewer legitimate transactions. ### Automated Document Validation Manual document review drives up costs. Veratad’s automated document verification solutions verify document validity and subject identity in an instant. They also minimize the amount of manual intervention. This speeds up transactions, mitigates costs and provides a seamless user experience. ## Implementation 1. Request access to the SDK from your account manager. In order to gain access, you will need a GitHub Account. 2. Add *Veratad SDK for Android* as a Package Dependency within your root build.gradle file. This will make available a library named *VeratadAndroidSDK*. > dependencies {      implementation 'com.veratad.android-sdk:native-ui:1.0.0' } 1. *Veratad SDK for Android* requires the following permissions to be included in AndroidManifest.xml > 1. Create a resource file for your secrets called res/values/veratadkeys.xml with a string pair per secret value, and ensure that this file is carefully managed within your project source control using .gitignore or similar > \ YOUR\_VERATAD\_USER\_CREDENTIAL YOUR\_VERATAD\_PASSWORD 1. From within your code, make a verification request with the specified journey. This will present the UI and provide you with an activity. > public void onVeratadSubmit(View v) {      VeratadRequest veratadRequest = new VeratadRequest()          .journey(VeratadDCAMSPlusJourney.FRONT\_BACK\_SELFIE);      startActivityForResult(veratadRequest.getIntent(this), REQUEST\_CODE); } 1. Listen for a response from the SDK by overriding onActivityResult: > @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {      if (requestCode == REQUEST\_CODE) {          if (resultCode == RESULT\_OK) {          VeratadResult res = data.getParcelableExtra(VeratadResult.EXTRA\_RESULT);          } else if (resultCode == RESULT\_CANCELED) { > >          } else {            Exception error = data.getSerializableExtra(VeratadActivity.EXTRA\_ERROR);          }      } } ## Change Log ### Version 1.0 * Initial release of Veratad SDK for Android ## License The license granted to each *Veratad SDK for Android* customer allows the user to install the SDK on a development computer and use the SDK for development of an end user application, by integrating certain Veratad redistributable libraries and files into the end user application using the SDK sample code and documentation. The basic rules for the development licenses are as follows: * **License Needed for Each Application Developed.** A copy of *Veratad SDK for Android* must be licensed for each application that is developed. For example, if three (3) separate applications are developed, three (3) *Veratad SDK for Android* Development Licenses need to be purchased. (Discounts are available for additional development licenses.) * **End User Applications Only.** *Veratad SDK for Android* may only be used to develop an "end user" application. An end user application is an application for business or personal use that may not be copied or redistributed by the user or used to develop software. *Veratad SDK for Android* may not be used in a developer oriented product, such as a development toolkit or a product that contains an API. If a customer wishes to use *Veratad SDK for Android* in connection with the development of an application that is not an "end user" application, the customer may be able to obtain a customized license from Veratad. # Overview The Bouncer is an advanced ML-powered solution developed by Veratad for secure and efficient transaction data management. It enables the storage of transaction input data for a defined period, allowing this data to be checked against any incoming transaction. When used as an add-on, Bouncer automatically stores incoming transaction details, simultaneously cross-checks them against existing records, and applies customizable rules. These rules include velocity limits—such as restricting a certain number of transactions per customer within a specific timeframe—tracking previously verified customers, and managing customer Knowledge-Based Authentication (KBA) interactions. ## Key Features ### Velocity Rules Set thresholds to flag or block transactions if the number of attempts exceeds a predefined limit within a certain time window. For example, you can limit a customer to three attempts in 24 hours. ### Historical Success Will track if a customer has been involved in a PASS transaction event within a certain timeframe. For example, you can limit a customer to one PASS within 365 days. ### KBA Question Management When paired with a KBA service, Bouncer tracks which questions have been asked and ensures users do not see repeat questions within the defined time span. It will also track and limit the amount fo quizzes returned per customer within a timeframe. ### Rule-Based Flexibility You can define and apply multiple rules simultaneously, whether they relate to velocity checks, repeat verifications within a certain period, or KBA quiz limits. ## Use Cases ### Fraud Prevention By applying velocity checks and rules around repeated transactions, Bouncer helps identify fraudulent attempts before they escalate. ### KBA Optimization Track the KBA questions asked to a user over time to avoid repetition, thereby maintaining the integrity and effectiveness of your KBA process. ## Conclusion Bouncer offers a powerful, machine learning-driven approach to storing, analyzing, and applying rules to transaction data. By integrating with your existing verification processes, it provides real-time risk assessment, improved user experiences, and peace of mind around data privacy. Whether you need to limit high-velocity fraud attempts or optimize KBA experiences, Bouncer delivers an adaptable, secure, and intelligent solution. # Bouncer as an add-on Bouncer it excels when added to your existing verification services. By doing so, all incoming transaction data is automatically captured and evaluated against the stored dataset, allowing you to run a variety of rules in real time. ## Request To invoke Bouncer as an add-on, append `.Bouncer` to the end of the service name in your request: ```json { "user": "username", "pass": "password", "service": "IDMatch5.0.Bouncer", "target": { // PII or transaction-related parameters } } ``` ## Response When bouncer is activated your request and response structure remain the same. You will just see new details that appear when a rule is triggered. See below. ```json { "meta": { "confirmation": 71483084, "reference": "12345", "service": "IDMatch5.0.Bouncer", "timestamp": "2024-10-17 14:29:48", "company": "Company, LLC", "user": "ws@company.com" }, "result": { "action": "FAIL", "detail": "TARGET ALREADY VERIFIED", "issues": [] } } ``` ## Actions and Details | Action | Detail | Explanation | | ------ | -------------------------------- | --------------------------------------------------------- | | FAIL | TARGET ALREADY VERIFIED | The user has been marked as verified and cannot proceed. | | FAIL | TARGET ATTEMPTS EXCEED THE LIMIT | The user has exceeded the permissible number of attempts. | | FAIL | TOO MANY QUIZZES | The user has attempted more quizzes than allowed. | | FAIL | QUIZ CANNOT BE GENERATED | The system could not produce a new quiz for the user. | ## Default Rules All rules are customizable, please discuss with your Veratad professional services team member, but by default the following are put into place. * Velocity: A customer can run 3 transactions within 24 hours * Already Verified: A customer can have 1 `PASS`event within 365 days * KBA: A customer can only see a question one time in 365 days * KBA: A customer can only have 2 quizzes in 365 days # Overview In today's increasingly interconnected and digital ecosystem, businesses struggle to maintain accurate, unified customer profiles while simultaneously ensuring data privacy. Traditional identification methods like Personal Identification Information (PII) are no longer viable due to the potential risks they pose in terms of security and duplication. Enter V-PIN, the Veratad-Personal Identification Number, a revolutionary identification platform powered by cutting-edge AI and machine learning technologies. ## The Problem with Traditional Methods Businesses often collect and store large amounts of customer data, but lack a reliable way to maintain unique customer profiles. This causes a slew of problems, including: * **Data Duplication**: Multiple entries for the same customer clutter databases and make analytics unreliable. * **Data Privacy**: Sharing data between partners or even different departments within an organization can expose sensitive information. * **Fraud Risks**: Duplicated or false profiles open doors for various types of fraudulent activities. ## What is V-PIN? V-PIN is a sophisticated identification platform that solves these challenges by generating a unique ID for every individual customer. By leveraging AI and machine learning algorithms, V-PIN analyzes a wide range of inputs from various data sources, creating a singular, identity for each user. The platform uses: * **Machine Learning Technologies:** Highly trained models that detect matches even with reduced data entry and slight discrepancies. * **Proprietary Matching Platform**: Our own state-of-the-art matching algorithm to correlate data points from different sources. * **Trusted Data Sources**: Integration with verified databases enriches the data, providing a more comprehensive profile of the individual. ## Key Features ### Interoperability The generated V-PIN can be used across departments or even with external partners without risking data privacy, making data sharing seamless and secure. ### Data Enrichment By pulling in data from trusted, verified sources, V-PIN enriches the customer profile with accurate information, adding layers of context that businesses can use for analytics and decision-making. ### Unparalleled Security Instead of storing sensitive PII, V-PIN produces a unique ID that represents the customer, significantly reducing the risk of data exposure. ### Anti-Fraud Capabilities A unique V-PIN for each customer makes it easier to identify fraudulent activities by flagging inconsistent or duplicate profiles. ## Use Cases ### Partner Communication Businesses can share V-PINs with partners or vendors to discuss customer preferences, behavior, or issues without exposing sensitive data. ### Marketing Analytics With a unique V-PIN, businesses can track customer interactions across platforms, enabling more accurate and personalized marketing strategies. ### Fraud Prevention By analyzing behaviors associated with V-PINs, businesses can more easily flag unusual activities, aiding in the early detection of fraud. ## Conclusion V-PIN represents a paradigm shift in the way businesses handle customer identification. With its unique combination of AI, machine learning, and trusted data sources, it not only ensures that every customer has a unique, secure identity, but it also brings a new level of sophistication to analytics, partnership collaboration, and fraud prevention. By adopting V-PIN, businesses can enter a new era of data management, enhancing their capabilities while maintaining the highest standards of data privacy and security. # V-PIN as an add-on The Veratad V-PIN (Veratad Personal Identification Number) is a unique identifier assigned to each individual for reliable tracking. This service generates a unique, immutable V-PIN for every individual, creating a consistent reference point irrespective of changes in other personal details. #### Request To get a V-PIN returned just add `.VPIN` to the end of the service name in your request. 
{
    "user": "username",
    "pass": "password",
    "service": "IDMatch5.0.VPIN",
    "target": {
        // PII Params
    }    
}
#### Example Output When V-PIN is active as an add-on to a verification service you will recieve an additional block on response called `output` which will containt the `vpin` block and `uuid.` ```json "output": { "vpin": { "uuid": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce" } } ``` #### Full Example Response Body This is what the output block will look like when being returned as an add-on to a verification service transaction. ```json { "meta": { "confirmation": 158032933, "timestamp": "2023-09-01 11:34:35", "reference": "", "user": "user@veratad.com", "company": "Veratad Technologies, LLC", "service": "PhoneMatch5.0.VPIN" }, "output": { "vpin": { "uuid": "15ebd7a0-4r5c-4d4b-b2a5-54b5a24becce" } }, "result": { "action": "REVIEW", "detail": "TRANSACTION REQUIRES FURTHER ATTENTION", "issues": [ "PHONE CHECK FAILED", "ADDRESS CHECK FAILED" ] } } ``` {% hint style="info" %} The V-PIN serves as a unique identifier for each individual in our system. However, it's crucial to understand that the presence of a V-PIN does not automatically imply that the user has been verified. The V-PIN is solely used for tracking and identification purposes, and it is not an endorsement or confirmation of the user's validity or identity.You must still examine the service result to determine whether or not the user is verified. {% endhint %} {% hint style="warning" %} Please be aware that in some instances, the V-PIN may be empty. {% endhint %} In an empty case the result will look like the below ```json "output": { "vpin": {} } ``` # V-PIN Stand Alone ## VPINMatch5.0 `POST` `https://production.idresponse.com/process/comprehensive/gateway` Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and i**ssues object.** #### Request Body | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------ | | user\* | string | Your account's API username | | pass\* | string | Your account's API password | | service\* | string | The service name (VPINMatch5.0) | | reference | string | A unique identifier for your customer | | target\* | object | The individual being sent for verification | | fn\* | string | The target's first name | | ln\* | object | The target's last name | | addr\* | string | The target's street address (line 1 and line 2) | | city | string | the target's city | | state | string | The target's state | | zip\* | string | The target's zip | | dob\* | string | The target's Date of Birth (YYYYMMDD format) | | ssn | string | The target's SSN (either 4 or 9) | | phone | string | The target's phone number | | email | string | The target's email address | | age | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) | | test\_key | string | The test key value that you are using to test | {% tabs %} {% tab title="200 Transaction processed and result returned" %} ```javascript { "meta": { "confirmation": 160393597, "timestamp": "2023-11-08 11:26:55", "reference": "", "user": "user@veratad.com", "company": "Veratad Technologies, LLC", "service": "IDMatch5.0.VPIN" }, "output": { "vpin": { "uuid": "5c13f55e-f438-47c1-9b2c-ffa10fe4464e" } }, "result": { "action": "INFO", "detail": "NOT A VERIFICATION", "issues": [] } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Use the test\_key attribute to test the service. When the test\_key is provided the system will use the dummy data provider and return a VPIN value. {% endhint %} ## Sample Request Body ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "VPINMatch5.0", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "test_key": "general_identity" } } ``` ## Action and Detail Responses {% hint style="info" %} The following are all values that will be returned in the result object of the response. {% endhint %} | Action | Detail | Description | | ------ | --------------------------- | ------------------------------------------------ | | INFO | NOT A VERIFICATION | The trasnaction haas returned with INFO | | FAIL | NO MATCH | There is no person matching the entered details. | | FAIL | MULTIPLE VPIN MATCHES FOUND | We are finding an ambiguous result. | # V-PIN Webhook Receive notifications when Veratad merges, splits, or retires V-PINs and learn how to verify webhook signatures. ## Status {% hint style="warning" %} **Early Access:** This is an early version for select partners. Interfaces and payloads may change, and we will work with partners on updates. Contact support to request access. {% endhint %} ## Purpose Notify customers when Veratad determines that multiple V-PINs refer to the same individual and consolidates them into a single canonical V-PIN, when an issued V-PIN must be split because it was assigned to multiple distinct people, or when a V-PIN is retired after being linked to fraudulent activity. *** ## High-Level Overview When a client is returned a V-PIN in any request across all Veratad services, that V-PIN is automatically added to a monitor for that client. If future intelligence indicates that multiple V-PINs actually represent the same person, Veratad will merge them and publish a `vpin.merged` webhook event to subscribed endpoints. If we later discover that a single V-PIN was used for more than one individual, Veratad will split it into distinct V-PINs and emit a `vpin.split` event that lists the replacements. If a V-PIN is determined to be synthetic or tied to a fake identity, Veratad will retire it and emit a `vpin.retired` event. Customers should treat the canonical V-PIN as the ongoing identifier and migrate all references from the superseded V-PIN(s) to the canonical V-PIN. Retired V-PINs should be purged from systems and not used in future transactions. *** ## Event Model ### Event Types * `vpin.merged` — Sent when one or more V-PINs are merged into a canonical V-PIN. * `vpin.split` — Sent when a V-PIN is split into multiple replacement V-PINs. * `vpin.retired` — Sent when a V-PIN is permanently retired due to confirmed or suspected fraud. * `vpin.merge.reverted` — Sent if a prior merge is undone. * `vpin.retire.reverted` — Sent if a previously retired V-PIN is reinstated. `vpin.merged` is required for monitoring. Other events, including `vpin.split` and `vpin.retired`, are opt‑in. ### Event Envelope All webhook deliveries share a standard envelope for parsing and idempotency. ```json { "id": "evt_01J6X9VQ8E2Q3RZ2KQYH3F7W2B", "type": "vpin.merged", "version": "2025-09-10", "created_at": "2025-09-10T14:22:31.840Z", "data": {}, "trace": { "correlation_id": "cor_3b6f6d7e-4a6d-4f7a-b60a-2f8e3fef1c9a", "source": "veratad.vpin.monitoring" } } ``` * `id` — Unique event id used for idempotency. * `version` — Semantic version/date of payload contract. * `trace.correlation_id` — Stable id for cross-system troubleshooting. *** ## `vpin.merged` — Payload Contract ```json { "canonical_vpin": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "superseded": [ { "vpin": "a1a1d7a0-1111-4d4b-b2a5-54b5a24be001", "first_seen_at": "2024-06-02T11:05:09Z", "last_used_at": "2025-08-29T17:21:04Z" }, { "vpin": "b2b2d7a0-2222-4d4b-b2a5-54b5a24be002", "first_seen_at": "2024-10-18T09:44:20Z", "last_used_at": "2025-09-01T12:10:33Z" } ], "effective_at": "2025-09-10T14:22:31Z", "reason": { "code": "NEW_DATA_AVAILABLE", "summary": "Trusted external source linked these identifiers", "signals": [ { "name": "external_data_source", "value": "verified_partner" }, { "name": "human_review", "value": true }, { "name": "ai_agent_review", "value": true } ] }, "actions": { "redirect_window_days": 90, "resolution_endpoint": "/v1/vpin/resolve/{vpin}", "replay_from": "2024-01-01T00:00:00Z" } } ``` * `canonical_vpin` — V-PIN that survives after the merge; use this going forward. * `superseded` — Array of V-PINs that should no longer be used. * `effective_at` — Timestamp from which the merge is authoritative. * `reason` — Machine and/or human justification. Common codes include `NEW_DATA_AVAILABLE`, `HUMAN_REVIEW`, and `AI_AGENT_REVIEW`. * `actions.redirect_window_days` — Period during which Veratad will auto-resolve superseded V-PINs. * `actions.resolution_endpoint` — Companion API to resolve any historical V-PIN to the canonical V-PIN. * `actions.replay_from` — Earliest recommended timestamp to re-key historical records, if needed. *** ## `vpin.split` — Payload Contract ```json { "source_vpin": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "replacements": [ { "vpin": "c3c3d7a0-3333-4d4b-b2a5-54b5a24be003", "first_seen_at": "2025-09-12T18:00:00Z", "links": [ { "name": "first_name", "value": "Jo***" }, { "name": "last_name", "value": "Sm***" }, { "name": "date_of_birth", "value": "1988-04-**" }, { "name": "verification_confirmation_number", "value": "VRFD-20240915-****" } ] }, { "vpin": "d4d4d7a0-4444-4d4b-b2a5-54b5a24be004", "first_seen_at": "2025-09-12T18:05:32Z", "links": [ { "name": "first_name", "value": "Ma***" }, { "name": "last_name", "value": "Le***" }, { "name": "date_of_birth", "value": "1991-11-**" }, { "name": "verification_confirmation_number", "value": "VPIN-20240801-****" } ] } ], "effective_at": "2025-09-12T18:10:00Z", "reason": { "code": "COLLISION_DETECTED", "summary": "Identity collision review determined the original V-PIN represented multiple people", "signals": [ { "name": "human_review", "value": true } ] }, "actions": { "resolution_endpoint": "/v1/vpin/resolve/{vpin}", "superseded_vpin_status": "retired" } } ``` * `source_vpin` — The V-PIN that previously represented more than one person. * `replacements` — Array of new V-PINs to use going forward. Metadata is masked to protect PII and help route each record to the correct subject. * `effective_at` — Timestamp from which the split mapping is authoritative. * `reason` — Machine and/or human justification for the split. Common codes include `COLLISION_DETECTED`, `HUMAN_REVIEW`, and `AI_AGENT_REVIEW`. * `actions.resolution_endpoint` — Use to resolve existing references to the correct replacement V-PIN. * `actions.superseded_vpin_status` — Expected disposition of the original V-PIN (for example, `retired`). *** ## `vpin.retired` — Payload Contract ```json { "vpin": "a1a1d7a0-1111-4d4b-b2a5-54b5a24be001", "retired_at": "2025-09-15T10:00:00Z", "reason": { "code": "HUMAN_REVIEW", "summary": "Manual review of external data flagged this V-PIN" } } ``` * `vpin` — V-PIN that has been retired and should no longer be used. * `retired_at` — Timestamp from which the retirement is authoritative. * `reason` — Machine and/or human justification for retirement. Examples: `HUMAN_REVIEW`, `AI_AGENT_REVIEW`, `EXTERNAL_DATA_CONFLICT`. *** ## Resolution API Resolve any V-PIN to its current canonical V-PIN or understand how to handle a split. `GET` `/v1/vpin/resolve/{vpin}` **Response 200** ```json { "input": "b2b2d7a0-2222-4d4b-b2a5-54b5a24be002", "canonical_vpin": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "superseded": true, "effective_at": "2025-09-10T14:22:31Z" } ``` **Response 404** ```json { "error": "VPIN_NOT_FOUND" } ``` **Response 409** (V-PIN was split) ```json { "input": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "split": true, "replacements": [ { "vpin": "c3c3d7a0-3333-4d4b-b2a5-54b5a24be003", "effective_at": "2025-09-12T18:10:00Z" }, { "vpin": "d4d4d7a0-4444-4d4b-b2a5-54b5a24be004", "effective_at": "2025-09-12T18:10:00Z" } ] } ``` *** ## Webhook Delivery Mechanics ### Registration Include your API token in the `Authorization` header when registering. `POST` `/v1/vpin/webhooks/subscriptions` **Headers** * `Authorization: Bearer {api_token}` **Request** ```json { "url": "https://api.yourcompany.com/veratad/webhooks", "event_types": ["vpin.merged", "vpin.retired"], "secret": "(one-time-generated secret)", "enabled": true } ``` **Response 201** ```json { "id": "whsub_01J6XA2C3Y7D4", "url": "https://api.yourcompany.com/veratad/webhooks", "event_types": ["vpin.merged", "vpin.retired"], "status": "active", "created_at": "2025-09-10T13:11:21Z" } ``` ### Security & Signing All webhook requests are signed with an HMAC SHA‑256 using your subscription secret. **Headers** * `X-Veratad-Signature` — Hex digest of HMAC SHA‑256 over body, using the subscription secret. * `X-Veratad-Timestamp` — Milliseconds since epoch when the signature was computed. * `X-Veratad-Event-Id` — Same as envelope id for idempotency. **Signature Base String** ``` {timestamp}.{raw_request_body} ``` Compute `HMAC_SHA256(secret, base_string)` and compare (constant‑time) to `X-Veratad-Signature`. **Replay Protection** Reject requests where `abs(now - X-Veratad-Timestamp) > 5 minutes`. #### Example: Verifying Signature {% tabs %} {% tab title="TypeScript" %} ```typescript import crypto from 'crypto'; export function verifyWebhook({ rawBody, timestamp, signature, secret, }: { rawBody: string; timestamp: string; signature: string; secret: string; }): void { const base = `${timestamp}.${rawBody}`; const expected = crypto .createHmac('sha256', secret) .update(base) .digest('hex'); const valid = crypto.timingSafeEqual( Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex') ); const age = Math.abs(Date.now() - Number(timestamp)); if (!valid || age > 5 * 60 * 1000) { throw new Error('Invalid signature'); } } ``` {% endtab %} {% tab title="Python" %} ```python import hashlib import hmac import time def verify_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> None: base = f"{timestamp}.{raw_body.decode('utf-8')}" expected = hmac.new(secret.encode(), base.encode(), hashlib.sha256).hexdigest() valid = hmac.compare_digest(signature, expected) age = abs(int(time.time() * 1000) - int(timestamp)) if not valid or age > 5 * 60 * 1000: raise ValueError('Invalid signature') ``` {% endtab %} {% endtabs %} ### Retries & Ordering * Retries: Up to five attempts with exponential backoff (1m, 5m, 15m, 60m, 120m). * Idempotency: Use `X-Veratad-Event-Id` to dedupe. We may deliver an event more than once. * Ordering: Best-effort in-order per subscription; do not rely on strict global ordering. ### Response Expectations Return 2xx to acknowledge receipt. Any non‑2xx will be treated as a failure and retried. *** ## Consumer Responsibilities 1. Verify signature on every request. 2. Deduplicate using the event id. 3. For `vpin.merged` events, migrate references from `superseded[].vpin` to `canonical_vpin`. 4. For `vpin.split` events, evaluate the `replacements[]` payload and re-key impacted records to the correct new V-PIN; archive or retire any lingering references to `source_vpin`. 5. Update caches and any identity graphs keyed by V-PIN. 6. Optionally re-key history from `actions.replay_from` if your use case requires. *** ## Change Management & Versioning * The envelope version and the `vpin` event payloads (e.g., `vpin.merged`, `vpin.split`, `vpin.retired`) may evolve. Backwards-compatible changes include new optional fields. * Breaking changes will increment the **MAJOR** version (e.g., `2026-01-01`) with 90 days’ notice. *** ## Examples ### Merge of Two V-PINs **Request (from Veratad to your webhook)** ```http POST /veratad/webhooks HTTP/1.1 Host: api.yourcompany.com Content-Type: application/json X-Veratad-Event-Id: evt_01J6X9VQ8E2Q3RZ2KQYH3F7W2B X-Veratad-Timestamp: 1757517751840 X-Veratad-Signature: 9e3b0c...d2 { "id": "evt_01J6X9VQ8E2Q3RZ2KQYH3F7W2B", "type": "vpin.merged", "version": "2025-09-10", "created_at": "2025-09-10T14:22:31.840Z", "data": { "canonical_vpin": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "superseded": [ { "vpin": "a1a1d7a0-1111-4d4b-b2a5-54b5a24be001" }, { "vpin": "b2b2d7a0-2222-4d4b-b2a5-54b5a24be002" } ], "effective_at": "2025-09-10T14:22:31Z", "reason": { "code": "NEW_DATA_AVAILABLE", "summary": "Trusted external data indicates these V-PINs refer to the same person" }, "actions": { "redirect_window_days": 90, "resolution_endpoint": "/v1/vpin/resolve/{vpin}" } }, "trace": { "correlation_id": "cor_3b6f6d7e-4a6d-4f7a-b60a-2f8e3fef1c9a", "source": "veratad.vpin.monitoring" } } ``` **Expected Handler Response** ```http HTTP/1.1 200 OK ``` ### Split of a Shared V-PIN **Request (from Veratad to your webhook)** ```http POST /veratad/webhooks HTTP/1.1 Host: api.yourcompany.com Content-Type: application/json X-Veratad-Event-Id: evt_01J6Y3M4N5P6Q7R8S9T0U1V2W3 X-Veratad-Timestamp: 1757691000000 X-Veratad-Signature: 8b7c1d...aa { "id": "evt_01J6Y3M4N5P6Q7R8S9T0U1V2W3", "type": "vpin.split", "version": "2025-09-10", "created_at": "2025-09-12T18:10:00.000Z", "data": { "source_vpin": "15ebd7a0-2b4e-4d4b-b2a5-54b5a24becce", "replacements": [ { "vpin": "c3c3d7a0-3333-4d4b-b2a5-54b5a24be003" }, { "vpin": "d4d4d7a0-4444-4d4b-b2a5-54b5a24be004" } ], "effective_at": "2025-09-12T18:10:00Z", "reason": { "code": "COLLISION_DETECTED", "summary": "Shared V-PIN was reassigned to two unique identities" } }, "trace": { "correlation_id": "cor_5c7a9b1d-2e3f-4a5b-8c9d-0e1f2a3b4c5d", "source": "veratad.vpin.monitoring" } } ``` **Expected Handler Response** ```http HTTP/1.1 200 OK ``` ### Retirement of a V-PIN **Request (from Veratad to your webhook)** ```http POST /veratad/webhooks HTTP/1.1 Host: api.yourcompany.com Content-Type: application/json X-Veratad-Event-Id: evt_01J6X9VQ8E2Q3RZ2KQYH3F7W2B X-Veratad-Timestamp: 1757517751840 X-Veratad-Signature: 9e3b0c...d2 { "id": "evt_01J6X9VQ8E2Q3RZ2KQYH3F7W2B", "type": "vpin.retired", "version": "2025-09-10", "created_at": "2025-09-15T10:00:00Z", "data": { "vpin": "a1a1d7a0-1111-4d4b-b2a5-54b5a24be001", "retired_at": "2025-09-15T10:00:00Z", "reason": { "code": "HUMAN_REVIEW", "summary": "Manual review of external data flagged this V-PIN" } }, "trace": { "correlation_id": "cor_3b6f6d7e-4a6d-4f7a-b60a-2f8e3fef1c9a", "source": "veratad.vpin.monitoring" } } ``` **Expected Handler Response** ```http HTTP/1.1 200 OK ``` *** ## Test & Sandbox Use these endpoints to validate your integration. * Send test event: `POST` `/v1/vpin/webhooks/subscriptions/{id}:test` with `{ "type": "vpin.merged" }`, `{ "type": "vpin.split" }`, or `{ "type": "vpin.retired" }` to receive a mock delivery. ```bash curl -X POST https://production.response.com/v1/vpin/webhooks/subscriptions/{id}:test \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{ "type": "vpin.split" }' ``` * Replay live event: `POST` `/v1/vpin/webhooks/events/{event_id}:replay` re-delivers a historical event to your endpoint (authorization required). ```bash curl -X POST https://production.response.com/v1/vpin/webhooks/events/{event_id}:replay \ -H "Authorization: Bearer {api_token}" ``` *** ## Changelog * `2025-09-10`: Early access release. # Data Coverage Below is a list of all international countries where a data check is available. Included with each is the percent of the adult population covered and the available and required fields. ![](/files/-MC7sZL8RIruhEpv23rS) {% hint style="info" %} If you are looking for a country that is not found below please contact us with your request. Sometimes countries are in the pipeline or have yet to make it to the documentation. {% endhint %} ## Countries Covered ### Albania Data sources cover 71% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | ----------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | recommended | | Phone | yes | no | ### Argentina Data sources cover 78% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Armenia Data sources cover 54% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Australia Data sources cover 81% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Austria Data sources cover 77% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Belarus Data sources cover 17% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Belgium Data sources cover 75% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Brazil Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Bulgaria Data sources cover 27% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Canada Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Canary Islands Data sources cover 60% of the adult population. Country Name for Service: CanaryIslands | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### China Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Czech Republic Data sources cover 55% of the adult population. Country Name for Service: CzechRepublic #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | International ID | no | no | | Phone | yes | no | ### Denmark Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Egypt Data sources cover 62% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | no | no | ### Finland Data sources cover 97% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### France Data sources cover 70% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Germany Data sources cover 70% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Greece Data sources cover 80% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Hong Kong Data sources cover 90% of the adult population. Country Name for Service: HongKong #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### India Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Indonesia Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Ireland Data sources cover 30% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Israel Data sources cover 67% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | ----------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | recommended | | Phone | yes | no | ### Italy Data sources cover 67% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Japan Data sources cover 50% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Jordan Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Kazakhstan Data sources cover 10% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Kuwait Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Latvia Data sources cover 92% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Lebanon Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | no | no | ### Luxembourg Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | International ID | no | no | | Phone | yes | no | ### Malaysia Data sources cover 75% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | -------------------------------- | --------- | -------- | | First Name | no | no | | Last Name (place full name here) | yes | yes | | Address | yes | no | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Mexico Data sources cover 75% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Moldova Data sources cover 93% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Netherlands Data sources cover 95% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### New Zealand Data sources cover 90% of the adult population. Country Name for Service: NewZealand #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Nigeria Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | yes | no | ### Norway Data sources cover 70% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Oman Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | International ID | yes | yes | | Phone | no | no | ### Palestine Auth. Area Data sources cover 76% of the adult population. Country Name for Service: Palestine #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Philippines Data sources cover 15% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | ----------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | recommended | | Phone | yes | no | ### Poland Data sources cover 50% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | no | no | ### Portugal Data sources cover 64% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Qatar Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | International ID | yes | yes | | Phone | no | no | ### Romania Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Russia Data sources cover 72% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Saudi Arabia Data sources cover 15% of the adult population. Country Name for Service: SaudiArabia #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | no | | Date of Birth | yes | yes | | International ID | yes | no | | Phone | no | no | ### Singapore Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Slovenia Data sources cover 23% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | International ID | no | no | | Phone | yes | no | ### South Africa Data sources cover 90% of the adult population. Country Name for Service: SouthAfrica #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Spain Data sources cover 60% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Sweden Data sources cover 80% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | ----------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | recommended | | Phone | yes | no | ### Switzerland Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### Thailand Data sources cover 100% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | no | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Turkey Data sources cover 90% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### Ukraine Data sources cover 76% of the adult population. #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### United Arab Emirates Data sources cover 60% of the adult population. Country Name for Service: UAE #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | yes | yes | | Phone | yes | no | ### United Kingdom Data sources cover 90% of the adult population. Country Name for Service: UK #### Required and Available Fields | Attribute | Available | Required | | ---------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | yes | | International ID | no | no | | Phone | yes | no | ### United States Data sources cover 95% of the adult population. | Attribute | Available | Required | | ------------------- | --------- | -------- | | First Name | yes | yes | | Last Name | yes | yes | | Address | yes | yes | | Date of Birth | yes | no | | SSN (last 4 digits) | yes | no | | SSN (full 9 digits) | yes | no | | Phone | yes | no | | Email | yes | no | # Test Cases The following are test cases for data matching services in the United States {% hint style="info" %} The cases below reveal the information in the test database for each associated test key. So, for example, if you send test key `general_identity` and change the targets first name from Barbara to Steve you will then get a `FAIL - NO MATCH` response. {% endhint %} #### General ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "VERATAD SERVICE NAME", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Barbara", "ln": "Miller", "addr": "123 Main St", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com", "age": "21+", "test_key": "general_identity" } } ``` {% hint style="info" %} If you are using a KBA service and need the answers to the `general_identity` questions please click the link below. {% endhint %} {% content-ref url="/pages/-MCNLykXQxzMAZRbV-Yc" %} [Answers to KBA Questions](/testing-1/answers-to-kba-questions) {% endcontent-ref %} #### Deceased ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "VERATAD SERVICE NAME", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Abraham", "ln": "Lincoln", "addr": "1600 Pennsylvania Ave NW", "city": "Washington", "state": "DC", "zip": "20500", "dob": "19820212", "age": "21+", "test_key": "deceased2" } } ``` #### Possible Minor ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "VERATAD SERVICE NAME", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Tim", "ln": "Hardaway", "addr": "5 Broadway", "city": "New York", "state": "NY", "zip": "10458", "dob": "19750614", "ssn": "123456897", "age": "21+", "test_key": "pos_minor" } } ``` #### Age Not Verified ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "VERATAD SERVICE NAME", "reference": "12345 {A UNIQUE ID}", "target":{ "fn":"Steve", "ln": "Jones", "addr": "PO Box 451", "city": "New York", "state": "NY", "zip": "10458", "dob": "19900215", "ssn": "232145987", "age": "21+", "test_key": "age_not_verified" } } ``` #### Name on Watch List ```javascript { "user": "USERNAME", "pass": "PASSWORD", "service": "IDMatchCOMPLY5.1", "reference": "12345", "target":{ "fn": "Osama", "ln": "Bin Laden", "addr": "123 Main St", "city": "Anytown", "state":"TX", "zip": "12345", "dob": "19700213", "ssn": "123456789", "test_key":"name_on_list" } } ``` # Answers to KBA Questions ## Barbara Miller (general\_identity) The following are all data points in the test database associated with the `general_identity` test case. To pass a quiz, use this data for reference to find the answers. If you do not see the data point the answer to the question is most likely "NONE OF THE ABOVE". ```json { "target": "general_identity", "identities": [{ "fn": "Barbara", "ln": "Miller", "addr": "123 Main ST", "city": "Stratford", "state": "CT", "zip": "06614", "dob": "19740821", "ssn": "854125698", "county": "fairfield", "phone": "2015106000", "email": "bmiller@veratad.com" }, { "fn": "Barbara", "ln": "Miller", "addr": "87 East Broadway Blvd", "city": "Green Bay", "state": "WI", "zip": "54155", "county": "bucks", "dob": "19740821", "ssn": "854125698", "phone": "2015106000", "email": "bmiller@veratad.com" }] } ``` # Reporting API endpoints to get IDR5 transaction details # Audit ## Overview The Veratad Audit API is designed to retrieve an audit trail of all transactions processed on a specific day. Please note that data for a particular day is available only on the next calendar day after 7 am EST. **Base URL**: `https://reporting.veratad.app` ## Authentication To authenticate, you'll need the `user` and `pass` for the audit trail you want to inquire about. *** ## Audit Trail Endpoint ### POST `/api/audit` Fetches an audit trail of transactions for a specified day. #### Request Parameters | Parameter | Type | Description | | --------- | ------ | ----------------- | | `user` | string | Your API username | | `pass` | string | Your API password | | `day` | string | Date (YYYY-MM-DD) | #### Request Example ```json { "user": "yourUsername", "pass": "yourPassword", "day": "YYYY-MM-DD" } ``` #### Response The response is a JSON object containing a data field, which is an array of transaction objects. #### Response Fields * data: An array of transaction objects * id: Transaction ID * timestamp: Timestamp of the transaction * service: Service utilized * reference: Reference code * user: User who initiated the transaction * company: Company name * origin: Origin IP * path: API path * flags: Flags (e.g., test, error) * action: Resulting action * detail: Additional details * issues: Any issues encountered (array) * inputs: Extra input fields ```json { "data": [ { "id": 157929511, "timestamp": "2023-09-09T23:59:54", // additional fields here }, // additional transactions here ] } ``` #### Error Handling The API could return various errors depending on the situation. Below are the types of errors and their corresponding JSON bodies and HTTP status codes: Bad Credentials - HTTP Status Code: 401 Unauthorized ```json { "error": "Unauthorized", "message": "Invalid username or password." } ``` Data Not Ready - HTTP Status Code: 404 Not Found ```json { "error": "Data Not Ready", "message": "Data for the requested day is not yet available." } ``` Day Not Available - HTTP Status Code: 404 Not Found ```json { "error": "Day Not Available", "message": "Data for the specified day is not available." } ``` Invalid Date Format - HTTP Status Code: 400 Bad Request ```json { "error": "Invalid Date Format", "message": "Date should be in YYYY-MM-DD format." } ``` Server Error - HTTP Status Code: 500 Internal Server Error ```json { "error": "Server Error", "message": "An internal server error occurred." } ``` # Error Returns The following are all error responses that can be returned via the API. {% hint style="danger" %} 400: Bad Request {% endhint %} #### No Query No payload provided in the body of the request. ```javascript { "meta": { "timestamp": "2019-10-21T13:02:48" }, "error": { "message": "No Query", "code": "IN0" } } ``` #### Query Not Parsable Input JSON not valid. ```javascript { "meta": { "timestamp": "2019-10-21T13:04:26" }, "error": { "message": "Query Not Parsable", "code": "IN1", "detail": "{the payload body}" } } ``` #### Bad Login Invalid username or password. ```javascript { "meta": { "timestamp": "2019-10-21T13:06:12" }, "error": { "message": "Bad Login", "code": "AUTH0" } } ``` #### No Target No target object provided in the body of the request. ```javascript { "meta": { "timestamp": "2019-10-21T13:17:30" }, "error": { "message": "No Target", "code": "QRY0", "detail": "This service requires a target to be specified." } } ``` #### Missing Required Input One or more of the required input attributes are missing or empty. ```javascript { "meta": { "timestamp": "2019-10-21T13:19:46" }, "error": { "message": "Missing Required Input", "code": "QRY1", "detail": "Service requires Address to be specified." } } ``` #### Input Failed Validation One or more of the input fields are not being sent as described. ```javascript { "meta": { "timestamp": "2019-10-21T13:21:08" }, "error": { "message": "Input Failed Validation", "code": "QRY2", "detail": "Age input must conform to (^[<>]=?[0-9]{1,3}$|^[0-9]{1,3}[+-]$|^[0-9]{1,3}-[0-9]{1,3}$)." } } ``` #### Token Bad or Expired The token you are sending for quiz scoring is either invalid or has expired. ```javascript { "meta": { "timestamp": "2019-10-23T11:36:49" }, "error": { "message": "Token Bad or Expired", "code": "QRY6", "detail": "1bauxkpczhdiyy3vqm15ais8ue12u7zw" } } ``` {% hint style="danger" %} 403: Forbidden {% endhint %} #### User Not Active The API user is not an active account. ```javascript { "meta": { "timestamp": "2019-10-21T13:15:24" }, "error": { "message": "User Not Active", "code": "AUTH3", "detail": "This user account (username) is not currently active." } } ``` {% hint style="danger" %} 404: Not Found {% endhint %} #### No Such Service Invalid or empty service name provided. ```javascript { "meta": { "timestamp": "2019-10-21T13:07:17" }, "error": { "message": "No Such Service", "code": "AUTH1", "detail": "Request service not found." } } ``` # Best Practices Below are some best practices when implementing the IDR5 API. ## What data should I send with each request? You must send the required fields and if you use an additional matching ruleset you must provide that element or the transaction will fail. That said, when searching for an individual in the data sources it is always more helpful to provide as much data as you collect. The more information we have on a person, the more people we will find. ## Does Veratad store the input request? No, Veratad does not store any sensitive PII information from your request. The only exception to this rule is when you use the document storage service. ## How should I use the reference field? Since Veratad does not store sensitive PII it is important for you to send a unique value in the reference field with each request. This will help for reporting and audit trail purposes. # Understanding Veratad Services ![](/files/-MCDXZslzxzd_pddV4Gm) ## What is a service? A Veratad service is defined by four attributes: * **The goal(s) of the service transaction** For example, the AgeMatch service goal is to discover the target's age, while the PhoneMatch service goal is to discover the target's phone number. With both services you can still verify other data points, but the main goal is as above. See the ***What if I have multiple goals*** section below for more details. * **The data sources to be accessed** For example, the AgeMatch service may have additional data sources that are age specific and only beneficial if you are trying to verify an individual's age. While the PhoneMatch service may have phone number specific data sources that are only useful when you are attempting to verify a phone number. * **The base evaluation rules** Each service has a distinct base rule set that will run on each transaction. That said, if you require something other than the base this is as simple as changing the `rules` attribute value in the query. For example, AgeMatch has a base rule set that consists of the following: ***target is found, is not deceased and meets the minimum age requirement***. But, if you want to ensure the Year of Birth always matches in order to receive a `PASS` you would just set the `rules` attribute to `AgeMatch5_0_RuleSet_YOB` . Most service descriptions include pre-made rule sets, but if you require a different rule set from what is documented please contact your Veratad Representative and they will configure and provide the name. * **The required inputs** For example, when you run AgeMatch you will never be allowed to process without setting the `age` attribute and with PhoneMatch you will never be able to process without the `phone` attribute. ## What if I have multiple goals? **Not a problem!** All Veratad services can be customized and coupled. So, for example, if your goal is to verify a user's age and their phone number Veratad will create a service that has these goals for your business. During this creation process Veratad will also ensure you are accessing the correct data sources to accomplish them efficiently. ## What if I want a different rule set? Not a problem! Rule sets can be customized and provided to you for any Veratad service. Using a custom rule set is as simple as including the custom rule set value in the `rules` attribute in your initial POST request. You can also have as many rule sets as you require, that way you can adjust the rules per transaction for the same service. # IDMax Button Creator SDK ## Overview The `IDMax Button Creator` is a JavaScript utility designed to dynamically generate and manage authentication buttons for various identity providers. It facilitates the integration of identity verification services, allowing customizable options for both appearance and behavior. ## Constructor Options | Option | Type | Description | Example | | ----------------- | ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------- | | **providers** | Array of strings | List of identity provider keys for which buttons will be created. See full list below. | `['clear', 'plaid', 'mdl_la']` | | **method** | String | Determines the method of interaction, such as modal popups. | `'popup' \|\| 'redirect'` | | **settings** | Object | Additional settings for providers, controlling UI elements. | See Settings Details Below | | **styles** | Object | CSS styles for buttons and modal overlays. | See Styles Details Below | | **onComplete** | Function | Callback when an operation completes successfully. | `(data) => console.log(data)` | | **onError** | Function | Callback invoked when an error occurs. | `(error) => console.error(error)` | | **onClose** | Function | Callback when a modal or a session is explicitly closed. | `() => console.log('Closed')` | | **onInit** | Function | Callback when a provider is initialized. | `(provider) => console.log(provider)` | | **targetElement** | HTMLElement | DOM element where the buttons should be rendered. | | ### Settings Details | Key | Sub-Key | Type | Description | Example | | ------------------------ | ------------- | ------- | -------------------------------------------------------------------------- | ------- | | **digital\_id\_connect** | showWorksWith | Boolean | Controls whether to display associated partners or additional UI elements. | `true` | ### Styles Details #### Buttons | Key | Type | Description | Example | | ---------- | ------ | --------------------------------------------------------------- | -------- | | **radius** | String | CSS value for border-radius of the buttons, must include units. | `'8px'` | | **gap** | String | Vertical gap between buttons, must include units. | `'10px'` | #### Modal **Overlay** | Key | Type | Description | Example | | --------------------- | ------- | ----------------------------------------------------------------- | -------- | | **color** | String | Background color of the modal overlay, accepts CSS color formats. | `'#000'` | | **backgroundOpacity** | Float | Opacity level of the modal overlay background, from 0.0 to 1.0. | `0.35` | | **blur** | Integer | Blur amount for the overlay, specified in pixels. | `1` | **Content** | Key | Type | Description | Example | | ---------------- | ------ | --------------------------------------------------------------------- | -------- | | **borderRadius** | String | CSS value for border-radius of the modal content, must include units. | `'10px'` | ## Provider Descriptions | Provider | Description | | ------------------------ | -------------------------------------------------------------------------------- | | **clear** | Provides identity verification services using CLEAR systems. | | **plaid** | Specializes in securely connecting financial accounts for identity verification. | | **mdl\_la** | State-specific ID verification using Louisiana's digital driver's licenses. | | **digital\_id\_connect** | General digital identity verification provider. | | **one\_id** | Provides banking-based identity verification services. | | **digilocker** | An Indian digital locker for securely storing and sharing personal documents. | ## Usage Examples ### React Integration ```jsx import React, { useEffect, useRef } from "react"; const IDMaxButtonContainer = () => { const containerRef = useRef(null); useEffect(() => { if (window.IDMax && window.IDMax.ButtonCreator) { new window.IDMax.ButtonCreator({ targetElement: containerRef.current, providers: ["clear", "plaid"], settings: { digital_id_connect: { showWorksWith: true, }, }, styles: { buttons: { radius: "10px", gap: "10px", }, modal: { overlay: { color: "#000", backgroundOpacity: 0.4, blur: 3, }, }, }, onInit: (provider) => console.log(`Provider initialized: ${provider}`), onComplete: (data) => console.log("Authentication successful:", data), onError: (error) => console.error("Error during authentication:", error), onClose: () => console.log("Modal closed"), }); } }, []); return
; }; export default IDMaxButtonContainer; ``` ### Vanilla JavaScript Integration ```html IDMax Integration Example
```