How to manage batch numbers through API

Overview

This document provides an in-depth explanation of managing batch numbers via an API. It specifically elaborates on the usage and management of phone numbers and phone number set.

Authentication

Navigate to the API Authentication to learn more about Authorization Token Endpoint and Authentication process.

Error Codes

Omilia's HTTP response codes can be found on the HTTP Code Responses page.

API Reference

The following provides a thorough explanation of the batch numbers management API endpoints. All the endpoints are grouped as follows:

{{baseUrl}} depends on the user's environment which could be the following:

EU1 - https://eu1-m.ocp.ai/integrations

US1 - https://us1-m.ocp.ai/integrations

US2 - https://us2-m.ocp.ai/integrations

US1W - https://us1-w-m.ocp.ai/integrations

Managing phone numbers

Fetch list of numbers

GET	{{baseUrl}}/api/numbers	Fetches the list of numbers under a group.

Click to see the details

Body Parameters

Parameter	Type	Required	Description
`page`	Integer	No	Page number. Starts from 1. Default value: 1.
`pageSize`	Integer	No	The number of items to be fetched per page. Starts from 1. Default value: 50.
`searchTerm`	String	No	Search for a specific number or note. Default value: %
`orderBy`	String	No	Order the result by `miniapp`, `miniapp-type`, `number`, `locale`, `note`, `group`, `miniapp-group` or `none`. Default value: none
`direction`	String	No	Available options: ASC and DESC for ascending or descending order respectively. Default value: ASC

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
    "numbers": [
        {
            "number": "+12012049893",
            "country": "US",
            "groupId": "ocp-qa",
            "miniAppId": "3781bcc1-7c76-439b-ba26-05d22217b316.SND_dmt_test_app_vp.Flow.ocp-qa@SND_dmt_test_app_vp.ocp-qa",
            "miniAppName": "SND_dmt_test_app_vp",
            "miniAppType": "Flow",
            "miniAppDiamantAppName": "ocp-qa@SND_dmt_test_app_vp",
            "miniAppGroup": "ocp-qa",
            "locale": "en-US",
            "note": "DiaManT - vpolitis",
            "applicationTag": null,
            "phoneNumbersSetId": null,
            "phoneNumbersSetName": null
        },
    ],
    "page": 1,
    "pageSize": 51,
    "numberOfPages": 1,
    "allNumbers": 43
}

Parameter		Type	Description
`numbers`		Array of objects	List of numbers and their parameters.
	`number`	String	The phone number.
	`country`	String	The country code.
	`groupId`	String	The group ID.
	`miniAppId`	String	The miniApp ID.
	`miniAppName`	String	The name of the miniApp.
	`miniAppType`	String	The type of the miniApp.
	`miniAppDiamantAppName`	String	The miniApp DiaManT app name.
	`miniAppGroup`	String	The miniApp group.
	`locale`	String	Locale of the miniApp. Required format: pd-XY.
	`note`	String	A note or comment.
	`applicationTag`		The miniApp tag.
	`phoneNumberSetId`	String	Phone number set ID.
`page`		Integer	The page number.
`pageSize`		Integer	The number of items to be fetched per page.
`orderBy`		String	Order the result by `'miniapp'`, `'miniapp-type'`, `'number'`, `'locale'`, `'note'`, `'group'`, `'miniapp-group'` or `'none'.`
`direction`		String	Available options: ASC and DESC for ascending or descending order respectively.

List available for purchase numbers

POST	{{baseUrl}}/api/numbers	Retrieves the list of available for purchase numbers.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "provider": "string",
  "prefix": "+38",
  "code": "string",
  "group": "string"
}

Parameter	Type	Required	Description
`provider`	String	Yes	CCaaS provider name
`prefix`	String	NI’m o	Telephone number prefix. You can optionally use a leading + followed by digits. Regex pattern: ^\+?\d$*?
`code`	String	Yes	Country code
`group`	String	Yes	OCP group the number is being purchased for

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

[
  {
    "number": "string",
    "country": "string",
    "locality": "string",
    "region": "string",
    "price": 0
  }
]

Parameter		Type	Description
`AvailableNumber`		Array of objects	The list of available numbers with their parameters.
	`number`	String	The phone number.
	`country`	String	The country of the number.
	`locality`	String	The number area.
	`region`	String	The number region.
	`price`	Integer	The price to purchase the number .

Buy a number

