Add entries

Add up to 100 records to a list.

POST /data/v1/lists/{list_id}/entries/add

cURL

cURL

curl --request POST \
  --url https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "records": [
    {
      "id": "<string>"
    }
  ]
}
'

200

{
  "status": "success",
  "data": [
    {
      "status": "added",
      "record": {
        "id": "<string>"
      },
      "entry": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "list_id": "<string>",
        "object": "<string>",
        "record_id": "<string>"
      }
    }
  ],
  "summary": {
    "total": 123,
    "added": 123,
    "already_in_list": 123,
    "record_not_found": 123,
    "object_mismatch": 123
  }
}

Overview

The add entries method adds up to 100 records to a list in one request. Each record is identified either by its ID or by match criteria on the list’s object. Both forms can be mixed in one request.

The request returns HTTP 200 whenever the body is valid, even if some records could not be added. Each item in data reports the outcome for one record, in request order:

Status	Meaning
added	The record was added to the list.
already_in_list	The record was already in the list. Nothing changed.
record_not_found	No record with this ID, or matching this match, exists.
object_mismatch	The record belongs to a different object than the list.

No records are created. Re-adding a record that is already in the list has no effect, so the request is safe to retry.

Examples

Add records by ID and by match

This adds one person by ID and one by email to a person list:

Request

POST /data/v1/lists/0b5d3c1e-6f2a-4b8e-9c71-2d4e8a6f1b03/entries/add

{
  "records": [
    { "id": "73fcb798-9ccd-4138-8f6a-9a801123783c" },
    { "match": { "email": "[e-mail]" } }
  ]
}

Usage

match works the same way as the request body of find unique record. It must include at least one unique attribute of the list’s object, such as email for a person or domain for a company.

The request fails as a whole only when:

• The body is malformed, including a record listed twice or a match that is not valid for the list’s object (HTTP 400)
• The list does not exist (HTTP 404)
• The caller does not have manage access to the list (HTTP 403)

Authorizations

x-api-key · string · header · required

Path Parameters

list_id · string · required

ID of the list. String UUIDv4 value.

Body

application/json

Request body for adding records to a list.

records · object[] · required

Up to 100 record identifiers to add, processed in request order. ID and match identifiers may be mixed. Duplicate identifiers are not allowed.

Required array length: 1 - 100 elements

Record identifier using an ID or attribute values.

Option 1

Option 2

Show child attributes

Response

200

application/json

Response for adding records to a list.

Response for adding records to a list.

status · enum<string> · required

Available options: success

data · object[] · required

One result per requested record, in request order.

Result for a record added to the list.

Option 1

Option 2

Option 3

Option 4

Show child attributes

summary · object · required

Counts of add outcomes by status.

Show child attributes