---
title: "Create a consent event"
method: POST
path: "/consent-events"
tags: ["consents"]
---

# Create a consent event

`POST /consent-events`

## Request

- Base URL: `https://api.pscrpt.com/v1`
- URL: `https://api.pscrpt.com/v1/consent-events`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.pscrpt.com/oauth/authorize`
    - Token URL: `https://api.pscrpt.com/oauth/token` scopes: `consent:write`

Email consent only.

## Headers

- `Idempotency-Key` string
- `Postscript-Version` string, date

## Request body

- ConsentEventCreate: Pass exactly one of `profile_id` or `identifier`.
  - `action` 'subscribe' | 'unsubscribe' | 'mark_pending' | 'expire', required
  - `channel` 'email', required
  - `evidence` ConsentEvidence, required
    - `detail` string, nullable: More specific context for `method`, such as `shopify_checkout`.
    - `lawful_basis` string, nullable: The legal basis the consent was collected under, such as `express_consent`, `express_written_consent`, `implied_consent`, `soft_opt_in`, `legitimate_interest`, or `contract`; other values are kept as sent. Required for `subscribe`. It is recorded as evidence and does not affect whether messages send.
    - `method` string, required: How the consent was collected, such as `checkout`, `popup`, `keyword`, `api`, or `import`.
  - `identifier` ConsentIdentifierInput
    - `type` 'email', required
    - `value` string, required
  - `occurred_at` string, date-time
  - `profile_id` string
  - `source_reference` string, nullable: Your own label for the write, returned on the event and the consent.

## Response `200`

The consent already had this status; returns the stored event.

- ConsentEventEnvelope
  - `data` ConsentEvent, required: A recorded change to a profile's consent.
    - `action` 'subscribe' | 'unsubscribe' | 'mark_pending' | 'expire', required
    - `changed_projection` boolean, required: Whether the event changed the consent.
    - `channel` string, required
    - `consent` Consent
      - `channel` string, required
      - `consented_at` string, date-time, required
      - `id` string, required
      - `identifier` Identifier
        - `created_at` string, date-time, required
        - `display_value` string, required
        - `id` string, required
        - `is_primary` boolean, required
        - `object` 'identifier', required
        - `profile_id` string, required
        - `source` string, required
        - `type` string, required
        - `updated_at` string, date-time, required
        - `value` string: Requires the `identifiers:read_value` scope.
        - `verified_at` string, date-time, required
      - `identifier_id` string, required
      - `method` string, required: How consent was collected.
      - `method_detail` string, nullable, required
      - `object` 'consent', required
      - `profile_id` string, required
      - `source` string, required: Origin derived from the credential.
      - `source_reference` string, nullable, required
      - `status` 'subscribed' | 'unsubscribed' | 'never_subscribed' | 'pending' | 'expired', required
      - `updated_at` string, date-time, required
    - `created_at` string, date-time, required
    - `evidence` ConsentEvidence, required
      - `detail` string, nullable: More specific context for `method`, such as `shopify_checkout`.
      - `lawful_basis` string, nullable: The legal basis the consent was collected under, such as `express_consent`, `express_written_consent`, `implied_consent`, `soft_opt_in`, `legitimate_interest`, or `contract`; other values are kept as sent. Required for `subscribe`. It is recorded as evidence and does not affect whether messages send.
      - `method` string, required: How the consent was collected, such as `checkout`, `popup`, `keyword`, `api`, or `import`.
    - `id` string, required
    - `identifier_id` string, required
    - `object` 'consent_event', required
    - `occurred_at` string, date-time, required
    - `profile_id` string, required
    - `source` string, required: The credential that recorded the event, such as `api_key:merchant` or `app:{app_id}`.
    - `source_reference` string, nullable, required: Your own reference for the event, returned as sent.
  - `meta` Meta, required
    - `as_of` string, date-time
    - `livemode` boolean, required
    - `page` PageMeta
      - `limit` integer, required
      - `next_cursor` string, nullable, required: Pass as `page[after]`. Null on the last page.
    - `request_id` string, required
    - `resolved_from` string: The merged-away profile ID the request addressed; `data` holds the survivor.
    - `revision` string, date, required

## Other responses

- `201`: The recorded event, with the resulting consent.
- `400`: Malformed input, an unknown parameter, an unsupported filter, sort, or expand, or a mistyped ID.
- `401`: Missing or invalid API key.
- `403`: The key lacks the required scope.
- `404`: No such resource in the authenticated property.
- `409`: State conflict: an identifier collision (`identity_conflict`), an idempotency key reused with a different body, or a duplicate request still in flight (`Retry-After` present).
- `422`: Semantically invalid, e.g. an impossible lifecycle transition.
- `429`: Rate limit exceeded.
- `500`: Internal error.
- `502`: Upstream provider failure.
- `503`: Temporarily unavailable.

## Changes

- **2026-10-10** `8a6f51e140b8`: 5 breaking, 2 warning, 2 info
  - request property `allOf[#/components/schemas/ConsentEventWriteFields]/identifier/type` was restricted to a list of enum values
  - added `#/components/schemas/Timestamp, subschema #2` to the `data/occurred_at` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/Timestamp, subschema #2` to the `data/occurred_at` response property `oneOf` list for the response status `201`
  - the `data/occurred_at` response's property type changed from `string` to no type, and format from `date-time` to no format for status `200`
  - …5 more
- **2026-10-09** `8dfa57319d25`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/changes/consent-events/post.md)

---

[API](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta.md) - [All operations](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/pscrpt/apis/postscript-native-api-beta/revisions/882458ee1f36?raw)