---
title: "Replace audience companies"
method: POST
path: "/v1/ads/audiences/{audienceId}/companies"
tags: ["Ad Audiences"]
---

# Replace audience companies

`POST /v1/ads/audiences/{audienceId}/companies`

Upload the company rows of a LinkedIn `company_list` audience (account-based marketing).
LinkedIn-only, every other platform returns 422.

A LinkedIn audience segment holds exactly one uploaded list, so the list you send here
REPLACES the segment's list instead of being appended to it: always send the full set of
companies. LinkedIn returns only the identifier of the uploaded file, never its rows, so the
merge cannot be done for you, keep the source list on your side.

How the matching behaves:

- Rows are plain text (not hashed), matched against LinkedIn's own company graph.
- Matching is asynchronous: LinkedIn takes up to 48h for a new audience and up to 24h for a
  later update, and the audience stays `processing` meanwhile.
- LinkedIn does not document how quickly companies dropped from the list stop being targeted,
  so treat removals as eventual rather than immediate.
- LinkedIn recommends at least 1,000 companies for a usable match rate, and caps a list at
  300,000.

The initial list is sent with `companies` on `POST /v1/ads/audiences`; this endpoint is for
every change after that.

## Path parameters

- `audienceId` string, required

## Request body

- object
  - `companies` object[], required — The complete company list. Each row needs at least one of name, domain, website or linkedinPageUrl.
    - `name` string
    - `domain` string
    - `website` string
    - `linkedinPageUrl` string

## Response `200`

Companies uploaded

- object
  - `message` string
  - `numReceived` integer — Rows sent to LinkedIn. Matching happens asynchronously, so this is not the matched company count.

## Other responses

- `400` — Invalid input (malformed audienceId, empty companies array, a row with no identifier)
- `401` — Unauthorized
- `403` — Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
- `404` — Resource not found
- `422` — Audience is not a company_list type, is not on LinkedIn, or has no platform ID yet

## Changes

- **2026-08-22** `19fd2b70854e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/audiences/:audienceId/companies/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/be448f13ecdc?raw)