Authentication and API responses

Use API credentials

Send v3 requests over HTTPS to https://api.multitel.net. Every endpoint in this guide requires authentication. Keep credentials on your server, and never put them in browser JavaScript, public pages, screenshots or source control.

Use one of these credential forms:

HTTP Basic with the API username and password configured for your MultiTEL account.
Bearer token in an Authorization: Bearer YOUR_API_TOKEN header, for an enabled API account configured for token authentication. Token requests are accepted only from addresses permitted for that API account.

If an IP allowlist is configured for your API account, send all requests from permitted addresses.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

The variables in these examples are placeholders for credentials you store privately in your environment.

Handle authentication failures

Authentication failures are sent with HTTP status 401. The body uses the standard envelope, with status.code set to 401 and an empty string as response.

No credentials: status.msg is Username and password are required, and the response includes a Basic authentication challenge.
Bearer token rejected: if the Authorization header uses the Bearer scheme and the token is unknown, disabled or not permitted from your address, status.msg is Invalid bearer token. No other credentials are tried when a Bearer header is present.
Invalid Basic credentials: status.msg starts with A valid username and password pair are required., and the response includes a Basic authentication challenge. The message can contain more diagnostic text, so do not parse it.

Do not retry automatically with the same credentials. Many failed attempts from one address within a short period can cause further requests from that address to be blocked.

Read the response body

Most v3 endpoints, including getcountries, getstates, getareas and other, return JSON in this envelope:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

This is an illustrative country-list response, not a statement of current inventory or capabilities.

Field	Meaning
`status.code`	The API result code, for example `200`, `401`, `404` or `500`.
`status.msg`	A human-readable message. It can be empty. Base program logic on `status.code`, not on the message text.
`status.results`	The number of entries. For the discovery endpoints documented here, it is present when `response` is a JSON list, including an empty list (`0`). It is absent when `response` is an empty string or `null`. Other endpoint payloads can report a count differently; follow their own response documentation.
`response`	The endpoint payload. Its type depends on the endpoint and the outcome. On errors it is an empty string.

An error response looks like this:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

If a response cannot be encoded, the body has status.code 500, status.msg Response encoding error, and an empty object as response.

The legacy GET /v3/countries endpoint returns {"code": 200, "data": [...]} instead. Check each endpoint's documented response. If a body is not valid JSON, for example after an unexpected server failure, treat the request as failed and retry later.

API result codes and HTTP status

status.code is the API result code. It is not the HTTP status. Authentication failures are sent with HTTP 401. Otherwise, the discovery endpoints report outcomes such as 404 and 500 only in status.code and do not set a matching HTTP status. A not-found or missing-parameter result can therefore arrive with a successful HTTP status. Always check status.code before using response.

Result code 500 with the message ISO Code parameter is required means a required parameter is missing. Correct the request instead of treating it as a server outage.

Follow next_function

Discovery results include next_function. It is a relative path without a leading slash, sometimes with a query string, such as v3/getareas/US or v3/getareas/US?state=NY. Prefix it with https://api.multitel.net/ to build the next request, and authenticate that request the same way. Optional filters you sent, such as pid, are not carried into next_function. Add them again if you need them.

Optional inventory selector (pid)

getcountries, getstates and getareas accept an optional pid query parameter that narrows results to one inventory source. Use it only with a value provided by MultiTEL, in either its numeric form or its 32-character hexadecimal form. Omit it for normal use. Send pid in the query string. If the endpoint does not recognise or accept the value, it ignores it without an error, and the request behaves as if pid had been omitted.

Separate discovery from orders

Country, state and area lookups do not change your account. The special-number catalog (other) refreshes catalog details and saves price quotes for your account, but it does not place an order. No discovery request reserves a number, and inventory can change between requests. Review the requirements and price for a number before using an ordering endpoint.

For purchases, assignments, messages, fax sends and other actions, follow that endpoint's own retry rules. If an action times out after submission, check its status or your account records before repeating it. A lost response does not prove that the action failed.