mv.organizations

Partner accounts: your client organisations. Act inside one with the Mv-Account header. These methods are on mv.organizations, where mv is your client (see the Node.js SDK). Each one returns the response object and throws 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).

mv.organizations.create(body: OrganizationsCreateData["body"], options?: RequestOptions): Promise<OrganizationsCreateResponse>

POST /organizations · API reference

Parameters

Name	Type	Required	Description
body.name	string	yes	The client’s name.
body.admin_email	string	no	The client’s first admin: invited as its owner by email.
body.billing_mode	"wholesale" | "direct"	no	Default wholesale (billed to you).
body.country	string	no	ISO 3166-1 alpha-2 (default: yours).
body.locale	"he" | "en"	no	Default: yours.
body.plan	"starter" | "growth" | "business" | "enterprise"	no	A plan your wholesale price book offers (default starter).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options.headers["Idempotency-Key"]	string	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

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

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const organization = await mv.organizations.create({
  admin_email: "owner@haifa-dental.example",
  name: "Haifa Dental Clinic",
  plan: "growth",
});
console.log(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.

mv.organizations.list(query?: NonNullable<OrganizationsListData["query"]>, options?: RequestOptions): PagedList<OrganizationsListResponse["data"][number], NonNullable<OrganizationsListData["query"]>>

GET /organizations · API reference

Parameters

Name	Type	Required	Description
query.limit	integer	no	How many objects to return, 1–100 (default 20).
query.starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
query.ending_before	string	no	A cursor or object ID: return the objects before it (newer).
query.status	string	no	Only organisations in this status.
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

A PagedList: await it for the first page, for await it for every item.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

for await (const organization of mv.organizations.list()) {
  console.log(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.

mv.organizations.retrieve(id: OrganizationsRetrieveData["path"]["id"], options?: RequestOptions): Promise<OrganizationsRetrieveResponse>

GET /organizations/{id} · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A org ID (org_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

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

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const organization = await mv.organizations.retrieve("org_7Hk2Lm9Qp");
console.log(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.

mv.organizations.usage.retrieve(id: OrganizationsUsageRetrieveData["path"]["id"], query: NonNullable<OrganizationsUsageRetrieveData["query"]>, options?: RequestOptions): Promise<OrganizationsUsageRetrieveResponse>

GET /organizations/{id}/usage · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A org ID (org_…).
query.from	string	yes	The first day (YYYY-MM-DD, the organisation’s time zone).
query.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.
query.granularity	string	no	One row per day (default) or per calendar month.
query.group_by	string	no	kind (default): one row per period and usage kind; assistant / campaign: also split by the assistant or campaign the usage belongs to.
query.kind	string	no	Only this usage kind.
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

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

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const usageReport = await mv.organizations.usage.retrieve("org_7Hk2Lm9Qp", {
  from: "2026-10-01",
  to: "2026-10-31",
});
console.log(usageReport);