Fragen? 0800 55400300

Number Order API

TENIOS provides geographical numbers in Germany and nearly all European countries. Customers can order numbers via the TENIOS customer portal or as described here via the TENIOS API. To order phone numbers, TENIOS requires a verification document, such as a certificate of registration, which proves that you have a valid address within an area code. If not yet available, you have to create a verification document for the desired area code using the method /verification/create before ordering. You will receive a uuid for this document. Once this document has been approved by TENIOS, you can order the corresponding phone numbers with the /number/order method.

Create verification document:

Create a new verification document for customer. For the document to be approved, the specified address must be within the area of the code area.

POST https://api.tenios.com/verification/create

Request Parameter:

access_key String The Api Access Key. It can be found in the menu MY ACCOUNT–>General Settings in the section API in the customer portal.
country String Country name (e.g.:Germany).
city String City name (e.g.:Berlin).
street String Street name.(e.g.:Musterstr).
house_number String House number (e.g.: 4a)
document_type String Type of provided document. Possible values are:

  • ALLOCATION_NOTICE
  • IDENTITY_CARD
  • BUSINESS_LICENSE
  • IDENTITY_CARD_AND_BUSINESS_LICENSE
  • CERTIFICATE_OF_REGISTRATION
  • CONTRACT
document_data String Must be a base64 encoded PDF document (RFC-4648).
area_code String Area code of the city.(e.g.: 221 für Köln)

Examples of correct requests:

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "country": "Germany",
   "city": "Aarbergen",
   "zip": "50670",
   "street": "Musterstr.",
   "house_number": "11",
   "document_type": "ALLOCATION_NOTICE",
   "area_code": "221",
   "document_data": "iVBORw0KGgoAAAANSUhEUgAAA3cA..."
}

 

API Response:

HTTP Status Code: 200 (OK)

{
   "verification_id": "705d5302-d918-454a-b703-c9c23995726e"
}


A response will contain the verification_id (uuid) of created verification document. After the address is validated, one can initiate the number order by selecting the COUNTRY, CITY and AREA_CODE. TENIOS can provide a list of all German cities with related area codes.

Requesting number:

This method creates a number request for a customer. The request body should contain the correct access key, number type, area code, and verification document id.

POST https://api.tenios.com/number/order

Please make sure that the verification_id (uuid) belongs to an already approved verification document.

Request Parameter:

access_key String The Api Access Key. It can be found in the menu MY ACCOUNT –> General Settings in the section API in the customer portal.
number_type String Number type. Currently only the type GEOGRAPHICAL is supported.
verification_id String UUID of verification document.
link_to_number String Optional The link_to_number is optional and allows linking the requested phone number to an already existing number
push_url String Optional HTTPS URL.A POST request to specified URL will be made once the order is completed.
push_secret String Optional If push_url is specified, push_secret must also be specified. Max length of push_secret is 64 characters.

Example of a successful request:

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

 

API Response:

HTTP Status Code: 200 (OK)

{
   "order_id": "300000"
}

 

If you had provided a push_url in your request, our system will make an HTTPS POST request to the specified URL once the order is completed. In this particular example, a push request will be sent to https://www.example.com/order-success.

POST https://www.example.com/order-success

Request parameter:

phonenumber String The call number assigned for the order ID. This number will be available in the customer portal and can be used from now on. If you have also specified a phone number in the “link_to_number” parameter in the order request, the same routing plan is stored for this phone number.
order_id String References the order id to which a phone number was added (you received this id as a return value in case of a successful order request).
push_secret String The “push_secret” that was set in the order request. You can use this to validate the request in your application.

Push URL request:

{
   "phonenumber": "+4912344557",
   "order_id": "28",
   "push_secret": "iwillnottellyou"
}

 

Examples of invalid requests:

NUMBER_ORDER_ILLEGAL_NUMBER_TYPE
This error is returned if a wrong or invalid number_type was provided.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "wrong value",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

 

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_ILLEGAL_NUMBER_TYPE",
   "error_message": "Only 'GEOGRAPHICAL' number type is acceptable.",
   "fields": [
      "number_type"
   ]
}
NUMBER_ORDER_VERIFICATION_ID_NOT_VALID
This error is returned if a wrong or invalid verification_id was provided.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "wrong uuid",
   "link_to_number": "+49888888",
   "push_url": "https://www.example.com/order-success%22",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_VERIFICATION_ID_NOT_VALID",
   "error_message": "Invalid verificationId. Valid document UUID expected.",
   "fields": [
      "verification_id"
   ]
}
NUMBER_ORDER_WRONG_LINK_NUMBER
This error is returned if a wrong or invalid link_to_number was provided.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+123",
   "push_url": "https://www.example.com/order-success",
   "push_secret": "iwillnottellyou"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_WRONG_LINK_NUMBER",
   "error_message": "The provided link phone number is not valid. You can use only suitable for linking numbers which are assigned to your account.",
   "fields": [
      "link_to_number"
   ]
}
NUMBER_ORDER_INVALID_PUSH_SECRET
This error is returned if a wrong or invalid push_secret was provided.

Request:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "number_type": "GEOGRAPHICAL",
   "verification_id": "5b7a8d2a-a09f-4dc5-9924-93829c13fe18",
   "link_to_number": "+49888888",
   "push_url": "https://myurl",
   "push_secret": "*****************************************************************"
}

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "NUMBER_ORDER_INVALID_PUSH_SECRET",
   "error_message": "Provided push secret is not valid. Text up to 64 characters long is allowed.",
   "fields": [
      "push_secret"
   ]
}
After the order process has been completed, TENIOS will confirm the activation of the number within 24 hours.
Afterwards, the routing settings of the phone number can be edited via the TENIOS customer portal. [/mkb-info]
It is also possible to link the phone number with an existing phone number. In this case, changes to the routing and routing settings of the main phone number are automatically applied to this phone number.
 TENIOS has implemented this mechanism so that an existing routing can be assigned to a new phone number via the API. You can set the parameter link_to_number to assign the routing plan and the routing options of the main number of the newly ordered phone number. [/su_note]    

 

TOP