An allocation request generates the pin and maps it to a set of users over a requested Virtual Number. The users in the API are referred to as a-party_numbers and b-party_numbers. A user in one party dials into the Virtual Number, enters the Pin (as required), and on successful validation of the pin, gets connected to the user in the other party. The a-party_numbers are Optional in which case any number (other than b-party_numbers) dialing on the virtual number and entering the correct pin are considered as a-party_number and connected to the b-party_number.

Conventionally, A-Party Numbers are business side numbers (like Delivery Agent, Store Manager, Administrator, etc.) and B-Party Number are customer side numbers. However, they can be used interchangeably or in any interpreted manner, based upon the business logic being served.

POST

https://leadassist.exotel.in/v1/tenants/<tenant_id>/greenpin

Replace <your_sid> with your tenant ID.

The following are the POST parameters:

Parameter Name Mandatory / Optional Value / Description
transaction_id Mandatory Client side identifier which can be used to track each request. The transaction_id can be a client order id that the developer can use to map the allocation in their system.
a.numbers Optional*

List of numbers for one side of the allocation. Numbers must be in E.164 format. Maximum A-Party numbers allowed in the list are 10.

*  Either a[“numbers”] or b[“numbers”] must be present in request payload.

b.numbers Optional*

List of numbers for the other side of the allocation. Numbers must be in E.164 format. Maximum B-Party numbers allowed in the list are 10.

*  Either a[“numbers”] or b[“numbers”] must be present in request payload.

a.vns Optional*

A-Party Virtual number which will be used to connect A-Party to b-party’s number.

*  Either a[“vns”] or b[“vns”] must be present in request payload. If either one is missing, the other party's VNs will be associated with the missing party's VNs.

b.vns Optional*

B-Party Virtual number which will be used to connect B-Partyto a-party’s number.

*  Either a[“vns”] or b[“vns”] must be present in request payload. If either one is missing, the other party's VNs will be associated with the missing party's VNs.

a.pin Optional A-Party pin to be used for verification of  a-party_caller and unregistered_caller. A-Party pin will be generated of a.pin_length, when a-party_pin is not mentioned in request. If not required, it can be set as an account level setting.
b.pin Optional B-Party pin to be used for verification of  b-party_caller and unregistered_caller. B-Party pin will be generated of b.pin_length, when b-party_pin is not mentioned in the request. If not required, it can be set as an account level setting.
a.pin_length Optional

Desired length of A-Party pin. Allowed values are 1 to 9.

Default value is 4.

b.pin_length Optional

Desired length of B-Party pin. Allowed values are 1 to 9.

Default value is 4.

usage Optional "oneway" allocations only permit a-party callers to talk to the b-party. “twoway” allocations permit both sides to call the other. The default value is "twoway".
Deallocation_policy Optional A deallocation policy parameter.  Duration can be specified in any unit (d, m, s)  Eg: “20s”. If not set, the default deallocation period (6 months) is used which is configurable at account level.

 

curl -X POST \
 https://leadassist.exotel.in/v1/tenants/<your_sid>/greenpin \
 -H 'Authorization: Basic <your Auth string which is Base64 encoded version of “username:Password” string>' \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{
"transaction_id": "random_string",
    "a": {
        "vns": [
            "6292134471",
            "6292134464"
        ],
        "numbers": [
            "7987686144"
        ],
        "pin": "123",
        "pin_length": 2
    },
    "b": {
        "vns": [
            "6292134465",
            "6292134464"
        ],
        "numbers": [
            "9956555625"
        ],
        "pin": "234",
        "pin_length": "3"
    },
    "usage": "twoway",
    "deallocation_policy": {
        "duration": "1200s"
    }
}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The greenpin_id is the unique identifier of the allocation, and it will be referred in HTTP body will contain a JSON similar to the one below
{
    "success": true,
    "status": 200,
    "code": null,
    "message": null,
    "data": {
        "transaction_id": "random_string",
        "greenpin_id": "d7ffd4b3-c861-4bda-a024-9cef1ae2f2a8",
        "a": {
            "vns": [
                "+916292134471",
                "+916292134464"
            ],
            "numbers": [
                "+917987686144"
            ],
            "pin": "123"
        },
        "b": {
            "vns": [
                "+916292134465",
                "+916292134464"
            ],
            "numbers": [
                "+919956555625"
            ]
        },
        "usage": "twoway",
        "state": "active",
        "deallocation_time": "2020-03-27 12:17:09"
    }
}

Description of parameters mentioned in the above response:

Parameter Name Mandatory / Optional Value / Description
success Mandatory   Set to true or false
status Mandatory   Http status code
code Mandatory   Error code, if any
message Mandatory   Error message, if any
transaction_id Mandatory   Customer specific Id as provided in the input
greenpin_id Mandatory   Unique Pin Id generated by the system to the allocation
a.vns Mandatory   A-Party Virtual Numbers as provided in the input
b.vns Mandatory   B-Party Virtual Numbers as provided in the input
a.numbers Optional*

  A-Party_Numbers as provided in the input

*  Either a[“numbers”] or b[“numbers”] must be present in response payload.

b.numbers Optional*

  B-Party_Numbers as provided in the input

*  Either a[“numbers”] or b[“numbers”] must be present in response payload.

a.pin Optional   A-Party_Pin if tenant enabled a-party_pin
b.pin Optional   B-Party_Pin if tenant enabled b-party_pin
deallocation_time Optional   Time When this allocation will be deallocated.
usage Optional   Set to twoway