Contacts API — Upsert, Import, Retrieve, and Delete

Authentication

All endpoints accept either an ApiKey header or an OAuth header. See the OAuth Endpoints page for token generation.

Upsert Contact

Creates a new contact or updates an existing one. At least one of email or phoneNumber is required.

Request Body

string

Display name for the contact. Defaults to the email address if omitted.

string

required

Email address of the contact. Required if phoneNumber is not provided.

string

required

Phone number of the contact. Required if email is not provided.

string

Name of an existing contact list to add this contact to after upserting.

boolean

When true, the operation is simulated and no data is persisted.

Response

integer

200 on success.

string

Empty string on success; an error description on failure.

curl --request POST \
  --url https://api.effilink.co/v5/contacts/upsert \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phoneNumber": "18800008888",
    "listName": "Newsletter Subscribers"
  }'

Response

{
  "code": 200,
  "message": ""
}

Bulk Import Contacts

Imports multiple contacts in a single request using a 2-D array format paired with a column-mapping definition.

Request Body

array[array]

required

A two-dimensional array of contact values. Each inner array represents one contact row; column order must match contactDataMapping.

array[object]

required

Describes which property each column maps to.

Show contactDataMapping object

integer

required

Zero-based index of the column in contactData.

string

required

Property identifier for the column (e.g. email, name). See the Contact Properties reference for valid values.

integer

required

Controls how existing contacts are handled:

1 — Create new contacts and update existing ones.
2 — Create new contacts only; skip existing ones.
3 — Update existing contacts only; skip new ones.

string

Name of a contact list to add all imported contacts to.

string

Description applied when a new list is created via listName.

boolean

When true, the operation is simulated and no data is persisted.

Response

integer

200 on success.

string

Empty string on success; an error description on failure.

curl --request POST \
  --url https://api.effilink.co/v5/contacts/imports \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "contactData": [
      ["alice@example.com", "Alice Chen"],
      ["bob@example.com", "Bob Wang"]
    ],
    "contactDataMapping": [
      {"columnNum": 0, "propertyName": "email"},
      {"columnNum": 1, "propertyName": "name"}
    ],
    "updateMode": 1,
    "listName": "Q2 Campaign"
  }'

Response

{
  "code": 200,
  "message": ""
}

Get Contact

Retrieves a single contact record by email address.

Request Body

string

required

Email address of the contact to retrieve.

Response

integer

200 on success.

string

Empty string on success; an error description on failure.

object

The matched contact record.

Show contact object

string

Unique identifier for the contact.

string

Display name of the contact.

string

Email address of the contact.

string

Phone number of the contact.

object

Key-value map of custom and system properties (e.g. company, email_bounced_flag, email_open_count). All values are strings.

string

ISO 8601 timestamp of when the contact was created.

string

ISO 8601 timestamp of the most recent update.

integer

ID of the user who created the contact.

curl --request POST \
  --url https://api.effilink.co/v5/contacts/get \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{"email": "alice@example.com"}'

Response

{
  "code": 200,
  "message": "",
  "contact": {
    "id": "653f663a17e04f6e5a263de6",
    "name": "Alice Chen",
    "email": "alice@example.com",
    "phoneNumber": "18800008888",
    "properties": {
      "company": "Acme Inc",
      "email_bounced_flag": "0",
      "email_open_count": "5"
    },
    "createDate": "2024-01-15T08:00:00.000Z",
    "modifyTime": "2025-04-21T05:53:01.089Z",
    "createUserId": 42
  }
}

Get Contacts in List

Returns a paginated list of contacts belonging to a named contact list.

Request Body

string

required

Name of the contact list to retrieve contacts from.

integer

Number of contacts to return per page. Defaults to 200; maximum is 1000.

integer

One-based page number. Defaults to 1.

string

Query a list belonging to another team. Requires special cross-team permission.

Response

integer

200 on success.

string

Empty string on success; an error description on failure.

array[object]

Array of contact records. Each object contains the same fields as the Get Contact response: id, name, email, phoneNumber, properties, createDate, modifyTime, and createUserId.

integer

Total number of contacts in the list across all pages.

Delete Contact

Permanently deletes a contact identified by email address.

Request Body

string

required

Email address of the contact to delete.

boolean

When true, the operation is simulated and no data is deleted.

Response

integer

200 on success.

string

Empty string on success; an error description on failure.

Response

{
  "code": 200,
  "message": ""
}

Transactional Email

Campaign Email

SMS

Contacts & Lists

Webhooks

Authentication

Contacts API — Upsert, Import, Retrieve, and Delete

Authentication

Upsert Contact

Request Body

Response

Bulk Import Contacts

Request Body

Response

Get Contact

Request Body

Response

Get Contacts in List

Request Body

Response

Delete Contact

Request Body

Response

​Authentication

​Upsert Contact

​Request Body

​Response

​Bulk Import Contacts

​Request Body

​Response

​Get Contact

​Request Body

​Response

​Get Contacts in List

​Request Body

​Response

​Delete Contact

​Request Body

​Response

Authentication

Upsert Contact

Request Body

Response

Bulk Import Contacts

Request Body

Response

Get Contact

Request Body

Response

Get Contacts in List

Request Body

Response

Delete Contact

Request Body

Response