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

# Upload contacts CSV

> Bulk import contacts into a list from a CSV file

Uploads a CSV spreadsheet containing contact phone numbers, names, emails, and custom metadata variables to populate a contact list.

### Requirements & Limits

* **Content-Type**: `multipart/form-data`
* **File extension**: `.csv`
* **Maximum rows**: 500 contacts per upload
* **Supported CSV Headers** (case-insensitive, spaces or underscores):
  * `phone_number` / `phone` / `mobile` / `customer_number` *(Required, E.164 format e.g. `+919876543210` or `+14155552671`)*
  * `name` / `customer_name` / `contact_name` / `first_name` *(Optional)*
  * `email` *(Optional, valid email address format)*
  * `metadata` *(Optional, valid JSON string containing custom variables e.g. `{"tier": "gold", "account_balance": 150}`)*

### Path parameters

<ParamField path="id" type="string" required>
  The unique UUID of the target contact list.
</ParamField>

### Body parameters

<ParamField body="file" type="file" required>
  The binary `.csv` file to upload.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agentic-os.com/api/v1/contact-lists/33333333-3333-3333-3333-333333333333/upload \
    -H "Authorization: Bearer $AGENTIC_OS_API_KEY" \
    -F "file=@/path/to/leads.csv"
  ```

  ```python Python theme={null}
  import requests

  with open("leads.csv", "rb") as f:
      response = requests.post(
          "https://api.agentic-os.com/api/v1/contact-lists/33333333-3333-3333-3333-333333333333/upload",
          headers={"Authorization": f"Bearer {API_KEY}"},
          files={"file": f},
      )
  print(response.json())
  ```

  ```javascript Node theme={null}
  const formData = new FormData();
  formData.append("file", fileBlob, "leads.csv");

  const response = await fetch(
    "https://api.agentic-os.com/api/v1/contact-lists/33333333-3333-3333-3333-333333333333/upload",
    {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}` },
      body: formData,
    },
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "imported": 48,
  "skipped": 2,
  "invalidRows": [
    {
      "row": 15,
      "phone": "987654321",
      "reason": "Invalid phone number length"
    }
  ]
}
```