# Link profiles to companies

> POST /api/v0/roles: link customer profiles to B2B companies with a role, from your server. Creates the profiles when they do not exist.

`POST https://releva.ai/api/v0/roles` links profiles to companies. Each link carries a role, such as `buyer`.

## When to use it

Call it from your server when a person joins a company in your system, or changes role there. If no profile has the email or phone number you send, Releva creates one. The company does not have to exist yet: you can send it later with [Create or update companies](https://releva.ai/documentation/reference/companies/create-or-update-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/link-profiles-to-companies/#errors)).

## Request

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

| Field                 | Type   | Required    | Notes                                                                                                                                           |
| --------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`           | string | yes         | The company’s id, as you send it to `POST /companies`.                                                                                          |
| `profile`             | object | yes         | `{ "email": "...", "phoneNumber": "..." }` with at least one of the two. No other keys.                                                         |
| `profile.email`       | string |             | A valid email address.                                                                                                                          |
| `profile.phoneNumber` | string |             | International form only: `+` and digits. National numbers are not converted here.                                                               |
| `role`                | string | recommended | The person’s role in the company, for example `CTO`. Always send it. (The API also accepts an entry without `role` and stores an empty string.) |

A profile has one role per company. Sending the same profile and company again replaces the role.

```plaintext
curl -X POST 'https://releva.ai/api/v0/roles' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "roles": [
      { "companyId": "DEMO-1001", "role": "CTO", "profile": { "email": "maria@example.com", "phoneNumber": "+15555550199" } },
      { "companyId": "DEMO-1001", "role": "CEO", "profile": { "email": "alex@example.com", "phoneNumber": "+15555550142" } }
    ]
  }'
```

## Response

`202 Accepted` with the body `{}`. Profiles are created or found before the response returns; the links are queued and show in the admin shortly after.

## Errors

Errors have one shape, `{ "message": "..." }`, with one exception: when a role’s `profile` has neither `email` nor `phoneNumber`, the `400` body is plain text.

| 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 `roles` key, or the body was sent without `content-type: application/json` | `The 'roles' field is required.`                                                                                                         |
| `400`  | Empty array                                                                   | `The 'roles' field must contain at least 1 items.`                                                                                       |
| `400`  | Missing `profile`                                                             | `The 'roles[0].profile' field is required.`                                                                                              |
| `400`  | `profile` is `{}`                                                             | Plain text: `At least one of (email, phoneNumber) is required for each role!`                                                            |
| `400`  | National phone number, for example `0888123456`                               | `roles[0].profile.phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got 0888123456 instead.` |
| `400`  | Unknown key, for example `profile.firstName`                                  | `The object 'roles[0].profile' contains forbidden keys: 'firstName'.`                                                                    |
| `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 roles in one request.
* Rate limits: none on this endpoint.
* Roles are processed one by one. If a request fails halfway with a `500`, the roles before the failure are already saved. Sending the whole request again is safe.

## Next steps

* [Remove a profile from a company](https://releva.ai/documentation/reference/companies/remove-a-profile-from-a-company/): Unlink a person who left the company.
* [Companies and roles](https://releva.ai/documentation/learn/companies/companies-and-roles/): Learn how roles appear in segments and on profiles.
* [Find a company and see its activity](https://releva.ai/documentation/guides/companies/find-a-company/): Check the linked profiles in the admin.