# B2B API overview

> The company and role calls of the Releva API, one page each (create or update companies, delete a company, link profiles to companies, remove a profile from a company).

The B2B API creates, updates and deletes the companies of one shop, and links profiles to companies with roles. Every call is under `https://releva.ai/api/v0` and is made from your server with your shop’s Secret Key.

| Call                                                                                                   | Endpoint                                   | Purpose                                                                  |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------ |
| [Create or update companies](https://releva.ai/documentation/reference/companies/create-or-update-companies/)           | `POST /companies`                          | Create or replace companies.                                             |
| [Delete a company](https://releva.ai/documentation/reference/companies/delete-a-company/)                               | `DELETE /companies/{companyId}`            | Delete one company.                                                      |
| [Link profiles to companies](https://releva.ai/documentation/reference/companies/link-profiles-to-companies/)           | `POST /roles`                              | Link profiles to companies with a role, creating the profiles if needed. |
| [Remove a profile from a company](https://releva.ai/documentation/reference/companies/remove-a-profile-from-a-company/) | `DELETE /roles/{companyId}/{emailOrPhone}` | Unlink one profile from one company.                                     |

**When to use it.** Integrate these calls if you use Releva in a B2B context, where buyers act for companies. A B2C shop only needs the [profile calls](https://releva.ai/documentation/reference/profiles/overview/). For how companies, roles and events fit together, read [Companies and roles](https://releva.ai/documentation/learn/companies/companies-and-roles/).

There is no call to read companies or roles back. They are visible in the admin under **Data Platform › Companies** and usable in segments.

## Calls

### Create or update companies

`POST /api/v0/companies` creates companies or replaces them whole. See [Create or update companies](https://releva.ai/documentation/reference/companies/create-or-update-companies/).

### Delete a company

`DELETE /api/v0/companies/{companyId}` deletes one company and keeps its roles. See [Delete a company](https://releva.ai/documentation/reference/companies/delete-a-company/).

### Link profiles to companies

`POST /api/v0/roles` links profiles to companies with a role. See [Link profiles to companies](https://releva.ai/documentation/reference/companies/link-profiles-to-companies/).

### Remove a profile from a company

`DELETE /api/v0/roles/{companyId}/{emailOrPhone}` removes one link and keeps the profile and the company. See [Remove a profile from a company](https://releva.ai/documentation/reference/companies/remove-a-profile-from-a-company/).

## Authentication, errors and limits

* Send your shop’s Secret Key as `authorization: Bearer $RELEVA_SECRET_KEY`. Find it under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).
* Authentication failures answer `400`, not `401`. A disabled shop answers `402`.
* HTTPS only. Send JSON with `content-type: application/json`.
* Every successful call answers `202 Accepted` with `{}`. Companies and roles are written in the background and show in the admin shortly after. See [Writes are asynchronous](https://releva.ai/documentation/learn/companies/companies-and-roles/#writes-are-asynchronous).
* Errors have one shape, `{ "message": "..." }`, except the plain-text `400` described in [Link profiles to companies](https://releva.ai/documentation/reference/companies/link-profiles-to-companies/#errors).
* Bodies are limited to 800 KB (`413` above that). There are no rate limits on these calls.
* Unknown fields are rejected. All calls are under `/api/v0`. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/).

## Next steps

* [Create or update companies](https://releva.ai/documentation/reference/companies/create-or-update-companies/): Start by sending your companies.
* [Companies and roles](https://releva.ai/documentation/learn/companies/companies-and-roles/): Learn how people are linked to companies and how updates and deletes behave.
* [Find a company and see its activity](https://releva.ai/documentation/guides/companies/find-a-company/): Check in the admin that your companies and their profiles arrived.