Contacts

Contacts are the recipients of your campaigns.

List Contacts

GET /contacts

Query parameters:

Parameter	Type	Description
page	integer	Page number
per_page	integer	Items per page (max 100)
search	string	Search by email, name, company
status	string	Filter by status: active, unsubscribed, bounced
list_id	integer	Filter by list
tag_id	integer	Filter by tag

Example:

curl "https://app.beeving.com/api/v1/contacts?status=active&per_page=50" \
  -H "Authorization: Bearer TOKEN"

Create a Contact

POST /contacts

Request body:

{
  "email": "alice@example.com",
  "first_name": "Alice",
  "last_name": "Martin",
  "company": "Acme Corp",
  "phone": "+33612345678",
  "custom_fields": {
    "plan": "pro",
    "trial_end": "2026-03-15"
  },
  "tags": [1, 2],
  "lists": [3]
}

Response 201:

{
  "id": 42,
  "email": "alice@example.com",
  "first_name": "Alice",
  "last_name": "Martin",
  "full_name": "Alice Martin",
  "company": "Acme Corp",
  "status": "active",
  "custom_fields": { "plan": "pro" },
  "subscribed_at": "2026-02-23T10:00:00.000Z",
  "created_at": "2026-02-23T10:00:00.000Z",
  "updated_at": "2026-02-23T10:00:00.000Z",
  "tags": [...],
  "lists": [...]
}

Import from CSV

POST /contacts/import

Form data:

Field	Type	Description
file	file	CSV file (max 10 MB)
mapping[email]	string	Email column name
mapping[first_name]	string	First name column
mapping[last_name]	string	Last name column
skip_duplicates	boolean	Skip duplicates (default: true)

curl -X POST https://app.beeving.com/api/v1/contacts/import \
  -H "Authorization: Bearer TOKEN" \
  -F "file=@contacts.csv" \
  -F "mapping[email]=Email" \
  -F "mapping[first_name]=FirstName" \
  -F "skip_duplicates=true"

Unsubscribe a Contact

POST /contacts/{id}/unsubscribe

Sets the contact status to unsubscribed and records the unsubscription date.