Quick Start

This short tutorial should help you integrate Waldo AI into your system.

Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can generate an API key from your Dashboard at any time.

Authenticate

The authentication is made by making a POST request to `https://api.waldo.ai/authenticate` and passing your client API key and client API secret.

Authenticate your account

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

Request Body

Name	Type	Description
apiKey*
clientSecret*	String

401: Unauthorized Invalid API key or invalid client secret

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key"
}

400: Bad Request Missing parameters

{
  "code": "MISSING_PARAMETERS",
  "message": "Missing parameters"
}

403: Forbidden API key has been revoked

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

200: OK Token generated

{
  "token": "eyJh...."
}

Authentication requests should look like below. A successful request will receive a JWT token in response. Please note that the token has an expiry date of 1 hour from the authentication request. The following API requests will receive a fresh token in response, so it's advised to verify the expiry date before making an API request. Take a look at the authentication guide for how to implement the token refresh smoothly.

CURL

curl --location 'https://api.waldo.ai/authenticate' \
--data '{"apiKey": "YOUR_API_KEY","clientSecret": "CLIENT_SECRET"}'

NODE.JS

import axios from "axios";
const data = JSON.stringify({
  "apiKey": "YOUR_API_KEY",
  "clientSecret": "CLIENT_SECRET"
});

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.waldo.ai/authenticate',
  headers: {
    'Content-Type': 'application/json'
  },
  data : data
};
axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

PYTHON

import requests
import json

url = "https://api.waldo.ai/authenticate"

payload = json.dumps({
  "apiKey": "YOUR_API_KEY",
  "clientSecret": "CLIENT_SECRET"
})
headers = {
  'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP

<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json'
];
$body = '{
  "apiKey": "YOUR_API_KEY",
  "clientSecret": "CLIENT_SECRET"
}';
$request = new Request('POST', 'https://api.waldo.ai/authenticate', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.waldo.ai/authenticate");
var content = new StringContent("{\"apiKey\": \"YOUR_API_KEY\",\"clientSecret\": \"CLIENT_SECRET\"}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Make your first request

To make your first request, send an authenticated request to the onboarding endpoint. This will perform an initial evaluation of a customer.

Onboard a customer

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

Headers

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

Request Body

Name	Type	Description
firstName*		Customer's first name
lastName*		Customer's last name
officialId*	Object	Customer ID
dob*	String	Birthdate in format yyyy-MM-dd
address*	String	Customer's address
email*	String	Customer's e-mail address
zipCode*	String	Customer's postal code
state*	String	Customer's state abbreviated
phone*	String	Customer's phone number
entityId	String	Customer ID in your database
city*	String	Customer's city

200 Onboarding successfully performed

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

401 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."
}

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

Take a look at how you might call this method:

CURL

curl --location 'https://api.waldo.ai/onboard' \
--header 'Authorization: Bearer eyJhbGc...' \
--header 'Content-Type: application/json' \
--data-raw '{
  "firstName": "Paul",
  "lastName": "Atreides",
  "officialId": {
    "docType": "SSN",
    "value": "123-45-6789",
    "country": "US"
  },
  "dob": "1959-03-14",
  "address": "123 Fremen City",
  "email": "[e-mail]",
  "zipCode": "01234",
  "state": "NV",
  "phone": "[phone]",
  "externalId": "abcd-123-456-efgh",
  "city": "Arrakis",
  "options": {"includeFraudCheck": true}
}'

NODE.JS

import axios from "axios";
const data = JSON.stringify({
  "firstName": "Paul",
  "lastName": "Atreides",
  "officialId": {
    "docType": "SSN",
    "value": "123-45-6789",
    "country": "US"
  },
  "dob": "1959-03-14",
  "address": "123 Fremen City",
  "email": "[e-mail]",
  "zipCode": "01234",
  "state": "NV",
  "phone": "[phone]",
  "externalId": "abcd-123-456-efgh",
  "city": "Arrakis",
  "options": {"includeFraudCheck": true}
});

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.waldo.ai/onboard',
  headers: { 
    'Authorization: Bearer eyJhbGc...', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

PYTHON

import requests
import json

url = "https://api.waldo.ai/onboard"

payload = json.dumps({
  "firstName": "Paul",
  "lastName": "Atreides",
  "officialId": {
    "docType": "SSN",
    "value": "123-45-6789",
    "country": "US"
  },
  "dob": "1959-03-14",
  "address": "123 Fremen City",
  "email": "[e-mail]",
  "zipCode": "01234",
  "state": "NV",
  "phone": "[phone]",
  "externalId": "abcd-123-456-efgh",
  "city": "Arrakis",
  "options": {"includeFraudCheck": true}
})
headers = {
  'Authorization: Bearer eyJhbGc...',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP

<?php
$client = new Client();
$headers = [
  'Authorization' => 'Bearer eyJhbGc...',
  'Content-Type' => 'application/json'
];
$body = '{
  "firstName": "Paul",
  "lastName": "Atreides",
  "officialId": {
    "docType": "SSN",
    "value": "123-45-6789",
    "country": "US"
  },
  "dob": "1959-03-14",
  "address": "123 Fremen City",
  "email": "[e-mail]",
  "zipCode": "01234",
  "state": "NV",
  "phone": "[phone]",
  "externalId": "abcd-123-456-efgh",
  "city": "Arrakis",
  "options": {"includeFraudCheck": true}
}';
$request = new Request('POST', 'https://api.waldo.ai/onboard', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.waldo.ai/onboard");
request.Headers.Add("Authorization", "Bearer eyJhbGc...");
var content = new StringContent("{\r\n  \"firstName\": \"Paul\",\r\n  \"lastName\": \"Atreides\",\r\n  \"officialId\": {\r\n    \"docType\": \"SSN\",\r\n    \"value\": \"123-45-6789\",\r\n    \"country\": \"US\"\r\n  },\r\n  \"dob\": \"1959-03-14\",\r\n  \"address\": \"123 Fremen City\",\r\n  \"email\": \"[e-mail]\",\r\n  \"zipCode\": \"01234\",\r\n  \"state\": \"NV\",\r\n  \"phone\": \"[phone]\",\r\n  \"externalId\": \"abcd-123-456-efgh\",\r\n  \"city\": \"Arrakis\"\r\n  \"options\": {\r\n  \"includeFraudCheck\": true}}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());