# Stripe Radar API Documentation

This documentation covers the Stripe Radar API, which provides tools for detecting and preventing fraud.

## Customer Evaluation

The Customer Evaluation API allows you to create and manage customer evaluations. These evaluations are used by Radar to assess the risk associated with customer activity.

### Customer Evaluation Object

The Customer Evaluation object represents a single customer evaluation.

**Attributes:**

*   `id` (string): Unique identifier for the object.
*   `object` (string): String representing the object’s type. Objects of the same type share the same value.
*   `customer` (nullable string): The ID of the Customer to associate with this CustomerEvaluation.
*   `event_type` (enum): The type of evaluation event. Possible values: `login`, `registration`.
*   `events` (nullable array of objects): A list of events that have been reported on this customer evaluation.
*   `signals` (nullable object): A hash of signal objects providing Radar’s evaluation of the customer.
*   `created_at` (timestamp): Time at which the object was created.
*   `livemode` (boolean): If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

**Example Customer Evaluation Object:**

```json
{
  "id": "cuseval_123456789",
  "object": "radar.customer_evaluation",
  "event_type": "registration",
  "livemode": true,
  "created_at": 1715769600,
  "customer": "cus_123456789",
  "events": null,
  "signals": {
    "multi_accounting": {
      "score": 50.1,
      "evaluated_at": 1715769600,
      "risk_level": null
    }
  }
}
```

### Create a Customer Evaluation

Creates a new CustomerEvaluation object.

**Endpoint:** `POST /v1/radar/customer_evaluations`

**Parameters:**

*   `evaluation_context` (array of objects) **Required**: Array of context entries for the evaluation.
    *   `type` (enum) **Required**: The type of evaluation event. Possible values: `login`, `registration`.
*   `event_type` (enum) **Required**: The type of evaluation event. Possible values: `login`, `registration`.

**Returns:** A CustomerEvaluation object if creation succeeds.

**Example Request:**

```bash
curl https://api.stripe.com/v1/radar/customer_evaluations \
  -u "sk_test_..." \
  -d event_type=registration \
  -d "evaluation_context[0][type]=client_details" \
  -d "evaluation_context[0][client_details][radar_session]=rse_123456789" \
  -d "evaluation_context[1][type]=customer_details" \
  -d "evaluation_context[1][customer_details][customer]=cus_123456789"
```

**Example Response:**

```json
{
  "id": "cuseval_123456789",
  "object": "radar.customer_evaluation",
  "event_type": "registration",
  "livemode": true,
  "created_at": 1715769600,
  "customer": "cus_123456789",
  "events": null,
  "signals": {
    "multi_accounting": {
      "score": 50.1,
      "evaluated_at": 1715769600,
      "risk_level": null
    }
  }
}
```

### Report an Event on a Customer Evaluation

Reports an event on a CustomerEvaluation object.

**Endpoint:** `POST /v1/radar/customer_evaluations/:id/report`

**Parameters:**

*   `customer_evaluation` (string) **Required**: The ID of the customer evaluation to report the event on.
*   `type` (enum) **Required**: The type of event to report. Possible values: `login_failed`, `login_success`, `registration_failed`, `registration_success`.
*   `login_failed` (object): Event payload for `login_failed`.
*   `registration_failed` (object): Event payload for `registration_failed`.
*   `registration_success` (object): Event payload for `registration_success`.

**Returns:** The CustomerEvaluation object if reporting succeeds.

**Example Request:**

```bash
curl https://api.stripe.com/v1/radar/customer_evaluations/cuseval_123456789/report \
  -u "sk_test_..." \
  -d type=registration_success
```

**Example Response:**

```json
{
  "id": "cuseval_123456789",
  "object": "radar.customer_evaluation",
  "event_type": "registration",
  "livemode": true,
  "created_at": 1715769600,
  "customer": "cus_123456789",
  "events": [
    {
      "type": "registration_success",
      "occurred_at": 1715779600
    }
  ],
  "signals": {
    "multi_accounting": {
      "score": 50.1,
      "evaluated_at": 1715769600,
      "risk_level": null
    }
  }
}
```