{ "openapi": "3.0.2", "info": { "title": "Klaviyo API", "version": "2026-04-15", "description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.", "contact": { "name": "Klaviyo Developer Experience Team", "email": "developers@klaviyo.com", "url": "https://developers.klaviyo.com" }, "termsOfService": "https://www.klaviyo.com/legal/api-terms", "license": { "name": "License", "url": "https://www.klaviyo.com/legal" } }, "servers": [ { "url": "https://a.klaviyo.com", "description": "Production" } ], "security": [ { "Klaviyo-API-Key": [] } ], "paths": { "/api/profile-suppression-bulk-create-jobs": { "post": { "operationId": "bulk_suppress_profiles", "summary": "Bulk Suppress Profiles", "description": "Manually suppress profiles by email address or specify a segment/list ID to suppress all current members of a segment/list.\n\nSuppressed profiles cannot receive email marketing, independent of their consent status. To learn more, see our guides on [email suppressions](https://help.klaviyo.com/hc/en-us/articles/115005246108#what-is-a-suppressed-profile-1) and [collecting consent](https://developers.klaviyo.com/en/docs/collect_email_and_sms_consent_via_api).\n\nEmail address per request limit: 100

*Rate limits*:
Burst: `75/s`
Steady: `750/m`\n\n**Scopes:**\n`profiles:write`\n`subscriptions:write`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/bulk_suppress_profiles.json)", "parameters": [ { "name": "fields[profile-suppression-bulk-create-job]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "completed_at", "completed_count", "created_at", "id", "skipped_count", "status", "total_count" ] } }, "explode": false }, { "name": "revision", "in": "header", "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])", "required": true, "schema": { "type": "string", "default": "2026-04-15" } } ], "requestBody": { "description": "Suppresses one or more profiles from receiving marketing. Currently, supports email only. If a profile is not found with the given email, one will be created and immediately suppressed.", "required": true, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SuppressionCreateJobCreateQuery" } } } }, "responses": { "202": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PostBulkProfileSuppressionsCreateJobResponse" } } } }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "tags": [ "Profiles" ], "x-klaviyo-operation-aliases": [ "suppress_profiles", "create_profile_suppression_bulk_create_job" ], "x-klaviyo-pre-release": "None", "x-klaviyo-ratelimit": { "burst": "75/s", "steady": "750/m" }, "x-klaviyo-scopes": [ "profiles:write", "subscriptions:write" ], "x-klaviyo-subtag": "Consent" } } }, "components": { "responses": { "ClientError": { "description": "Client Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } }, "ServerError": { "description": "Server Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } } }, "schemas": { "ListEnum": { "type": "string", "enum": [ "list" ] }, "ObjectLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "PostBulkProfileSuppressionsCreateJobResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileSuppressionBulkCreateJobEnum" }, "id": { "description": "Unique identifier for retrieving the job. Generated by Klaviyo.", "type": "string" }, "attributes": { "type": "object", "properties": { "status": { "description": "Status of the asynchronous job.", "type": "string", "example": "processing", "enum": [ "cancelled", "complete", "processing", "queued" ] }, "created_at": { "description": "The date and time the job was created in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm).", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00" }, "total_count": { "description": "The total number of operations to be processed by the job. See `completed_count` for the job's current progress.", "type": "integer", "example": 10 }, "completed_count": { "description": "The total number of operations that have been completed by the job.", "type": "integer", "example": 9, "default": 0, "nullable": true }, "completed_at": { "description": "Date and time the job was completed in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm).", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00", "nullable": true }, "skipped_count": { "description": "The total number of profiles that have been skipped as part of the job.", "type": "integer", "example": 1, "default": 0, "nullable": true } }, "required": [ "status", "created_at", "total_count" ] }, "relationships": { "type": "object", "properties": { "lists": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ListEnum" }, "id": { "description": "Suppress/Unsuppress all profiles in this list", "type": "string", "example": "Y6nRLr" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "segments": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/SegmentEnum" }, "id": { "description": "Suppress/Unsuppress all profiles in this segment", "type": "string", "example": "Y6nRLr" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "data" ] }, "ProfileEnum": { "type": "string", "enum": [ "profile" ] }, "ProfileSuppressionBulkCreateJobEnum": { "type": "string", "enum": [ "profile-suppression-bulk-create-job" ] }, "ProfileSuppressionCreateQueryResourceObject": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileEnum" }, "attributes": { "type": "object", "properties": { "email": { "description": "The email of the profile to suppress.", "type": "string", "example": "matt-kemp@klaviyo-demo.com" } }, "required": [ "email" ] } }, "required": [ "type", "attributes" ] }, "RelationshipLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "related": { "type": "string", "format": "uri" } }, "required": [ "self", "related" ] }, "SegmentEnum": { "type": "string", "enum": [ "segment" ] }, "SuppressionCreateJobCreateQuery": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SuppressionCreateJobCreateQueryResourceObject" } }, "required": [ "data" ] }, "SuppressionCreateJobCreateQueryResourceObject": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileSuppressionBulkCreateJobEnum" }, "attributes": { "type": "object", "properties": { "profiles": { "description": "The profile(s) to create suppressions for.", "type": "object", "nullable": true, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileSuppressionCreateQueryResourceObject" } } }, "required": [ "data" ] } } }, "relationships": { "type": "object", "properties": { "list": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ListEnum" }, "id": { "description": "Suppress all profiles in this list", "type": "string", "example": "Y6nRLr" } }, "required": [ "type", "id" ] } } }, "segment": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/SegmentEnum" }, "id": { "description": "Suppress all profiles in this segment", "type": "string", "example": "Y6nRLr" } }, "required": [ "type", "id" ] } } } } } }, "required": [ "type", "attributes" ] } }, "securitySchemes": { "Klaviyo-API-Key": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Profiles", "description": "profiles" } ] }