# Companies and roles

> How Releva models B2B customers, how people are linked to companies, how updates and deletes behave, and where the data is used.

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

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](https://releva.ai/documentation/guides/companies/add-a-company/).

## 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

`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

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

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

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

* On `POST /api/v0/companies`, phone numbers are normalised with your shop’s country before validation: a local number such as `0888 123 456` becomes `+359888123456` on a Bulgarian shop, spaces are removed and `00` becomes `+`.
* 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

* **Data Platform › Companies**: list, search, details, linked profiles, events and statistics per company. See [Find a company and see its activity](https://releva.ai/documentation/guides/companies/find-a-company/).
* **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.

## Next steps

* [B2B API overview](https://releva.ai/documentation/reference/companies/overview/): Get auth, limits, errors and a working request for every company endpoint.
* [Add a company](https://releva.ai/documentation/guides/companies/add-a-company/): Create a company by hand with the id your own systems use.
* [Edit or delete a company](https://releva.ai/documentation/guides/companies/edit-a-company/): Change a company’s name, contact details and tags, or remove it.