Bulk Create Contacts

curl -X POST "https://api.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
}

POST

contacts

bulk

curl -X POST "https://api.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.

Show Contact object properties

phone_number

string

required

Contact phone number in E.164 format (e.g., +14155559876).

list_number

string

required

Sending list phone number in E.164 format (e.g., +18005551234). Must be a list owned by your account.

use_journeys

boolean

default:"false"

When true, enroll the contact in matching Welcome Journeys.

skip_journey_if_exists

boolean

default:"true"

Skip journey enrollment if the ListContact already exists.

Signup date in ISO 8601 UTC format. Defaults to now.

ip_address

string

IP address for consent tracking.

url

string

Signup URL for consent tracking.

custom_fields

object

Key-value pairs of custom data. Merged with existing fields.

override_custom_fields

boolean

default:"false"

When true, replaces existing custom fields entirely instead of merging.

ad_network_source

string

Ad network source for attribution tracking.

ad_network_id

string

Ad network campaign or account ID.

use_validation

boolean

default:"false"

Run phone validation before adding. Rejects invalid / unreachable dispositions. Billed $0.003 per non-cached lookup; once validated for your account, repeat lookups of the same number are free indefinitely (force=true to re-validate). See Phone Validation for disposition rules.Batch behavior. If any contact in the batch has use_validation=true, the billing gate is checked once for the whole request — a failing gate returns 402 before any contacts are processed. Rejected contacts surface in the errors array with a validation_failed code and the full validation sub-object showing why.

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.

Show Error object properties

index

integer

Zero-based index of the failed contact in the input array.

phone_number

string

Phone number of the failed contact (if provided).

code

string

Machine-readable error code (e.g., invalid_phone, list_not_found, validation_failed).

error

string

Human-readable error description.

validation

object

Present only on validation_failed errors. Full validation payload showing which disposition caused the rejection. Same schema as the /v1/phone/validate response.

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://api.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 Status	Error Code	Description
400	`missing_contacts`	The `contacts` array was not provided in the request body.
401	`unauthorized`	Missing or invalid `X-Api-Key` header.
402	`no_billing_config` / `no_payment_method` / `payment_failed` / `suspended`	At least one contact requested `use_validation=true` but the account has no active payment method. The whole batch is rejected.
413	`too_many_contacts`	The `contacts` array exceeds the 1,000 item limit.
500	`internal_error`	An unexpected server error occurred.

Per-Contact Error Codes

These codes appear in the errors array for individual contacts that failed:

Code	Description
`missing_phone_number`	The contact object is missing the `phone_number` field.
`missing_list_number`	The contact object is missing the `list_number` field.
`invalid_phone`	The phone number is not a valid E.164 number.
`invalid_list_number`	The list number is not a valid E.164 number.
`list_not_found`	No sending list with the given `list_number` exists for this account.
`not_sendable`	The phone number failed carrier validation or is a rejected VOIP number.
`validation_failed`	`use_validation=true` rejected the number (disposition `invalid` or `unreachable`). The `validation` sub-object shows why.
`provider_error`	`use_validation=true` could not reach the validation provider for this number. Other contacts in the batch are still processed.
`payload_too_large`	The 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

Update Contact Get Contact

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Body Parameters

Response Fields

Examples

Error Codes

Per-Contact Error Codes

Next Steps

Importing Contacts

Create Audience

API Reference

V2 API Reference

Messages (v2)

Contacts (v2)

Lists (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Data Import (v2)

Links (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Documentation Index

​Body Parameters

​Response Fields

​Examples

​Error Codes

​Per-Contact Error Codes

​Next Steps

Importing Contacts

Create Audience

Body Parameters

Response Fields

Examples

Error Codes

Per-Contact Error Codes

Next Steps