Skip to main content

Register phone numbers

POST 
/v1/businesses/{businessId}/phone-numbers

Registers one or more phone numbers. Numbers must be in E.164 format with a leading +. branding and spoofDefense, if set, apply to every number in the request.

This endpoint only creates. A number already registered to this business is ignored: it is not re-verified, and neither its branding nor its Spoof Defense state is touched. Use PUT to replace an existing number's state or PATCH to change part of it.

A number Hiya cannot accept does not fail the batch. The rest are registered and it is returned in needsAttention with its own error — so a mixed request still returns 200, and the response is what tells you the outcome per number. That holds even if every number needs attention.

The business must have completed verification (ACTIVE or INACTIVE). Registering against one still UNDER_REVIEW or in NEEDS_ATTENTION returns 409. Numbers may be registered while the business is INACTIVE, ready for when branded call is turned on.

Path Parameters​

    businessId string<uuid>required

    The ID of the business, assigned by Hiya.

    Example: 9b8a1c4e-2c0f-4f3d-9a1e-7b3a2b4c6d8f

Header Parameters​

    X-Hiya-Request-Id string

    Your own correlation ID for this call, returned as 

    requestId
    in the response body. Hiya generates one if omitted. A value that doesn't match the pattern is rejected with 
    400
    INVALID_HEADER
    .

    Possible values: <= 200 characters, Value must match regular expression ^[A-Za-z0-9._:/+=@-]+$

    Example: job-2f9c1a7e-0042

Body

required

application/json

Responses​

The batch was processed. Check the response to see which numbers were added, which were already registered, and which need attention.

Response Body

application/json