Create contact

Create a new contact with an email address and any other contact properties.

POST /v1/contacts/create

Create contact

cURL

curl --request POST \
  --url https://app.loops.so/api/v1/contacts/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "source": "<string>",
  "subscribed": true,
  "userGroup": "<string>",
  "userId": "<string>",
  "mailingLists": {}
}
'

Response

{
  "success": true,
  "id": "id_of_contact"
}

If you want to “update or create” contacts, consider using the Update a contact endpoint instead.

Request

Body

email · string · required

The contact’s email address.

firstName · string

The contact’s first name.

lastName · string

The contact’s last name.

source · string

A custom source value to replace the default “API”. Read more

subscribed · boolean · default: true

Whether the contact will receive campaign and workflow emails. Read more

We recommend leaving this field out of your requests unless you specifically want to unsubscribe or re-subscribe a contact. All new contacts are subscribed by default.

userGroup · string

You can use groups to segment users when sending emails. Currently, a contact can only be in one user group. Read more

userId · string

A unique user ID (for example, from an external application). Read more

mailingLists · object

Manage mailing list subscriptions.
Include key-value pairs of mailing list IDs and a boolean denoting if the contact should be added (true) or removed (false) from the list. Read more

"mailingLists": {
  "cm06f5v0e45nf0ml5754o9cix": true,
  "cm16k73gq014h0mmj5b6jdi9r": false
}

Custom properties

You can also include custom contact properties in your request body. These should be added as top-level attributes in the request.

Custom properties can be of type string, number, boolean or date (see allowed date formats).

{
  "email": "[e-mail]",
  "plan": "pro" /* Custom property */,
  "dateJoined": 1704711066 /* Custom property */
}

There are a few reserved names that you cannot use for custom properties.

To empty or reset the value of a contact property, send a null value.

Response

Success

success · boolean · required

id · string · required

The internal ID of the new contact.

Error

If a matching contact already exists in your audience, a 409 Conflict error will be returned. All other errors will be 400 Bad Request.

success · boolean · required

message · string · required

An error message describing the problem with the request.

Response

{
  "success": true,
  "id": "id_of_contact"
}