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

# Student Favourites

> Upload student favourite mappings to the Cobi Data API.

<Note>
  **Important**: Student favourite records have dependencies on both
  customers/students and shops. The system validates both the `student_id` and
  `shop_id` fields against existing records in the database. You should upload
  customer/student and shop data before uploading student favourite mappings to
  ensure proper data validation.
</Note>

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

## About the Data API

This endpoint is part of the Cobi Data API (`/v1/data/:type`), which provides a consistent interface for uploading different types of structured data.

## Request Body

<ParamField body="records" type="array" required>
  An array of student favourite mapping records (up to 5000)

  <Expandable title="Student Favourite Record">
    <ParamField body="favourite_id" type="string (UUID)">
      Unique identifier for the favourite mapping
    </ParamField>

    <ParamField body="student_id" type="string (UUID)" required>
      ID of the student (must reference an existing customer/student)
    </ParamField>

    <ParamField body="shop_id" type="string (UUID)" required>
      ID of the shop (must reference an existing shop)
    </ParamField>

    <ParamField body="created" type="string (date-time)">
      Timestamp when the record was created
    </ParamField>

    <ParamField body="updated" type="string (date-time)">
      Timestamp when the record was last updated
    </ParamField>

    <ParamField body="is_deleted" type="boolean">
      Flag indicating if the record is marked as deleted
    </ParamField>
  </Expandable>
</ParamField>

## Response

The API returns a JSON response with the following fields:

```json theme={null}
{
  "request_id": "string", // Unique ID for the overall request
  "type": "student-favourites", // Type of data being processed
  "batches": [
    {
      "batch": 1, // Sequential batch number
      "status": 200, // HTTP-like status code (200, 207, 400, 500)
      "data": {
        "status": "success", // "success", "partial", or "error"
        "type": "student-favourites", // Matches the top-level type
        "message": "Records uploaded successfully", // Summary message
        "request_id": "string",
        "batch_id": "string",
        "error": "" // Optional — empty or null on success; contains error details otherwise
      }
    }
  ]
}
```

| Field                       | Type   | Description                                               |
| --------------------------- | ------ | --------------------------------------------------------- |
| `request_id`                | string | Unique ID for the overall request                         |
| `type`                      | string | Type of data being processed (e.g., "student-favourites") |
| `batches`                   | array  | Array of batch results                                    |
| `batches[].batch`           | int    | Sequential batch number                                   |
| `batches[].status`          | int    | HTTP-like status code (200, 207, 400, 500)                |
| `batches[].data`            | object | Batch result details                                      |
| `batches[].data.status`     | string | "success", "partial", or "error"                          |
| `batches[].data.type`       | string | Matches the top-level type                                |
| `batches[].data.message`    | string | Summary message of the batch result                       |
| `batches[].data.request_id` | string | Unique request ID for the batch                           |
| `batches[].data.batch_id`   | string | Unique batch ID                                           |
| `batches[].data.error`      | string | Error details (empty or null on success)                  |

## Error Codes

| Status Code | Description                               | data.status value |
| ----------- | ----------------------------------------- | ----------------- |
| 200         | All records processed successfully        | success           |
| 207         | Some records failed, others succeeded     | partial           |
| 400         | Validation or dependency error            | error             |
| 500         | Internal or unexpected server error       | error             |
| 401         | Unauthorized - Invalid or missing API key | error             |

## Example

```bash theme={null}
curl -X POST https://api.hellocobi.com/v1/data/student-favourites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "favourite_id": "550e8400-e29b-41d4-a716-446655440000",
        "student_id": "550e8400-e29b-41d4-a716-446655440001",
        "shop_id": "550e8400-e29b-41d4-a716-446655440002",
        "created": "2023-01-15T14:30:00Z",
        "updated": "2023-06-22T09:15:30Z",
        "is_deleted": false
      }
    ]
  }'
```

## Best Practices

1. **Upload Order**: Upload customers/students and shops before student-favourites to ensure references exist
2. **Batch Size**: Upload up to 5000 records at a time for optimal performance
3. **Data Validation**: Ensure all required fields are present and properly formatted
4. **Error Handling**: Implement proper error handling for failed requests
5. **Rate Limiting**: Be mindful of API rate limits
6. **Soft Deletion**: Use the is\_deleted flag instead of permanently deleting records

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