Skip to content

Area: Developers

POST

Create or update companies

Path
/companies
Auth
Secret key · server only
POST
/companies
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.

Media typeapplication/json
object
companies
required
Array<object>
>= 1 items
object
companyId
required

Your unique id for the company within the domain.

string
name
required
string
email
string format: email
phoneNumber

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.

string
>= 2 characters <= 32 characters /^\+\d+$/
tags
Array<string>
custom

Custom fields you can use in segments and workflow conditions.

object
string
Array<object>
object
key
required
string
values
required
Array<string>
numeric
Array<object>
object
key
required
string
values
required
Array<number>
date
Array<object>
object
key
required
string
values
required

ISO-8601 date, optionally with time and offset. Stored in UTC; a date alone is midnight UTC.

Array<string>

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

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

Authentication or validation error.

Media typeapplication/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."
}