Contacts

Create and update contacts with the SDK or HTTP API

Use the Contacts API to add or update a contact for your organization. The primary identifier is email: if a contact with that email already exists, attributes are merged into their stored properties (upsert).

SDK method

noketa.contacts.create(payload: CreateContactRequest): Promise<CreateContactResponse>

HTTP

POST /api/v1/contacts (legacy alias: POST /api/v1/profiles)

Authenticate with the Noketa-Secret header set to your organization API key, or with a valid session cookie when calling from the browser.

Request body

Field	Type	Required	Description
`email`	`string`	Yes	Contact email (normalized to lowercase)
`attributes`	`ContactAttributes?`	No	Standard and custom fields (merged into `properties` on the contact)
`subscribed`	`boolean?`	No	Only used when inserting a new contact (default `true` if omitted)
`tags`	`string[]?`	No	Only used when inserting; non-empty strings, max 100 chars each, max 50

ContactAttributes can include known optional fields and any custom keys. See Type Reference for the full shape.

Response

{
  "message": "Contact created",
  "contactId": "<uuid>",
  "action": "created"
}

On update, message is "Contact updated" and action is "updated".

Example (SDK)

import { Noketa } from "noketa";

const noketa = new Noketa(process.env.NOKETA_API_KEY!);

const response = await noketa.contacts.create({
  email: "person@example.com",
  attributes: {
    first_name: "Jane",
    last_name: "Doe",
    locale: "en",
    external_id: "usr_123",
    properties: {
      plan: "pro",
      signup_source: "landing_page",
    },
  },
});

Notes

Use attributes for both standard fields and custom data. Custom keys are supported on the object and under properties.
Pass dates (e.g. birthdate, last_event_date) as Date instances; they are serialized correctly for the API.
The profiles namespace on the SDK is deprecated and forwards to contacts.