---
title: "Modify List"
method: POST
path: "/api/v1.4/lists/{list_uid}/companies/"
tags: ["lists"]
---

# Modify List

`POST /api/v1.4/lists/{list_uid}/companies/`

## Request

- Base URL: `https://search.grata.com`
- URL: `https://search.grata.com/api/v1.4/lists/{list_uid}/companies/`
- Auth: API key in header `Authorization`

Allows users to add or remove companies from an existing list.

## Path parameters

- `list_uid` string, required

## Request body

- ModifyListRequest
  - `action` 'add' | 'remove', required: The action to perform.
  - `domains` string[]: Domains to add or remove from a list (max of 500 permitted per call).
  - `uids` string[]: Grata company UIDs to add or remove from a list (max of 500 permitted per call).

## Response `200`

OK

- ModifyListResponse
  - `results` ModifyResult[], required
    - `input` string, required: The inputted domain or UID.
    - `processed` boolean, required: Indicates whether the domain was processed.
    - `company` object, required
      - `domain` string, required: The associated domain.
      - `uid` string, required: The associated company UID.
  - `processed` ProcessSummary, required
    - `count` integer, required: The number of companies processed.
    - `companies` string[], required
  - `not_processed` ProcessSummary, required
    - `count` integer, required: The number of companies processed.
    - `companies` string[], required

## Other responses

- `400`: Bad Request. Incorrect request body.
- `401`: Unauthorized. API key is invalid.
- `404`: Not Found.
- `429`: Too Many Requests. Rate limit exceeded.
- `500`: Internal Server Error. An error occurred with our API.

## Changes

- **2024-12-05** `b36e8e329afb`: 1 breaking, 19 info
  - the request property `action` became required
  - the endpoint scheme security `ApiKeyAuth` was removed from the API
  - api tag `lists` added
  - added the media type `application/json` for the response with the status `400`
  - …16 more
- **2024-12-05** `f80fb2a115ff`: 1 breaking, 9 warning, 7 info
  - request body became required
  - deleted the `header` request parameter `Content-Type`
  - removed the optional property `count` from the response with the `200` status
  - removed the optional property `page` from the response with the `200` status
  - …13 more
- **2024-12-04** `29fbf7a6e106`: 1 warning
  - deleted the `header` request parameter `Authorization`

[Operation history](https://skmtc.dev/tjc-lp/apis/grata-unified-api/changes/api/v1.4/lists/:list_uid/companies/post.md)

---

[API](https://skmtc.dev/tjc-lp/apis/grata-unified-api.md) - [All operations](https://skmtc.dev/tjc-lp/apis/grata-unified-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tjc-lp/apis/grata-unified-api/revisions/d78ed69a85eb?raw)