Skip to main content
POST
/
contact
curl --request POST \
  --url https://api.sendx.io/api/v1/rest/contact \
  --header 'Content-Type: application/json' \
  --header 'X-Team-ApiKey: <api-key>' \
  --data '
{
  "email": "[email protected]"
}
'
{
  "id": "contact_BnKjkbBBS500CoBCP0oChQ",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "company": "Example Corp",
  "customFields": {
    "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering",
    "field_QqfhckbdcvQinLPlduIbHq": "Senior"
  },
  "lists": [
    "list_OcuxJHdiAvujmwQVJfd3ss",
    "list_xyz789ghi012"
  ],
  "tags": [
    "tag_UhsDkjL772Qbj5lWtT62VK",
    "tag_UhsDkjL772Qbj5lWtT62VK"
  ],
  "unsubscribed": false,
  "bounced": false,
  "spam": false,
  "blocked": false,
  "dropped": false,
  "created": "2024-01-10T14:20:00Z",
  "updated": "2024-01-15T09:15:00Z",
  "trackData": "utm_source=website&utm_campaign=signup&utm_medium=banner",
  "contactSource": 1,
  "pageSource": "https://example.com/signup?ref=google-ads",
  "lastTrackedIp": "203.0.113.42",
  "LTV": 7500
}

Authorizations

​
X-Team-ApiKey
string
header
required

Team API key for authentication. Find your API key in SendX Settings → Team API Key.

Example:

X-Team-ApiKey: your_team_api_key_here

Body

application/json
​
email
string<email>
required

Email address of the contact (required and must be unique within team).

Validation:

  • Must be a valid email format
  • Must be unique within the team
  • Cannot be empty or null
Maximum string length: 255
Example:

"[email protected]"

​
firstName
string

First name of the contact

Maximum string length: 255
Example:

"John"

​
lastName
string

Last name of the contact

Maximum string length: 255
Example:

"Doe"

​
company
string

Company name of the contact

Maximum string length: 255
Example:

"Example Corp"

​
customFields
object

Custom fields as key-value pairs. Keys should use custom_field_ prefix.

Processing:

  • Keys are case-sensitive
  • Values are stored as strings

Examples:

  • "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering" → stored as department: Engineering
Example:
{
  "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering",
  "field_QqfhckbdcvQinLPlduIbHq": "Senior"
}
​
lists
string[]

Array of list identifiers to associate with the contact. Identifiers should use list_ prefix.

Processing:

  • Invalid list IDs will send our 400 error
  • Duplicates will be removed

Examples:

  • "list_OcuxJHdiAvujmwQVJfd3ss" → valid prefixed format
Example:
["list_OcuxJHdiAvujmwQVJfd3ss"]
​
tags
string[]

Array of tag identifiers to associate with the contact. Identifiers should use tag_ prefix.

Processing:

  • Invalid tag IDs will be ignored
  • Duplicates will be removed

Examples:

  • "tag_UhsDkjL772Qbj5lWtT62VK" → valid prefixed format
Example:
["tag_UhsDkjL772Qbj5lWtT62VK"]
​
lastTrackedIp
string<ipv4>

Last tracked IP address of the contact for analytics purposes.

Usage:

  • Used for geographic analytics
  • Helps with spam detection
  • Optional field
Example:

"192.168.1.100"

Response

✅ Contact created successfully

​
id
string

Unique contact identifier with contact_ prefix.

Format: contact_ + 22 alphanumeric characters

Usage:

  • Use this ID for all subsequent API calls
  • Unique across the entire SendX platform
  • Never changes once created
Example:

"contact_BnKjkbBBS500CoBCP0oChQ"

​
firstName
string | null

First name of the contact

Example:

"John"

​
lastName
string | null

Last name of the contact

Example:

"Doe"

​
email
string<email>

Email address of the contact (unique within team)

Example:

"[email protected]"

​
company
string | null

Company name of the contact

Example:

"Example Corp"

​
customFields
object

Custom fields with custom_field_ prefixed keys.

Format: All keys have custom_field_ prefix in responses

Example Structure:

{
  "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering",
  "field_QqfhckbdcvQinLPlduIbHq": "Senior",
  "field_MnuqBAG2NPLm7PZMWbjQxt": "$75000"
}
Example:
{
  "field_MnuqBAG2NPLm7PZMWbjQxt": "Engineering",
  "field_QqfhckbdcvQinLPlduIbHq": "Senior"
}
​
lists
string[]

Associated lists with list_ prefixed identifiers.

Format: All IDs have list_ prefix in responses

Example:
[
  "list_OcuxJHdiAvujmwQVJfd3ss",
  "list_xyz789ghi012"
]
​
tags
string[]

Associated tags with tag_ prefixed identifiers.

Format: All IDs have tag_ prefix in responses

Example:
[
  "tag_UhsDkjL772Qbj5lWtT62VK",
  "tag_UhsDkjL772Qbj5lWtT62VK"
]
​
unsubscribed
boolean

Whether the contact has unsubscribed from emails

Example:

false

​
bounced
boolean

Whether emails to this contact have bounced

Example:

false

​
spam
boolean

Whether the contact has marked emails as spam

Example:

false

​
blocked
boolean

Whether the contact is blocked from receiving emails

Example:

false

​
dropped
boolean

Whether emails to this contact have been dropped

Example:

false

​
created
string<date-time>

Contact creation timestamp (ISO 8601 format)

Example:

"2024-01-10T14:20:00Z"

​
updated
string<date-time>

Contact last update timestamp (ISO 8601 format)

Example:

"2024-01-15T09:15:00Z"

​
trackData
string

Email tracking data and UTM parameters.

Contains:

  • UTM parameters from campaigns
  • Attribution data
  • Custom tracking parameters
Example:

"utm_source=website&utm_campaign=signup&utm_medium=banner"

​
contactSource
integer

Source type of the contact creation.

Values:

  • 1 - API/Manual
  • 2 - Import
  • 3 - Form
  • 4 - Integration
Example:

1

​
pageSource
string | null

URL of the page where contact was created

Example:

"https://example.com/signup?ref=google-ads"

​
lastTrackedIp
string<ipv4> | null

Last tracked IP address of the contact

Example:

"203.0.113.42"

​
LTV
integer

Lifetime Value of the contact in cents.

Example: 7500 = $75.00

Example:

7500