Skip to content

Area: Developers

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.

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.

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.

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.

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.

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.

  • 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.
  • 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.
  • API referenceB2B API overview

    Get auth, limits, errors and a working request for every company endpoint.

  • Data PlatformAdd a company

    Create a company by hand with the id your own systems use.

  • Data PlatformEdit or delete a company

    Change a company’s name, contact details and tags, or remove it.