NUACOM API

Numbers & call routing

Numbers

Numbers are the public phone numbers (DIDs) callers dial to reach the account. This group lists the numbers the account holds and covers getting new ones: the countries and prices on offer, searching NUACOM's stock and the provider catalogues, filing an order request, including the identity and address proof some countries require. Where a number's calls go (an extension, a queue or an IVR) is set in the portal under Numbers & Inbound Call Routing; the API has no routing endpoint. Number Providers and Porting are managed by NUACOM and have no public endpoints: to move an existing number to NUACOM, contact support, who need your authorisation before the port is requested.

Workflow (what the portal does)

  1. The account's numbers: GET /v2/my-numbers answers a plain array with one {"in_ext", "number_name"} object per assigned number. in_ext is the number as international digits without + (35312345678); number_name is the label given to the line, which, when enabled for that number, is appended to the caller ID name of inbound calls so agents see which line was called. That is the whole row: country, routing target and capabilities are not returned. The numbers an extension may present as caller ID come from GET /v2/extensions/available-cli (see Extensions), fax numbers from GET /v2/fax.
  2. Countries and prices (account admin): GET /v2/numbers/order/countries-info answers one row each for Ireland, the United States and the United Kingdom (iso in lower case: ie, us, gb) with name, priceMonthly (the lowest monthly price in euro), price (the same as text, €5 / month, with a leading space) and currency (€), followed by an Others Regions row with iso xx, price Custom Price and priceMonthly null.
  3. Search the catalogue (account admin): GET /v2/numbers/order/search-available-numbers with category=paid_1 (the only value accepted), iso (the country, IE) and optionally type (Local, National, Mobile, Toll-free, Shared Cost or Global) and areaCode (digits are matched against the provider's area prefix, text against the area name, for example Dublin). It answers up to 20 rows of {"number", "country_iso", "monthly_price"} with number in E.164 (+35312345678) and the monthly price in euro.
  4. File the order (account admin): POST /v2/numbers/order/phone-number-request with category: "paid_1", numbers as an array of {"number", "price"} objects copied from the search (price is the monthly price) and an optional description. The request is recorded and opens a ticket with NUACOM's number team, who contact the requesting user to complete the purchase; the call itself provisions nothing. It answers 200 with {"status": "success", "numbers": [...]} echoing the array, or 400 with {"status": "error"} when the request could not be recorded.
  5. Search the stock: GET /v2/numbers/search takes category (free, paid_1, paid_2 or paid_3), optional iso (ISO 3166-1 alpha-2) and number_contains (2 to 20 digits, optional leading +). free lists numbers NUACOM already holds in stock, ten per page as {"id", "number"} rows in data with current_page and next_page_url, narrowed by dial code and area with country_code and area_code. The paid categories are the provider catalogues, answered as one array of rows with number (digits without +), country_iso, area_name, prefix, features (sms when the number supports SMS), needs_registration, restriction_message, the provider's setup_price and monthly_price, and the prices you pay, setup_price_with_fee and monthly_price_with_fee. Ordering a number from these results goes through the request flow above; the direct assignment the portal uses is not a public endpoint.
  6. Registration: when the chosen row has needs_registration: true, read GET /v2/numbers/get-requirements with category (paid_1 or paid_2) and country_iso first. For paid_1 it answers address_area_level, business_area_level, business_mandatory_fields, service_description_required, proof_types, business_permanent_document, business_onetime_document, restriction_message and country. Send the assign request as multipart/form-data with company_name, first_name, last_name, phone_number, address[country_iso], address[city_name], address[postal_code], address[address], service_description when required, every field named in business_mandatory_fields, and the documents: proofs[0][type] (an id from GET /v2/numbers/proof-types) with proofs[0][files][], and supporting_documents[0][template] (an id from GET /v2/numbers/supporting-document-types; permanent says whether the document stays on file) with supporting_documents[0][files][]. The provider verifies the address after the order and NUACOM records that verification against the number.

Roles and access

  • Any authenticated user: GET /v2/my-numbers, GET /v2/numbers/search, GET /v2/numbers/get-requirements, GET /v2/numbers/proof-types and GET /v2/numbers/supporting-document-types.
  • Account admin (403 otherwise): the three /v2/numbers/order/... endpoints.

Pitfalls

  • GET /v2/my-numbers is the only list of the account's numbers and it holds two fields. Numbers are digits without +; the search endpoints answer them with + (order search) or without (direct search).
  • category differs per endpoint: the order endpoints accept only paid_1, get-requirements accepts paid_1 and paid_2, search and assign accept free, paid_1, paid_2 and paid_3. Any other value is 422.
  • The order search returns at most 20 numbers and silently leaves out numbers whose setup price, fee included, is above 5. An areaCode that matches nothing is ignored and the whole country is searched; an unknown iso answers 200 with [], not 422.
  • numbers on the order request must be objects with number and price; plain strings answer 400. The request is a ticket, not a purchase: the numbers reach GET /v2/my-numbers only once NUACOM completes the order.
  • When address_area_level is Area, address[country_iso] must equal the number's country (422).
  • Monthly prices on the order endpoints and the *_with_fee prices on the direct search include NUACOM's fee and are rounded up to a multiple of 5; setup_price and monthly_price on the direct search are the provider's raw prices.
  • number_contains takes 2 to 20 digits; a leading + is accepted and stripped; wildcards and letters answer 422. The free search is simple pagination without a total: follow next_page_url.