API Number Order

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

Push URL Anfrage:

{ 
  "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":"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]

[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. [/mkb-info]

 

 

 

 

TOP