> For the complete documentation index, see [llms.txt](https://docs.waldo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.waldo.ai/api-reference/check-fraud.md).

# Check Fraud

## Request a fraud evaluation

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

{% hint style="info" %}
All evaluation requests are asynchronous. \
Therefore, the response to the fraud check 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 %}

**Request body**

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| customerId<mark style="color:red;">\*</mark> | string | Customer ID |

**Response**

{% hint style="warning" %}
When requesting a fraud check, always verify the `evaluation` property; if its status is `initiated,` the `fraudScore` value is the last known fraud score, not of the current evaluation.
{% endhint %}

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

#### Webhooks complete event notification

```json
{
  "event": "evaluation",
  "evaluation": {
    "type": "fraud",
    "status": "completed"
  },
  "validation": {
    "status": "APPROVED",
    "kyc": "PASSED",
    "fraudScore": 0.89,
    "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": {}
    }
  },
  "customerId": "<customer-id>",
  "uri": "https://app.waldo.ai/customers//<customer-id>"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.waldo.ai/api-reference/check-fraud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.