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
country*	String	Customer's country
options	Object	Optional parameters.
ipAddress	Boolean	Customer IP address

Options

Name	Type	Description
includeFraudCheck	Boolean	Set includeFraudCheck parameter to true to include the fraud check
useExpressKYC	Boolean	Set useExpressKYC parameter to true to obtain the preliminary KYC evaluation

Sample Request Data

{
  "firstName": "Paul",
  "lastName": "Atreides",
  "officialId": {
    "docType": "SSN",
    "value": "123-45-6789",
    "format": "XXX-XX-XXXX",
    "country": "US"
  },
  "dob": "1959-03-14",
  "address": "123 Fremen City",
  "city": "Arrakis",
  "email": "[email protected]",
  "phone": "[phone]",
  "zipCode": "01234",
  "state": "NV",
  "country": "US",
  "externalId": "",
  "options": {
    "includeFraudCheck": true,
    "useExpressKYC": false
  }
}

Response

200: OK Onboarding successfully performed

{
    "requestId": "ayclpQyi6p",
    "event": "onboard",
    "evaluation": {
        "type": "kyc",
        "status": "initiated"
    },
    "validation": {
        "status": "REVIEW",
        "kyc": "PENDING",
        "fraudScore": 0
    },
    "options": {
        "includeFraudCheck": true
    },
    "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": {}
    }
  }
}

Express KYC

Please read the feature documentation to understand when to use it.

Include Express KYC in the onboarding options

{
  "firstName": "Paul",
  "lastName": "Atreides",
  ....
  "options": {
    "useExpressKYC": true
  }
}

Sample response with Express KYC evaluation

{
  "requestId": "cqsji7gyKE",
  "customerId": "<customer-id>",
  "event": "onboard",
  "evaluation": {
    "type": "kyc",
    "status": "initiated"
  },
  "options": {
    "useExpressKYC": true
  },
  "expressKYC": {
    "success": true,
    "outcome": "PASSED"
  },
  "validation": {
    "status": "PENDING",
    "kyc": "PENDING",
    "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
      }
    },
    "kycBreakdown": {
      "identityBreakdown": {},
      "watchlistBreakdown": {},
      "documentBreakdown": {}
    }
  },
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "errors": []
}

Sample response without Express KYC evaluation

{
  "requestId": "cqsji7gyKE",
  "customerId": "<customer-id>",
  "event": "onboard",
  "evaluation": {
    "status": "initiated",
    "type": "kyc"
  },
  "expressKYC": {
    "success": false,
    "message": "Express KYC is taking longer than expected. If you have configured webhooks, you will receive notifications as the process progresses, or check in the Waldo dashboard."
  },
  "options": {
    "useExpressKYC": true
  },
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "validation": {
    "status": "REVIEW",
    "kyc": "PENDING",
    "fraudFlag": false,
    "fraudScore": 0
  },
  "errors": []
}