Skip to the content

Read the caller's Organization

GET /v1/organization

Property	Value
Operation	`get_organization`
Group	Organization
Scope	`organization:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A configuration read; the Organization is not Call content.
Released in	1.21.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Answers the Organization of the credential with its Call duration ceiling and its revision, which is also the ETag (1.21.0), and from 1.22.0 its dial policy. Every Member role holds organization:read.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the organization:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/organization" \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/organization`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/organization",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	Organization
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is Organization.

Field	Type	Required	Description
`created_at`	Timestamp	yes
`dial_policy`	DialPolicy	no	What outbound phone Calls the Organization may place (1.22.0, FR-telephony-5). The api from 1.22.0 always sends it; an api before 1.22.0 omits it.
`id`	OrganizationId	yes
`max_call_duration_s`	integer	no	The Organization's Call duration ceiling in seconds, from 60 to 7,200 (FR-calls-15). It is the platform ceiling, 7,200 seconds or 120 minutes, until the `owner` lowers it. Added in 1.21.0: a reader treats its absence as the platform ceiling.
`name`	string	yes
`object`	`"organization"`	yes
`phi_mode`	boolean	no	Whether the Organization runs in PHI mode (1.65.0): what a Webhook subscription's selection, a payload's projection and an `include` are checked against, readable by every Member before a request. PHI mode is planned for slices 3.3 to 3.5 and not built, so the api answers false until it is; absent from an older api, which a reader treats as false.
`preview_providers`	boolean	no	Whether the Organization opts in to `preview` Providers (1.60.0): when false, a `preview` Provider runs only for `test` keys and is dropped from every `live` chain with the reason `preview_not_opted_in`; when true, it runs in both. The `owner` turns it on. The api from 1.60.0 always sends it, false until the `owner` turns it on; a reader treats its absence as false.
`production_decision_cases`	boolean	no	Whether the Organization labels its own production Turns for decision corpora (1.59.0; decision-models.md section 9): when true, a `production` decision case copies the redacted caller text of a Turn of one of its Calls; when false, every `production` case is refused with `decision_case_production_not_allowed`. The `owner` turns it on only where the Organization's terms with its callers allow it. Turning it off keeps the cases already copied. The api from 1.59.0 always sends it, false until the `owner` turns it on; a reader treats its absence as false.
`revision`	integer	yes	Counts writes to the Organization (1.21.0); returned as the ETag and required in the If-Match of PATCH `/v1/organization`.
`slug`	string	yes	A URL-safe unique name.
`spend_cap_micros`	SpendCapMicros or null	no	The monthly spend cap; null means none. Added in 1.19.0: a reader treats its absence as null.
`status`	OrganizationStatus	yes
`transfer_allowlist`	TransferAllowlist	no	The only destinations a transfer may reach (1.50.0, FR-telephony-6), by key, each with its number or SIP URI. The api from 1.50.0 always sends it, empty until the `owner` adds one; an api before 1.50.0 omits it.