# Sandbox Testing Scenarios In our Public API sandbox environment, you can simulate different outcomes by including a specific `externalId` value in your request payload. Each value corresponds to a predefined response for various evaluation types. {% hint style="warning" %} Please note that the testing scenarios are for customer onboarding and evaluation requests. For other types of API requests, please check the [API Reference](https://docs.waldo.ai/api-reference) {% endhint %} ### How It Works 1. **Initial Request**: Send an API request to the sandbox endpoint, including one of the supported `externalId` values. 2. **Request Stage Response**: The sandbox returns an immediate HTTP response (the *request stage*) with initial metadata. 3. **Webhook Events**: If you have configured webhooks, the sandbox will dispatch up to three events in this order: * `initiated` * `in_progress` * `completed` ### Available Request Types & externalId Options | Request Type | Description | externalId values | | ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- | | `kyc` | Onboarding (KYC) | `kyc-pass`, `kyc-review` | | `fraud` | Onboarding with fraud check | `fraud-pass`, `fraud-review`, `fraud-reject` | | `expressKYC` | Onboarding with Express KYC | `expressKYC-pass`, `expressKYC-review`, `expressKYC-delay` | | `expressKYCFraud` | Onboarding with Express KYC + fraud check | `expressKYCFraud-pass`, `expressKYCFraud-review`, `expressKYCFraud-reject`, `expressKYCFraud-delay` | | `fraudCheck` | Standalone fraud evaluation | `fraudCheck-pass`, `fraudCheck-review`, `fraudCheck-reject` | | `documentUpload` | Standalone document evaluation | `documentUpload-pass`, `documentUpload-warn` | ### Common Request Payload All sandbox endpoints share a similar request structure. Below is a generic example for the `kyc` endpoint. Replace `externalId` with one of the supported values above, and adjust the `options` object as needed for other request types. {% hint style="info" %} The request type is not a parameter, but an onboarding method. Include `useExpressKYC` or `includeFraudCheck` in the payload options to apply the desired request type. Check the [API Reference](https://docs.waldo.ai/api-reference) to learn more. {% endhint %} ```json POST https://api.waldo.ai/onboard Content-Type: application/json { "firstName": "Cassian", "lastName": "Andor", "officialId": { "docType": "SSN", "value": "439-46-5491", "format": "XXX-XX-XXXX", "country": "US" }, "dob": "1982-03-14", "address": "10436 Donnelly Green", "city": "Coruscant", "email": "trycia.effertz80@hotmail.com", "phone": "+12044372083", "zipCode": "81304", "state": "VA", "country": "US", "externalId": "kyc-pass", // choose from the table above "options": {} // optional parameters vary by request type } ``` ### Response Stages #### 1. Request Stage An immediate HTTP response containing basic metadata about the evaluation. **Example: `kyc-pass`** ```json { "requestId": "f4XChEEXbz", "event": "onboard", "evaluation": { "type": "kyc", "status": "initiated" }, "externalId": "kyc-pass", "customerId": "688ca69a34a12dc2f648163c", "uri": "https://app.waldo.ai/customers/688ca69a34a12dc2f648163c", "errors": [] } ``` #### 2. Webhook Events If webhooks are configured, the sandbox will send three notifications to your endpoint in sequence. **a. Initiated** ```json { "requestId": "f4XChEEXbz", "event": "onboard", "evaluation": {"type": "kyc","status": "initiated"}, "externalId": "kyc-pass", "customerId": "688ca69a34a12dc2f648163c", "uri": "https://app.waldo.ai/customers/688ca69a34a12dc2f648163c", "errors": [] } ``` **b. In Progress** ```json { "requestId": "f4XChEEXbz", "event": "onboard", "evaluation": {"type": "kyc","status": "in_progress"}, "externalId": "kyc-pass", "customerId": "688ca69a34a12dc2f648163c", "uri": "https://app.waldo.ai/customers/688ca69a34a12dc2f648163c", "errors": [] } ``` **c. Completed** ```json { "requestId": "f4XChEEXbz", "event": "onboard", "evaluation": {"type": "kyc","status": "completed"}, "validation": { "status": "REVIEW", "kyc": "PASSED", "fraudScore": 0, "fraudFlag": false, "warnings": 0, "warningTags": { "ssn": {"tag": "ssn","label": "SSN Integrity","passed": true}, "date_of_birth": {"tag": "date_of_birth","label": "Date of Birth Integrity","passed": true}, "address": {"tag": "address","label": "Address Integrity","passed": true}, "legal_and_regulatory_warnings": {"tag": "legal_and_regulatory_warnings","label": "Legal and Regulatory Warnings","passed": true}, "politically_exposed_person": {"tag": "politically_exposed_person","label": "Politically Exposed Person","passed": true}, "sanction": {"tag": "sanction","label": "Sanctions List","passed": true}, "fraud_reports": {"tag": "fraud_reports","label": "Network Fraud Detection","passed": true}, "watchlists_validation": {"tag": "watchlists_validation","label": "Watchlists Validation","passed": true}, "phone_number_validation": {"tag": "phone_number_validation","label": "Phone Number Validation","passed": true}, "email_address_validation": {"tag": "email_address_validation","label": "Email Address Validation","passed": true} }, "kycBreakdown": {"identityBreakdown": {},"watchlistBreakdown": {},"documentBreakdown": {}} }, "externalId": "kyc-pass", "customerId": "688ca69a34a12dc2f648163c", "uri": "https://app.waldo.ai/customers/688ca69a34a12dc2f648163c", "errors": [] } ``` > **Tip**: The structure above is representative. To explore other scenarios (e.g., express kyc, fraud checks, document uploads), replace the `externalId` and examine the corresponding JSON in the `sandbox_event_triggers.txt` file below. ### Additional Scenarios All other request types (`fraud`, `expressKYC`, `expressKYCFraud`, `fraudCheck`, `documentUpload`) follow the same pattern: 1. Send a request with one of the supported `externalId` values. 2. Receive an immediate `requestStage` HTTP response. 3. Optionally handle the three webhook events (`initiated`, `in_progress`, `completed`). Refer to the `sandbox_event_triggers.txt` file below for full sample payloads and responses for each scenario. {% file src="" %}