# Audience profiles

## Endpoints

- `POST /platform/audience-profile-imports`: [Create audience profile import](https://docs.polymorfa.com/api/audience-profiles/create-audience-profile-import)
- `GET /platform/audience-profiles`: [List audience profiles](https://docs.polymorfa.com/api/audience-profiles/list-audience-profiles)
- `GET /platform/audience-profiles/{phone}/consent`: [List audience profile consent](https://docs.polymorfa.com/api/audience-profiles/list-audience-profile-consent)
- `GET /platform/audience-profiles/{phone}`: [Get audience profile](https://docs.polymorfa.com/api/audience-profiles/get-audience-profile)
- `GET /platform/audience-profile-imports/{jobId}`: [Get audience profile import](https://docs.polymorfa.com/api/audience-profiles/get-audience-profile-import)
- `PUT /platform/audience-profiles/{phone}`: [Put audience profile](https://docs.polymorfa.com/api/audience-profiles/put-audience-profile)
- `DELETE /platform/audience-profile-imports/{jobId}`: [Cancel audience profile import](https://docs.polymorfa.com/api/audience-profiles/cancel-audience-profile-import)
- `DELETE /platform/audience-profiles/{phone}`: [Delete audience profile](https://docs.polymorfa.com/api/audience-profiles/delete-audience-profile)

## Create audience profile import

`POST https://api.polymorfa.com/platform/audience-profile-imports` (Platform API)

Required permission: `campaigns:manage`

Queues a bounded CSV import of customer-supplied team profiles. Exact CSV header names can be mapped to profile fields. At most one import is active per team. Files contain at most 10 MiB and 10,000 rows; the CSV is removed after completion or cancellation. The same replay key, file and mapping return the existing job. Requires beta enrollment.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Body

- `replayKey` (string, required, length 1–128, pattern ^[A-Za-z0-9._:-]+$). Specifies replay key for this schema.
- `csvBase64` (string (byte), required, length 1–13981016, format byte). UTF-8 CSV encoded as standard padded base64; decoded file at most 10 MiB and 10,000 data rows. The `tags` cell holds a JSON array of strings and the `attributes` cell a JSON object, quoted as CSV requires, for example `+15550100001,"[""vip""]","{""city"":""Lisbon""}"`.
- `mapping` (object). Maps profile fields to exact CSV header names. Required when the CSV uses different headers; unmapped CSV columns are ignored.
  - `phone` (string, required, length 1–64). Phone number in international format.
  - `tags` (string, required, length 1–64). Specifies tags for this mapping.
  - `attributes` (string, required, length 1–64). Specifies attributes for this mapping.
  - `expectedRevision` (string, length 1–64). Specifies expected revision for this mapping.
  - `provenanceReference` (string, length 1–64). Specifies provenance reference for this mapping.
  - `consentAllowed` (string, length 1–64). Specifies consent allowed for this mapping.
  - `consentAssertedAt` (string, length 1–64). Timestamp for consent asserted at.
  - `consentReference` (string, length 1–64). Specifies consent reference for this mapping.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/audience-profile-imports" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "replayKey": "string",
  "csvBase64": "string"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `state` (string, required). Current lifecycle state of this resource. Values: `queued`, `completed`, `cancelled`.
  - `totalValid` (integer, required, min 0). Rows that passed validation and will be written.
  - `invalidCount` (integer, required, min 0). Rows refused by validation; `invalidSamples` lists up to 20.
  - `invalidSamples` (array of object, required, max items 20). Invalid samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this invalid sample.
    - `reason` (string, required). Reason for the reported state or outcome.
  - `conflictSamples` (array of object, required, max items 20). Conflict samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this conflict sample.
    - `reason` (string, required). Reason for the reported state or outcome. Values: `quota`, `revision_conflict`.
  - `processedValid` (integer, required, min 0). Valid rows written so far.
  - `createdCount` (integer, required, min 0). Profiles created.
  - `updatedCount` (integer, required, min 0). Existing profiles updated.
  - `conflictCount` (integer, required, min 0). Valid rows not written because of the team's profile quota or a revision conflict; `conflictSamples` lists up to 20.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
  - `completedAt` (integer, required, nullable, min 0). Unix timestamp in milliseconds when this operation completed.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 413

Request body exceeds the endpoint limit.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "media_too_large",
    "message": "The message or media exceeds the size limit.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#media-too-large"
}
```

## List audience profiles

`GET https://api.polymorfa.com/platform/audience-profiles` (Platform API)

Required permission: `campaigns:read`

Lists customer-supplied profiles for the team with cursor pagination. Deleted profiles are omitted.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Query parameters

- `cursor` (string (uuid), format uuid). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.
- `tag` (string, min length 1, UTF-8 size: At most `48` UTF-8 bytes, pattern ^[^\u0000-\u001f\u007f]+$). Only profiles that carry this exact tag.
- `phonePrefix` (string, pattern ^\+[0-9]{1,15}$). Only profiles whose E.164 phone number starts with this prefix, such as `+4479`.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-profiles" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `phone` (string, required, pattern ^\+[1-9][0-9]{6,14}$). Phone number in international format.
  - `revision` (integer, required, min 1). Specifies revision for this data.
  - `tags` (array of string, required, max items 20, item max length 48). Tags associated with this data.
  - `attributes` (object, required, max properties 20). Structured attributes values for this data.
  - `provenance` (object, required, nullable). Structured provenance values for this data.
    - `source` (string, required). Specifies source for this provenance. Values: `api`, `csv`, `form`.
    - `reference` (string, required, max length 128). Specifies reference for this provenance.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "phone": "string",
      "revision": 1,
      "tags": [
        "string"
      ],
      "attributes": {},
      "provenance": {
        "source": "api",
        "reference": "string"
      },
      "createdAt": 0,
      "updatedAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## List audience profile consent

`GET https://api.polymorfa.com/platform/audience-profiles/{phone}/consent` (Platform API)

Required permission: `campaigns:read`

Lists the customer's recorded campaign consent assertions for one profile. Assertions do not override opt-outs.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Path parameters

- `phone` (string, required). Phone number in international format.

### Query parameters

- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-profiles/<phone>/consent" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `profileRevision` (integer, required, min 1). Specifies profile revision for this data.
  - `purpose` (string, required). Specifies purpose for this data. Values: `campaigns`.
  - `source` (string, required). Specifies source for this data. Values: `api`, `csv`, `form`.
  - `reference` (string, required). Specifies reference for this data.
  - `allowed` (boolean, required). Whether allowed.
  - `assertedAt` (integer, required, min 0). Timestamp for asserted at.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "profileRevision": 1,
      "purpose": "campaigns",
      "source": "api",
      "reference": "string",
      "allowed": true,
      "assertedAt": 0,
      "createdAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get audience profile

`GET https://api.polymorfa.com/platform/audience-profiles/{phone}` (Platform API)

Required permission: `campaigns:read`

Gets one customer-supplied profile by its E.164 phone. Deleted profiles return 404.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Path parameters

- `phone` (string, required). Phone number in international format.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-profiles/<phone>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `phone` (string, required, pattern ^\+[1-9][0-9]{6,14}$). Phone number in international format.
  - `revision` (integer, required, min 1). Specifies revision for this data.
  - `tags` (array of string, required, max items 20, item max length 48). Tags associated with this data.
  - `attributes` (object, required, max properties 20). Structured attributes values for this data.
  - `provenance` (object, required, nullable). Structured provenance values for this data.
    - `source` (string, required). Specifies source for this provenance. Values: `api`, `csv`, `form`.
    - `reference` (string, required, max length 128). Specifies reference for this provenance.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "phone": "string",
    "revision": 1,
    "tags": [
      "string"
    ],
    "attributes": {},
    "provenance": {
      "source": "api",
      "reference": "string"
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get audience profile import

`GET https://api.polymorfa.com/platform/audience-profile-imports/{jobId}` (Platform API)

Required permission: `campaigns:read`

Returns aggregate counts and up to 20 row-number/reason samples. Raw phone numbers and custom values are not included. Reports expire 30 days after completion or cancellation.

Team keys require `campaigns:read`. Project tokens are not accepted.

### Path parameters

- `jobId` (string, required). Identifier for the job.

### Request

```bash
curl "https://api.polymorfa.com/platform/audience-profile-imports/<jobId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `state` (string, required). Current lifecycle state of this resource. Values: `queued`, `completed`, `cancelled`.
  - `totalValid` (integer, required, min 0). Rows that passed validation and will be written.
  - `invalidCount` (integer, required, min 0). Rows refused by validation; `invalidSamples` lists up to 20.
  - `invalidSamples` (array of object, required, max items 20). Invalid samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this invalid sample.
    - `reason` (string, required). Reason for the reported state or outcome.
  - `conflictSamples` (array of object, required, max items 20). Conflict samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this conflict sample.
    - `reason` (string, required). Reason for the reported state or outcome. Values: `quota`, `revision_conflict`.
  - `processedValid` (integer, required, min 0). Valid rows written so far.
  - `createdCount` (integer, required, min 0). Profiles created.
  - `updatedCount` (integer, required, min 0). Existing profiles updated.
  - `conflictCount` (integer, required, min 0). Valid rows not written because of the team's profile quota or a revision conflict; `conflictSamples` lists up to 20.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
  - `completedAt` (integer, required, nullable, min 0). Unix timestamp in milliseconds when this operation completed.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Put audience profile

`PUT https://api.polymorfa.com/platform/audience-profiles/{phone}` (Platform API)

Required permission: `campaigns:manage`

Creates a bounded team profile, or replaces tags and attributes at the observed revision. A stale revision returns 409. To recreate a profile deleted in the last 30 days, send the `revision` the delete returned as `expectedRevision`; a put without it returns 409 with a message naming that revision. A consent assertion records the customer's statement; it does not clear an opt-out or authorize a send. This beta requires enrollment and release eligibility.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Path parameters

- `phone` (string, required). Phone number in international format.

### Body

- `expectedRevision` (integer, min 1). Required to edit or recreate a deleted profile; omit only for first creation.
- `tags` (array of string, required, max items 20, item max length 48). Tags associated with this schema.
- `attributes` (object, required, max properties 20). Structured attributes values for this schema.
- `provenance` (object). Structured provenance values for this schema.
  - `source` (string, required). Specifies source for this provenance. Values: `api`, `csv`, `form`.
  - `reference` (string, required, max length 128). Specifies reference for this provenance.
- `consent` (object). Structured consent values for this schema.
  - `purpose` (string, required). Specifies purpose for this consent. Values: `campaigns`.
  - `source` (string, required). Specifies source for this consent. Values: `api`, `csv`, `form`.
  - `reference` (string, required, max length 128). Specifies reference for this consent.
  - `allowed` (boolean, required). Whether allowed.
  - `assertedAt` (integer, required, range 0–8640000000000000). Timestamp for asserted at.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/audience-profiles/<phone>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "string"
  ],
  "attributes": {}
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `phone` (string, required, pattern ^\+[1-9][0-9]{6,14}$). Phone number in international format.
  - `revision` (integer, required, min 1). Specifies revision for this data.
  - `tags` (array of string, required, max items 20, item max length 48). Tags associated with this data.
  - `attributes` (object, required, max properties 20). Structured attributes values for this data.
  - `provenance` (object, required, nullable). Structured provenance values for this data.
    - `source` (string, required). Specifies source for this provenance. Values: `api`, `csv`, `form`.
    - `reference` (string, required, max length 128). Specifies reference for this provenance.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "phone": "string",
    "revision": 1,
    "tags": [
      "string"
    ],
    "attributes": {},
    "provenance": {
      "source": "api",
      "reference": "string"
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Cancel audience profile import

`DELETE https://api.polymorfa.com/platform/audience-profile-imports/{jobId}` (Platform API)

Required permission: `campaigns:manage`

Stops the next batch and removes the CSV. Already committed profile edits remain. Cancellation and report reads remain available after beta withdrawal.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Path parameters

- `jobId` (string, required). Identifier for the job.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/audience-profile-imports/<jobId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `state` (string, required). Current lifecycle state of this resource. Values: `queued`, `completed`, `cancelled`.
  - `totalValid` (integer, required, min 0). Rows that passed validation and will be written.
  - `invalidCount` (integer, required, min 0). Rows refused by validation; `invalidSamples` lists up to 20.
  - `invalidSamples` (array of object, required, max items 20). Invalid samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this invalid sample.
    - `reason` (string, required). Reason for the reported state or outcome.
  - `conflictSamples` (array of object, required, max items 20). Conflict samples associated with this data.
    - `row` (integer, required, min 2). Specifies row for this conflict sample.
    - `reason` (string, required). Reason for the reported state or outcome. Values: `quota`, `revision_conflict`.
  - `processedValid` (integer, required, min 0). Valid rows written so far.
  - `createdCount` (integer, required, min 0). Profiles created.
  - `updatedCount` (integer, required, min 0). Existing profiles updated.
  - `conflictCount` (integer, required, min 0). Valid rows not written because of the team's profile quota or a revision conflict; `conflictSamples` lists up to 20.
  - `createdAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, min 0). Unix timestamp in milliseconds when this resource was last updated.
  - `completedAt` (integer, required, nullable, min 0). Unix timestamp in milliseconds when this operation completed.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Delete audience profile

`DELETE https://api.polymorfa.com/platform/audience-profiles/{phone}` (Platform API)

Required permission: `campaigns:manage`

Removes profile fields, consent assertions and reusable audience-list memberships at the observed revision, and clears the preview row of each audience the phone belonged to. Recipients already added to campaigns (including drafts), previously uploaded files and opt-outs are not changed. The phone's deletion record is kept for 30 days; `revision` is its revision. During that time, adding the phone to an audience returns 409, and recreating the profile requires `expectedRevision` set to this revision. Deletion remains available after beta withdrawal.

Team keys require `campaigns:manage`. Project tokens are not accepted.

### Path parameters

- `phone` (string, required). Phone number in international format.

### Query parameters

- `expectedRevision` (string, required). The profile revision you last read. A different current revision returns 409.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/audience-profiles/<phone>?expectedRevision=<expectedRevision>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.
  - `phone` (string, required). Phone number in international format.
  - `revision` (integer, required, min 2). Specifies revision for this data.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "deleted": true,
    "phone": "string",
    "revision": 2
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```
