> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifygtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add entries

> Add up to 100 records to a list.

## 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

<AccordionGroup>
  <Accordion title="Add records by ID and by match">
    This adds one person by ID and one by email to a person list:

    <CodeGroup>
      ```http Request theme={null}
      POST /data/v1/lists/0b5d3c1e-6f2a-4b8e-9c71-2d4e8a6f1b03/entries/add

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

      ```json Response theme={null}
      {
        "status": "success",
        "data": [
          {
            "status": "added",
            "record": { "id": "73fcb798-9ccd-4138-8f6a-9a801123783c" },
            "entry": {
              "id": "c4a1e2f0-8b3d-4e6a-9f12-5d7c8b9a0e14",
              "created_at": "2026-10-01T12:00:00Z",
              "updated_at": "2026-10-01T12:00:00Z",
              "list_id": "0b5d3c1e-6f2a-4b8e-9c71-2d4e8a6f1b03",
              "object": "person",
              "record_id": "73fcb798-9ccd-4138-8f6a-9a801123783c"
            }
          },
          {
            "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
        }
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

`match` works the same way as the request body of
[find unique record](/developers/api/data/records/find-unique). 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)


## OpenAPI

````yaml POST /data/v1/lists/{list_id}/entries/add
openapi: 3.1.0
info:
  title: Unify Data API
  summary: Interact with objects, attributes, and records within the Unify platform.
  version: '1'
  termsOfService: https://www.unifygtm.com/legal/terms-and-conditions
  contact:
    name: Unify Support
    url: https://www.unifygtm.com/support
    email: support@unifygtm.com
servers:
  - url: https://api.unifygtm.com
    variables: {}
security:
  - ApiKeyAuth: []
tags:
  - name: Data
  - name: Object Record Query Jobs
  - name: Event Query Jobs
  - name: Lists
  - name: List Entries
  - name: Objects
  - name: Object Attributes
  - name: Object Attribute Options
  - name: Object Records
paths:
  /data/v1/lists/{list_id}/entries/add:
    post:
      tags:
        - Data
        - List Entries
      description: >-
        Add records to a list. Records already in the list are unchanged. A
        valid

        request returns HTTP 200 even if individual records cannot be added.
      operationId: add_list_entries
      parameters:
        - name: list_id
          in: path
          required: true
          description: ID of the list.
          schema:
            $ref: '#/components/schemas/UValues.UUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddListEntriesRequest'
      responses:
        '200':
          description: Response for adding records to a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddListEntriesResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    enum:
                      - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: >-
                  Response for any operation that results in a bad request
                  error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - unauthorized
                  message:
                    type: string
                description: >-
                  Response for any operation that results in an unauthorized
                  error.
        '403':
          description: Response for any operation that results in a forbidden error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - forbidden
                  message:
                    type: string
                description: Response for any operation that results in a forbidden error.
        '404':
          description: Response for any operation that results in a not found error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - list_not_found
                  message:
                    type: string
                description: Response for any operation that results in a not found error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  message:
                    type: string
                description: >-
                  Response for any operation that results in an internal server
                  error.
components:
  schemas:
    UValues.UUuid:
      type: string
      description: String UUIDv4 value.
      title: UUuid
    AddListEntriesRequest:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/ListRecordIdentifier'
          minItems: 1
          maxItems: 100
          description: >-
            Up to 100 record identifiers to add, processed in request order. ID
            and

            match identifiers may be mixed. Duplicate identifiers are not
            allowed.
      description: Request body for adding records to a list.
    AddListEntriesResponse:
      type: object
      required:
        - status
        - data
        - summary
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: array
          items:
            $ref: '#/components/schemas/AddListEntryResult'
          description: One result per requested record, in request order.
        summary:
          $ref: '#/components/schemas/AddListEntriesSummary'
      description: Response for adding records to a list.
    UResponses.BadRequestError:
      type: object
      required:
        - code
      properties:
        code:
          type: string
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        object_api_name:
          type: string
        attribute_api_name:
          type: string
      allOf:
        - type: object
          unevaluatedProperties: {}
      description: Validation error detail returned for bad request responses.
    ListRecordIdentifier:
      anyOf:
        - $ref: '#/components/schemas/ListRecordById'
        - $ref: '#/components/schemas/ListRecordByMatch'
      description: Record identifier using an ID or attribute values.
    AddListEntryResult:
      type: object
      oneOf:
        - $ref: '#/components/schemas/ListEntryAddedResult'
        - $ref: '#/components/schemas/ListEntryAlreadyInListResult'
        - $ref: '#/components/schemas/ListEntryRecordNotFoundResult'
        - $ref: '#/components/schemas/ListEntryObjectMismatchResult'
      discriminator:
        propertyName: status
        mapping:
          added:
            $ref: '#/components/schemas/ListEntryAddedResult'
          already_in_list:
            $ref: '#/components/schemas/ListEntryAlreadyInListResult'
          record_not_found:
            $ref: '#/components/schemas/ListEntryRecordNotFoundResult'
          object_mismatch:
            $ref: '#/components/schemas/ListEntryObjectMismatchResult'
      description: Per-record outcome of an add request, discriminated by `status`.
    AddListEntriesSummary:
      type: object
      required:
        - total
        - added
        - already_in_list
        - record_not_found
        - object_mismatch
      properties:
        total:
          type: integer
          description: Number of requested records. Equal to the sum of the outcome counts.
        added:
          type: integer
        already_in_list:
          type: integer
        record_not_found:
          type: integer
        object_mismatch:
          type: integer
      description: Counts of add outcomes by status.
    ListRecordById:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/UValues.UUuid'
          description: ID of the record.
      description: Record identifier using an ID.
    ListRecordByMatch:
      type: object
      required:
        - match
      properties:
        match:
          type: object
          unevaluatedProperties: {}
          description: >-
            Attribute values used to find a record of the list's object. Include
            at

            least one unique attribute. Additional attributes narrow the match.
      description: Record identifier using attribute values.
    ListEntryAddedResult:
      type: object
      required:
        - status
        - record
        - entry
      properties:
        status:
          type: string
          enum:
            - added
        record:
          $ref: '#/components/schemas/ListRecordIdentifier'
        entry:
          $ref: '#/components/schemas/UListEntry'
      description: Result for a record added to the list.
    ListEntryAlreadyInListResult:
      type: object
      required:
        - status
        - record
        - entry
      properties:
        status:
          type: string
          enum:
            - already_in_list
        record:
          $ref: '#/components/schemas/ListRecordIdentifier'
        entry:
          $ref: '#/components/schemas/UListEntry'
      description: Result for a record already in the list.
    ListEntryRecordNotFoundResult:
      type: object
      required:
        - status
        - record
      properties:
        status:
          type: string
          enum:
            - record_not_found
        record:
          $ref: '#/components/schemas/ListRecordIdentifier'
      description: Result for a record not found in the workspace.
    ListEntryObjectMismatchResult:
      type: object
      required:
        - status
        - record
      properties:
        status:
          type: string
          enum:
            - object_mismatch
        record:
          $ref: '#/components/schemas/ListRecordIdentifier'
      description: Result for a record belonging to a different object than the list.
    UListEntry:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - list_id
        - object
        - record_id
      properties:
        id:
          $ref: '#/components/schemas/UValues.UUuid'
          description: Unique identifier for the entry.
        created_at:
          type: string
          format: date-time
          description: Date and time the entry was created.
        updated_at:
          type: string
          format: date-time
          description: Date and time the entry was last updated.
        list_id:
          $ref: '#/components/schemas/UValues.UUuid'
          description: ID of the list the entry belongs to.
        object:
          $ref: '#/components/schemas/UObjects.UObjectName'
          description: API name of the object the record belongs to.
        record_id:
          $ref: '#/components/schemas/UValues.UUuid'
          description: ID of the record in the list.
      description: A record's membership in a list.
    UObjects.UObjectName:
      type: string
      description: |-
        The API name of an object, e.g. `company`, `person`, `opportunity`, or a
        custom object's API name.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.