Create or update companies
POST https://releva.ai/api/v0/companies creates or replaces one or more companies of your shop. For how companies, roles and profiles fit together, read Companies and roles.
When to use it
Section titled “When to use it”Call it from your server if you sell B2B, where buyers act for companies, to send bulk company updates: when companies are created or change in your system, or to load all companies once. Any company that does not exist in Releva is created. A B2C shop does not need it. To link people to a company, use Link profiles to 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/companies with content-type: application/json. The body has companies, an array of at least 1 company. Each company is validated strictly: a key that is not in this table is rejected.
| Field | Type | Required | Notes |
|---|---|---|---|
companyId |
string | yes | Your id for the company. |
name |
string | yes | |
email |
string | no | A valid email address. |
phoneNumber |
string | no | Must start with + followed by digits only, for example +49875345976. |
tags |
array of strings | no | Tags for the company. |
custom |
object | no | Custom fields: string, numeric and date lists of { "key": "...", "values": [...] }. Can be used to build segments and conditions in workflows. date values are YYYY-MM-DD or ISO-8601 with seconds and an offset. Send a time and an offset when the exact moment matters. |
Each request replaces the stored company. Optional fields you leave out are cleared, so always send the whole company.
curl -X POST 'https://releva.ai/api/v0/companies' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "companies": [ { "companyId": "DEMO-1001", "name": "Demo Wholesale", "email": "maria@example.com", "phoneNumber": "+15555550199", "tags": ["wholesale"], "custom": { "string": [{ "key": "industry", "values": ["Retail"] }], "numeric": [{ "key": "employees", "values": [42] }], "date": [{ "key": "contractStart", "values": ["2026-01-15T00:00:00Z"] }] } }, { "companyId": "DEMO-1002", "name": "Demo Office Supplies", "email": "alex@example.com", "phoneNumber": "+15555550142", "tags": ["active", "acceptingMessages"], "custom": { "string": [ { "key": "industry", "values": ["Office supplies"] }, { "key": "location", "values": ["Sofia"] } ] } } ] }'Response
Section titled “Response”202 Accepted with the body {}. The companies are queued and show in the admin under Data Platform › Companies shortly after. There is no API call to read companies back.
Errors
Section titled “Errors”Errors have one shape, { "message": "..." }. When several fields fail, the messages are joined with a space.
| 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 companies key, or the body was sent without content-type: application/json |
The 'companies' field is required. |
400 |
Empty array | The 'companies' field must contain at least 1 items. |
400 |
Missing name |
The 'companies[0].name' field is required. |
400 |
Numeric companyId |
The 'companies[0].companyId' field must be a string. |
400 |
Unknown key, for example website |
The object 'companies[0]' contains forbidden keys: 'website'. |
400 |
custom.date value such as 15/01/2026 |
companies[0].custom.date[0].values[0] must be a valid ISO-8601 date such as 2020-01-01 with optional time ... Got 15/01/2026 instead. |
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 companies in one request.
- Rate limits: none on this endpoint.