client.organizations

Partner accounts: your client organisations. Act inside one with the Mv-Account header. These methods are on client.organizations, where client is a MoreVoice client (see the Python SDK). On AsyncMoreVoice the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

create()

Create a client organization. Creates a client organisation under your partner account (live keys only). With admin_email, that person is invited as its owner (the invitation link is emailed, never returned).

client.organizations

def create(self, body: _m.OrganizationCreateParamsInput | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Organization

client.organizations.create() · await async_client.organizations.create() · POST /organizations · API reference

Request body

Field	Type	Required	Description
name	string	yes	The client’s name.
admin_email	string	no	The client’s first admin: invited as its owner by email.
billing_mode	"wholesale" | "direct"	no	Default wholesale (billed to you).
country	string	no	ISO 3166-1 alpha-2 (default: yours).
locale	"he" | "en"	no	Default: yours.
plan	"starter" | "growth" | "business" | "enterprise"	no	A plan your wholesale price book offers (default starter).

Returns

Organization:

Field	Type	Description
id	string	The client organisation’s ID. Send it as Mv-Account to act inside it.
object	"organization"	Always organization.
livemode	boolean	true in live mode, false in test mode.
name	string	—
slug	string	—
status	"trial" | "active" | "past_due" | "suspended" | "closed"	trial, active, past_due, suspended or closed.
plan	string	The organisation’s plan (starter, growth, business, enterprise).
billing_mode	"wholesale" | "direct"	wholesale: its usage is billed on your partner invoice; direct: it is billed directly, not through you.
region	string	The data region it lives in (always yours).
country	string	ISO 3166-1 alpha-2.
locale	"he" | "en"	—
parent	string	Your (the partner’s) organisation ID.
members	integer	Active members (seats in use).
created	string	An ISO-8601 timestamp in UTC.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

organization = client.organizations.create({
    "admin_email": "owner@haifa-dental.example",
    "name": "Haifa Dental Clinic",
    "plan": "growth",
})
print(organization)

list()

List client organizations. Your partner account’s client organisations, newest first. Act inside one by sending its ID as the Mv-Account header.

client.organizations

def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, status: _m.OrganizationsListStatus | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Organization]

client.organizations.list() · await async_client.organizations.list() · GET /organizations · API reference

Parameters

Name	Type	Required	Description
limit	integer	no	How many objects to return, 1–100 (default 20).
starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
ending_before	string	no	A cursor or object ID: return the objects before it (newer).
status	"trial" | "active" | "past_due" | "suspended" | "closed"	no	Only organisations in this status.

Returns

A page of results (OrganizationList): data, has_more and next_cursor.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for organization in client.organizations.list():
    print(organization)

retrieve()

Retrieve a client organization. Returns the Organization object. Answers 404 with the code resource_missing when nothing has this ID in this organisation and mode.

client.organizations

def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Organization

client.organizations.retrieve() · await async_client.organizations.retrieve() · GET /organizations/{id} · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A org ID (org_…).

Returns

Organization:

Field	Type	Description
id	string	The client organisation’s ID. Send it as Mv-Account to act inside it.
object	"organization"	Always organization.
livemode	boolean	true in live mode, false in test mode.
name	string	—
slug	string	—
status	"trial" | "active" | "past_due" | "suspended" | "closed"	trial, active, past_due, suspended or closed.
plan	string	The organisation’s plan (starter, growth, business, enterprise).
billing_mode	"wholesale" | "direct"	wholesale: its usage is billed on your partner invoice; direct: it is billed directly, not through you.
region	string	The data region it lives in (always yours).
country	string	ISO 3166-1 alpha-2.
locale	"he" | "en"	—
parent	string	Your (the partner’s) organisation ID.
members	integer	Active members (seats in use).
created	string	An ISO-8601 timestamp in UTC.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

organization = client.organizations.retrieve("org_7Hk2Lm9Qp")
print(organization)

usage.retrieve()

Retrieve a client organization’s usage. The client’s metered usage, as GET /v1/usage reports it for its own key (the client’s prices: wholesale for a wholesale client). Test keys get its test-mode usage.

client.organizations.usage

def retrieve(self, id: str, *, from_: str, to: str, granularity: _m.OrganizationsUsageRetrieveGranularity | Unset = "day", group_by: _m.OrganizationsUsageRetrieveGroupBy | Unset = "kind", kind: _m.OrganizationsUsageRetrieveKind | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> _m.UsageReport

client.organizations.usage.retrieve() · await async_client.organizations.usage.retrieve() · GET /organizations/{id}/usage · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A org ID (org_…).
from	string	yes	The first day (YYYY-MM-DD, the organisation’s time zone).
to	string	yes	The last day, inclusive. Per kind: up to 400 days; per assistant or campaign (and in test mode): up to 92 days.
granularity	"day" | "month"	no	One row per day (default) or per calendar month.
group_by	"kind" | "assistant" | "campaign"	no	kind (default): one row per period and usage kind; assistant / campaign: also split by the assistant or campaign the usage belongs to.
kind	"ai_minute" | "pbx_minute" | "carrier_minute" | "copilot_minute" | "seat_day" | "copilot_seat_day" | "qa_scored_call" | "kb_storage_gb_day" | …	no	Only this usage kind.

Returns

UsageReport:

Field	Type	Description
object	"usage_report"	Always usage_report.
livemode	boolean	true in live mode, false in test mode.
from	string	—
to	string	—
timezone	string	The organisation’s time zone: the days and months are its local calendar.
granularity	"day" | "month"	—
group_by	"kind" | "assistant" | "campaign"	—
data	object[]	—
totals	object[]	The whole range per kind: for a calendar month, the figures of the billing page’s usage summary.
total	Money | null	The whole range’s price; null when nothing was priced.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

usage_report = client.organizations.usage.retrieve("org_7Hk2Lm9Qp", from_="2026-10-01", to="2026-10-31")
print(usage_report)