How to manage batch numbers through CSV

Overview

This document describes how to manage batch numbers through a CSV file. You can efficiently use a CSV file for different operations, such as Create, Update, Attach, Detach, and Delete.

To make changes using the CSV file, you're required to have OWNER role. You also need to respect the configured limits per application.

Step 1: Access the CSV file

The CSV file can be downloaded via the following endpoint:

POST	{{baseUrl}}/api/numbers/csv	Retrieves numbers as a CSV file.

Click to see the details

The CSV file contains data on numbers structured as follows:

APPLICATION_TAG: [empty]
COUNTRY: US
GROUP_ID: ocp
LOCALE: en-US
MINIAPP_DIAMANT_APP_NAME: miniApps
MINIAPP_GROUP: ocp
MINIAPP_ID: test.surname_test.Numeric.MiniApps.ocp
MINIAPP_NAME: czindros_test
MINIAPP_TYPE: Numeric
NUMBER: (UUID)
PHONE_NUMBER_SET_ID: testSetId
NOTE: [empty]

Below you can see a file example:

This structure is identical to what you will find in OCP → Integrations -> Numbers.

Step 2: Prepare CSV for operations

For operations via the endpoint below, you are required to add an OPERATION column:

PUT	{{baseUrl}}/api/numbers/csv	Execute operations on numbers using a CSV file.

You can execute such operations as Create, Update, Attach, Detach, and Delete. If the operation involves acquiring a new number, ensure you also include a PROVIDER column.

Null or empty fields are ignored during the CSV file check.

Create

Click to see the required fields

The required fields are as follows:

GROUP_ID
NUMBER
OPERATION
PROVIDER

Below you can see a file example for the Create operation:

When using the Create operation, you need to specify the provider. For example, when dealing with numbers related to the Twilio service, simply use twilio as the provider.

Update

Click to see the details

The required fields are the following:

NUMBER
MINIAPP_ID
PHONE_NUMBER_SET_ID
APPLICATION_TAG
LOCALE
NOTE
OPERATION

You will find an example below:

When you specify PHONE_NUMBER_SET_ID, the number will be moved to that set, and it should be the same as the number's group.

If a MINIAPP_ID is specified, the number will be attached to that application.

If you want to remove the value in any field, use <NULL>.

Attach

Click to see the details

The following fields are necessary:

NUMBER
MINIAPP_ID
OPERATION
LOCALE

Mind that LOCALE and MINIAPP_ID are mandatory fields.

Below you can see an example:

Detach

Click to see the details

The required fields are:

NUMBER
OPERATION

Below you can see a file example for the Detach operation:

Delete

Click to see the details

The required fields are:

NUMBER
OPERATION

Below you can see a file example for the Delete operation:

Step 3: Execute operations

To make changes using the CSV file, you're required to have OWNER role.

Each type of operation has its limits, which are configured based on the application. Below you can find the default limits for the operations:

To perform operations on multiple numbers from different groups, you must have the appropriate permissions for each number’s group.

For more information on executing operations via CSV, refer to the Batch numbers management through API available on this link.