Skip to main content
Skip table of contents

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.