Customer Onboarding

Endpoint to onboard a customer. The API responds with customer validation information.

Onboard a customer

POST https://api.waldo.ai/onboard

All evaluation requests are asynchronous. Onboarding a customer includes a kyc or fraud evaluation. Therefore, the response to the onboarding request will not be completed in real time. If you have set up the webhooks, your system will receive notifications automatically. Otherwise, your system can poll Waldo's API until the evaluation is completed.

Headers

Name	Type	Description
Authorization*	String	The token obtained in the authentication request in the format Bearer eyJhbG...
Content-Type*	String	Expected type is application/json

Request Body

Name	Type	Description
firstName*	String	Customer's first name
lastName*	String	Customer's last name
officialId*	Object	Customer ID in format {"docType": "SSN", "value": "123-45-6789", "country": "US"}
email*	String	Customer's e-mail address
phone*	String	Customer's phone number
dob*	String	Birthdate in format yyyy-MM-dd
address*	String	Customer's address
state*	String	Customer's state (abbreviated) in format NY
zipCode*	String	Customer's postal code
entityId	String	Customer ID in your database
city*	String	Customer's city
includeFraudCheck	Boolean	Whether to include the fraud check
ipAddress	Boolean	Customer IP address

Response

200: OK Onboarding successfully performed

{
    "requestId": "ayclpQyi6p",
    "event": "onboard",
    "evaluation": {
        "type": "kyc",
        "status": "initiated"
    },
    "validation": {
        "status": "REVIEW",
        "kyc": "PENDING",
        "fraudScore": 0
    },
    "externalId": "abcd-123-456-efgh",
    "customerId": "<customer-id>",
    "uri": "https://app.waldo.ai/customers/<customer-id>"
}

400: Bad Request Missing customer data

{ 
  "code": "MISSING_DATA",
  "message": "Missing customer data."
}

400: Bad Request Invalid data format (birthdate, email, state)

{ 
  "code": "INVALID_DATA",
  "message": "Invalid <field name>"
}

401: Unauthorized Invalid token

{
  "code": "INVALID_TOKEN", 
  "message": "Invalid token."
}

403: Forbidden Authorization header missing

{ 
  "code": "NOT_AUTHORIZED",
  "message": "Not authorized."
}

403: Forbidden Service or user not authorized

{ 
  "code": "NOT_AUTHORIZED",
  "message": "You are not authorized to perform this action. Please contact support for assistance."
}

403: Forbidden Inactive API key

{ 
  "code": "API_KEY_REVOKED",
  "message": "This API key has been revoked. Please visit the Waldo AI dashboard to review your API key."
}

Webhooks complete event notification

{
  "requestId": "ayclpQyi6p",
  "event": "onboard",
  "evaluation": {
    "type": "fraud",
    "status": "completed"
  },
  "customerId": "<customer-id>",
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "validation": {
    "status": "APPROVED",
    "kyc": "PASSED",
    "fraudScore": 0.9,
    "fraudFlag": false,
    "warnings": 3,
    "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": false
      },
      "watchlists_validation": {
        "tag": "watchlists_validation",
        "label": "Watchlists Validation",
        "passed": true
      },
      "phone_number_validation": {
        "tag": "phone_number_validation",
        "label": "Phone Number Validation",
        "passed": false
      },
      "email_address_validation": {
        "tag": "email_address_validation",
        "label": "Email Address Validation",
        "passed": false
      }
    },
    "kycBreakdown": {
      "identityBreakdown": {},
      "watchlistBreakdown": {},
      "documentBreakdown": {}
    }
  }
}