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

# Overview

> The Cobi Data API provides a consistent interface for uploading different types of structured data into the Cobi system for analytics and segmentation.

<Note>
  The Cobi Data API is the foundation for all data integration with the Cobi
  platform.
</Note>

## API Structure

All Data API endpoints follow the same URL pattern:

<CodeGroup>
  ```http URL Pattern theme={null}
  POST /v1/data/:type
  ```

  ```http Customers Example theme={null}
  POST /v1/data/customers
  ```

  ```http Transactions Example theme={null}
  POST /v1/data/transactions
  ```

  ```http Offers Example theme={null}
  POST /v1/data/offers
  ```

  ```http Shops Example theme={null}
  POST /v1/data/shops
  ```

  ```http Branches Example theme={null}
  POST /v1/data/branches
  ```

  ```http Categories Example theme={null}
  POST /v1/data/categories
  ```

  ```http Shop Categories Example theme={null}
  POST /v1/data/shop-categories
  ```

  ```http Institutes Example theme={null}
  POST /v1/data/institutes
  ```

  ```http Courses Example theme={null}
  POST /v1/data/courses
  ```

  ```http Interactions Example theme={null}
  POST /user-interactions
  ```
</CodeGroup>

Where `:type` is one of:

<Steps>
  <Step title="Customers">Upload customer profile information</Step>

  <Step title="Transactions">
    Upload transaction records with savings and discounts
  </Step>

  <Step title="Offers">Upload offer details for promotions and discounts</Step>
  <Step title="Shops">Upload shop information</Step>

  <Step title="Branches">
    Upload branch information (requires shops to exist first)
  </Step>

  <Step title="Categories">
    Upload category information for product classification
  </Step>

  <Step title="Shop Categories">
    Upload shop-category associations (requires shops and categories to exist
    first)
  </Step>

  <Step title="Institutes">Upload educational institution information</Step>
  <Step title="Courses">Upload course information</Step>
  <Step title="Tags">Upload tag information</Step>

  <Step title="Shop Tags">
    Upload shop-tag associations (requires shops and tags to exist first)
  </Step>

  <Step title="Keywords">Upload keyword information</Step>

  <Step title="Shop Keywords">
    Upload shop-keyword associations (requires shops and keywords to exist
    first)
  </Step>

  <Step title="Student Favourites">
    Upload student-favourites associations (requires customer and shops to exist
    first)
  </Step>

  <Step title="Interactions">
    Record user interactions with items (TAG, OFFER, SHOP) for analytics
  </Step>
</Steps>

<Note>
  **Data Dependencies**: Some data types have dependencies on other types. For
  example, branches require valid shop\_id references. It's important to upload
  data in the correct order: 1. Upload shops first 2. Then upload branches that
  reference those shops
</Note>

## Common Features

<AccordionGroup>
  <Accordion title="Batch Processing">
    Each endpoint accepts a batch of records (up to 5000) in a single request:

    ```json theme={null}
    {
      "records": [
        { /* record 1 */ },
        { /* record 2 */ },
        // ...up to 5000 records
      ]
    }
    ```

    This batch processing capability allows for efficient data uploads and reduces the number of API calls needed.
  </Accordion>

  <Accordion title="Authentication">
    All endpoints require API key authentication via the Authorization header:

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

    <Tip>
      Contact our support team to obtain your API key.
    </Tip>
  </Accordion>

  <Accordion title="Response Format">
    All endpoints return a consistent response format:

    ```json theme={null}
    {
      "request_id": "string", // Unique ID for the overall request
      "type": "branches", // 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": "branches", // 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., "branches") |
    | `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)        |
  </Accordion>
</AccordionGroup>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Customers" icon="users" href="/api-reference/data/endpoint/customers" color="#4CAF50">
    Upload customer profile records with demographic and identification details
  </Card>

  <Card title="Transactions" icon="receipt" href="/api-reference/data/endpoint/transactions" color="#2196F3">
    Upload transaction records with savings, discounts, and purchase information
  </Card>

  <Card title="Offers" icon="gift" href="/api-reference/data/endpoint/offers" color="#FF9800">
    Upload offer details including validity periods and restrictions
  </Card>

  <Card title="Shops" icon="store" href="/api-reference/data/endpoint/shops" color="#9C27B0">
    Upload shop information including location and visibility settings
  </Card>

  <Card title="Branches" icon="code-branch" href="/api-reference/data/endpoint/branches" color="#E91E63">
    Upload branch information with location coordinates and shop association
  </Card>

  <Card title="Categories" icon="tags" href="/api-reference/data/endpoint/categories" color="#00BCD4">
    Upload category information for product classification and organization
  </Card>

  <Card title="Shop Categories" icon="link" href="/api-reference/data/endpoint/shop-categories" color="#3F51B5">
    Upload shop-category associations to organize shops by category
  </Card>

  <Card title="Institutes" icon="school" href="/api-reference/data/endpoint/institutes" color="#795548">
    Upload educational institution information including region and status
  </Card>

  <Card title="Courses" icon="book" href="/api-reference/data/endpoint/courses" color="#607D8B">
    Upload course information with official names and status
  </Card>

  <Card title="Interactions" icon="activity" href="/api-reference/data/endpoint/user-interactions" color="#FF5722">
    Record user interactions with items (TAG, OFFER, SHOP) for analytics
  </Card>
</CardGroup>

## Best Practices

<Tabs>
  <Tab title="Performance">
    * Upload up to 5000 records at a time for optimal performance - Consider
      scheduling regular batch uploads rather than individual API calls -
      Implement retry logic with exponential backoff for failed requests
  </Tab>

  <Tab title="Data Quality">
    * Ensure all required fields are present and properly formatted - Validate
      UUIDs and other formatted fields before sending - Use consistent region
      codes across all data types
  </Tab>

  <Tab title="Security">
    * Store your API key securely - Rotate API keys periodically - Use HTTPS for
      all API requests
  </Tab>
</Tabs>

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