> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellocobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Recommendations

> Get personalized recommendations for a specific customer based on their preferences and behavior.

## Authentication Required

This endpoint requires API key authentication via Bearer token in the Authorization header.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Path Parameters

<ParamField header="customer_id" type="string (UUID)" required>
  Unique identifier for the customer to get recommendations for
</ParamField>

## Query Parameters

<ParamField query="includeSegments" type="boolean">
  Whether to include segment-based recommendations in the response. Defaults to
  false.
</ParamField>

<ParamField query="regions" type="string">
  Filter recommendations by region (e.g., "BH" for Bahrain). Comma-separated
  values for multiple regions.
</ParamField>

## Response

The API returns a JSON array of recommendation objects:

```json theme={null}
[
  {
    "recommendation_id": "00000000-1234-5678-9abc-def012345678",
    "name": "Recommended For you",
    "student_id": "00000000-9779-438e-ae0d-b52099f6be51",
    "offers": [
      "00000000-e9c5-4b43-9d46-4cd02baabc6a",
      "00000002-c1f0-44d4-af13-32028f522f31",
      "00000001-4d21-4206-8ced-ff2a11162bf0"
    ],
    "type": "SELF"
  }
]
```

| Field               | Type   | Description                                       |
| ------------------- | ------ | ------------------------------------------------- |
| `recommendation_id` | string | Unique identifier for the recommendation          |
| `name`              | string | Human-readable name for the recommendation set    |
| `student_id`        | string | UUID of the customer (matches the path parameter) |
| `offers`            | array  | Array of offer UUIDs that are recommended         |
| `type`              | string | Type of recommendation (SELF or SEGMENT)          |

## Error Codes

| Status Code | Description                               |
| ----------- | ----------------------------------------- |
| 200         | Recommendations retrieved successfully    |
| 400         | Invalid customer\_id format               |
| 401         | Unauthorized - Invalid or missing API key |
| 404         | Customer not found                        |
| 500         | Internal server error                     |

## Example

```bash theme={null}
curl -X GET "https://api.hellocobi.com/v1/recommendations/customers/00000000-9779-438e-ae0d-b52099f6be51?includeSegments=false&regions=BH" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Best Practices

1. **Caching**: Cache recommendations for frequently requested customers to improve performance
2. **Error Handling**: Implement proper error handling for cases where no recommendations are available
3. **Rate Limiting**: Be mindful of API rate limits (1000 requests per minute)
4. **Validation**: Validate the customer\_id format before making the request

Need help? Contact our support team at [support@hellocobi.com](mailto:support@hellocobi.com)