Skip to content

Area: Developers

POST

Link profiles to companies

Path
/roles
Auth
Secret key · server only
POST
/roles
curl --request POST \
--url https://releva.ai/api/v0/roles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "roles": [ { "companyId": "DEMO-CO-1001", "role": "buyer", "profile": { "email": "maria@example.com" } } ] }'

Creates or updates roles. A role links one profile (found by email or phone number) to one company, with an optional role name. If no profile matches, a new profile is created. A profile has at most one role per company; sending a new role name replaces the old one. The company is not checked for existence. Phone numbers are not normalised here: use + and the international code. Asynchronous.

Media typeapplication/json
object
roles
required
Array<object>
>= 1 items
object
companyId
required
string
role

Free-text role name, for example buyer. Stored as an empty string when omitted.

string
profile
required

At least one of email and phoneNumber is required.

object
>= 1 properties
email
string format: email
phoneNumber
string
>= 2 characters <= 32 characters /^\+\d+$/

Example

{
"roles": [
{
"companyId": "DEMO-CO-1001",
"role": "buyer",
"profile": {
"email": "maria@example.com"
}
}
]
}

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error. When a profile has neither email nor phoneNumber the body is plain text (text/html), not 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."
}