/integrations/* are HMAC-authenticated. Full
request/response schemas with try-it-out controls are in the
API Reference tab.
Endpoints at a glance
| Method | Path | Purpose |
|---|---|---|
POST | /integrations/users | Idempotently provision or update a user. |
DELETE | /integrations/users/{externalUserId} | Anonymise a user (soft delete). |
POST /integrations/users
Idempotently creates or updates a user keyed by (partner_id, externalUserId).
If the user was previously anonymised, this call revives the row and
clears anonymizedAt.
PII fields that are omitted are left unchanged. Passing an explicit
null clears them.
Headers
x-partner-slugx-signaturecontent-type: application/json
| Field | Type | Required | Notes |
|---|---|---|---|
externalUserId | string (1–255) | ✓ | Your stable ID. |
email | string | null | Set to null to clear; omit to leave unchanged. | |
displayName | string | null | Up to 200 chars. | |
phone | string | null | E.164 recommended. | |
countryCode | string | null | ISO 3166-1 alpha-2 (auto-uppercased). | |
locale | string | null | BCP-47 (e.g. en-SG). Currently informational. |
| HTTP | Body | Meaning |
|---|---|---|
| 200 | { userId, created: false } | Existing user updated. |
| 201 | { userId, created: true } | New user created. |
| 400 | { error: "validation_failed", issues: [...] } | Bad body. |
| 401 | { error } | HMAC auth failed. See errors. |
| 403 | { error: "partner_disabled" } | Your partner record is disabled. |
| 500 | { error: "upsert_failed" } | Race-recovery failed; safe to retry. |
DELETE /integrations/users/{externalUserId}
Soft-deletes the user: clears email/displayName/phone/countryCode/locale and
stamps anonymizedAt. Redemption and claim history is preserved for
audit and reporting.
A subsequent POST /integrations/users with the same externalUserId
revives the row and re-populates the PII.
Headers — same as above. The body is empty; sign the empty string:
hmac_sha256(secret, "${timestamp}.").
Responses
| HTTP | Body | Meaning |
|---|---|---|
| 204 | (empty) | Anonymised. |
| 401 / 403 | { error } | HMAC / disabled. |
| 404 | { error: "user_not_found" } | No user for (partner, externalUserId). |