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.
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:
{
"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 |
