Link profiles to companies
POST https://releva.ai/api/v0/roles links profiles to companies. Each link carries a role, such as buyer.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “Authentication”Send your shop’s Secret Key as a bearer token, from your server only:
authorization: Bearer $RELEVA_SECRET_KEYFind the key under Settings › Shop & Integration; see Find your Access Token and Secret Key. Authentication failures answer 400, not 401 (see Errors).
Request
Section titled “Request”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" } } ] }'Response
Section titled “Response”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
Section titled “Errors”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. |
Limits
Section titled “Limits”- 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.