---
title: "Request a higher phone number allowance"
method: POST
path: "/v1/phone-numbers/allowance-requests"
tags: ["Phone Numbers"]
---

# Request a higher phone number allowance

`POST /v1/phone-numbers/allowance-requests`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/phone-numbers/allowance-requests`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Needs a verified business (BUSINESS_VERIFICATION_REQUIRED until then; see /v1/business-verification). Files a request for HonkIO staff to review. Only one request may be pending at a time. Approval raises the account limit; you are emailed when that happens.

Requires `phone_numbers:w`.

## Request body

- object
  - `requested_limit` integer, required: Total numbers you want to be able to hold (not an increment)
  - `reason` string, required: What you need them for. Staff decide on this.

## Response `201`

The request, pending review.

- NumberAllowanceRequest: A request for a higher phone number allowance.
  - `id` string, required
  - `requested_limit` integer, required: Total numbers asked for, not an increment.
  - `limit_at_request` integer, required
  - `held_at_request` integer, required
  - `reason` string, required
  - `status` 'PENDING' | 'APPROVED' | 'DENIED', required
  - `granted_limit` integer, nullable, required
  - `staff_note` string, nullable, required
  - `decided_at` string, date-time, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: BUSINESS_VERIFICATION_REQUIRED: verify your business first (PUT /v1/business-verification, then submit it). Also LIVE_KEY_REQUIRED for a test key, or FORBIDDEN when the key lacks the permission this operation requires.
- `409`: ALLOWANCE_REQUEST_PENDING: a request is already pending.
- `422`: VALIDATION_ERROR, or INVALID_ALLOWANCE_REQUEST when requested_limit is not above the current limit.
- `429`: RATE_LIMITED: 3 requests per day per account.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)