Upsert Contact - AutoSend Documentation

POST

contacts

curl --request POST \
  --url https://api.autosend.com/v1/contacts/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "userId": "user_12345",
  "customFields": {
    "company": "Acme Corp",
    "role": "Developer",
    "plan": "premium"
  }
}'

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    },
    "listIds": ["507f1f77bcf86cd799439011"],
    "segmentIds": [],
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "projectId": "229f1f77bcf86cd9273048038"
  }
}

curl --request POST \
  --url https://api.autosend.com/v1/contacts/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "userId": "user_12345",
  "customFields": {
    "company": "Acme Corp",
    "role": "Developer",
    "plan": "premium"
  }
}'

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    },
    "listIds": ["507f1f77bcf86cd799439011"],
    "segmentIds": [],
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "projectId": "229f1f77bcf86cd9273048038"
  }
}

This is the recommended endpoint for most contact synchronization scenarios.

Authorizations

string | header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Contact information to create or update

string<email>

required

Valid email address (automatically normalized to lowercase)Example: "[email protected]"

firstName

string

Contact’s first nameExample: "John"

lastName

string

Contact’s last nameExample: "Doe"

userId

string

An optional reference field to store your application’s user ID. Use this to map your internal users to AutoSend contacts.Example: "user_12345"

listIds

array

IDs of the contact lists to add this contact to. You can find list IDs in your AutoSend Dashboard.Do not pass segment IDs here. Segments are computed automatically based on contact field values. Adding a contact to a list will also trigger any live automations associated with that list.Example: ["507f1f77bcf86cd799439011"]

customFields

object

Key-value pairs for custom contact attributes. There are four supported value types: string, number, boolean, and date. Learn more about custom fields.

Show child attributes

customFields.{key}

string

Example:

customFields: {
  "company": "Acme Corp",
  "isPremium": true,
  "loginCount": 42,
  "trialEndsAt": "2024-03-01"
}

Response

Contact created or updated successfully

success

boolean

Indicates if the request was successfulExample: true

data

object

Show child attributes

data.id

string

Contact IDExample: "507f1f77bcf86cd799439011"

data.email

string

Contact email addressExample: "[email protected]"

data.firstName

string

Contact’s first nameExample: "John"

data.lastName

string

Contact’s last nameExample: "Doe"

data.userId

string

Your application’s user identifierExample: "user_12345"

data.customFields

object

Custom contact attributes

Show child attributes

customFields.{key}

string

Example:

customFields: {
  "company": "Acme Corp",
  "role": "Developer",
  "plan": "premium"
}

data.createdAt

string

Contact creation timestampExample: "2024-01-15T10:30:00.000Z"

data.updatedAt

string

Contact last update timestampExample: "2024-01-15T10:30:00.000Z"

data.projectId

string

Project ID that the contact belongs toExample: "229f1f77bcf86cd9273048038"

data.listIds

array

Contact List IDsExample: ["507f1f77bcf86cd799439011"]

data.segmentIds

array

Segment IDs the contact belongs to (computed automatically based on contact field values)Example: []

Create Contact

Remove Contacts

curl --request POST \
  --url https://api.autosend.com/v1/contacts/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "userId": "user_12345",
  "customFields": {
    "company": "Acme Corp",
    "role": "Developer",
    "plan": "premium"
  }
}'

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "userId": "user_12345",
    "customFields": {
      "company": "Acme Corp",
      "role": "Developer",
      "plan": "premium"
    },
    "listIds": ["507f1f77bcf86cd799439011"],
    "segmentIds": [],
    "updatedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "projectId": "229f1f77bcf86cd9273048038"
  }
}

​Authorizations

​Body

​Response

Authorizations

Body

Response