PUT	{{baseUrl}}/api/numbers	Request to buy a phone number from the provider.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "provider": "string",
  "numbers": [
    "string"
  ],
  "group": "string",
  "note": "string",
}

Parameter	Type	Required	Description
`provider`	String	Yes	CCaaS provider name.
`numbers`	Array of strings	Yes	List of telephone numbers.
`group`	String	Yes	OCP group the telephone number is being purchased for.
`note`	String	No	A note or comment.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "failedNumbers": [
    "string"
  ],
  "purchasedNumbers": [
    {
      "number": "string",
      "id": "string"
    }
  ]
}

Parameter		Type	Description
`failedNumbers`		Array of strings	List of failed numbers.
`purchasedNumbers`		Array of strings	List of purchased numbers.
	`number`	String	The purchased number.
	`id`	String	The purchased number ID.

Update group

PUT	{{baseUrl}}/api/numbers/group	Updates a group of telephone numbers.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ],
  "group": "string"
}

Parameter	Type	Required	Description
`numbers`	Array of strings	Yes	List of telephone numbers.
`group`	String	Yes	Group name.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Detach a number from a miniApp

PUT	{{baseUrl}}/api/numbers/detach	Detaches a number from a miniApp.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ]
}

Parameter	Type	Required	Description
`numbers`	Array of strings	Yes	List of telephone numbers

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Operations on numbers using CSV file

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

Click to see the details

For this endpoint you can re-use the file from the Fetch numbers as CSV endpoint, but it should include an additional column with the operation type, such as create, delete, attach, detach, update.

Rows with different operations in single file are allowed.

Headers

Content-type: multipart/form-data

Form-data

Parameter	Type	Required	Description
File	String	Yes	CSV file is required.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Fetch numbers as CSV

POST	{{baseUrl}}/api/numbers/csv	Fetches numbers as CSV using advanced search.

Click to see the details

You can find a detailed information on phone numbers management via CSV in this document.

Headers

Content-type: application/json

Request Body

JSON

{
  "miniAppName": "string",
  "miniAppType": "string",
  "number": "string",
  "locale": "string",
  "note": "string",
  "setId": "string",
  "groups": [
    "string"
  ],
  "page": 0,
  "pageSize": 0,
  "orderBy": "string",
  "direction": "string"
}

Parameter	Type	Required	Description
`miniAppName`	String	Optional	The name of the miniApp.
`miniAppType`	String	Optional	The type of the miniApp.
`number`	String	Optional	The phone number.
`locale`	String	Optional	Locale of the miniApp. Required format: pd-XY.
`note`	String	Optional	A note or comment.
`setId`	String	Optional	Phone number set ID.
`groups`	Array of strings	Optional	List of groups.
`page`	Integer	Optional	The number of page.
`pageSize`	Integer	Optional	The number of items to be fetched per page.
`orderBy`	String	Optional	Order the result by `'miniapp'`, `'miniapp-type'`, `'number'`, `'locale'`, `'note'`, `'group'`, `'miniapp-group'` or `'none'.`
`direction`	String	Optional	Available options: ASC and DESC for ascending or descending order respectively.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

"string"

Attach number to an app

PUT	{{baseUrl}}/api/numbers/attach	Attaches a phone number to an app.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ],
  "miniAppId": "string",
  "locale": "ee-DO",
  "applicationTag": "string"
}

Parameter		Type	Required	Description
`AttachRequest`		Object		Request to attach a phone number(s) to a miniApp.
	`numbers`	Array of strings	No	List of telephone numbers.
	`miniAppId`	String	Yes	ID of the miniApp.
	`locale`	String	Yes	Locale of the miniApp. Required format: pd-XY.
	`applicationTag`	String	No	The miniApp tag.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Updates a phone number’s note

PUT	{{baseUrl}}/api/number/note	Updates a note to linked to a phone number.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "number": "string",
  "note": "string"
}

Parameter	Type	Required	Description
`number`	String	Yes	The phone number.
`note`	String	Yes	The new note or comment.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Search for numbers

POST	{{baseUrl}}/api/numbers/search	Searches for numbers based on the search parameters.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "miniAppName": "string",
  "miniAppType": "string",
  "number": "string",
  "pageSize": "string",
  "note": "string",
  "setId": "string",
  "groups": [
    "string"
  ],
  "page": 0,
  "pageSize": 0,
  "orderBy": "string",
  "direction": "string"
}

