Skip to main content

Server-side user sync (REST API)

Besides the client-side identifyUser call, you can create and update identified users from your backend with the REST API. This is useful for syncing user attributes on a schedule (e.g. from your CRM or billing system), without waiting for the user's next browser session.

Authentication​

Use an API key from Settings → API keys — the same key used for identity verification and the MCP server, not the client token from your script tag. Send it as a Bearer token:

Authorization: Bearer <your-api-key>

Treat the key like a password: it can read and write all of your Produktly data.

Update attributes (merge)​

PATCH merges attributes into the user: keys you send overwrite, keys you omit are kept, and a key set to null is removed. If the user doesn't exist yet, it is created. This is the safest option for scheduled syncs because it won't overwrite attributes your frontend sets via identifyUser.

curl -X PATCH "https://api.produktly.com/api/v1/users/123" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"plan": "startup", "mrr": 99, "trialEndsAt": null}}'

Create or replace a user​

PUT replaces the user's entire attribute object (and creates the user if needed) — same behavior as identifyUser.

curl -X PUT "https://api.produktly.com/api/v1/users/123" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"plan": "startup", "companyId": 42}}'

Read a user​

GET returns the user's current attributes and timestamps. Useful for verifying a sync or reading before a targeted update. Returns 404 if the user doesn't exist. metadata can be null for users that were identified client-side without attributes.

curl "https://api.produktly.com/api/v1/users/123" \
  -H "Authorization: Bearer <your-api-key>"

Delete a user​

curl -X DELETE "https://api.produktly.com/api/v1/users/123" \
  -H "Authorization: Bearer <your-api-key>"

Notes​

  • The user ID in the URL is the same ID you pass to identifyUser. URL-encode it if it contains special characters.
  • Attributes must be a JSON object, up to 32 KB serialized. Nested values are allowed.
  • Attributes synced this way are immediately available for user segmentation and targeting, just like attributes set client-side.
  • Rate limit: 300 requests per minute per API key on the /users endpoints.
  • Full request/response schemas: see the API reference.