Skip to main content
POST
/
v2
/
contacts
curl -X POST "https://api.tracklysms.com/api/v2/contacts" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "use_journeys": true,
    "custom_fields": {
      "first_name": "Jane",
      "source": "landing_page_v2"
    },
    "ip_address": "203.0.113.42",
    "url": "https://example.com/signup"
  }'

{
  "success": true,
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "is_new_contact": true,
  "is_new_list_contact": true,
  "journeys_enrolled": 1
}

Documentation Index

Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt

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

Creates or updates a contact on the specified sending list. If the contact already exists on the list, their custom fields are merged (not replaced) and existing data is preserved. New contacts are automatically validated via carrier lookup, which populates carrier, timezone, and line type fields.

​
Body Parameters

​
phone_number
string
required
Contact phone number in E.164 format (e.g., +14155559876). The number is validated via carrier lookup on first creation.
​
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, the contact will be enrolled in any matching Welcome Journeys configured for the target list.
​
skip_journey_if_exists
boolean
default:"true"
When true, skips journey enrollment if the ListContact record already exists (i.e., the contact was previously added to this list). Only relevant when use_journeys is true.
​
signup_date
string
Signup date in ISO 8601 UTC format (e.g., 2025-03-15T14:30:00Z). Defaults to the current timestamp if omitted.
​
ip_address
string
IP address of the contact at the time of signup. Used for consent tracking and compliance records.
​
url
string
URL of the page where the contact signed up. Used for consent tracking and compliance records.
​
custom_fields
object
Key-value pairs of custom data to attach to the contact on this list. Values can be strings, numbers, or booleans. Custom fields are merged with any existing fields — existing keys not included in the request are preserved.
​
override_custom_fields
boolean
default:"false"
When true, replaces the contact’s custom fields entirely instead of merging. When false (default), provided custom fields are merged into existing fields.
​
ad_network_source
string
Ad network source for attribution tracking (e.g., adwords, facebook).
​
ad_network_id
string
Ad network campaign or account ID for attribution tracking.
​
use_validation
boolean
default:"false"
When true, the contact’s phone number is run through phone validation (LRN + internal DNC) and the result is attached to the response and persisted to the contact’s profile. The contact is created either way — invalid or unreachable numbers are accepted and stored, then can be segmented out of campaigns using the validation_status audience filter. The validation field in the response shows the per-disposition outcome.Billing. Requires an active payment method on file — requests without one return HTTP 402. Each non-cached lookup is billed at $0.003 (same as the /v1/phone/validate endpoint) and rolled up into your monthly invoice. Once a number has been validated for your account, repeat opt-ins of the same number are free indefinitely (validation.cached: true, validation.cost: 0). Pass force=true to bypass the cache and re-validate at $0.003 (rare; LRN data only changes on carrier porting).

​
Response Fields

​
success
boolean
Whether the operation completed successfully.
​
contact_id
string
Unique identifier of the Contact record.
​
list_contact_id
string
Unique identifier of the ListContact record (contact-on-list membership).
​
is_new_contact
boolean
true if a new Contact record was created. false if the phone number already existed in the system.
​
is_new_list_contact
boolean
true if a new ListContact record was created. false if the contact was already on this list.
​
journeys_enrolled
integer
Number of Welcome Journeys the contact was enrolled in. Always 0 if use_journeys is false.
​
warnings
array
Array of warning strings about missed configuration. For example, if there are active Welcome Journeys matching this list but use_journeys was not set to true.
​
validation
object
Present only when use_validation was true. Contains the full phone validation payload — same schema as the /v1/phone/validate response: phone, valid, line_type, carrier, carrier_raw, ported, country, state, city, on_dnc, disposition, cost, cached. The contact is created regardless of disposition — use the validation_status audience filter to segment out invalid or unreachable numbers from campaigns.

​
Examples

curl -X POST "https://api.tracklysms.com/api/v2/contacts" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "use_journeys": true,
    "custom_fields": {
      "first_name": "Jane",
      "source": "landing_page_v2"
    },
    "ip_address": "203.0.113.42",
    "url": "https://example.com/signup"
  }'

{
  "success": true,
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "is_new_contact": true,
  "is_new_list_contact": true,
  "journeys_enrolled": 1
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_phone_numberThe phone_number field was not provided in the request body.
400missing_list_numberThe list_number field was not provided in the request body.
400list_not_foundNo sending list with the given list_number exists for this account.
400invalid_phoneThe phone_number is not a valid E.164 phone number.
400invalid_list_numberThe list_number is not a valid E.164 phone number.
400not_sendableThe phone number failed carrier validation or is a VOIP number rejected by account settings.
401unauthorizedMissing or invalid X-Api-Key header.
402no_billing_config / no_payment_method / payment_failed / suspendeduse_validation=true requires an active payment method on file.
503provider_erroruse_validation=true could not reach the validation provider. Retry later.
500internal_errorAn unexpected server error occurred.
VOIP numbers may be rejected if your account has the reject_voip_numbers setting enabled. Contact support to adjust this setting.

​
Next Steps

Importing Contacts

Import contacts from CSV or API

Create Audience

Segment your contacts into audiences