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

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

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

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

{
  "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 --location 'https://api.waldo.ai/authenticate' \
--data '{"apiKey": "YOUR_API_KEY","clientSecret": "CLIENT_SECRET"}'

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);
});

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
$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();

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

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

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

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

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

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

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

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

Take a look at how you might call this method:

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": "paul.atreides@yahoo.com",
  "zipCode": "01234",
  "state": "NV",
  "phone": "+1 123-456-7890",
  "externalId": "abcd-123-456-efgh",
  "city": "Arrakis",
  "options": {"includeFraudCheck": true}
}'

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": "paul.atreides@yahoo.com",
  "zipCode": "01234",
  "state": "NV",
  "phone": "+1 123-456-7890",
  "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);
});

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": "paul.atreides@yahoo.com",
  "zipCode": "01234",
  "state": "NV",
  "phone": "+1 123-456-7890",
  "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
$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": "paul.atreides@yahoo.com",
  "zipCode": "01234",
  "state": "NV",
  "phone": "+1 123-456-7890",
  "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();

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\": \"paul.atreides@yahoo.com\",\r\n  \"zipCode\": \"01234\",\r\n  \"state\": \"NV\",\r\n  \"phone\": \"+1 123-456-7890\",\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());

PreviousMeet Waldo AI NextGetting Started

Last updated 1 month ago