Profiles API

Write customer profile records to the Experiture CDP. The Profiles API is a purpose-built wrapper around /records/profiles/upsert with identity-resolution defaults tuned for profile entities.

Base URL: https://api.experiture.ai/public/v1

Authentication: All endpoints require a bearer token with cdp:profiles:write scope. See Authentication.

Overview

For batch writes or other object types, use the Records API.

Upsert a Profile

Insert or update one profile row. Matching uses the workspace's configured identity key (typically email or customer_id) unless you override via matchKey.

POST /profiles/upsert
Authorization: Bearer <token>
Content-Type: application/json

Request body

Example request

curl -X POST https://api.experiture.ai/public/v1/profiles/upsert \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "tier": "gold",
      "last_order_at": "2026-04-20T12:00:00Z"
    },
    "matchKey": "email"
  }'

Response — 200 OK

{
  "success": true,
  "data": {
    "operation": "upsert",
    "objectName": "profiles",
    "accepted": true,
    "acceptedAt": "2026-04-21T15:30:00Z",
    "acceptedRecords": 1,
    "matchKey": "email"
  },
  "correlationId": "<uuid>"
}

Field Semantics

• Null vs. missing: omit a field to leave it unchanged. Send null to clear it.
• Timestamps: ISO 8601 with timezone (2026-04-21T15:30:00Z). The server rejects naive datetimes.
• Custom fields: any field that matches the workspace's profiles schema. Unknown fields fail with 422 schema_mismatch.

Use GET /metadata/objects/profiles to inspect the schema before writing.

Errors

See Also

• Records API — general-purpose object writes and batch endpoints
• Metadata API — inspect the profiles schema
• Single Write Guide — end-to-end walkthrough