# Companies API

Companies exist so resellers can separate their resources by client. AFID and CID values are scoped per Company, so there are no collisions between Companies. Each Company also has its own balance, payment settings, and embedded-affiliate key.

Company endpoints authenticate with `api_key` alone. For other API resources, pass `company_id` to select the Company for the request; if omitted, the request uses the active Company for the authenticated user.

## The Company object

> Example Company:

```json
{
  "company": {
    "id": 1,
    "name": "Retreaver",
    "embedded_key": "6e1a3c121f83dad4c0bef78414b9e597",
    "per_number": "1.0",
    "use_global_suppression_list": true,
    "balance": "100.0",
    "owner_user_name": "Alice Bob",
    "created_at": "2012-04-17T22:58:17Z",
    "updated_at": "2024-12-19T11:00:37Z"
  }
}
```

### Top-level fields

| Field                         | Type              | Description                                                                                          |
| ----------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `id`                          | integer           | Retreaver's internal ID for the company.                                                             |
| `name`                        | string            | Company name.                                                                                        |
| `embedded_key`                | string            | Key used for embedded affiliate phone number management.                                             |
| `per_number`                  | string            | Per-number cost, returned as a decimal string.                                                       |
| `use_global_suppression_list` | boolean           | Whether the company applies the global suppression list.                                             |
| `balance`                     | string            | Account balance, returned as a decimal string.                                                       |
| `owner_user_name`             | string \| null    | Name of the company owner. Only returned for administrator accounts.                                 |
| `created_at` / `updated_at`   | string (ISO 8601) | Creation and last-modified timestamps.                                                               |

## Get the active Company

```shell
curl "https://api.retreaver.com/company.json?api_key=[api_key]"
```

> The above command returns a single Company object.

Returns the currently active Company for the authenticated user. This is the Company used by API requests made without a specific `company_id`.

> [!WARNING]
> Always pass `company_id` explicitly when working with other resources. Switching Companies in the web interface also switches the active Company for the API, so relying on the active Company can produce surprising results in shared accounts.

### HTTP Request

`GET https://api.retreaver.com/company.json?api_key=[api_key]`

## List all Companies

```shell
curl "https://api.retreaver.com/companies.json?api_key=[api_key]"
```

> The above command returns an array of Company objects.

Returns all Companies accessible via your account. Results are paginated.

### HTTP Request

`GET https://api.retreaver.com/companies.json?api_key=[api_key]`

### Query Parameters

| Parameter  | Type    | Default | Description                                     |
| ---------- | ------- | ------- | ----------------------------------------------- |
| `page`     | integer | 1       | The page of results to return.                  |
| `per_page` | integer | 25      | The number of results per page. Maximum is 100. |

## Get a specific Company

```shell
curl "https://api.retreaver.com/companies/1.json?api_key=[api_key]"
```

> The above command returns a single Company object.

Returns a Company by its Retreaver internal ID.

### HTTP Request

`GET https://api.retreaver.com/companies/{id}.json?api_key=[api_key]`

### Path Parameters

| Parameter | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `id`      | integer | Retreaver's internal ID of the company. |

## Create a Company

```shell
curl -s \
    -X POST \
    "https://api.retreaver.com/companies.json?api_key=[api_key]" \
    -H "Content-Type: application/json" \
    -d '{"company":{"name":"CallPixels.com"}}'
```

> The above command returns the newly created Company object.

Creates a new Company under your account. Each Company you create has its own resources (Numbers, Campaigns, Affiliates) and its own payment settings.

### HTTP Request

`POST https://api.retreaver.com/companies.json?api_key=[api_key]`

`Content-Type: application/json`

### Body Parameters

All parameters must be nested under a `company` key.

| Parameter | Type   | Required | Description       |
| --------- | ------ | -------- | ----------------- |
| `name`    | string | required | The company name. |

## Update a Company

```shell
curl -s \
    -X PUT \
    "https://api.retreaver.com/companies/1.json?api_key=[api_key]" \
    -H "Content-Type: application/json" \
    -d '{"company":{"name":"New Company Name"}}'
```

> The above command returns the updated Company object.

Updates the Company with any attributes you pass in. Only the fields you pass are changed.

### HTTP Request

`PUT https://api.retreaver.com/companies/{id}.json?api_key=[api_key]`

`Content-Type: application/json`

### Path Parameters

| Parameter | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `id`      | integer | Retreaver's internal ID of the company. |

### Body Parameters

Accepts the same parameters as [Create a Company](#create-a-company). All parameters are optional on update.