You can find the request schema details in the Fetch numbers as CSV endpoint.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "numbers": [
    {
      "number": "string",
      "country": "string",
      "groupId": "string",
      "miniAppId": "string",
      "miniAppName": "string",
      "miniAppType": "string",
      "miniAppDiamantAppName": "string",
      "miniAppGroup": "string",
      "locale": "string",
      "note": "string",
      "applicationTag": "string",
      "phoneNumberSetId": "string"
    }
  ],
  "page": 0,
  "pageSize": 0,
  "numberOfPages": 0,
  "allNumbers": 0
}

Parameter		Type	Description
`numbers`		Array of objects	List of numbers and their parameters.
	`number`	String	The phone number.
	`country`	String	The country code.
	`groupId`	String	The group ID.
	`miniAppId`	String	The miniApp ID.
	`miniAppName`	String	The name of the miniApp.
	`miniAppType`	String	The type of the miniApp.
	`miniAppDiamantAppName`	String	The miniApp diamand app name.
	`miniAppGroup`	String	The miniApp group.
	`locale`	String	Locale of the miniApp. Required format: pd-XY.
	`note`	String	A note or comment.
	`applicationTag`		The miniApp tag.
	`phoneNumberSetId`	String	Phone number set ID.
`page`		Integer	The page number.
`pageSize`		Integer	The number of items to be fetched per page.
`orderBy`		String	Order the result by `'miniapp'`, `'miniapp-type'`, `'number'`, `'locale'`, `'note'`, `'group'`, `'miniapp-group'` or `'none'.`
`direction`		String	Available options: ASC and DESC for ascending or descending order respectively.

Add numbers to the database

POST	{{baseUrl}}/api/numbers/direct	Adds numbers directly to the database.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ],
  "group": "string",
  "country": "string",
  "miniAppId": "string",
  "locale": "string",
  "logAni": true,
  "logDnis": true,
  "note": "string",
  "applicationTag": "string"
}

Parameter	Type	Required	Description
`numbers`	Array of strings	Yes	The list of numbers to add to the database.
`group`	String	Yes	The group to add the numbers to.
`country`	String	No	The country of the numbers.
`miniAppId`	String	No	The miniApp ID.
`locale`	String	No	Locale of the miniApp. Required format: pd-XY.
`logAni`	Boolean	No	Enables/disables logging of the dialer’s number.
`logDnis`	Boolean	No	Enables/disables logging of the dialed numbers.
`note`	String	No	A note or comment.
`applicationTag`	String	No	The miniApp tag.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Delete a number

DELETE	{{baseUrl}}/api/numbers/delete/{number}	Deletes a number from the database.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`number`	String	Yes	The phone number to be deleted from the database.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Managing phone numbers sets

Create a set

POST	{{baseUrl}}/api/numbers-set	Creates a set.

Click to see the details

Headers

Content-type: application/json

Request Body

JSON

{
  "name": "string",
  "groupId": "string"
}

Parameter	Type	Required	Description
`name`	String	Yes	Name of the set.
`groupId`	String	Yes	The ID of the group.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "id": "string",
  "name": "string",
  "groupId": "string", "phoneNumberCount": 0
}

Parameter	Type	Description
`id`	String	The ID of the set.
`name`	String	The name of the set.
`groupId`	String	The ID of the group.
`phoneNumberCount`	Integer	The total amount of phone numbers contained in the set.

Get set by ID

GET	{{baseUrl}}/api/numbers-set/{setId}	Retrieves set by ID.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "id": "string",
  "name": "string",
  "groupId": "string",
  "phoneNumberCount": 0,
  "numbersAttachedCount": 0
}

Parameter	Type	Description
`id`	String	The ID of the set.
`name`	String	The name of the set.
`groupId`	String	The ID of the group.
`phoneNumberCount`	Integer	The total amount of phone numbers contained in the set.
`numbersAttachedCount`	Integer	The total amount of phone numbers attached to apps in the set.

Get phone numbers sets for group

GET	{{baseUrl}}/api/numbers-set/group/{groupId}	Retrieves phone numbers sets for group.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`groupId`	String	Yes	ID of the group.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "id": "string",
  "name": "string",
  "groupId": "string",
  "phoneNumberCount": 0,
  "numbersAttachedCount": 0
}

Parameter	Type	Description
`id`	String	The ID of the set.
`name`	String	The name of the set.
`groupId`	String	The ID of the group.
`phoneNumberCount`	Integer	The number of phone numbers in the set.
`numbersAttachedCount`	Integer	The total amount of phone numbers attached to apps in the set.

