Companies and roles
In a B2B shop the buyer is a person who acts for a company. Releva models this with two records: a company and a role that links a profile (a person) to a company. Profiles work as in any Releva shop; companies and roles add the B2B layer on top. This page explains how the pieces fit together.
Companies
Section titled “Companies”A company has an id from your own systems (companyId), a name, an optional contact email and phone number, free-text tags and custom fields. Custom fields come in three types, string, numeric and date, each a list of { key, values } pairs, and you can use them in segment conditions.
A company is identified by its companyId within your shop. Send the same id again and you update that company. The id is also what links the rest of your data to the company:
- Custom events, search events and cart or order updates accept an optional
companyId. Events with a company’s id appear on its Recent Events tab and are counted in its Aggregated Statistics. - Roles reference a company by
companyId. Releva does not check that the company exists, so you can send roles before the company or for a company you never send.
Companies reach Releva in two ways: POST /api/v0/companies (any number of companies per request, with custom fields) or the Add Company form in Data Platform › Companies (one company, no custom fields). See Add a company.
Roles link people to companies
Section titled “Roles link people to companies”A role is one profile in one company, with an optional role name such as buyer. You create roles with POST /api/v0/roles, giving the company id and the profile’s email or phone number. If no profile matches, Releva creates one. A profile can belong to several companies, and has at most one role per company: sending a role again replaces its name.
There is no form for roles. The Profiles tab of a company lists the linked profiles, without the role name. To unlink a person, call DELETE /api/v0/roles/{companyId}/{emailOrPhone}; the profile and the company are kept.
Updates replace the whole company
Section titled “Updates replace the whole company”POST /api/v0/companies does not merge. Every request writes a complete company, and any optional field you leave out (email, phoneNumber, tags, custom) is cleared. Always send the full company, even to change one field. This differs from the products API, where omitted fields keep their value.
The Edit form and the API write the same record
Section titled “The Edit form and the API write the same record”The Edit form in the admin saves only the Company Id, name, email, phone number and tags, and that save replaces the stored company like an API request does. A company that has custom fields loses them when someone saves the form. If your integration sends custom fields, treat the API as the only writer for those companies, or send the company again after an edit.
Deletes are reversible
Section titled “Deletes are reversible”Deleting a company, from the admin or with DELETE /api/v0/companies/{companyId}, marks it deleted. It disappears from the Companies list. Its roles and events stay, and sending the same companyId again restores the company with the new data. Delete roles explicitly if the company is gone for good.
Deleting an unknown company answers 202 like any other delete.
Writes are asynchronous
Section titled “Writes are asynchronous”Every B2B endpoint and the admin forms answer as soon as the request is validated and queued. The company or role is written a few seconds later; on the local test stack rows appeared 5 to 25 seconds after the response. A 202 means the request was valid, not that the data is stored. A search in the admin right after a save can still show the old state.
Phone numbers
Section titled “Phone numbers”- On
POST /api/v0/companies, phone numbers are normalised with your shop’s country before validation: a local number such as0888 123 456becomes+359888123456on a Bulgarian shop, spaces are removed and00becomes+. - On
POST /api/v0/roles, numbers are not normalised. Send+and the country code, or the request is rejected. - The admin forms do not check or change the number. Enter it with
+and the country code so that searches and role lookups match.
Where the data is used
Section titled “Where the data is used”- Data Platform › Companies: list, search, details, linked profiles, events and statistics per company. See Find a company and see its activity.
- Segments: conditions on company fields and on roles select the profiles of matching companies.
- There is no public endpoint to read companies or roles back. Keep your own system as the source of truth.