# Create or update companies

> POST /api/v0/companies: create or replace the B2B companies of your shop from your server, with the company field table, a working request and the errors.

`POST https://releva.ai/api/v0/companies` creates or replaces one or more companies of your shop. For how companies, roles and profiles fit together, read [Companies and roles](https://releva.ai/documentation/learn/companies/companies-and-roles/).

## When to use it

Call it from your server if you sell B2B, where buyers act for companies, to send bulk company updates: when companies are created or change in your system, or to load all companies once. Any company that does not exist in Releva is created. A B2C shop does not need it. To link people to a company, use [Link profiles to companies](https://releva.ai/documentation/reference/companies/link-profiles-to-companies/).

## Authentication

Send your shop’s Secret Key as a bearer token, from your server only:

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

Find the key 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` (see [Errors](https://releva.ai/documentation/reference/companies/create-or-update-companies/#errors)).

## Request

`POST /api/v0/companies` with `content-type: application/json`. The body has `companies`, an array of at least 1 company. Each company is validated strictly: a key that is not in this table is rejected.

| Field         | Type             | Required | Notes                                                                                                                                                                                                                                                                                  |
| ------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`   | string           | yes      | Your id for the company.                                                                                                                                                                                                                                                               |
| `name`        | string           | yes      |                                                                                                                                                                                                                                                                                        |
| `email`       | string           | no       | A valid email address.                                                                                                                                                                                                                                                                 |
| `phoneNumber` | string           | no       | Must start with `+` followed by digits only, for example `+49875345976`.                                                                                                                                                                                                               |
| `tags`        | array of strings | no       | Tags for the company.                                                                                                                                                                                                                                                                  |
| `custom`      | object           | no       | Custom fields: `string`, `numeric` and `date` lists of `{ "key": "...", "values": [...] }`. Can be used to build segments and conditions in workflows. `date` values are `YYYY-MM-DD` or ISO-8601 with seconds and an offset. Send a time and an offset when the exact moment matters. |

Each request **replaces** the stored company. Optional fields you leave out are cleared, so always send the whole company.

```plaintext
curl -X POST 'https://releva.ai/api/v0/companies' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "companies": [
      {
        "companyId": "DEMO-1001",
        "name": "Demo Wholesale",
        "email": "maria@example.com",
        "phoneNumber": "+15555550199",
        "tags": ["wholesale"],
        "custom": {
          "string": [{ "key": "industry", "values": ["Retail"] }],
          "numeric": [{ "key": "employees", "values": [42] }],
          "date": [{ "key": "contractStart", "values": ["2026-01-15T00:00:00Z"] }]
        }
      },
      {
        "companyId": "DEMO-1002",
        "name": "Demo Office Supplies",
        "email": "alex@example.com",
        "phoneNumber": "+15555550142",
        "tags": ["active", "acceptingMessages"],
        "custom": {
          "string": [
            { "key": "industry", "values": ["Office supplies"] },
            { "key": "location", "values": ["Sofia"] }
          ]
        }
      }
    ]
  }'
```

## Response

`202 Accepted` with the body `{}`. The companies are queued and show in the admin under **Data Platform › Companies** shortly after. There is no API call to read companies back.

## Errors

Errors have one shape, `{ "message": "..." }`. When several fields fail, the messages are joined with a space.

| Status | When                                                                              | Message                                                                                                                                 |
| ------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | No `authorization` header                                                         | `Authorization header is missing.`                                                                                                      |
| `400`  | The header is not `Bearer <token>`                                                | ``Authorization header is malformed. It should look like `Bearer <string>`.``                                                           |
| `400`  | The token is not a UUID                                                           | `Authorization header contains an invalid Bearer token.`                                                                                |
| `400`  | No shop has this key                                                              | `Domain with the provided secret key cannot be found.`                                                                                  |
| `400`  | No `companies` key, or the body was sent without `content-type: application/json` | `The 'companies' field is required.`                                                                                                    |
| `400`  | Empty array                                                                       | `The 'companies' field must contain at least 1 items.`                                                                                  |
| `400`  | Missing `name`                                                                    | `The 'companies[0].name' field is required.`                                                                                            |
| `400`  | Numeric `companyId`                                                               | `The 'companies[0].companyId' field must be a string.`                                                                                  |
| `400`  | Unknown key, for example `website`                                                | `The object 'companies[0]' contains forbidden keys: 'website'.`                                                                         |
| `400`  | `custom.date` value such as `15/01/2026`                                          | `companies[0].custom.date[0].values[0] must be a valid ISO-8601 date such as 2020-01-01 with optional time ... Got 15/01/2026 instead.` |
| `402`  | The shop is disabled                                                              | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                                                               |
| `413`  | Body larger than 800 KB                                                           | `request entity too large`                                                                                                              |
| `500`  | Unexpected error                                                                  | `An internal error occurred.` Retry later.                                                                                              |

## Limits

* Body size: 800 KB per request. There is no other limit on the number of companies in one request.
* Rate limits: none on this endpoint.

## Next steps

* [Link profiles to companies](https://releva.ai/documentation/reference/companies/link-profiles-to-companies/): Connect the buyers to the companies you created.
* [Companies and roles](https://releva.ai/documentation/learn/companies/companies-and-roles/): Learn how companies show up in segments and the admin.
* [Find a company and see its activity](https://releva.ai/documentation/guides/companies/find-a-company/): Check in the admin that your companies arrived.