---
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. LinkedIn does not document how quickly companies dropped from the list stop
being targeted, so treat removals as eventual rather than immediate.
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 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

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/19fd2b70854e/schema)