Add entries

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>"
    }
  ]
}
'

import requests

url = "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add"

payload = { "records": [{ "id": "<string>" }] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({records: [{id: '<string>'}]})
};

fetch('https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'records' => [
        [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": "bad_request",
  "errors": [
    {
      "code": "<string>",
      "path": [
        "<string>"
      ],
      "object_api_name": "<string>",
      "attribute_api_name": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "status": "unauthorized",
  "message": "<string>"
}

{
  "status": "forbidden",
  "message": "<string>"
}

{
  "status": "list_not_found",
  "message": "<string>"
}

{
  "status": "rate_limited",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

POST

lists

{list_id}

entries

add

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>"
    }
  ]
}
'

import requests

url = "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add"

payload = { "records": [{ "id": "<string>" }] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({records: [{id: '<string>'}]})
};

fetch('https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'records' => [
        [
                'id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add"

	payload := strings.NewReader("{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unifygtm.com/data/v1/lists/{list_id}/entries/add")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"records\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "status": "bad_request",
  "errors": [
    {
      "code": "<string>",
      "path": [
        "<string>"
      ],
      "object_api_name": "<string>",
      "attribute_api_name": "<string>"
    }
  ],
  "message": "<string>"
}

{
  "status": "unauthorized",
  "message": "<string>"
}

{
  "status": "forbidden",
  "message": "<string>"
}

{
  "status": "list_not_found",
  "message": "<string>"
}

{
  "status": "rate_limited",
  "message": "<string>"
}

{
  "status": "error",
  "message": "<string>"
}

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:

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

{
  "records": [
    { "id": "73fcb798-9ccd-4138-8f6a-9a801123783c" },
    { "match": { "email": "ada@acme.com" } }
  ]
}

{
  "status": "success",
  "data": [
    {
      "status": "added",
      "record": { "id": "73fcb798-9ccd-4138-8f6a-9a801123783c" },
      "entry": {
        "id": "c4a1e2f0-8b3d-4e6a-9f12-5d7c8b9a0e14",
        "list_id": "0b5d3c1e-6f2a-4b8e-9c71-2d4e8a6f1b03",
        "object": "person",
        "record_id": "73fcb798-9ccd-4138-8f6a-9a801123783c",
        "original_added_at": "2026-10-01T12:00:00Z",
        "latest_added_at": "2026-10-01T12:00:00Z",
        "created_at": "2026-10-01T12:00:00Z",
        "updated_at": "2026-10-01T12:00:00Z"
      }
    },
    {
      "status": "record_not_found",
      "record": { "match": { "email": "ada@acme.com" } }
    }
  ],
  "summary": {
    "total": 2,
    "added": 1,
    "already_in_list": 0,
    "record_not_found": 1,
    "object_mismatch": 0
  }
}

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.

A match that finds no record is reported as record_not_found; no record is created. A match that is not valid for the list's object fails the request with HTTP 400.

Records are applied in request order: when two records resolve to the same record (such as an ID and a match for that record), the later one is reported as already_in_list.

records

object[]

required

Records to add, at most 100 per request. Each record must appear only once in the request.

Required array length: 1 - 100 elements

Identifies a record to add to or remove from a list, either by ID or by match criteria. Both forms can be mixed in one request.

Option 1
Option 2

Show child attributes

Response

Response for an add request. Returned with HTTP 200 whenever the request itself was valid, even if some or all records could not be added; inspect summary and each item's status for per-record outcomes.

status

enum<string>

required

Available options:

success

data

object[]

required

One result per requested record, in request order.

The record was added to the list.

Option 1
Option 2
Option 3
Option 4

Show child attributes

summary

object

required

Counts of add outcomes by status. total equals the number of records in the request and the sum of the other counts.

Show child attributes

⌘I

Unify Platform

MCP

Developer Guides

API Reference

SDKs

Overview

Examples

Usage

Authorizations

Path Parameters

Body

Response

​Overview

​Examples

​Usage

Authorizations

Path Parameters

Body

Response

Overview

Examples

Usage