Skip to main content
POST
/
v2
/
contacts
/
bulk
curl -X POST "https://app.tracklysms.com/api/v2/contacts/bulk" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone_number": "+14155559876",
        "list_number": "+18005551234",
        "use_journeys": true,
        "custom_fields": {"first_name": "Jane"}
      },
      {
        "phone_number": "+12125551000",
        "list_number": "+18005551234",
        "custom_fields": {"first_name": "John"}
      },
      {
        "phone_number": "+13105558888",
        "list_number": "+18005551234",
        "signup_date": "2025-03-10T08:00:00Z",
        "ip_address": "198.51.100.17"
      }
    ]
  }'

{
  "success_count": 2,
  "error_count": 1,
  "errors": [
    {
      "index": 2,
      "phone_number": "+13105558888",
      "code": "not_sendable",
      "error": "Phone number failed carrier validation"
    }
  ],
  "contacts_created": 2,
  "list_contacts_created": 2,
  "journeys_enrolled": 1
}
Creates or updates multiple contacts in a single batch operation. Each contact in the array follows the same schema as the single Create Contact endpoint. The operation processes all contacts and returns a summary with individual error details for any that failed. Contacts that fail validation do not prevent other contacts in the batch from being processed. Check the errors array in the response for per-contact failure details.

​
Body Parameters

​
contacts
array
required
Array of contact objects to create. Maximum of 1,000 contacts per request.

​
Response Fields

​
success_count
integer
Number of contacts that were successfully created or updated.
​
error_count
integer
Number of contacts that failed validation or processing.
​
errors
array
Array of error objects for contacts that failed.
​
contacts_created
integer
Number of new Contact records created (phone numbers not previously in the system).
​
list_contacts_created
integer
Number of new ListContact records created (new contact-on-list memberships).
​
journeys_enrolled
integer
Total number of journey enrollments across all contacts in the batch.
​
warnings
array
Array of warning strings about missed configuration, such as active Welcome Journeys matching the list when use_journeys was not set.

​
Examples

curl -X POST "https://app.tracklysms.com/api/v2/contacts/bulk" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone_number": "+14155559876",
        "list_number": "+18005551234",
        "use_journeys": true,
        "custom_fields": {"first_name": "Jane"}
      },
      {
        "phone_number": "+12125551000",
        "list_number": "+18005551234",
        "custom_fields": {"first_name": "John"}
      },
      {
        "phone_number": "+13105558888",
        "list_number": "+18005551234",
        "signup_date": "2025-03-10T08:00:00Z",
        "ip_address": "198.51.100.17"
      }
    ]
  }'

{
  "success_count": 2,
  "error_count": 1,
  "errors": [
    {
      "index": 2,
      "phone_number": "+13105558888",
      "code": "not_sendable",
      "error": "Phone number failed carrier validation"
    }
  ],
  "contacts_created": 2,
  "list_contacts_created": 2,
  "journeys_enrolled": 1
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_contactsThe contacts array was not provided in the request body.
401unauthorizedMissing or invalid X-Api-Key header.
413too_many_contactsThe contacts array exceeds the 1,000 item limit.
500internal_errorAn unexpected server error occurred.

​
Per-Contact Error Codes

These codes appear in the errors array for individual contacts that failed:
CodeDescription
missing_phone_numberThe contact object is missing the phone_number field.
missing_list_numberThe contact object is missing the list_number field.
invalid_phoneThe phone number is not a valid E.164 number.
invalid_list_numberThe list number is not a valid E.164 number.
list_not_foundNo sending list with the given list_number exists for this account.
not_sendableThe phone number failed carrier validation or is a rejected VOIP number.
payload_too_largeThe individual contact payload exceeds the 4KB limit.
For large imports exceeding 1,000 contacts, split your data into batches and send multiple requests. Consider adding a brief delay between batches to avoid rate limiting.

​
Next Steps

Importing Contacts

Learn about import options and formats

Create Audience

Segment your new contacts