Skip to content

Area: Developers

POST

Create or update profiles

Path
/profiles
Auth
Secret key · server only
POST
/profiles
curl --request POST \
--url https://releva.ai/api/v0/profiles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "profiles": [ { "profile": { "id": "DEMO-CUST-1001", "email": "maria@example.com", "firstName": "Maria", "lastName": "Example", "registeredAt": "2026-05-01T09:00:00Z", "subscribedAt": "2026-05-01T09:05:00Z", "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-CUST-1001", "addTags": [ "vip" ], "custom": { "string": [ { "key": "loyaltyTier", "values": [ "gold" ] } ] } }, "subscribedAtChanged": true } ] }'

Sends bulk profile updates, intended for backfill and bulk sync from your server. Profiles that do not exist are created. Events recorded by a write (subscribe, register) can start triggered workflows. Writes go to the domain that owns the secret key. Each entry is matched to an existing profile by id, email (case-insensitive) or phoneNumber; unmatched entries create a profile. Fields you omit keep their stored value. addTags/removeTags, addSubscriptions/removeSubscriptions and addCustom change only what they name; subscriptions and custom replace the whole list or object. The write is synchronous: the profile can be read back with GET as soon as the response arrives. Entries without any identifier are skipped; the request fails only if no entry is left. Send email or phoneNumber (international form, + and digits). To unsubscribe a user, call POST /unsubscribe.

Media typeapplication/json

Unknown top-level keys are ignored.

object
profiles
required
Array<object>
>= 1 items
object
profile
required

Send email or phoneNumber with every profile, plus your id. The API skips an entry with none of the three; an entry with only id updates an existing profile with that id and does not create a profile you can read back.

object
id

Your customer id.

string
email
string format: email
phoneNumber

International form (+359888000101) or national form (0888000101). National numbers and values with spaces or dashes (5-15 characters) are converted to +<digits> with the dialling code of the domain’s country before validation. The result must match ^\+\d{1,31}$.

string
<= 32 characters
firstName
string
lastName
string
registeredAt

ISO-8601 date and time with seconds and a timezone offset, optional milliseconds.

string
subscribedAt

When the user subscribed to your marketing. Omit it and the subscription status does not change (leaving it out never unsubscribes). Send it only for a subscribed user, with subscribedAtChanged: true on the entry. A date not later than the last opt-out does not re-subscribe. Do not send null: to unsubscribe, call POST /unsubscribe.

string
birthday

YYYY-MM-DD only.

string format: date
addTags
Array<string>
removeTags
Array<string>
subscriptions

Replaces the subscription list. To clear it, send an empty array []. Do not send null.

Array<string>
addSubscriptions

Adds subscriptions to the list. Adding a User Visible Subscription can also subscribe a profile that never answered; use subscribedAt or the Consent API to change consent.

Array<string>
removeSubscriptions

Removes subscriptions from the list (case-insensitive). Removing the last User Visible Subscription can also unsubscribe the profile; use the Consent API to unsubscribe.

Array<string>
unsubscribeLink

Your per-profile unsubscribe URL (http or https). Leave it out if the profile is not subscribed.

string
custom

Replaces all custom fields.

object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>
addCustom

Merges by key; keys you send replace their values, other keys are kept.

object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required
Array<string>
location
object
lat
required
number
lon
required
number
consent

legitimateInterest (default), privacyPolicy, cookiesPolicy or mandatoryCookies. A consent is never replaced by a lower one (cookiesPolicy = mandatoryCookies > privacyPolicy > legitimateInterest). Unknown values are ignored.

string
subscribedAtChanged

Send true whenever you send subscribedAt.

boolean

Example

{
"profiles": [
{
"profile": {
"id": "DEMO-CUST-1001",
"email": "maria@example.com",
"firstName": "Maria",
"lastName": "Example",
"registeredAt": "2026-05-01T09:00:00Z",
"subscribedAt": "2026-05-01T09:05:00Z",
"unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-CUST-1001",
"addTags": [
"vip"
],
"custom": {
"string": [
{
"key": "loyaltyTier",
"values": [
"gold"
]
}
]
}
},
"subscribedAtChanged": true
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Authorization header is missing."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Request body larger than 800 KB.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "request entity too large"
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}