Skip to content

Area: Developers

Link profiles to companies

POST https://releva.ai/api/v0/roles links profiles to companies. Each link carries a role, such as buyer.

Call it from your server when a person joins a company in your system, or changes role there. If no profile has the email or phone number you send, Releva creates one. The company does not have to exist yet: you can send it later with Create or update companies.

Send your shop’s Secret Key as a bearer token, from your server only:

authorization: Bearer $RELEVA_SECRET_KEY

Find the key under Settings › Shop & Integration; see Find your Access Token and Secret Key. Authentication failures answer 400, not 401 (see Errors).

POST /api/v0/roles with content-type: application/json. The body has roles, an array of at least 1 role. Each role is validated strictly: a key that is not in this table is rejected.

Field Type Required Notes
companyId string yes The company’s id, as you send it to POST /companies.
profile object yes { "email": "...", "phoneNumber": "..." } with at least one of the two. No other keys.
profile.email string A valid email address.
profile.phoneNumber string International form only: + and digits. National numbers are not converted here.
role string recommended The person’s role in the company, for example CTO. Always send it. (The API also accepts an entry without role and stores an empty string.)

A profile has one role per company. Sending the same profile and company again replaces the role.

curl -X POST 'https://releva.ai/api/v0/roles' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"roles": [
{ "companyId": "DEMO-1001", "role": "CTO", "profile": { "email": "maria@example.com", "phoneNumber": "+15555550199" } },
{ "companyId": "DEMO-1001", "role": "CEO", "profile": { "email": "alex@example.com", "phoneNumber": "+15555550142" } }
]
}'

202 Accepted with the body {}. Profiles are created or found before the response returns; the links are queued and show in the admin shortly after.

Errors have one shape, { "message": "..." }, with one exception: when a role’s profile has neither email nor phoneNumber, the 400 body is plain text.

Status When Message
400 No authorization header Authorization header is missing.
400 The header is not Bearer <token> Authorization header is malformed. It should look like `Bearer <string>`.
400 The token is not a UUID Authorization header contains an invalid Bearer token.
400 No shop has this key Domain with the provided secret key cannot be found.
400 No roles key, or the body was sent without content-type: application/json The 'roles' field is required.
400 Empty array The 'roles' field must contain at least 1 items.
400 Missing profile The 'roles[0].profile' field is required.
400 profile is {} Plain text: At least one of (email, phoneNumber) is required for each role!
400 National phone number, for example 0888123456 roles[0].profile.phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got 0888123456 instead.
400 Unknown key, for example profile.firstName The object 'roles[0].profile' contains forbidden keys: 'firstName'.
402 The shop is disabled Domain is disabled. Please reach out to support@releva.ai to enable it.
413 Body larger than 800 KB request entity too large
500 Unexpected error An internal error occurred. Retry later.
  • Body size: 800 KB per request. There is no other limit on the number of roles in one request.
  • Rate limits: none on this endpoint.
  • Roles are processed one by one. If a request fails halfway with a 500, the roles before the failure are already saved. Sending the whole request again is safe.