Create Contact

Create a new contact in your workspace.

---

Endpoint

POST https://api.campaignlark.com/v1/contacts

---

Request Body

Field	Type	Required	Description
fields	object	required	Key-value map of contact field values, keyed by merge_tag. email_address is always required. Any workspace fields marked required: true must also be provided. Use the List All Fields endpoint to check which fields are required.
tags	array of integers	optional	Tag IDs to assign to the contact.
status	string	required	Initial contact status. One of SUBSCRIBED, UNSUBSCRIBED, UNCONFIRMED, CLEANED, COMPLAINED.

---

Sample Request

POST https://api.campaignlark.com/v1/contacts
Content-Type: application/json

{
  "fields": {
    "email_address": "tywin@example.com",
    "first_name": "Tywin",
    "last_name": "Lannister"
  },
  "tags": [1, 2],
  "status": "SUBSCRIBED"
}

---

Response

Success — 201 Created

Returns the full contact object.

{
  "data": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "status": "SUBSCRIBED",
    "tags": [
      { "id": 1, "name": "newsletter" },
      { "id": 2, "name": "vip" }
    ],
    "data": {
      "email_address": "tywin@example.com",
      "first_name": "Tywin",
      "last_name": "Lannister"
    },
    "statistics": {
      "total_opens": 0,
      "total_clicks": 0,
      "total_bounces": 0,
      "total_delivered": 0
    },
    "created_at": "2024-02-15T10:30:00Z",
    "updated_at": "2024-02-15T10:30:00Z"
  }
}

---

Automation Behaviour

If the contact is created with status UNCONFIRMED, the Contact Subscribed (Pending) automation event is triggered, this is important for double opt-in workflows. No automation event fires for any other status on creation.

---

Errors

Status	Message	Cause
400	Please provide at least one field for the contact.	fields is empty or missing.
400	Contact status is required.	status field is missing.
400	The status you provided is not valid.	status is not one of the accepted values.
400	An email address is required.	email_address is missing or empty in fields.
400	Field '<label>' is required.	A workspace-required field was not provided or was empty.
400	We were unable to find a field with the merge_tag <tag>	A key in fields doesn't match any workspace merge tag.