Skip to content

Area: Developers

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.

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.

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/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"] }
]
}
}
]
}'

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 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.
  • 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.