Update set

PATCH	{{baseUrl}}/api/numbers-set/{setId}	Updates a set.

Click to see the details

This endpoint allows updating:

The group of the numbers set
The name of the numbers set
The numbers in the set

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Headers

Content-type: application/json

Request Body

JSON

{
  "groupId": "string",
  "name": "string",
  "numbers": [
    "string"
  ]
}

Parameter	Type	Required	Description
`groupId`	String	No	New group ID.
`name`	String	No	New numbers set name.
`numbers`	Array of Strings	No	Modify numbers list in the set

Updates the numbers in the set to match the state specified in the request. For example, if you provide an empty array in the ‘numbers’ field, the set will become empty. Set the ‘numbers’ field to null to ignore it entirely (or don’t include it at all).

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "Set successfully updated"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Get phone numbers in set

GET	{{baseUrl}}/api/numbers-set/{setId}/numbers	Retrieves phone numbers in set.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

[
  {
    "number": "string",
    "country": "string",
    "groupId": "string",
    "miniAppId": "string",
    "miniAppName": "string",
    "miniAppType": "string",
    "miniAppDiamantAppName": "string",
    "miniAppGroup": "string",
    "locale": "string",
    "note": "string",
    "applicationTag": "string",
    "phoneNumberSetId": "string"
  }
]

You can find the response schema details in the Search for numbers endpoint.

Get phone numbers for the current user

GET	{{baseUrl}}/api/numbers-set	Retrieves phone numbers sets for the current user.

Click to see the details

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

[
  {
    "id": "string",
    "name": "string",
    "groupId": "string",
    "phoneNumberCount": 0,
    "numbersAttachedCount": 0
  }
]

Parameter		Type	Description
`sets`		Array of objects	The list of sets and their parameters available for the current user.
	`id`	String	The ID of the set.
	`name`	String	The name of the set.
	`groupId`	String	The ID of the group.
	`phoneNumberCount`	Integer	The total amount of phone numbers contained in the set.
	`numbersAttachedCount`	Integer	The total amount of phone numbers attached to apps in the set.

Get unique app names and tags in the set

GET	{{baseUrl}}/api/numbers-set/{setId}/miniapps-and-tags	Retrieves pairs of application names and application tags from the numbers in the set.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

[
    {
        "miniAppName": "string",
        "applicationTag": "string"
    }
]

Parameter	Type	Description
`miniAppName`	String	The name of the miniApp.
`applicationTag`	String	The miniApp tag.

Add numbers to set

POST	{{baseUrl}}/api/numbers-set/{setId}/numbers	Adds numbers to set.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ]
}

Parameter	Type	Required	Description
`numbers`	Array of strings	Yes	List of numbers to be added to the set

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Attach numbers in set

PUT	{{baseUrl}}/api/numbers-set/{setId}/attach	Attaches phone numbers in set to miniApp.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Request Body

JSON

{
  "numbers": [
    "string"
  ],
  "miniAppId": "string",
  "locale": "pd-XY",
  "applicationTag": "string"
}

Parameter	Type	Required	Description
`numbers`	Array of strings	No	List of telephone numbers to be attached.
`miniAppId`	String	Yes	ID of the miniApp to attach the numbers to.
`locale`	String	Yes	Locale of the miniApp. Required format: pd-XY.
`applicationTag`	String	No	The miniApp tag.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Detach numbers in set

PUT	{{baseUrl}}/api/numbers-set/{setId}/detach	Detaches numbers in set from the miniApp.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Remove numbers from set

DELETE	{{baseUrl}}/api/numbers-set/{setId}/numbers	Deletes a number from the database.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Headers

Content-type: application/json

Request Body

JSON

{
  "numbers": [
    "string"
  ]
}

Parameter	Type	Required	Description
`numbers`	Array of strings	Yes	List of numbers to be deleted from the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Delete purchased numbers in set

DELETE	{{baseUrl}}/api/numbers-set/{setId}/delete	Deletes purchased numbers in set.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.

Delete a set

DELETE	{{baseUrl}}/api/numbers-set/{setId}	Deletes a set.

Click to see the details

Query parameters

Parameter	Type	Required	Description
`setId`	String	Yes	ID of the set.

Response (Success)

CODE

HTTP/1.1 200 OK

Example

JSON

{
  "success": true,
  "message": "string"
}

Parameter	Type	Description
`success`	Boolean	The success status of the response.
`message`	String	Response message that contains the success status details.