{ "components": { "examples": { "MergedProfile": { "summary": "Merged-away profile", "value": { "data": { "attributes": {}, "created_at": "2026-07-01T09:15:00.000000Z", "id": "prof_01h455vb4pex5vsknk084sn02p", "identifier_ids": [], "location": null, "merged_into": "prof_01h455vb4pex5vsknk084sn02q", "object": "profile", "profile_ref": "p_7qLm2", "status": "merged", "tags": [], "updated_at": "2026-07-23T18:05:00.000000Z" }, "meta": { "livemode": true, "request_id": "req_01h455vb4pex5vsknk084sn0ab", "revision": "2026-07-23" } } }, "Profile": { "summary": "Active profile", "value": { "data": { "attributes": { "loyalty_tier": "gold" }, "created_at": "2026-07-23T18:00:00.000000Z", "id": "prof_01h455vb4pex5vsknk084sn02q", "identifier_ids": [ "idnt_01h455vb4pex5vsknk084sn03a" ], "location": { "city": "Portland", "country": "US", "region": "OR", "timezone": null, "zip": null }, "merged_into": null, "object": "profile", "profile_ref": "p_Ab3x9", "status": "active", "tags": [ "vip" ], "updated_at": "2026-07-23T18:00:00.000000Z" }, "meta": { "livemode": true, "request_id": "req_01h455vb4pex5vsknk084sn0aa", "revision": "2026-07-23" } } } }, "headers": { "ETag": { "description": "Strong resource version; echo via `If-Match` on mutations.", "schema": { "type": "string" } }, "IdempotencyReplayed": { "description": "Present and `true` when this response is an idempotent replay.", "schema": { "type": "boolean" } }, "ProfileLocation": { "description": "Canonical URL of the created resource.", "schema": { "examples": [ "/v1/profiles/prof_01h455vb4pex5vsknk084sn02q" ], "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "parameters": { "IdempotencyKey": { "description": "Deduplicates retries for 24 hours: the same key returns the original response with `Idempotency-Replayed: true`; the same key with a different body returns 409 `idempotency_key_reused`.\n", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } }, "IfMatch": { "description": "Strong ETag from a prior read. When absent, the write is last-write-wins.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, "PostscriptVersion": { "description": "Overrides the key's pinned API revision for this request.", "in": "header", "name": "Postscript-Version", "required": false, "schema": { "examples": [ "2026-07-23" ], "format": "date", "type": "string" } }, "ProfileIdPath": { "in": "path", "name": "profile_id", "required": true, "schema": { "$ref": "#/components/schemas/ProfileId" } } }, "responses": { "BadRequest": { "content": { "application/json": { "example": { "error": { "code": "parameter_missing", "message": "profile must include at least one identifier (email, phone, or external_id).", "param": "profile", "request_id": "req_01h455vb4pex5vsknk084sn02q", "retry_after_ms": null, "retryable": false, "type": "invalid_request" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed input, an unknown parameter, an unsupported filter, sort, or expand, or a mistyped ID.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "Conflict": { "content": { "application/json": { "example": { "error": { "code": "identity_conflict", "message": "phone +15555550100 already belongs to prof_01h455vb4pex5vsknk084sn02q. Merge explicitly via POST /v1/profiles/{id}/merge.", "param": "identifiers", "request_id": "req_01h455vb4pex5vsknk084sn02s", "retry_after_ms": null, "retryable": false, "type": "conflict" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "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).\n", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "EventBatchResult": { "content": { "application/json": { "example": { "data": { "counts": { "failed": 1, "succeeded": 1 }, "object": "batch_result", "results": [ { "client_reference": "row-1", "data": { "id": "evt_01h455vb4pex5vsknk084sn02q", "object": "event" }, "error": null, "status": 201 }, { "client_reference": "row-2", "data": null, "error": { "code": "reserved_event_type", "message": "Event type sms.sent is a reserved platform namespace.", "param": "type", "type": "invalid_request" }, "status": 400 } ] }, "meta": { "livemode": true, "request_id": "req_01h455vb4pex5vsknk084sn0b4", "revision": "2026-07-23" } }, "schema": { "$ref": "#/components/schemas/BatchEnvelope" } } }, "description": "Per-item results in request order. Failed items carry a per-item `error`; successes carry the event reference.\n", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "EventCreated": { "content": { "application/json": { "example": { "data": { "currency": "USD", "dedupe_id": "shopify:order:8209829119", "id": "evt_01h455vb4pex5vsknk084sn02q", "object": "event", "occurred_at": "2026-07-23T14:03:22.000000Z", "profile_id": "prof_01h455vb4pex5vsknk084sn02q", "properties": { "currency": "USD", "line_item_count": 2, "order_id": "8209829119", "total_price": 139.97 }, "received_at": "2026-07-23T14:03:24.102331Z", "source": "api", "type": "order.completed", "value": "139.97" }, "meta": { "livemode": true, "request_id": "req_01h455vb4pex5vsknk084sn0b2", "revision": "2026-07-23" } }, "schema": { "$ref": "#/components/schemas/EventEnvelope" } } }, "description": "The created event.", "headers": { "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "Location": { "description": "Canonical URL of the new event.", "schema": { "type": "string" } }, "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "Forbidden": { "content": { "application/json": { "example": { "error": { "code": "missing_scope", "message": "This key lacks the profiles:write scope required by this operation.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02q", "retry_after_ms": null, "retryable": false, "type": "authorization_error" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key lacks the required scope.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "InternalError": { "content": { "application/json": { "example": { "error": { "code": "internal_error", "message": "Something went wrong on our end.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02x", "retry_after_ms": null, "retryable": true, "type": "internal_error" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "NotFound": { "content": { "application/json": { "example": { "error": { "code": "resource_not_found", "message": "No profile prof_01h455vb4pex5vsknk084sn02q exists in this property.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02r", "retry_after_ms": null, "retryable": false, "type": "not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such resource in the authenticated property.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "PreconditionFailed": { "content": { "application/json": { "example": { "error": { "code": "precondition_failed", "message": "The If-Match value is stale. Re-read the resource and retry with the current ETag.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02t", "retry_after_ms": null, "retryable": false, "type": "precondition_failed" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The `If-Match` ETag is stale. Re-read the resource and retry.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "Profile": { "content": { "application/json": { "examples": { "merged_away": { "$ref": "#/components/examples/MergedProfile" }, "profile": { "$ref": "#/components/examples/Profile" } }, "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } } }, "description": "The profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "ProfileCreated": { "content": { "application/json": { "examples": { "profile": { "$ref": "#/components/examples/Profile" } }, "schema": { "$ref": "#/components/schemas/ProfileEnvelope" } } }, "description": "The created profile.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" }, "Location": { "$ref": "#/components/headers/ProfileLocation" }, "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "RateLimited": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Too many requests. Retry after 22 seconds.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02w", "retry_after_ms": 22000, "retryable": true, "type": "rate_limit_error" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "Unauthorized": { "content": { "application/json": { "example": { "error": { "code": "invalid_api_key", "message": "Invalid API key. Send a ps_live_* or ps_test_* secret key as a Bearer token.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02q", "retry_after_ms": null, "retryable": false, "type": "authentication_error" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid API key.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "UnprocessableEntity": { "content": { "application/json": { "example": { "error": { "code": "invalid_state_transition", "message": "Campaign camp_01h455vb4pex5vsknk084sn02q has already sent and cannot be scheduled.", "param": null, "request_id": "req_01h455vb4pex5vsknk084sn02v", "retry_after_ms": null, "retryable": false, "type": "invalid_request" } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Semantically invalid, e.g. an impossible lifecycle transition.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "schemas": { "AttributeOperation": { "additionalProperties": false, "properties": { "op": { "description": "`set` replaces the value at `path`; objects replace atomically. `delete` removes the key; setting `null` does not. `append_unique` and `remove` treat the array at `path` as a set.\n", "enum": [ "set", "delete", "append_unique", "remove" ], "type": "string", "x-enum-policy": "closed" }, "path": { "description": "Top-level key, or an array of segments for nested values; dots inside a segment are literal.\n", "oneOf": [ { "type": "string" }, { "items": { "type": "string" }, "minItems": 1, "type": "array" } ] }, "value": { "description": "Required for `set`, `append_unique`, and `remove`; omit for `delete`." } }, "required": [ "op", "path" ], "type": "object" }, "BatchEnvelope": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "BatchItemResult": { "additionalProperties": false, "properties": { "client_reference": { "type": [ "string", "null" ] }, "data": { "description": "On success, the affected resource reference; null on failure.", "properties": { "id": { "$ref": "#/components/schemas/Id" }, "object": { "type": "string" } }, "required": [ "id", "object" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "description": "On failure, the per-item error; null on success.", "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "type": { "enum": [ "invalid_request", "authorization_error", "idempotency_error", "conflict", "not_found", "rate_limit_error", "provider_error", "internal_error" ], "type": "string", "x-enum-policy": "closed" } }, "required": [ "type", "code", "message" ], "type": [ "object", "null" ] }, "status": { "maximum": 599, "minimum": 200, "type": "integer" } }, "required": [ "status" ], "type": "object" }, "BatchResult": { "additionalProperties": false, "description": "Per-item results, ordered as the request. A batch takes up to 1,000 items for event ingestion and 100 elsewhere.\n", "properties": { "counts": { "additionalProperties": false, "properties": { "failed": { "minimum": 0, "type": "integer" }, "succeeded": { "minimum": 0, "type": "integer" } }, "required": [ "succeeded", "failed" ], "type": "object" }, "object": { "const": "batch_result" }, "results": { "items": { "$ref": "#/components/schemas/BatchItemResult" }, "type": "array" } }, "required": [ "object", "results", "counts" ], "type": "object" }, "Error": { "additionalProperties": false, "properties": { "code": { "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "errors": { "description": "Optional per-field detail; the top-level fields carry the primary error.", "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" }, "message": { "type": "string" }, "param": { "description": "Dotted path to the offending field or query param.", "type": [ "string", "null" ] }, "request_id": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "retry_after_ms": { "description": "Suggested minimum wait; non-null only when retryable and boundable (mirrors `Retry-After`).", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "True iff retrying the same unchanged request can succeed.", "type": "boolean" }, "type": { "enum": [ "invalid_request", "authentication_error", "authorization_error", "idempotency_error", "conflict", "not_found", "rate_limit_error", "precondition_failed", "provider_error", "internal_error" ], "type": "string", "x-enum-policy": "closed" } }, "required": [ "type", "code", "message", "request_id", "retryable" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "type": "object" }, "Event": { "additionalProperties": false, "properties": { "currency": { "description": "Non-null exactly when `value` is.", "type": [ "string", "null" ] }, "dedupe_id": { "description": "Property-scoped, first-write-wins for 48 hours.", "maxLength": 255, "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/EventId" }, "metric": { "oneOf": [ { "$ref": "#/components/schemas/Metric" }, { "type": "null" } ] }, "object": { "const": "event" }, "occurred_at": { "$ref": "#/components/schemas/Timestamp", "description": "When the event occurred; defaults to `received_at`." }, "profile": { "oneOf": [ { "$ref": "#/components/schemas/Profile" }, { "type": "null" } ] }, "profile_id": { "description": "Null only for anonymous events not yet linked to a profile.", "pattern": "^prof_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": [ "string", "null" ] }, "properties": { "type": "object" }, "received_at": { "$ref": "#/components/schemas/Timestamp" }, "source": { "examples": [ "api", "sdk", "shopify", "klaviyo", "system" ], "type": "string", "x-enum-policy": "open" }, "type": { "$ref": "#/components/schemas/EventType" }, "value": { "description": "Decimal string.", "type": [ "string", "null" ] } }, "required": [ "id", "object", "type", "profile_id", "properties", "value", "currency", "occurred_at", "received_at", "dedupe_id", "source" ], "type": "object" }, "EventBatchItem": { "allOf": [ { "$ref": "#/components/schemas/EventWriteFields" } ], "properties": { "client_reference": { "description": "Your own identifier, echoed on the matching result. See [Bulk requests](/docs/bulk-requests).\n", "maxLength": 255, "type": "string" }, "idempotency_key": { "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } }, "unevaluatedProperties": false }, "EventBatchRequest": { "additionalProperties": false, "description": "Up to 1,000 items and 2 MB per request.", "properties": { "backfill": { "default": false, "description": "Marks the whole batch as historical: stored and counted in aggregates, but never triggers flows or webhooks. Debits a separate rate window.\n", "type": "boolean" }, "events": { "items": { "$ref": "#/components/schemas/EventBatchItem" }, "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "EventCreate": { "allOf": [ { "$ref": "#/components/schemas/EventWriteFields" } ], "unevaluatedProperties": false }, "EventEnvelope": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Event" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "EventId": { "pattern": "^evt_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "EventType": { "description": "Lowercase dot notation, e.g. `order.completed`. Underscores are rewritten as dots. Platform namespaces such as `sms.*` and `profile.*` are reserved.\n", "maxLength": 200, "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+){0,4}$", "type": "string", "x-enum-policy": "open" }, "EventWriteFields": { "description": "Pass exactly one of `profile_id` or `identifier`.", "properties": { "currency": { "maxLength": 3, "minLength": 3, "type": "string" }, "dedupe_id": { "description": "Deduplicates the event for 48 hours. See [Idempotency](/docs/idempotency).\n", "maxLength": 255, "type": "string" }, "identifier": { "additionalProperties": false, "description": "`email` and `phone` create a profile when none matches.\n", "properties": { "type": { "examples": [ "email", "phone", "external_id", "shopify_customer_id" ], "type": "string", "x-enum-policy": "open" }, "value": { "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "occurred_at": { "description": "Defaults to `received_at`.", "format": "date-time", "type": "string" }, "profile_id": { "pattern": "^prof_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "properties": { "type": "object" }, "type": { "$ref": "#/components/schemas/EventType" }, "value": { "description": "Decimal string, sent with `currency`.", "type": "string" } }, "required": [ "type", "properties" ], "type": "object" }, "Id": { "description": "Type-prefixed ID, parsed case-insensitively. IDs of a type sort by creation time.\n", "pattern": "^[a-z]{2,5}_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "Identifier": { "additionalProperties": false, "properties": { "created_at": { "$ref": "#/components/schemas/Timestamp" }, "display_value": { "type": "string" }, "id": { "$ref": "#/components/schemas/IdentifierId" }, "is_primary": { "type": "boolean" }, "object": { "const": "identifier" }, "profile_id": { "$ref": "#/components/schemas/ProfileId" }, "source": { "type": "string", "x-enum-policy": "open" }, "type": { "examples": [ "email", "phone", "external_id" ], "type": "string", "x-enum-policy": "open" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" }, "value": { "description": "Requires the `identifiers:read_value` scope.", "type": "string" }, "verified_at": { "$ref": "#/components/schemas/NullableTimestamp", "description": "When the identifier was verified." } }, "required": [ "id", "object", "profile_id", "type", "display_value", "is_primary", "verified_at", "source", "created_at", "updated_at" ], "type": "object" }, "IdentifierId": { "pattern": "^idnt_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "IdentifierInput": { "additionalProperties": false, "properties": { "is_primary": { "default": false, "type": "boolean" }, "type": { "examples": [ "email", "phone", "external_id", "shopify_customer_id" ], "pattern": "^[a-z][a-z0-9_.]*$", "type": "string", "x-enum-policy": "open" }, "value": { "description": "Must be a valid E.164 phone number.", "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "type", "value" ], "type": "object" }, "Location": { "additionalProperties": false, "properties": { "city": { "maxLength": 255, "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2.", "maxLength": 2, "pattern": "^[A-Z]{2}$", "type": [ "string", "null" ] }, "region": { "maxLength": 255, "type": [ "string", "null" ] }, "timezone": { "description": "IANA time zone name.", "maxLength": 255, "type": [ "string", "null" ] }, "zip": { "maxLength": 32, "type": [ "string", "null" ] } }, "type": "object" }, "Meta": { "additionalProperties": false, "properties": { "as_of": { "description": "The response reflects data through this instant.\n", "format": "date-time", "type": "string" }, "livemode": { "type": "boolean" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "request_id": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "resolved_from": { "description": "The merged-away profile ID the request addressed; `data` holds the survivor.\n", "type": "string" }, "revision": { "format": "date", "type": "string" } }, "required": [ "request_id", "revision", "livemode" ], "type": "object" }, "Metric": { "additionalProperties": false, "description": "The registered meaning and observed schema of an event type.\n", "properties": { "description": { "description": "Writable on custom metrics only.", "type": [ "string", "null" ] }, "first_seen_at": { "$ref": "#/components/schemas/NullableTimestamp", "description": "When the type was first observed. Null until the first event lands. For recency, use `POST /v1/metric-aggregates`.\n" }, "id": { "$ref": "#/components/schemas/MetricId" }, "name": { "description": "The event type this metric aggregates, e.g. `order.completed`.", "type": "string", "x-enum-policy": "open" }, "object": { "const": "metric" }, "schema": { "additionalProperties": { "enum": [ "string", "number", "boolean", "timestamp", "array", "object", "mixed" ], "type": "string", "x-enum-policy": "closed" }, "description": "Discovered property types, `{property path: type}`. Fills in as events arrive; a path observed with conflicting types reads `mixed`.\n", "type": "object" }, "source": { "description": "Originating integration (`shopify`, `api`, `sdk`).", "type": [ "string", "null" ], "x-enum-policy": "open" }, "system": { "description": "True for platform-owned standard metrics.", "readOnly": true, "type": "boolean" } }, "required": [ "id", "object", "name", "source", "system", "description", "first_seen_at", "schema" ], "type": "object" }, "MetricId": { "description": "Metric ID (`mtr_*`).", "pattern": "^mtr_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "NullableTimestamp": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "type": "null" } ] }, "PageMeta": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "has_more": { "const": true } }, "required": [ "has_more" ] }, "then": { "properties": { "next_cursor": { "pattern": "^cur_", "type": "string" } }, "required": [ "next_cursor" ] } } ], "properties": { "has_more": { "type": "boolean" }, "limit": { "description": "Granted page size.", "maximum": 500, "minimum": 1, "type": "integer" }, "next_cursor": { "description": "Cursor for `page[after]`, valid 7 days.\n", "pattern": "^cur_", "type": [ "string", "null" ] } }, "required": [ "limit", "has_more" ], "type": "object" }, "Profile": { "additionalProperties": false, "properties": { "attributes": { "type": "object" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "id": { "$ref": "#/components/schemas/ProfileId" }, "identifier_ids": { "items": { "$ref": "#/components/schemas/IdentifierId" }, "type": "array" }, "identifiers": { "items": { "$ref": "#/components/schemas/Identifier" }, "type": "array" }, "location": { "oneOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ] }, "merged_into": { "oneOf": [ { "$ref": "#/components/schemas/ProfileId" }, { "type": "null" } ] }, "object": { "const": "profile" }, "profile_ref": { "description": "Property-scoped compact reference, present for properties enabled for the rollout. It is not authorization or merge evidence.", "pattern": "^p_[0-9A-Za-z]{5}$", "type": "string" }, "status": { "$ref": "#/components/schemas/ProfileStatus" }, "tags": { "description": "Managed in the Postscript app and by the Shopify customer sync.", "items": { "type": "string" }, "readOnly": true, "type": "array" }, "updated_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "id", "object", "status", "identifier_ids", "attributes", "tags", "location", "merged_into", "created_at", "updated_at" ], "type": "object" }, "ProfileCreate": { "allOf": [ { "$ref": "#/components/schemas/ProfileWriteFields" } ], "unevaluatedProperties": false }, "ProfileEnvelope": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "type": "object" }, "ProfileId": { "pattern": "^prof_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" }, "ProfileStatus": { "enum": [ "active", "merged", "redacted" ], "type": "string", "x-enum-policy": "closed" }, "ProfileUpdate": { "additionalProperties": false, "description": "Pass exactly one of `attributes` or `attribute_operations`. With `attributes`, each top-level key you send replaces that key atomically. Identifiers are written through their own endpoints.\n", "minProperties": 1, "not": { "required": [ "attributes", "attribute_operations" ] }, "properties": { "attribute_operations": { "items": { "$ref": "#/components/schemas/AttributeOperation" }, "minItems": 1, "type": "array" }, "attributes": { "minProperties": 1, "type": "object" }, "location": { "oneOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ] } }, "type": "object" }, "ProfileUpsert": { "allOf": [ { "$ref": "#/components/schemas/ProfileWriteFields" }, { "not": { "required": [ "attributes", "attribute_operations" ] }, "properties": { "attribute_operations": { "items": { "$ref": "#/components/schemas/AttributeOperation" }, "minItems": 1, "type": "array" } }, "type": "object" } ], "unevaluatedProperties": false }, "ProfileWriteFields": { "properties": { "attributes": { "description": "Custom attributes.", "type": "object" }, "identifiers": { "items": { "$ref": "#/components/schemas/IdentifierInput" }, "minItems": 1, "type": "array" }, "location": { "$ref": "#/components/schemas/Location" } }, "required": [ "identifiers" ], "type": "object" }, "Timestamp": { "examples": [ "2026-07-23T17:32:01.123456Z" ], "format": "date-time", "type": "string" } }, "securitySchemes": { "oauth2": { "description": "OAuth 2.1 + PKCE, per-installation, property-bound, cell claim in signed state — partner apps. The scope vocabulary below is shared with secret-key scopes.\n", "flows": { "authorizationCode": { "authorizationUrl": "https://api.pscrpt.com/oauth/authorize", "refreshUrl": "https://api.pscrpt.com/oauth/token", "scopes": { "accounts:read": "Read the account, calling-key metadata, and discovered schemas.", "apps:read": "Read partner apps and installations.", "campaigns:read": "Read campaigns.", "campaigns:send": "Schedule, send, test-send, and cancel campaigns.", "campaigns:write": "Author campaigns.", "catalogs:read": "Read and export catalog resources.", "catalogs:write": "Manage and import catalog resources.", "consent:read": "Read current consent.", "consent:read_audit": "Export consent evidence.", "consent:write": "Record consent evidence.", "conversations:read": "Read conversations.", "conversations:reply": "Reply within an active conversation context.", "events:read": "Read events.", "events:write": "Create events.", "flows:publish": "Publish and activate flows.", "flows:read": "Read flows.", "flows:trigger": "Trigger flows.", "flows:write": "Author flow drafts.", "identifiers:read_value": "Read normalized identifier values (PII tier).", "identifiers:write": "Manage profile identifiers.", "keywords:read": "Read keywords.", "keywords:write": "Manage keywords.", "lists:read": "Read lists and memberships.", "lists:write": "Manage lists and memberships.", "messages:read": "Read message delivery state.", "messages:send_marketing": "Send consent-gated marketing messages.", "messages:send_transactional": "Send approved transactional template versions.", "metrics:read": "Read metrics and aggregates.", "metrics:write": "Register custom metrics.", "offers:grant": "Grant offers.", "offers:read": "Read offers and codes.", "offers:write": "Manage offers and codes.", "privacy:delete": "Request or retry erasure.", "privacy:export": "Request profile exports.", "privacy:read": "Read privacy requests.", "profiles:merge": "Irreversibly merge profiles with audit provenance.", "profiles:read": "Read profiles.", "profiles:write": "Create and update profiles (includes tag writes).", "reports:read": "Read reports.", "reports:write": "Create reports.", "segments:read": "Read segments and memberships; run side-effect-free previews.", "segments:write": "Author segments.", "suppressions:read": "Read suppressions.", "suppressions:write": "Manage suppressions.", "surfaces:read": "Read onsite surfaces and their performance.", "templates:publish": "Publish templates.", "templates:publish_transactional": "Attest and publish an approved transactional template.", "templates:read": "Read and render templates.", "templates:write": "Author template drafts.", "webhooks:read": "Read endpoints and deliveries.", "webhooks:write": "Manage webhook subscriptions." }, "tokenUrl": "https://api.pscrpt.com/oauth/token" } }, "type": "oauth2" }, "secretKey": { "bearerFormat": "ps_live_* or ps_test_*", "description": "Secret merchant API key with resource:action scopes. Test keys hit the same surface against the property's dedicated sandbox property (meta.livemode false; cross-mode reads 404).\n", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Postscript Native API (Beta)", "version": "2026-07-23" }, "openapi": "3.1.0", "paths": { "/events": { "post": { "description": "`external_id` and `shopify_customer_id` also create a profile when none matches.\n", "operationId": "createEvent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "requestBody": { "content": { "application/json": { "example": { "currency": "USD", "dedupe_id": "shopify:order:8209829119", "identifier": { "type": "email", "value": "jane@example.com" }, "occurred_at": "2026-07-23T14:03:22Z", "properties": { "currency": "USD", "line_item_count": 2, "order_id": "8209829119", "total_price": 139.97 }, "type": "order.completed", "value": "139.97" }, "schema": { "$ref": "#/components/schemas/EventCreate" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/EventCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "events:write" ] } ], "summary": "Create an event", "tags": [ "events" ], "x-auth": { "dynamic": false, "required_scope": "events:write" }, "x-quota-class": "high_volume" } }, "/events/batch": { "post": { "description": "Accepts up to 1,000 events. `external_id` and `shopify_customer_id` must already match a profile. See [Bulk requests](/docs/bulk-requests) for per-item results and retry behaviour.\n", "operationId": "createEventBatch", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "requestBody": { "content": { "application/json": { "example": { "events": [ { "client_reference": "row-1", "currency": "USD", "dedupe_id": "shopify:order:8209829119", "identifier": { "type": "email", "value": "jane@example.com" }, "occurred_at": "2026-07-23T14:03:22Z", "properties": { "currency": "USD", "order_id": "8209829119", "total_price": 139.97 }, "type": "order.completed", "value": "139.97" }, { "client_reference": "row-2", "profile_id": "prof_01h455vb4pex5vsknk084sn02q", "properties": {}, "type": "sms.sent" } ] }, "schema": { "$ref": "#/components/schemas/EventBatchRequest" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/EventBatchResult" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "events:write" ] } ], "summary": "Bulk create events", "tags": [ "events" ], "x-auth": { "dynamic": false, "required_scope": "events:write" }, "x-quota-class": "high_volume" } }, "/profiles": { "post": { "operationId": "createProfile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "requestBody": { "content": { "application/json": { "examples": { "create": { "summary": "Create with one identifier", "value": { "attributes": { "loyalty_tier": "gold" }, "identifiers": [ { "type": "email", "value": "jane@example.com" } ], "location": { "city": "Portland", "country": "US", "region": "OR" } } } }, "schema": { "$ref": "#/components/schemas/ProfileCreate" } } }, "required": true }, "responses": { "201": { "$ref": "#/components/responses/ProfileCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "profiles:write" ] } ], "summary": "Create a profile", "tags": [ "profiles" ], "x-auth": { "dynamic": false, "required_scope": "profiles:write" } } }, "/profiles/lookup": { "get": { "description": "Pass exactly one identifier or property-scoped compact profile reference. An address that moved to another profile in a merge resolves to the survivor.\n", "operationId": "lookupProfile", "parameters": [ { "description": "Case-insensitive.", "in": "query", "name": "email", "schema": { "format": "email", "type": "string" } }, { "description": "International format (`+15035550142`); percent-encode the `+` as `%2B`.", "in": "query", "name": "phone", "schema": { "type": "string" } }, { "in": "query", "name": "external_id", "schema": { "type": "string" } }, { "description": "Case-sensitive property-scoped compact profile reference.", "in": "query", "name": "profile_ref", "schema": { "example": "p_Ab3x9", "pattern": "^p_[0-9A-Za-z]{5}$", "type": "string" } }, { "explode": false, "in": "query", "name": "expand", "required": false, "schema": { "items": { "enum": [ "identifiers" ], "type": "string" }, "maxItems": 5, "type": "array" }, "style": "form", "x-allowed-expansions": [ "identifiers" ] }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "responses": { "200": { "$ref": "#/components/responses/Profile" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "profiles:read" ] } ], "summary": "Look up a profile", "tags": [ "profiles" ], "x-auth": { "dynamic": false, "required_scope": "profiles:read" } } }, "/profiles/upsert": { "post": { "description": "Resolves `identifiers` to a profile and applies the body, creating one if none matches. Pass at most one of `attributes` or `attribute_operations`.\n", "operationId": "upsertProfile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "requestBody": { "content": { "application/json": { "examples": { "upsert": { "summary": "Update-or-create by email", "value": { "attributes": { "loyalty_tier": "platinum" }, "identifiers": [ { "type": "email", "value": "jane@example.com" } ] } }, "upsert_operations": { "summary": "Append to an array attribute without reading first", "value": { "attribute_operations": [ { "op": "append_unique", "path": "sizes", "value": "M" } ], "identifiers": [ { "type": "email", "value": "jane@example.com" } ] } } }, "schema": { "$ref": "#/components/schemas/ProfileUpsert" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/Profile" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "profiles:write" ] } ], "summary": "Upsert a profile", "tags": [ "profiles" ], "x-auth": { "dynamic": false, "required_scope": "profiles:write" } } }, "/profiles/{profile_id}": { "get": { "description": "A merged-away ID returns the source profile's frozen pre-merge snapshot: `status: merged` with `merged_into` set. Writes addressed to that ID follow the permanent alias and apply to the survivor.\n", "operationId": "getProfile", "parameters": [ { "explode": false, "in": "query", "name": "expand", "required": false, "schema": { "items": { "enum": [ "identifiers" ], "type": "string" }, "maxItems": 5, "type": "array" }, "style": "form", "x-allowed-expansions": [ "identifiers" ] }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "responses": { "200": { "$ref": "#/components/responses/Profile" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "profiles:read" ] } ], "summary": "Retrieve a profile", "tags": [ "profiles" ], "x-auth": { "dynamic": false, "required_scope": "profiles:read" } }, "parameters": [ { "$ref": "#/components/parameters/ProfileIdPath" } ], "patch": { "operationId": "updateProfile", "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/PostscriptVersion" } ], "requestBody": { "content": { "application/json": { "examples": { "typed_delete": { "summary": "Delete an attribute key", "value": { "attribute_operations": [ { "op": "delete", "path": "loyalty_tier" } ] } } }, "schema": { "$ref": "#/components/schemas/ProfileUpdate" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/Profile" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream provider failure.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Temporarily unavailable.", "headers": { "Postscript-Version": { "description": "The API revision this response was rendered under.", "schema": { "format": "date", "type": "string" } }, "RateLimit-Limit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Globally unique request identifier.", "schema": { "pattern": "^req_[0-7][0-9a-hjkmnp-tv-z]{25}$", "type": "string" } } } } }, "security": [ { "secretKey": [] }, { "oauth2": [ "profiles:write" ] } ], "summary": "Update a profile", "tags": [ "profiles" ], "x-auth": { "dynamic": false, "required_scope": "profiles:write" } } } }, "security": [ { "secretKey": [] }, { "oauth2": [] } ], "servers": [ { "url": "https://api.pscrpt.com/v1" } ], "tags": [ { "description": "A profile is one person: the identifiers that reach them, the attributes stored about them, and their consent state.", "name": "profiles", "x-displayName": "Profiles" }, { "description": "An event is an immutable record of something a person did — an order, a page view, a custom action. Events drive flows, segments, and analytics.", "name": "events", "x-displayName": "Events" } ], "x-standard-error-statuses": { "400": "malformed or invalid request (BadRequest)", "401": "missing or invalid credential (Unauthorized)", "403": "insufficient scope (Forbidden)", "404": "resource absent in the authenticated property or mode (NotFound)", "409": "state or idempotency conflict (Conflict)", "412": "If-Match ETag mismatch (PreconditionFailed)", "422": "semantically invalid / impossible lifecycle transition (UnprocessableEntity)", "429": "quota exceeded (RateLimited)", "500": "internal API error (InternalError)", "502": "Upstream provider failure.", "503": "Temporarily unavailable." } }