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.

Please note that the testing scenarios are for customer onboarding and evaluation requests. For other types of API requests, please check the API Reference

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.

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 to learn more.

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": "[email protected]",
  "phone": "[phone]",
  "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

{
  "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

{
  "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

{
  "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

{
  "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.

84KB

sandbox_event_triggers.txt