> ## Documentation Index
> Fetch the complete documentation index at: https://developer.effilink.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Contacts API — Upsert, Import, Retrieve, and Delete
> Create, update, bulk import, retrieve, and delete contacts via the EffiLink Contacts API. Supports list assignment and sandbox testing.
## Authentication
All endpoints accept either an `ApiKey` header or an `OAuth` header. See the [OAuth Endpoints](/api/oauth) 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
Display name for the contact. Defaults to the email address if omitted.
Email address of the contact. Required if `phoneNumber` is not provided.
Phone number of the contact. Required if `email` is not provided.
Name of an existing contact list to add this contact to after upserting.
When `true`, the operation is simulated and no data is persisted.
### Response
`200` on success.
Empty string on success; an error description on failure.
```bash theme={null}
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"
}'
```
```json Response theme={null}
{
"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
A two-dimensional array of contact values. Each inner array represents one contact row; column order must match `contactDataMapping`.
Describes which property each column maps to.
Zero-based index of the column in `contactData`.
Property identifier for the column (e.g. `email`, `name`). See the Contact Properties reference for valid values.
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.
Name of a contact list to add all imported contacts to.
Description applied when a new list is created via `listName`.
When `true`, the operation is simulated and no data is persisted.
### Response
`200` on success.
Empty string on success; an error description on failure.
```bash theme={null}
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"
}'
```
```json Response theme={null}
{
"code": 200,
"message": ""
}
```
***
## Get Contact
Retrieves a single contact record by email address.
### Request Body
Email address of the contact to retrieve.
### Response
`200` on success.
Empty string on success; an error description on failure.
The matched contact record.
Unique identifier for the contact.
Display name of the contact.
Email address of the contact.
Phone number of the contact.
Key-value map of custom and system properties (e.g. `company`, `email_bounced_flag`, `email_open_count`). All values are strings.
ISO 8601 timestamp of when the contact was created.
ISO 8601 timestamp of the most recent update.
ID of the user who created the contact.
```bash theme={null}
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"}'
```
```json Response theme={null}
{
"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
Name of the contact list to retrieve contacts from.
Number of contacts to return per page. Defaults to `200`; maximum is `1000`.
One-based page number. Defaults to `1`.
Query a list belonging to another team. Requires special cross-team permission.
### Response
`200` on success.
Empty string on success; an error description on failure.
Array of contact records. Each object contains the same fields as the [Get Contact](#get-contact) response: `id`, `name`, `email`, `phoneNumber`, `properties`, `createDate`, `modifyTime`, and `createUserId`.
Total number of contacts in the list across all pages.
***
## Delete Contact
Permanently deletes a contact identified by email address.
### Request Body
Email address of the contact to delete.
When `true`, the operation is simulated and no data is deleted.
### Response
`200` on success.
Empty string on success; an error description on failure.
```json Response theme={null}
{
"code": 200,
"message": ""
}
```