Create or update companies
- Path
/companies- Auth
- Secret key · server only
const url = 'https://releva.ai/api/v0/companies';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"companies":[{"companyId":"DEMO-CO-1001","name":"Demo Wholesale Ltd","email":"purchasing@example.com","phoneNumber":"+15555550123","tags":["wholesale","demo"],"custom":{"string":[{"key":"industry","values":["Retail"]}],"numeric":[{"key":"employees","values":[42]}]}},{"companyId":"DEMO-CO-1002","name":"Example Office Supplies","email":"office@example.com","tags":["demo"]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://releva.ai/api/v0/companies \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "companies": [ { "companyId": "DEMO-CO-1001", "name": "Demo Wholesale Ltd", "email": "purchasing@example.com", "phoneNumber": "+15555550123", "tags": [ "wholesale", "demo" ], "custom": { "string": [ { "key": "industry", "values": [ "Retail" ] } ], "numeric": [ { "key": "employees", "values": [ 42 ] } ] } }, { "companyId": "DEMO-CO-1002", "name": "Example Office Supplies", "email": "office@example.com", "tags": [ "demo" ] } ] }'Creates or updates companies of the domain that owns the secret key. A company is identified by its
companyId within the domain. Each request replaces the stored company: optional fields you leave out
(email, phoneNumber, tags, custom) are cleared, so always send the full company.
Phone numbers are normalised before validation using the domain’s country (for example 0888 123 456
becomes +359888123456 on a Bulgarian domain).
Processing is asynchronous: a 202 means the companies were queued. They usually appear in Releva within
seconds.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
object
Your unique id for the company within the domain.
Normalised before validation with the domain’s country code: a leading 0 or no prefix gets the
country code, 00 becomes +, spaces and other non-digits are removed.
Custom fields you can use in segments and workflow conditions.
object
object
object
object
ISO-8601 date, optionally with time and offset. Stored in UTC; a date alone is midnight UTC.
Example
{ "companies": [ { "companyId": "DEMO-CO-1001", "name": "Demo Wholesale Ltd", "email": "purchasing@example.com", "phoneNumber": "+15555550123", "tags": [ "wholesale", "demo" ], "custom": { "string": [ { "key": "industry", "values": [ "Retail" ] } ], "numeric": [ { "key": "employees", "values": [ 42 ] } ] } }, { "companyId": "DEMO-CO-1002", "name": "Example Office Supplies", "email": "office@example.com", "tags": [ "demo" ] } ]}Responses
Section titled “Responses”Accepted for asynchronous processing.
object
Example
{}Authentication or validation error.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Authorization header is missing."}{ "message": "Domain with the provided secret key cannot be found."}{ "message": "The 'companies[0].companyId' field must be a string. The 'companies[0].email' field must be a valid e-mail. The object 'companies[0]' contains forbidden keys: 'website'."}{ "message": "The 'companies[0].name' field is required."}{ "message": "The 'companies' field must contain at least 1 items."}{ "message": "companies[0].custom.date[0].values[0] must be a valid ISO-8601 date such as 2020-01-01 with optional time in hours, minutes, seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 15/01/2026 instead."}{ "message": "The 'companies' field is required."}The domain is disabled.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "Domain is disabled. Please reach out to support@releva.ai to enable it."}Request body larger than 800 KB.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "request entity too large"}Unexpected server error.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "An internal error occurred."}