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

# Branches

> Upload branch records to the Cobi Data API.

<Note>
  **Important**: Branch records have a dependency on shops. The system validates
  the `shop_id` field against existing shops in the database. You should upload
  shop records before uploading branch records 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 branch records (up to 5000)

  <Expandable title="Branch Record">
    <ParamField body="branch_id" type="string (UUID)" required>
      Unique identifier for the branch
    </ParamField>

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

    <ParamField body="name" type="string" required>
      Name of the branch
    </ParamField>

    <ParamField body="region" type="string" required>
      Geographic region (2-letter country code, e.g., "CA" for Canada)
    </ParamField>

    <ParamField body="latitude" type="number">
      Latitude coordinate of the branch location
    </ParamField>

    <ParamField body="longitude" type="number">
      Longitude coordinate of the branch location
    </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": "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)        |

## 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/branches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "branch_id": "550e8400-e29b-41d4-a716-446655440000",
        "shop_id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Downtown Branch",
        "region": "CA",
        "latitude": 43.651070,
        "longitude": -79.347015,
        "created": "2023-01-15T14:30:00Z",
        "updated": "2023-06-22T09:15:30Z",
        "is_deleted": false
      }
    ]
  }'
```

## Best Practices

1. **Upload Order**: Upload shops before branches to ensure shop\_id 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

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