Provision organization-owned fax numbers through API v3. Existing v2 integrations can use the legacy v2 reference below.
Provision an organization number (v3)
POST /api/v3/fax_numbers rents a real, billable US local fax number for the organization linked to your developer account. Confirm provisioning availability with Medsender before integrating. The .json route suffix is also supported.
Use an explicit live developer API key with Bearer authentication. Your email must be confirmed, production access active, BAA coverage current and organization link enrolled. A portal browser session, test key or organization API credential cannot authorize this purchase. See authentication and enrollment.
Self-serve fax accounts include one number and cannot buy additional numbers through this endpoint; contact support. The server assigns ownership to your linked organization. Do not send an owner, organization, provider or legacy client ID.
| JSON field | Required | Description |
|---|
| area_code | Yes | Three-digit US area code, such as "312". Availability is checked before rental. |
| callback_url | No | HTTPS incoming-fax callback URL. Callback validation and an eligible webhook-signing developer account are required before rental. |
Send a flat JSON object with only these fields. Do not wrap it in fax_number. Extra or nested fields return 400 before rental.
Provisioning can take tens of seconds. The example allows 60 seconds for a response; a client timeout still leaves the rental outcome uncertain.
# Real, billable rental for an eligible organization. Do not automatically retry.
export API_KEY="sk_live_REPLACE_WITH_YOUR_KEY"
curl --retry 0 --fail-with-body --max-time 60 -sS -X POST "https://api.medsender.com/api/v3/fax_numbers" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data '{"area_code":"312","callback_url":"https://example.com/webhooks/fax"}'# Real, billable rental for an eligible organization. Do not automatically retry.
export API_KEY="sk_live_REPLACE_WITH_YOUR_KEY"
curl --retry 0 --fail-with-body --max-time 60 -sS -X POST "https://api.medsender.com/api/v3/fax_numbers" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data '{"area_code":"312","callback_url":"https://example.com/webhooks/fax"}'
# Real, billable rental for an eligible organization. Do not automatically retry.
export API_KEY="sk_live_REPLACE_WITH_YOUR_KEY"
curl --retry 0 --fail-with-body --max-time 60 -sS -X POST "https://api.medsender.com/api/v3/fax_numbers" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data '{"area_code":"312","callback_url":"https://example.com/webhooks/fax"}'
201 Created — the number was saved for your organization:
{
"faxNumber": {
"number": "+13125550199",
"status": "active",
"label": null
}
}{
"faxNumber": {
"number": "+13125550199",
"status": "active",
"label": null
}
}
{
"faxNumber": {
"number": "+13125550199",
"status": "active",
"label": null
}
}
The response contains faxNumber.number in E.164 format, status (active or inactive) and nullable label. The created number also appears in GET /api/v3/fax_numbers as a faxNumbers row. Callback configuration is not echoed in this response. Renting a number does not independently enable incoming webhook enrollment or AI extraction; coordinate those capabilities with Medsender.
V3 provisioning errors and retry safety
- 400: unsupported or nested request fields. Use the flat body above.
- 401: invalid credentials or missing enrollment. Known-account refusal codes include
TEST_KEY_UNSUPPORTED, EMAIL_UNCONFIRMED, ORGANIZATION_NOT_LINKED, PRODUCTION_ACCESS_REQUIRED and BAA_REQUIRED. - 402:
PAYMENT_REQUIRED for a self-serve account suspended for non-payment. - 422: a definite rejection before rental, such as invalid area code or callback, unavailable area code, self-serve additional-number restriction or provisioning not enabled. Follow
error.detail to correct the request or try again later for a transient pre-rental failure. - 502:
RENTAL_OUTCOME_UNKNOWN means a number may already have been rented even though provisioning or the local save could not be confirmed. error.retryable is false.
{
"error": {
"status": 502,
"title": "Rental Outcome Unknown",
"detail": "A fax number may already have been rented. Do not retry this request. Contact support to reconcile the rental before buying another number.",
"code": "RENTAL_OUTCOME_UNKNOWN",
"retryable": false
}
}{
"error": {
"status": 502,
"title": "Rental Outcome Unknown",
"detail": "A fax number may already have been rented. Do not retry this request. Contact support to reconcile the rental before buying another number.",
"code": "RENTAL_OUTCOME_UNKNOWN",
"retryable": false
}
}
{
"error": {
"status": 502,
"title": "Rental Outcome Unknown",
"detail": "A fax number may already have been rented. Do not retry this request. Contact support to reconcile the rental before buying another number.",
"code": "RENTAL_OUTCOME_UNKNOWN",
"retryable": false
}
}
Do not retry an uncertain rental. Disable automatic retries for this purchase, including generic 5xx retries. Treat other 5xx responses, an unreadable response, a lost response or a timeout as uncertain even without an error code. Contact Medsender support to reconcile the carrier rental before requesting another number. The endpoint has no idempotency key or duplicate-request protection. An empty App inventory does not prove that no number was rented.
Provision Number
POST /fax_numbers — Provisions a new fax number in the specified area code.
If your account has reached its fax-number limit, the API returns HTTP 422 with an error message and an upgradePath linking to the account upgrade page.
Request Parameters (JSON body)
| Parameter | Required | Description |
|---|
| fax_number.area_code | Yes | 3-digit US area code (e.g. "415", "212") |
| fax_number.callback_url | No | Webhook URL for incoming fax notifications |
| fax_number.client_id | No | Client ID to assign this number to |
export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."
curl -s -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"fax_number":{"area_code":"415"}}' "$API_BASE/fax_numbers" | jqexport API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."
curl -s -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"fax_number":{"area_code":"415"}}' "$API_BASE/fax_numbers" | jq
export API_BASE="https://api.medsender.com/api/v2"
export API_KEY="sk_test_..."
curl -s -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"fax_number":{"area_code":"415"}}' "$API_BASE/fax_numbers" | jq
Response
{
"faxNumber": {
"id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"number": "+15550100099",
"callbackUrl": null,
"createdAt": "2025-01-15T10:35:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/a1b2c3d4-e5f6-4890-abcd-ef1234567890"
}
}{
"faxNumber": {
"id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"number": "+15550100099",
"callbackUrl": null,
"createdAt": "2025-01-15T10:35:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/a1b2c3d4-e5f6-4890-abcd-ef1234567890"
}
}
{
"faxNumber": {
"id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
"number": "+15550100099",
"callbackUrl": null,
"createdAt": "2025-01-15T10:35:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/a1b2c3d4-e5f6-4890-abcd-ef1234567890"
}
}
Update Callback URL
PATCH /fax_numbers/:id — Updates the webhook callback URL for a fax number.
The :id parameter is the fax number's unique identifier (UUID).
curl -s -X PATCH -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" -d '{"fax_number":{"callback_url":"https://example.com/webhooks/fax"}}' "https://api.medsender.com/api/v2/fax_numbers/YOUR_FAX_NUMBER_ID" | jqcurl -s -X PATCH -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" -d '{"fax_number":{"callback_url":"https://example.com/webhooks/fax"}}' "https://api.medsender.com/api/v2/fax_numbers/YOUR_FAX_NUMBER_ID" | jq
curl -s -X PATCH -H "Authorization: Bearer sk_test_..." -H "Content-Type: application/json" -d '{"fax_number":{"callback_url":"https://example.com/webhooks/fax"}}' "https://api.medsender.com/api/v2/fax_numbers/YOUR_FAX_NUMBER_ID" | jq
Response
{
"faxNumber": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"number": "+15550100001",
"callbackUrl": "https://example.com/webhooks/fax",
"createdAt": "2025-01-15T10:30:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}{
"faxNumber": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"number": "+15550100001",
"callbackUrl": "https://example.com/webhooks/fax",
"createdAt": "2025-01-15T10:30:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}
{
"faxNumber": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"number": "+15550100001",
"callbackUrl": "https://example.com/webhooks/fax",
"createdAt": "2025-01-15T10:30:00.000Z",
"client": null,
"uri": "https://api.medsender.com/api/v2/fax_numbers/f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
}