Fax Numbers

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 fieldRequiredDescription
area_codeYesThree-digit US area code, such as "312". Availability is checked before rental.
callback_urlNoHTTPS 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.

bash
# 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:

JSON
{
  "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.
JSON
{
  "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.

Legacy v2 fax numbers

The remaining operations use /api/v2 and the legacy developer-owned number contract. The OpenAPI specification describes v2; the v3 provisioning contract is documented above.

List Numbers

GET /fax_numbers — Returns all fax numbers provisioned for your account.

bash
curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/fax_numbers" | jq
curl -s -H "Authorization: Bearer sk_test_..." "https://api.medsender.com/api/v2/fax_numbers" | jq

Response

JSON
{
  "faxNumbers": [
    {
      "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"
    }
  ]
}
{
  "faxNumbers": [
    {
      "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"
    }
  ]
}

Response Fields

FieldDescription
idUnique identifier (UUID) for this fax number
numberThe fax number in E.164 format (e.g. +15550100001)
callbackUrlWebhook URL for incoming fax notifications
createdAtWhen the number was provisioned (ISO 8601)
clientClient object if assigned, otherwise null
uriAPI endpoint URL for this fax number

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)

ParameterRequiredDescription
fax_number.area_codeYes3-digit US area code (e.g. "415", "212")
fax_number.callback_urlNoWebhook URL for incoming fax notifications
fax_number.client_idNoClient ID to assign this number to
bash
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
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

JSON
{
  "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).

bash
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
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

JSON
{
  "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"
  }
}