{ "openapi": "3.0.2", "info": { "title": "Klaviyo API", "version": "2026-07-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": { "/client/profiles": { "post": { "operationId": "create_client_profile", "summary": "Create or Update Client Profile", "description": "Create or update properties about a profile without tracking an associated event.\n\nThis endpoint is specifically designed to be called from publicly-browseable, client-side environments only and requires a [public API key (site ID)](https://www.klaviyo.com/settings/account/api-keys). Never use a private API key with our client-side endpoints.\n\nDo not use this endpoint from server-side applications.\nTo create or update profiles from server-side applications, instead use [POST /api/profile-import](https://developers.klaviyo.com/en/reference/create_or_update_profile).\n\nNote that to update a profile's existing identifiers (e.g., email), you must use a server-side endpoint authenticated by a private API key. Attempts to do so via client-side endpoints will return a 202, however the identifier field(s) will not be updated.

*Rate limits*:
Burst: `350/s`
Steady: `3500/m`\n\n**Scopes:**\n`profiles:write`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/create_client_profile.json)", "parameters": [ { "name": "company_id", "in": "query", "description": "Your Public API Key / Site ID. See [this article](https://help.klaviyo.com/hc/en-us/articles/115005062267) for more details.", "required": true, "schema": { "description": "Your Public API Key / Site ID. See [this article](https://help.klaviyo.com/hc/en-us/articles/115005062267) for more details.", "type": "string", "example": "PUBLIC_API_KEY" } }, { "name": "revision", "in": "header", "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])", "required": true, "schema": { "type": "string", "default": "2026-07-15" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OnsiteProfileCreateQuery" } } } }, "responses": { "202": { "description": "Success" }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "security": [], "tags": [ "Client" ], "x-klaviyo-pre-release": "None", "x-klaviyo-ratelimit": { "burst": "350/s", "steady": "3500/m" }, "x-klaviyo-scopes": [ "profiles:write" ] } } }, "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": { "OnsiteProfileCreateQuery": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OnsiteProfileCreateQueryResourceObject" } }, "required": [ "data" ] }, "OnsiteProfileCreateQueryResourceObject": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileEnum" }, "id": { "description": "Primary key that uniquely identifies this profile. Generated by Klaviyo.", "type": "string", "nullable": true }, "attributes": { "type": "object", "properties": { "email": { "description": "Individual's email address", "type": "string", "example": "sarah.mason@klaviyo-demo.com", "nullable": true }, "phone_number": { "description": "Individual's phone number in E.164 format", "type": "string", "example": "+15005550006", "nullable": true }, "external_id": { "description": "A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.", "type": "string", "nullable": true }, "anonymous_id": { "type": "string", "nullable": true }, "_kx": { "description": "Also known as the `exchange_id`, this is an encrypted identifier used for identifying a\nprofile by Klaviyo's web tracking.\n\nYou can use this field as a filter when retrieving profiles via the Get Profiles endpoint.", "type": "string", "nullable": true }, "first_name": { "description": "Individual's first name", "type": "string", "example": "Sarah", "nullable": true }, "last_name": { "description": "Individual's last name", "type": "string", "example": "Mason", "nullable": true }, "organization": { "description": "Name of the company or organization within the company for whom the individual works", "type": "string", "example": "Example Corporation", "nullable": true }, "locale": { "description": "The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)", "type": "string", "example": "en-US", "nullable": true }, "title": { "description": "Individual's job title", "type": "string", "example": "Regional Manager", "nullable": true }, "image": { "description": "URL pointing to the location of a profile image", "type": "string", "example": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg", "nullable": true }, "location": { "$ref": "#/components/schemas/ProfileLocation", "nullable": true }, "properties": { "description": "An object containing key/value pairs for any custom properties assigned to this profile", "type": "object", "example": { "pseudonym": "Dr. Octopus" }, "nullable": true } } }, "meta": { "$ref": "#/components/schemas/OnsiteProfileMeta", "nullable": true } }, "required": [ "type", "attributes" ] }, "OnsiteProfileMeta": { "type": "object", "properties": { "patch_properties": { "description": "Specify one or more patch operations to apply to existing property data", "example": { "append": { "skus": "92538" } }, "$ref": "#/components/schemas/ProfileMetaPatchProperties", "nullable": true }, "patch_identifiers": { "description": "Specify one or more patch operations to apply to existing identifier data. Currently only `email` is supported, and it is used to add or remove secondary email addresses on a profile.", "example": { "append": { "email": [ "example@test.com", "another@example.com" ] } }, "$ref": "#/components/schemas/PatchIdentifiers", "nullable": true } } }, "PatchIdentifiers": { "type": "object", "properties": { "append": { "type": "object" }, "unappend": { "type": "object" } } }, "ProfileEnum": { "type": "string", "enum": [ "profile" ] }, "ProfileLocation": { "type": "object", "properties": { "address1": { "description": "First line of street address", "type": "string", "example": "89 E 42nd St", "nullable": true }, "address2": { "description": "Second line of street address", "type": "string", "example": "1st floor", "nullable": true }, "city": { "description": "City name", "type": "string", "example": "New York", "nullable": true }, "country": { "description": "Country name", "type": "string", "example": "United States", "nullable": true }, "latitude": { "description": "Latitude coordinate. We recommend providing a precision of four decimal places.", "example": "40.7128", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "longitude": { "description": "Longitude coordinate. We recommend providing a precision of four decimal places.", "example": "74.0060", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "region": { "description": "Region within a country, such as state or province", "type": "string", "example": "NY", "nullable": true }, "zip": { "description": "Zip code", "type": "string", "example": "10017", "nullable": true }, "timezone": { "description": "Time zone name. We recommend using time zones from the IANA Time Zone Database.", "type": "string", "example": "America/New_York", "nullable": true }, "ip": { "description": "IP Address", "type": "string", "example": "127.0.0.1", "nullable": true } } }, "ProfileMetaPatchProperties": { "type": "object", "properties": { "append": { "description": "Append a simple value or values to this property array", "type": "object", "example": { "skus": "92538" }, "nullable": true }, "unappend": { "description": "Remove a simple value or values from this property array", "type": "object", "example": { "skus": "40571" }, "nullable": true }, "unset": { "description": "Remove a key or keys (and their values) completely from properties", "example": "skus", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } }, "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-07-15/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Client", "description": "client" } ] }