# Manage audience profiles

> Store customer-supplied campaign attributes and consent assertions for your team, or import them from CSV.

Audience profiles hold contact details that you supply for campaign audiences. A
profile belongs to your team and is identified by its E.164 phone number. Profile
attributes and consent assertions do not override [STOP opt-outs](https://docs.polymorfa.com/campaigns/opt-outs)
or grant permission to send a campaign.

> **Note**
>
> **Audience profiles require access.** Creating or updating profiles and
> starting imports require enrollment in the audience profiles beta. Reading
> profiles, polling or cancelling imports, and deleting profiles stay available
> if your team leaves the beta, so you can always inspect and remove the data you
> stored.

Use a team key with
`campaigns:read` to read profiles and import reports, or `campaigns:manage` to
change them. Project tokens cannot access team profiles.

The TypeScript SDK has no typed profile methods yet. Send each request on this
page with the team client's `raw.request`, and encode the leading `+` of a
phone in a path as `%2B`. List responses have rows at `response.data.data` and
pagination at `response.data.page`; a single profile is at `response.data.data`.

## Manage profiles in the Console

Open **Campaigns > Profiles**. An owner or admin can join the beta in
[Opt-in features](https://docs.polymorfa.com/teams/opt-in-features). The page lists your team's profiles, 50 at a time:

- filter by the start of a phone number, such as `+44 77`, and by one exact tag
- select **Edit** to change a profile's tags and attributes, or to record a
  consent assertion with its evidence reference and date
- select **Delete profile** to remove a profile; this works after your team
  leaves the beta
- select **Import CSV**, choose the file, and pick the column for each profile
  field; the page shows the import's progress, counts and the rows it could not
  apply, and lets you cancel it while it runs

The Console uses the same limits and checks as the API endpoints below.

## List and filter profiles

`GET /platform/audience-profiles` returns up to 100 profiles per page, in a
stable order. Pass `page.nextCursor` as `cursor` for the next page. Add
`tag` to return only profiles with that exact tag, and `phonePrefix` to return
only numbers that start with it:

```bash cURL
curl "https://api.polymorfa.com/platform/audience-profiles?tag=vip&phonePrefix=%2B44&limit=50" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const page = await platform.raw.request({
  method: "GET",
  path: "/platform/audience-profiles",
  query: { tag: "vip", phonePrefix: "+44", limit: 50 },
});
console.log(page.data);
```

`tag` must contain 1 to 48 UTF-8 bytes without control characters. Tags match
exactly, including case. Both filters must match when you supply both.
`phonePrefix` is `+` followed by 1 to 15 digits. Keep the same filters when you
request later pages. Filters scan your team's profiles. Invalid filters return
`400 invalid_parameter`; a valid filter with no matches returns an empty page.
Encode the leading `+` as `%2B` in a query string.

## Create or update a profile

Send the phone number in the path. Provide `tags` and `attributes` even when
they are empty. Omit `expectedRevision` for a new profile; use the revision from
the latest read when replacing an existing profile.

```bash
curl -X PUT "https://api.polymorfa.com/platform/audience-profiles/%2B14155550123" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["launch"],
    "attributes": { "first_name": "Ada" },
    "provenance": { "source": "api", "reference": "signup-42" }
  }'
```

The response includes the profile's `revision`. A stale revision returns `409`;
read the profile again before applying your intended replacement. A team can
hold at most 100,000 profiles, including deleted profiles pending expiry. A
deleted profile releases capacity only after its deletion record is purged.

To record a consent assertion, include `consent` with `purpose: "campaigns"`,
`source`, a reference to your evidence, `allowed`, and `assertedAt` as Unix
milliseconds. Read assertions with
`GET /platform/audience-profiles/{phone}/consent`. Assertions record what you
supplied; they do not clear an opt-out.

## Delete and recreate a profile

Delete a profile with its current revision:

```bash
curl -X DELETE "https://api.polymorfa.com/platform/audience-profiles/%2B14155550123?expectedRevision=2" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Deletion removes the profile's tags, attributes, consent assertions and its
membership in every audience, together with that member's variables. It also
clears the preview row of each of those audiences. It does not change
recipients already added to a campaign, including draft campaigns, CSV files you
uploaded earlier, or your team's opt-outs. Remove a draft campaign's recipient
separately if you no longer want to contact them.

Polymorfa keeps a deletion record with the phone number and a new `revision`
for 30 days, so delayed writes cannot bring the contact back. During those 30
days:

- adding the phone to an audience returns `409` naming its row, numbered as
  in `invalidRows`; nothing in that request is added
- recreating the profile requires `expectedRevision` set to the `revision` the
  delete returned; a put without it returns `409` with a message naming that
  revision

## Import profiles from CSV

Submit one UTF-8 CSV file of at most 10 MiB and 10,000 data rows per job. The
header must include `phone`, `tags`, and `attributes` unless you provide a
column mapping. `tags` contains a JSON array; `attributes` contains a JSON
object. Optional columns are
`expectedRevision`, `provenanceReference`, `consentAllowed`,
`consentAssertedAt`, and `consentReference`. Supply all three consent columns
together when recording an assertion. A row for a phone that already has a
profile, including one deleted in the last 30 days, must carry that profile's
current `expectedRevision`; otherwise the row is reported as a conflict and the
profile is left unchanged. The timestamp uses a date-time that
JavaScript can parse, such as `2026-09-27T00:00:00Z`.

If your CSV uses different names, pass `mapping` in the import request. Map
`phone`, `tags`, and `attributes` to their exact header names; map any optional
fields you want to import. Unmapped columns are ignored. A file can have at
most 32 columns, and each header name can use at most 64 UTF-8 bytes.

```csv
phone,tags,attributes,provenanceReference
+14155550123,"[""launch""]","{""first_name"":""Ada""}",signup-42
```

Encode the file as standard padded base64 and send it with a replay key:

```bash
base64 < profiles.csv | tr -d '\n' \
  | jq -Rs '{replayKey: "profiles-sep-27", csvBase64: .}' \
  | curl -X POST "https://api.polymorfa.com/platform/audience-profile-imports" \
      -H "Authorization: Bearer $POLYMORFA_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @-
```

The file is piped through `jq` and `curl`, so a file near the 10 MiB limit does
not hit the shell's argument size limit.

For a file with `Mobile`, `Labels`, and `Fields` headers, add this object to
the JSON request:

```json
{"mapping":{"phone":"Mobile","tags":"Labels","attributes":"Fields"}}
```

Only one import per team can be queued or running. Repeating the same replay
key with the same file, mapping, and key returns its existing job; reusing it
with different content or mapping returns `409`. An oversized file or row count
returns `413`.

Use `GET /platform/audience-profile-imports/{jobId}` to check the job. The
report includes processed, created, updated, invalid, and conflicting counts,
plus up to 20 row numbers and reason codes for each failure category. It does
not include submitted phone numbers or attribute values. When the job completes,
its CSV is removed. The aggregate report remains available for 30 days.

An import that has not finished seven days after you submit it is cancelled
and its CSV removed; profile changes from batches that already ran remain.

Use `DELETE /platform/audience-profile-imports/{jobId}` to cancel the remaining
work. Profile changes committed by earlier batches remain. Cancellation removes
the CSV and retains the aggregate report for 30 days.

## See also

- [Save an audience segment](https://docs.polymorfa.com/campaigns/segments)
- [Opt-outs and STOP replies](https://docs.polymorfa.com/campaigns/opt-outs)
- [Audience profile API reference](https://docs.polymorfa.com/api/audience-profiles/list-audience-profiles)
