API for phone numbers and documents

With Zadarma’s API you will be able to connect and manage virtual numbers from your own interface (admin interface) without needing to go into Zadarma personal account.

All Zadarma API capabilities and methods can be found here: https://zadarma.com/en/support/api/

Most companies require end-user identification for number connection. User documents can also be uploaded via API.

API features:

• virtual number selection and connection
• connected numbers settings
• handling documents required for number connection (connection requirements information, uploading, verifying previously uploaded documents for a certain number connection)

Steps to connect a number via API:

1. Receiving to-date list of countries and destinations for connection, displaying them to the user
2. Receiving and displaying a list of numbers available to connect
3. Creating user group of documents (if not done before) and uploading documents (if required)
4. Connecting a chosen number using the group of documents
5. Routing numbers to SIP login or SIP URI (set_sip_id)

New number connection

Method GET /v1/direct_numbers/countries/ should be used for receiving a list of countries that are available for number connection, if the request was sent without parameters, the response will be received in the language of the personal account, by adding an optional parameter language you can specify which of the personal account languages the response will be.

Method GET /v1/direct_numbers/country/ should be used for receiving a list of destinations within a country that are available for number connection. Required parameter country - iso country code (ISO 3166-1 alpha-2); Optional parameters language and direction_id. An array of data describing the number will be provided in the response: country, city, connection cost, monthly fee, specifications, SMS reception capabilities etc.

Receiving a list of numbers available for connection, method GET /v1/direct_numbers/available/<DIRECTION_ID>/ with parameters DIRECTION_ID – destination ID or ru495; and mask – optional parameter for searching for number matches.

Number can be connected using method POST /v1/direct_numbers/order/ .

A previously connected number can be extended is needed for several months in advance using method POST /v1/direct_numbers/prolong/

Required request parameters are number and months

Interactions with connected numbers

Method GET /v1/direct_numbers/ (without parameters) brings back an array of information about already connected numbers.

Using method GET /v1/direct_numbers/number/ you can receive information about a certain connected number, request is sent with parameters type and number

Number automatic extending status (if it will be automatically extended for the next period or disconnected at the end of current period) can be obtained using method GET /v1/direct_numbers/autoprolongation/ with request parameters type and number.

To change automatic extending status use method PUT /v1/direct_numbers/autoprolongation/ with request parameters type, number and value

Method PUT /v1/direct_numbers/set_caller_name/ - setting or enabling number Name (Roman alphabet and number, up to 30 symbols) textual number description, also transferred during incoming calls in the From field as CALLERID(name). Required request parameters type, number and caller_name - to delete number name pass an empty field.

Via method PUT /v1/direct_numbers/set_sip_id/ you can route calls from a virtual number to a certain sip login, external server via SIP URI or enable test mode. Required request parameters type, number and sip_id - sip login or external server address, for example 1234567890@myserver.com test_mode – optional, (on|off) – to enable test mode.

Interacting with documents

A group of documents is a collection of user or company data that will use the virtual number, there can be several groups.

Creating a new group of documents, method POST /v1/documents/groups/create/ .

Update information in an existing group of documents using method PUT /v1/documents/groups/update/<GROUPID>/ .

You can upload document file of a group of documents via method POST /v1/documents/upload/ /

Method GET /v1/documents/groups/list/ can be used to receive a list of document groups, and via method GET /v1/documents/groups/get/<ID>/ where ID is group identification, 0 – the main group of documents, you can receive information about a certain group of documents.

Method GET /v1/documents/files will bring back a list of previously uploaded files/documents in the group of documents. group_id – optional parameter, ID of group of documents, (0 or not specified – the main group of documents).

Check: if the group of documents is suitable for number connection in a certain city/destination is performed using method GET /v1/documents/groups/valid/<ID>/ .