Imports

The Imports API lets you bulk import contacts programmatically — ideal for ETL pipelines and automated data sync workflows.

API Bulk Import

For programmatic imports, use the JSON-based bulk import endpoint. It accepts an array of contacts directly without requiring a file upload.

POST /v1/imports/api/bulk

Request Body:

Field	Type	Required	Description
`contacts`	array	Yes	Array of contact objects to import (max 10,000 per request)
`audienceId`	string	No	Add all imported contacts to this audience
`webhookUrl`	string	No	URL to notify when import completes

Contact Object:

Field	Type	Required	Description
`name`	string	Yes	Contact's full name
`phoneNumber`	string	Yes	E.164 format
`language`	string	No	Language code (e.g., `hi-IN`)
`[any key]`	any	No	Extra fields become metadata

Example:

{
  "contacts": [
    {
      "name": "Priya Sharma",
      "phoneNumber": "+919876543210",
      "language": "hi-IN",
      "city": "Mumbai",
      "tier": "premium"
    },
    {
      "name": "Ravi Kumar",
      "phoneNumber": "+919123456789",
      "language": "en-IN",
      "city": "Delhi",
      "tier": "standard"
    }
  ],
  "audienceId": "aud_abc123",
  "webhookUrl": "https://your-app.com/webhooks/import-done"
}

Response:

{
  "importId": "imp_ghi789",
  "status": "PROCESSING",
  "total": 2
}

The import processes asynchronously. Use the importId to check status.

Get Import Status

GET /v1/imports/:id/status

Response:

{
  "id": "imp_ghi789",
  "status": "COMPLETED",
  "total": 2,
  "created": 2,
  "updated": 0,
  "failed": 0,
  "errorCount": 0,
  "completedAt": "2026-03-10T10:05:00.000Z"
}

Import Statuses:

Status	Description
`PENDING`	Queued, not yet started
`PROCESSING`	Currently running
`COMPLETED`	Finished successfully
`COMPLETED_WITH_ERRORS`	Finished but some rows failed
`FAILED`	Import failed entirely

List Imports

GET /v1/imports

Returns your organization's import history.

Query Parameters: page, limit

Webhook Notification

If you provide a webhookUrl, OliAI sends a POST request when the import completes:

{
  "event": "import.completed",
  "importId": "imp_ghi789",
  "status": "COMPLETED",
  "total": 2,
  "created": 2,
  "updated": 0,
  "failed": 0,
  "completedAt": "2026-03-10T10:05:00.000Z"
}

Webhook delivery is best-effort. Always poll the status endpoint as a fallback for critical workflows.

File-Based Import (UI only)

For CSV/Excel/JSON file imports, use the Contacts UI. The file upload endpoints (POST /v1/imports/upload) are not available via API key authentication.

Large Dataset Recommendations

For datasets larger than 10,000 contacts:

Split into batches of 5,000–10,000 contacts
Send batches sequentially (wait for each COMPLETED before sending the next)
Use the webhook to trigger the next batch automatically

Voice Flows