Import contacts | Talkif Docs

curl -X POST https://api.talkif.ai/api/v1/contacts/import \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "fileContent": "Sm9obiBEb2UsKzE1NTUxMjM0NTY3",
  "format": "vcf"
}'

{
  "errors": [
    {
      "message": "Invalid phone format: 555-1234. Must be E.164 format (e.g., +15551234567)",
      "reason": "INVALID_PHONE_FORMAT",
      "row": 7,
      "contactName": "Jane Smith",
      "phone": "+15551234567"
    }
  ],
  "failed": 15,
  "imported": 120,
  "skipped": 15,
  "totalRows": 150,
  "preview": [
    {
      "name": "Jane Smith",
      "primaryPhone": "+15551234567",
      "address": null,
      "company": "Acme Corp",
      "email": "jane@example.com",
      "interests": [
        "healthcare",
        "scheduling"
      ],
      "language": "en",
      "notes": "string",
      "occupation": "Product Manager",
      "secondaryPhones": [
        "+15559876543"
      ],
      "tags": [
        "vip",
        "priority"
      ],
      "timezone": "America/New_York"
    }
  ],
  "skippedPreview": [
    {
      "phone": "+15551234567",
      "reason": "Duplicate phone number already exists",
      "row": 3,
      "name": "Jane Smith"
    }
  ]
}

Authentication

AuthorizationBearer

Pass a JWT access token or an API key (prefixed with tif_live_) as a Bearer token.

Request

This endpoint expects an object.

fileContentstringRequired

Base64-encoded file content (VCF, CSV, or JSON)

formatenumRequired

File format of the encoded content

confirmedbooleanOptional

Set to true to execute the import; false returns a dry-run preview

defaultCountryCodestring or nullOptional

Default country code for phone numbers without + prefix

duplicateStrategyenumOptional

How to handle contacts whose phone number already exists (default: skip)

Response

Import result

errorslist of objects

Detailed error information for each failed row

failedinteger>=0

Number of contacts that failed validation

importedinteger>=0

Number of contacts successfully imported

skippedinteger>=0

Number of contacts skipped due to duplicate phone numbers

totalRowsinteger>=0

Total number of rows parsed from the file

previewlist of objects or nullOptional

Preview of first 10 contacts that will be imported (only in preview mode)

skippedPreviewlist of objects or nullOptional

Preview of first 10 skipped contacts with reasons (only in preview mode)

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error