Company

The company is the top-level account object. Use the API to read and update your business address, country, VAT ID, and two-factor authentication policy.

Company two-factor authentication updates are available through the API and apps, but deliberately excluded from MCP and assistant tools. The update_company tool only accepts profile fields and cannot change this security policy.

The company model

There is one company per account. The id is the stable public identifier you can use to reference the company in your own systems.

GET and PATCH responses include read-only plan (free or pro) and entitlements, an object with boolean add_employees, outbound_calls, and add_business_numbers fields. Use entitlements rather than deriving access from the plan: grandfathered Free accounts retain access. New Free accounts can create their first kept employee and acquire their first business number, but need Pro for additional employees, additional business numbers, and outbound calls in the web dashboard. Active Pro trials have Pro access. Existing employees can still be edited and incoming calls are unaffected.

First-party mobile clients receive the same company fields in the existing authenticated GET /api/private/me response, plus top-level plan, entitlements, and feature_flags. Refresh this payload after billing changes. The server enforces employee and additional-business-number creation gates. Outbound calling is currently gated only in the web UI; iOS and Android calls are not blocked by plan. Native outbound-call gating is deferred to a later release.

Properties

Name
id
Type
string
Description
Unique identifier for the company.
Name
name
Type
string
Description
The registered company name.
Name
address
Type
string
Description
Street address. May be null.
Name
city
Type
string
Description
City. May be null.
Name
state
Type
string
Description
State or region. May be null.
Name
zip
Type
string
Description
Postal code. May be null.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code, e.g. "DK".
Name
vat_id
Type
string
Description
VAT registration number, e.g. "DK12345678". May be null.
Name
requires_two_factor
Type
boolean
Description
Whether employees must use two-factor authentication.
Name
plan
Type
string
Description
Read-only subscription plan: free or pro. Active Pro trials return pro.
Name
entitlements
Type
object
Description
Read-only access decisions. add_employees allows creating another employee; outbound_calls controls the web outbound-call upgrade prompt, not native calling; add_business_numbers allows acquiring another business number in the dashboard. All are booleans and account for grandfathered access. The public API does not support purchasing numbers.

GET/v1/company

Retrieve the company

Returns the company associated with the authenticated API key or OAuth token.

Request

GET

/v1/company

curl https://app.phone.inc/api/v1/company \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "id": "019daef1-085e-79ca-bb4d-7f6bf51992d2",
  "name": "Acme ApS",
  "address": "Vesterbrogade 1",
  "city": "Copenhagen",
  "state": null,
  "zip": "1620",
  "country": "DK",
  "vat_id": "DK12345678",
  "requires_two_factor": false,
  "plan": "free",
  "entitlements": { "add_employees": false, "outbound_calls": false, "add_business_numbers": false }
}

PATCH/v1/company

Update the company

Updates one or more fields on the company. Pass only the fields you want to change — omitted fields are left unchanged.

Optional attributes

Name
address
Type
string
Description
Street address.
Name
city
Type
string
Description
City.
Name
state
Type
string
Description
State or region.
Name
zip
Type
string
Description
Postal code.
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code, e.g. "DK". Must match a country Phone.inc supports.
Name
vat_id
Type
string
Description
VAT registration number.
Name
requires_two_factor
Type
boolean
Description
Enable or disable the company two-factor authentication requirement. Omit to leave the policy unchanged. Not accepted by MCP or assistant tools.

Request

PATCH

/v1/company

curl -X PATCH https://app.phone.inc/api/v1/company \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"Aarhus","vat_id":"DK98765432"}'

Response

{
  "id": "019daef1-085e-79ca-bb4d-7f6bf51992d2",
  "name": "Acme ApS",
  "address": "Vesterbrogade 1",
  "city": "Aarhus",
  "state": null,
  "zip": "1620",
  "country": "DK",
  "vat_id": "DK98765432",
  "requires_two_factor": false,
  "plan": "free",
  "entitlements": { "add_employees": false, "outbound_calls": false, "add_business_numbers": false }
}