Skip to main content
POST
/
v2
/
contacts
curl -X POST "https://app.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
}
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.

​
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.

​
Examples

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