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:

{
  "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"
  }
}

Swipe horizontally for full code

Top-level fields

Swipe horizontally to view full table

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

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

Swipe horizontally for full code

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

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

Swipe horizontally for full code

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

Swipe horizontally to view full table

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

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

Swipe horizontally for full code

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

Swipe horizontally to view full table

Parameter	Type	Description
`id`	integer	Retreaver’s internal ID of the company.

Create a Company

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

Swipe horizontally for full code

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.

Swipe horizontally to view full table

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

Update a Company

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"}}'

Swipe horizontally for full code

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

Swipe horizontally to view full table

Parameter	Type	Description
`id`	integer	Retreaver’s internal ID of the company.

Body Parameters

Accepts the same parameters as Create a Company. All parameters are optional on update.