Introduction to the Partner Management APIs

The Partner Management APIs let Hiya Amplify partners create and manage business accounts for their customers programmatically: register businesses, turn their services on or off, manage their phone numbers, branding and logos, and query their billable calls.

Base URL for API requests -- https://partner.api.hiyaapi.com

Authentication

All endpoints use Basic HTTP Authentication with your API key, sent in the Authorization: Basic <credentials> header. This is the same key you already use for the Hiya API.

Overview

API	What it does
Businesses	Create, read and list your businesses. A new business starts in status UNDER_REVIEW while Hiya verifies it.
Service lifecycle	Turn a business's branded call and Spoof Defense on or off, or shut a business down.
Phone numbers	Register and manage the phone numbers of your businesses, together with their branding and Spoof Defense.
Logos	Upload and manage the logos used for branded calls. A logo's id is what you set as branding.logoId on a phone number.
Billing	Query billable call counts for your businesses and their phone numbers over a date range.

Conventions

Ownership scoping. Every resource is scoped to the partner the API key authenticates. A businessId, externalId, phone number or logoId that you don't own is treated exactly like one that doesn't exist — the API returns 404, never revealing whether the resource exists under another partner. externalId is namespaced per partner: your externalId values never collide with, or resolve to, another partner's businesses.

Correlation. Every write takes an optional X-Hiya-Request-Id request header carrying an ID of your own; Hiya generates one if you omit it. The ID is never echoed in a response header. Every write response — success or error — carries it as requestId in the body, next to a timestamp of when Hiya handled the call. Errors on reads carry both too.

Timestamps. Every timestamp in a response is in UTC, in RFC 3339 format with millisecond precision — for example 2026-05-28T14:32:10.123Z.

Phone numbers in URLs. A phone number in a path must be URL-encoded — the leading + becomes %2B.

Phone numbers

A business must have completed verification (status is ACTIVE or INACTIVE) before you can add numbers to it; otherwise the request returns 409. Numbers and branding can be set while the business is INACTIVE. Branding goes live when branded call is enabled (PUT /v1/businesses/{businessId}/branded-call with enabled: true).

Registering a number is synchronous — by the time a write returns, each number has either been registered or failed to register, and the response says which. Screening is not: a registered number is then checked against Hiya's number-attribute, conflict and fraud screening, and that outcome arrives later in its status. A number is live and brandable while still PENDING, and can reach NEEDS_ATTENTION after its branding is already in place. Branding distribution is separately asynchronous and is reported by branding.status.

Writing to a number — POST, PUT and PATCH

A number carries two independent products, branding and spoofDefense, and the three write methods treat them differently:

Method	branding / spoofDefense	Semantics
POST (register)	Optional; omitting is the same as null	Creates only. Applies to the numbers it registers; numbers that already exist are ignored, so nothing is ever overwritten.
PUT (replace)	Both required, and nullable	Sets the number to exactly what you send — pass null for a product you don't want. On the collection, numbers you leave out are not touched.
PATCH (partial)	Both optional, and nullable	Omit = unchanged, null = clear, object = replace.

PATCH replaces a whole subresource: a supplied branding or spoofDefense object replaces that object entirely, so include its required fields (branding.displayName, spoofDefense.enabled). Nested fields are not merged — this is not RFC 7396 merge patch, which is why the media type is plain application/json. PATCH is idempotent and never creates a number, and sending every field makes it equivalent to PUT.

Batch writes report per-number outcomes

POST, PUT and PATCH on the collection each take up to 1000 numbers and return a result body. A number Hiya cannot apply does not fail the batch — the rest are applied and it is listed in needsAttention with its own error. Phone-number format is therefore validated server-side, per number, not by the request schema.

Method	Result fields
POST	added, ignored, needsAttention
PUT	updated, needsAttention
PATCH	updated, needsAttention

The status describes the call, not the numbers. A batch Hiya processed returns 200, even if every number ended up in needsAttention. A 4xx means the request itself could not be processed at all: malformed JSON, a missing field, more than 1000 numbers or a malformed X-Hiya-Request-Id (400), a bad API key (401), a business that isn't yours (404), or one that isn't verified or is being deleted (409).

Billing

Counts are returned for the inclusive date range startDate..endDate (both YYYY-MM-DD). You can list counts across your verified businesses, query one business by its Hiya businessId or by your own externalId, and break a business's counts down by phone number.

Data freshness and finality. Billable calls are counted per calendar day, in the local time of the country the phone number belongs to, so that a country's business day falls on one calendar day (one reference time zone per country). A day's counts become available during the following day, and once available they are final — they are not recalculated later, so you can reconcile against them. Days whose counts are not yet available, including the current day, have no points and do not contribute to total; an endDate in the future is accepted. Counts are available from the day a business was created under your account, and calls stay billable and remain in these counts after a number is removed or a business is shut down.