# Customer Onboarding

## Onboard a customer

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

{% hint style="info" %}
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.
{% endhint %}

#### Headers

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

#### Request Body

| Name                                         | Type    | Description                                                                         |
| -------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| firstName<mark style="color:red;">\*</mark>  | String  | Customer's first name                                                               |
| lastName<mark style="color:red;">\*</mark>   | String  | Customer's last name                                                                |
| officialId<mark style="color:red;">\*</mark> | Object  | Customer ID in format `{"docType": "SSN", "value": "123-45-6789", "country": "US"}` |
| email<mark style="color:red;">\*</mark>      | String  | Customer's e-mail address                                                           |
| phone<mark style="color:red;">\*</mark>      | String  | Customer's phone number                                                             |
| dob<mark style="color:red;">\*</mark>        | String  | Birthdate in format `yyyy-MM-dd`                                                    |
| address<mark style="color:red;">\*</mark>    | String  | Customer's address                                                                  |
| state<mark style="color:red;">\*</mark>      | String  | Customer's state (abbreviated) in format `NY`                                       |
| zipCode<mark style="color:red;">\*</mark>    | String  | Customer's postal code                                                              |
| entityId                                     | String  | Customer ID in your database                                                        |
| city<mark style="color:red;">\*</mark>       | String  | Customer's city                                                                     |
| country<mark style="color:red;">\*</mark>    | 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

```json
{
  "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": "paul.atreides@yahoo.com",
  "phone": "+12044372083",
  "zipCode": "01234",
  "state": "NV",
  "country": "US",
  "externalId": "abcd-123-456-efgh",
  "options": {
    "includeFraudCheck": true,
    "useExpressKYC": false
  }
}
```

#### Response

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

```json
{
    "requestId": "ayclpQyi6p",
    "event": "onboard",
    "evaluation": {
        "type": "kyc",
        "status": "initiated"
    },
    "options": {
        "includeFraudCheck": true
    },
    "externalId": "abcd-123-456-efgh",
    "customerId": "<customer-id>",
    "uri": "https://app.waldo.ai/customers/<customer-id>"
}
```

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

{% tab title="401: Unauthorized 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 %}
{% endtabs %}

#### Webhooks complete event notification

```json
{
  "requestId": "ayclpQyi6p",
  "event": "onboard",
  "evaluation": {
    "type": "fraud",
    "status": "completed"
  },
  "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": {}
    }
  },
  "externalId": "abcd-123-456-efgh",
  "customerId": "<customer-id>",
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "errors": []
}
```

### Express KYC

{% hint style="info" %}
Please read the [feature documentation](https://docs.waldo.ai/features/express-kyc) to understand when to use it.&#x20;
{% endhint %}

#### Include Express KYC in the onboarding options

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

#### Sample response with Express KYC evaluation

```json
{
  "requestId": "cqsji7gyKE",
  "event": "onboard",
  "evaluation": {
    "type": "kyc",
    "status": "initiated"
  },
  "options": {
    "useExpressKYC": true
  },
  "expressKYCStatus": {
    "success": true,
    "outcome": "PASSED"
  },
  "customerId": "<customer-id>",
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "errors": []
}
```

#### Sample response without Express KYC evaluation

```json
{
  "requestId": "cqsji7gyKE",
  "customerId": "<customer-id>",
  "event": "onboard",
  "evaluation": {
    "status": "initiated",
    "type": "kyc"
  },
  "uri": "https://app.waldo.ai/customers/<customer-id>",
  "errors": []
}
```