Skip to main content
POST
/
api
/
v1
/
campaigns
/
{campaign_id}
/
import-data
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.burki.dev/llms.txt

Use this file to discover all available pages before exploring further.

Bulk import contacts from a CSV file into a campaign. The endpoint validates phone numbers, detects duplicates, and maps columns to contact fields.

​
Path Parameters

  • campaign_id (integer, required): The unique identifier of the campaign

​
Request

This endpoint accepts multipart/form-data with the following fields:
FieldTypeRequiredDescription
filefileYesCSV file with contacts
column_mappingsstringNoJSON string mapping CSV columns to fields

​
CSV Format Requirements

  • Required column: Phone number (auto-detected or mapped)
  • Recommended: Header row with column names
  • Encoding: UTF-8
  • Delimiter: Comma (,)

​
Phone Number Validation

Phone numbers are automatically normalized to E.164 format:
Input FormatNormalized Output
5551234567+15551234567
1-555-123-4567+15551234567
(555) 123-4567+15551234567
+15551234567+15551234567

​
Column Mapping

The system auto-detects common column names:
CSV Column NamesMaps To
phone, phone_number, mobile, cellphone_number
name, full_name, contact_namename
email, email_addressemail
company, organizationcompany
For custom mappings, provide a JSON object: 
{
  "Phone Number": "phone_number",
  "Customer Name": "name",
  "Appt Date": "appointment_date"
}

​
Example CSV

Phone Number,Customer Name,Company,Appointment Date
5551234567,John Smith,Acme Corp,2024-02-15
5559876543,Jane Doe,Tech Inc,2024-02-16

​
Response

Response
{
  "success": true,
  "message": "Successfully imported 250 contacts",
  "imported_count": 250,
  "total_contacts": 250,
  "file_name": "contacts_february.csv",
  "import_date": "2024-02-01T10:30:00Z"
}

​
Response Fields

FieldDescription
successWhether import succeeded
messageHuman-readable status
imported_countNumber of contacts imported
total_contactsTotal contacts in campaign after import
file_nameOriginal filename
import_dateImport timestamp

​
Example Code

cURL
curl -X POST "https://api.burki.dev/api/v1/campaigns/42/import-data" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  -F 'column_mappings={"Phone": "phone_number", "Name": "name"}'
Python
import requests

# Simple import
with open("contacts.csv", "rb") as f:
    response = requests.post(
        "https://api.burki.dev/api/v1/campaigns/42/import-data",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("contacts.csv", f, "text/csv")}
    )

result = response.json()
print(f"Imported {result['imported_count']} contacts")

# With custom column mappings
import json

with open("contacts.csv", "rb") as f:
    response = requests.post(
        "https://api.burki.dev/api/v1/campaigns/42/import-data",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": ("contacts.csv", f, "text/csv")},
        data={
            "column_mappings": json.dumps({
                "Phone": "phone_number",
                "Customer Name": "name",
                "Appt Date": "appointment_date"
            })
        }
    )
JavaScript
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("column_mappings", JSON.stringify({
  "Phone": "phone_number",
  "Name": "name"
}));

const response = await fetch("https://api.burki.dev/api/v1/campaigns/42/import-data", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: formData
});

const result = await response.json();
console.log(`Imported ${result.imported_count} contacts`);

​
Behavior

  • Existing contacts with same phone number are skipped (not duplicated)
  • Pending/skipped contacts from previous imports are deleted before new import
  • Completed/failed contacts are preserved for history
  • All custom columns become template variables

​
Error Responses

Status CodeDescription
400Invalid file format or empty file
404Campaign not found
500Import processing failed

​
Best Practices

  1. Validate data before importing - check phone number formats
  2. Use consistent column names across imports
  3. Include name column for better personalization
  4. Remove duplicates in your source data
  5. Test with small file before large imports

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
campaign_id
integer
required

Body

multipart/form-data
​
file
file
required
​
column_mappings
string
default:{}

Response

Successful Response