Submit a phone-number directory listing

Submit a carrier directory listing

Submit the name and address to use for a directory listing on an eligible phone number you own in MultiTEL. This is a paid carrier update, not a caller-name lookup, a private address-book entry or a general update to the portal’s LIDB inventory field.

Only submit details the customer has authorized for a directory listing. Confirm carrier support for the number before using this legacy route. The reviewed handler does not validate provider eligibility or international number format; its carrier request assumes a North American number and removes the first stored digit.

Account and number requirements

Use an enabled API account over HTTPS from an allowed source IP address. The exact number must be a non-void purchased-number row belonging to that account. Use the full international digits in your inventory, such as the country-code-1 format for a supported North American number. Do not use a price-plan ID, number UUID or a number belonging to another account.

Form POST request

Set NUMBER to the owned number. Replace the fictional example with the authorized listing information. This route reads form fields from POST; it does not parse an application/json body.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode "lastname=EXAMPLE" \
  --data-urlencode "firstname=EXAMPLE" \
  --data-urlencode "streetnum=1" \
  --data-urlencode "streetname=Example" \
  --data-urlencode "streetpredir=N" \
  --data-urlencode "streetpostdir=W" \
  --data-urlencode "city=Example City" \
  --data-urlencode "state=NY" \
  --data-urlencode "postalcode=10001" \
  "https://api.multitel.net/v3/directory/$NUMBER"

Directory-listing form fields
Field	Required by this API	Meaning
lastname	Yes	Listing last name or applicable listing-name field.
city	Yes	Listing city.
postalcode	Yes	Listing postal code.
state	Yes	Listing state or region accepted by the supported carrier.
streetname	Yes	Street name.
streetnum	Yes	Street number.
firstname	No	Additional first-name component.
streetpredir, streetpostdir	No	Directional components before and after the street name, when applicable.
streettype, location	No	Street-type or additional location text, when applicable.

The example’s directions and address are placeholders, not a recommended postal address. Do not add a fictitious direction to real customer data. The API’s required-field checks are shallow: they do not establish that an address is valid or accepted by the carrier, and the legacy website applied different form requirements.

The implementation can emit a missing-array-key warning when an optional directional component is absent or empty. If the response is malformed or the carrier rejects the address, retain the request reference and ask support to confirm the listing rather than repeatedly submitting modified address guesses.

Charge and retry behavior

The reviewed handler checks for at least 10.00 balance units before contacting the carrier. After the carrier reports success and the local number update reports success, it deducts 10.00 from the account balance and writes a directory-setup transaction. These are the current implemented amounts, not a new pricing proposal; confirm the applicable billing currency and supported service with your account terms before submitting.

The operation has no idempotency key, duplicate-order guard or transaction around carrier submission, local update and billing. A successful repeated request can cause another carrier submission and another charge. A timeout or API error does not prove that the carrier rejected the earlier request: the provider may have accepted it before a local update failed.

Response

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": ""
}

The normal success response has an empty-string response and no returned listing ID or completion details. It means the carrier and local update paths reported success; it does not prove publication in every external directory, immediate propagation or future caller-ID display.

Legacy errors

Directory-listing API result codes
API code	Meaning
404	The number was not found on the account, or one of the required form fields was empty.
400	The account balance is below the implemented charge.
500	The carrier request failed, or the local update failed after the carrier may already have accepted the request.
200	Reported success; the response contains no publication confirmation.

Read both HTTP status and the JSON status.code/status.msg. Authentication and source-IP restrictions can also prevent a usable response. Do not use GET or query parameters to request an update just because the legacy handler has no explicit HTTP-method guard.

Verify before retrying

Confirm the owned number, carrier eligibility, authorized listing data and charge before sending the request.
Submit once and retain the account-side result without exposing the customer’s address in public logs or analytics.
Check the saved listing and transaction history through the supported account workflow or support. Allow the carrier’s confirmed processing time; this API defines no guaranteed propagation deadline.
When the result is uncertain, have support reconcile the carrier order and local billing before trying again. A repeated request is not an idempotent status check.