> For the complete documentation index, see [llms.txt](https://docs.waldo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.waldo.ai/guides/sandbox-testing-scenarios.md). # 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](/api-reference/authentication.md) {% 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](/api-reference/authentication.md) 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="/files/UBBuoh07JMn3A03ZGJWX" %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.waldo.ai/guides/sandbox-testing-scenarios.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.