# Quick Start

## 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

<mark style="color:green;">`POST`</mark> `https://api.waldo.ai/authenticate`

#### Request Body

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| apiKey<mark style="color:red;">\*</mark>       |        |             |
| clientSecret<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="401: Unauthorized Invalid API key or invalid client secret" %}

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

{% endtab %}

{% tab title="400: Bad Request Missing parameters" %}

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

{% endtab %}

{% tab title="403: Forbidden API key has been revoked" %}

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

{% endtab %}

{% tab title="200: OK Token generated" %}

```json
{
  "token": "eyJh...."
}
```

{% endtab %}
{% endtabs %}

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](https://docs.waldo.ai/guides/authentication-process) for how to implement the token refresh smoothly.

{% tabs %}
{% tab title="CURL" %}
{% code overflow="wrap" fullWidth="false" %}

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

{% endcode %}
{% endtab %}

{% tab title="NODE.JS" %}

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

{% endtab %}

{% tab title="PYTHON" %}

```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)
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="C#" %}

```csharp
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());
```

{% endtab %}
{% endtabs %}

## 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

<mark style="color:green;">`POST`</mark> `https://api.waldo.ai/onboard`

#### Headers

| Name                                            | Type | Description                                                                       |
| ----------------------------------------------- | ---- | --------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> |      | The token obtained in the authentication request in the format `Bearer eyJhbG...` |
| Content-Type<mark style="color:red;">\*</mark>  |      | Expected type `application/json`                                                  |

#### Request Body

| Name                                         | Type   | Description                    |
| -------------------------------------------- | ------ | ------------------------------ |
| firstName<mark style="color:red;">\*</mark>  |        | Customer's first name          |
| lastName<mark style="color:red;">\*</mark>   |        | Customer's last name           |
| officialId<mark style="color:red;">\*</mark> | Object | Customer ID                    |
| dob<mark style="color:red;">\*</mark>        | String | Birthdate in format yyyy-MM-dd |
| address<mark style="color:red;">\*</mark>    | String | Customer's address             |
| email<mark style="color:red;">\*</mark>      | String | Customer's e-mail address      |
| zipCode<mark style="color:red;">\*</mark>    | String | Customer's postal code         |
| state<mark style="color:red;">\*</mark>      | String | Customer's state abbreviated   |
| phone<mark style="color:red;">\*</mark>      | String | Customer's phone number        |
| entityId                                     | String | Customer ID in your database   |
| city<mark style="color:red;">\*</mark>       | String | Customer's city                |

{% tabs %}
{% tab title="200 Onboarding successfully performed" %}

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

{% endtab %}

{% tab title="401 Invalid token" %}

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

{% endtab %}

{% tab title="403: Forbidden Authorization header missing" %}

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

{% endtab %}

{% tab title="403: Forbidden Service or user not authorized" %}

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

{% endtab %}

{% tab title="403: Forbidden Inactive API key" %}

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

{% endtab %}

{% tab title="400: Bad Request Missing customer data" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid data format (birthdate, email, state)" %}

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

{% endtab %}
{% endtabs %}

Take a look at how you might call this method:

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

{% endtab %}

{% tab title="NODE.JS" %}

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

{% endtab %}

{% tab title="PYTHON" %}

```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": "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)
```

{% endtab %}

{% tab title="PHP" %}

```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": "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();
```

{% endtab %}

{% tab title="C#" %}

```csharp
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());
```

{% endtab %}
{% endtabs %}