×

    • Create a Pin Allocation

    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

  • Try it

    • 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.

     

    • Example Request
    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
    • Example Response on Success
    {
    "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

     

    Delete a Pin Allocation

    A deallocation request deletes the pin-mapping between users and the assigned Virtual Number. It is essential to deallocate an existing allocation in order to free-up a pin which is no longer in use. So that the same pin can be reused for future transactions.

    DELETE

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

  • Try it

    • Replace <your_sid> with your tenant ID and <greenvn_id> with the same received in the allocation request

    • Example Request
    curl -X DELETE https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenpin_id>

    HTTP Response:

    • On success, the HTTP response status code will be 200.
    • The HTTP response body will contain a JSON similar to the one below:
    • Example 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"
    }
}

    The parameters in the above request are same as described in the response of the pin-allocation request.

    Get Details of a Pin Allocation

    The details of an allocation can be retrieved using this method. The greenpin_id needs to be provided in the API request.

    GET

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

  • Try it

    • Replace with your tenant ID and with the same received in the allocation request.

    • Example Request
    curl -X GET https://leadassist.exotel.in/v1/tenants/<your_sid>/greenvn/<greenpin_id>

     

    HTTP Response:

    • On success, the HTTP response status code will be 200.
    • The HTTP response body will contain a JSON similar to the one below:
    • Example 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"
    }
}

    The parameters in the above request are the same as described in the response of the allocation request.

    Update a GreenPin Allocation Beta

    This API helps update following parameters in an existing active GreenPin allocation:

    • A-party & B-party
      • Numbers
      • Pins
      • VNs
      • Pin Lengths
    • Deallocation Policy &
    • Usage (can be changed from 'oneway' to 'twoway' and vice versa)

    Although none of the above parameters are mandatory, at-least one of the parameters have to be passed as a mandate.

    PUT

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

  • Try it

    • Replace <your_sid> with your tenant ID.

    curl--location--request PUT 'https://<your_api_key>:<your_api_token>@leadassist.exotel.in/v1/tenants/<account_sid>/greenpin/<greenpin_id>'\
    --header 'Content-Type: application/json'\
    --data - raw '{
"a": {
    "vns": [
        "629XXXXX71",
        "629XXXXX64"
    ],
    "numbers": [
        "798XXXXX44"
    ],
    "pin": "123",
    "pin_length": 3
},
"b": {
    "vns": [
        "629XXXXX65",
        "629XXXXX64"
    ],
    "numbers": [
        "995XXXXX25"
    ],
    "pin": "234",
    "pin_length": "3"
},
"usage": "twoway",
"deallocation_policy": {
    "duration": "1200s"
}
}'
    var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')

var options = { 
  	method: 'PUT',
    'url': 'https://leadassist.exotel.in/v1/tenants/'+accountSid+'/greenpin/<greenpin_id>',
    'headers': {
        'Authorization': 'Basic'+ encoding,
        'Content-Type': 'application/json'
    },
  body: JSON.stringify({"a":{"vns":["629XXXXX71","629XXXXX64"],"numbers":["798XXXXX44"],"pin":"123","pin_length":3},"b":{"vns":["629XXXXX65","629XXXXX64"],"numbers":["995XXXXX25"],"pin":"234","pin_length":"3"},"usage":"twoway","deallocation_policy":{"duration":"1200s"}})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
    <?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";
$encoding = base64_encode($authKey.
    ":".$accountToken);
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://leadassist.exotel.in/v1/tenants/' + $accountSid + '/greenpin/<greenpin_id>',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS => '{
    "a": {
        "vns": [
            "629XXXXX71",
            "629XXXXX64"
        ],
        "numbers": [
            "798XXXXX44"
        ],
        "pin": "123",
        "pin_length": 3
    },
    "b": {
        "vns": [
            "629XXXXX65",
            "629XXXXX64"
        ],
        "numbers": [
            "995XXXXX25"
        ],
        "pin": "234",
        "pin_length": "3"
    },
    "usage": "twoway",
    "deallocation_policy": {
        "duration": "1200s"
    }
}
',
CURLOPT_HTTPHEADER => array(
    'Authorization: Basic ' + $encoding,
    'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    import requests, base64, json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"
encoding = base64.b64encode(authKey + ":" + authToken)
url = "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenpin/<greenpin_id>"
payload = json.dumps({
    "a": {
        "vns": [
            "629XXXXX71",
            "629XXXXX64"
        ],
        "numbers": [
            "798XXXXX44"
        ],
        "pin": "123",
        "pin_length": 3
    },
    "b": {
        "vns": [
            "629XXXXX65",
            "629XXXXX64"
        ],
        "numbers": [
            "995XXXXX25"
        ],
        "pin": "234",
        "pin_length": "3"
    },
    "usage": "twoway",
    "deallocation_policy": {
        "duration": "1200s"
    }
})
headers = {
    'Authorization': 'Basic ' + encoding,
    'Content-Type': 'application/json'
}
response = requests.request("PUT", url, headers = headers, data = payload)
print(response.text)
    package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))
	url := "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenpin/<greenpin_id>"

	payload := strings.NewReader(`{
"a": {
"vns": [
"629XXXXX71",
"629XXXXX64"
],
"numbers": [
"798XXXXX44"
],
"pin": "123",
"pin_length": 3
},
"b": {
"vns": [
"629XXXXX65",
"629XXXXX64"
],
"numbers": [
"995XXXXX25"
],
"pin": "234",
"pin_length": "3"
},
"usage": "twoway",
"deallocation_policy": {
"duration": "1200s"
}
}`)

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	req.Header.Add("cache-control", "no-cache")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

    HTTP Response:

    • On success, the HTTP response status code will be 200
    • The request_id is the unique identifier of the API call
    • Example Response on Success
    {
  "request_id": "b45f20XXX5f8712",
  "method": "PUT",
  "success": true,
  "status": 200,
  "code": null,
  "message": null,
  "data": {
    "transaction_id": "random_string",
    "greenpin_id": "d7ffd4b3-XPYX-4bda-a024-ibidatabatodoo",
    "a": {
      "vns": [
        "+916XXXXXX471",
        "+916XXXXXX464"
      ],
      "numbers": [
        "+917XXXXXX144"
      ],
      "pin": "123"
    },
    "b": {
      "vns": [
        "+916XXXXXX465",
        "+916XXXXXX464"
      ],
      "numbers": [
        "+919XXXXXX625"
      ]
    },
    "usage": "twoway",
    "state": "active",
    "deallocation_time": "2020-03-27 12:17:09"
  }
}

    Bulk Update GreenPin Allocations Beta

    This API helps update following parameters for several existing active GreenPin allocations in one go:

    • A-party & B-party
      • Numbers
      • Pins
      • VNs
      • Pin Lengths
    • Deallocation Policy
    • Usage (can be changed from 'oneway' to 'twoway' and vice versa)

    Although none of the above parameters are mandatory, at-least one of the parameters have to be passed as a mandate for each allocation that is attempted to be updated.

    Please note that in the case of a partial success; due to a request error, you will be able to update all those allocations for which the request was syntactically and semantically correct. 

    PUT

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

  • Try it

    • Replace <your_sid> with your tenant ID.

    curl--location--request PUT 'https://<your_api_key>:<your_api_token>@leadassist.exotel.in/v1/tenants/<account_sid>/greenpin'\
    --header 'Content-Type: application/json'\
    --data - raw '{
"greenpins": [{
        "greenpin_id": "GREENPIN_ID1",
        "a": {
            "vns": [
                "62XXXXXX71",
                "62XXXXXX64"
            ],
            "numbers": [
                "79XXXXXX44"
            ],
            "pin": "123",
            "pin_length": 3
        },
        "b": {
            "vns": [
                "62XXXXXX65",
                "62XXXXXX64"
            ],
            "numbers": [
                "99XXXXXX25"
            ],
            "pin": "234",
            "pin_length": "3"
        },
        "usage": "twoway",
        "deallocation_policy": {
            "duration": "1200s"
        }
    },
    {
        "greenpin_id": "GREENPIN_ID2",
        "a": {
            "vns": [
                "62XXXXXX71",
                "62XXXXXX64"
            ],
            "numbers": [
                "79XXXXXX44"
            ],
            "pin": "123",
            "pin_length": 3
        },
        "b": {
            "vns": [
                "62XXXXXX65",
                "629XXXXX64"
            ],
            "numbers": [
                "9XXXXXX625"
            ],
            "pin": "234",
            "pin_length": "3"
        },
        "usage": "twoway",
        "deallocation_policy": {
            "duration": "1200s"
        }
    }
]
}'
    var request = require("request");
var accountSid = "XXXXXXXXX";
var accountToken = "YYYYYYYYY";
var authKey = "ZZZZZZZZZZ";

var encoding = Buffer.from(authKey + ':' + accountToken).toString('base64')

var options = { 
  	method: 'PUT',
    'url': 'https://leadassist.exotel.in/v1/tenants/'+accountSid+'/greenpin',
    'headers': {
        'Authorization': 'Basic'+ encoding,
        'Content-Type': 'application/json'
    },
  body: JSON.stringify({"greenpins":[{"greenpin_id":"GREENPIN_ID1","a":{"vns":["62XXXXXX71","62XXXXXX64"],"numbers":["79XXXXXX44"],"pin":"123","pin_length":3},"b":{"vns":["62XXXXXX65","62XXXXXX64"],"numbers":["99XXXXXX25"],"pin":"234","pin_length":"3"},"usage":"twoway","deallocation_policy":{"duration":"1200s"}},{"transaction_id":"random_string","greenpin_id":"GREENPIN_ID2","a":{"vns":["62XXXXXX71","62XXXXXX64"],"numbers":["79XXXXXX44"],"pin":"123","pin_length":3},"b":{"vns":["62XXXXXX65","629XXXXX64"],"numbers":["9XXXXXX625"],"pin":"234","pin_length":"3"},"usage":"twoway","deallocation_policy":{"duration":"1200s"}}]})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
    <?php
$curl = curl_init();
$accountSid = "XXXXXXXXXX";
$accountToken = "YYYYYYYYYY";
$authKey = "ZZZZZZZZZZ";
$encoding = base64_encode($authKey.
    ":".$accountToken);
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://leadassist.exotel.in/v1/tenants/' + $accountSid + '/greenpin',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS => '{
    "greenpins": [{
            "greenpin_id": "GREENPIN_ID1",
            "a": {
                "vns": [
                    "62XXXXXX71",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "79XXXXXX44"
                ],
                "pin": "123",
                "pin_length": 3
            },
            "b": {
                "vns": [
                    "62XXXXXX65",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "99XXXXXX25"
                ],
                "pin": "234",
                "pin_length": "3"
            },
            "usage": "twoway",
            "deallocation_policy": {
                "duration": "1200s"
            }
        },
        {
            "greenpin_id": "GREENPIN_ID2",
            "a": {
                "vns": [
                    "62XXXXXX71",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "79XXXXXX44"
                ],
                "pin": "123",
                "pin_length": 3
            },
            "b": {
                "vns": [
                    "62XXXXXX65",
                    "629XXXXX64"
                ],
                "numbers": [
                    "9XXXXXX625"
                ],
                "pin": "234",
                "pin_length": "3"
            },
            "usage": "twoway",
            "deallocation_policy": {
                "duration": "1200s"
            }
        }
    ]
}
',
CURLOPT_HTTPHEADER => array(
    'Authorization: Basic ' + $encoding,
    'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    import requests, base64, json
accountSid = "XXXXXXXXX"
authToken = "YYYYYYYYY"
authKey = "ZZZZZZZZZZ"
encoding = base64.b64encode(authKey + ":" + authToken)
url = "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenpin"
payload = json.dumps({
    "greenpins": [{
            "greenpin_id": "GREENPIN_ID1",
            "a": {
                "vns": [
                    "62XXXXXX71",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "79XXXXXX44"
                ],
                "pin": "123",
                "pin_length": 3
            },
            "b": {
                "vns": [
                    "62XXXXXX65",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "99XXXXXX25"
                ],
                "pin": "234",
                "pin_length": "3"
            },
            "usage": "twoway",
            "deallocation_policy": {
                "duration": "1200s"
            }
        },
        {
            "greenpin_id": "GREENPIN_ID2",
            "a": {
                "vns": [
                    "62XXXXXX71",
                    "62XXXXXX64"
                ],
                "numbers": [
                    "79XXXXXX44"
                ],
                "pin": "123",
                "pin_length": 3
            },
            "b": {
                "vns": [
                    "62XXXXXX65",
                    "629XXXXX64"
                ],
                "numbers": [
                    "9XXXXXX625"
                ],
                "pin": "234",
                "pin_length": "3"
            },
            "usage": "twoway",
            "deallocation_policy": {
                "duration": "1200s"
            }
        }
    ]
})
headers = {
    'Authorization': 'Basic ' + encoding,
    'Content-Type': 'application/json'
}
response = requests.request("PUT", url, headers = headers, data = payload)
print(response.text)
    package main

import (
	b64 "encoding/base64"
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	// Please provide accountSid, authToken from your Exotel account
	accountSid := "XXXXXXXXX"
	authToken := "YYYYYYYY"
	authKey := "ZZZZZZZZZZ"

	// Encoding the accountSid and authToken, used in Authorization header
	encoding := b64.StdEncoding.EncodeToString([]byte(authKey + ":" + authToken))
	url := "https://leadassist.exotel.in/v1/tenants/" + accountSid + "/greenpin/<greenpin_id>"

	payload := strings.NewReader(`{
"greenpins": [
{
"greenpin_id": "GREENPIN_ID1",
"a": {
"vns": [
"62XXXXXX71",
"62XXXXXX64"
],
"numbers": [
"79XXXXXX44"
],
"pin": "123",
"pin_length": 3
},
"b": {
"vns": [
"62XXXXXX65",
"62XXXXXX64"
],
"numbers": [
"99XXXXXX25"
],
"pin": "234",
"pin_length": "3"
},
"usage": "twoway",
"deallocation_policy": {
"duration": "1200s"
}
},
{
"greenpin_id": "GREENPIN_ID2",
"a": {
"vns": [
"62XXXXXX71",
"62XXXXXX64"
],
"numbers": [
"79XXXXXX44"
],
"pin": "123",
"pin_length": 3
},
"b": {
"vns": [
"62XXXXXX65",
"629XXXXX64"
],
"numbers": [
"9XXXXXX625"
],
"pin": "234",
"pin_length": "3"
},
"usage": "twoway",
"deallocation_policy": {
"duration": "1200s"
}
}
]
}`)

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic "+encoding)
	req.Header.Add("cache-control", "no-cache")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

    HTTP Response:

    • On success, the HTTP response status code will be 200
    • The 'metadata' is a nested JSON block that will give an overall summary status of the number of allocations that were updated. 
    • A statuscode and message will be associated with each of the GreenPin allocations that sought to be updated.
    • All the parameters associated with an allocation will be returned for each allocation updated, irrespective of the number of parameters that actually sought an update.  
    • Example Response on Success
    {
  "request_id": "b45f202x5a65f8712",
  "method": "PUT",
  "http_code": 207,
  "metadata": {
    "failed": 0,
    "total": 2,
    "success": 2
  },
  "response": [
    {
      "success": true,
      "status": 200,
      "code": null,
      "message": null,
      "data": {
        "transaction_id": "random_string",
        "greenpin_id": "ibitifda-c861-4bda-a024-9cef1ae2f2a8",
        "a": {
          "vns": [
            "+91XXXXXX4471",
            "+91XXXXXX4464"
          ],
          "numbers": [
            "+91XXXXXX6144"
          ],
          "pin": "123"
        },
        "b": {
          "vns": [
            "+91XXXXXX4465",
            "+91XXXXXX4464"
          ],
          "numbers": [
            "+9199XXXXXX25"
          ]
        },
        "usage": "twoway",
        "state": "active",
        "deallocation_time": "2020-03-27 12:17:09"
      }
    },
    {
      "success": true,
      "status": 200,
      "code": null,
      "message": null,
      "data": {
        "transaction_id": "random_string",
        "greenpin_id": "yabadan-c861-4bda-a024-9cef1ae2f2a8",
        "a": {
          "vns": [
            "+9162XXXXXX71",
            "+9162XXXXXX64"
          ],
          "numbers": [
            "+9179XXXXXX44"
          ],
          "pin": "123"
        },
        "b": {
          "vns": [
            "+9162XXXXXX65",
            "+9162XXXXXX64"
          ],
          "numbers": [
            "+9199XXXXXX25"
          ]
        },
        "usage": "twoway",
        "state": "active",
        "deallocation_time": "2020-03-27 12:17:09"
      }
    }
  ]
}

    Events Call Backs

    There are multiple call backs that ExoBridge solution provides for the events happening on the allocation.

    Call Completed Event

    On every call that happens in an allocation, ExoBridge will make a HTTP POST request to the specified endpoint with the call details. The HTTP body will consist of the following parameters as shown below:

    Parameter Name

    Type & Value
    transation_id connection_id that was part of the request
    call_sid call_sid is a unique identifier for a call
    vn The VN on which the call landed
    greenpin_id The unique identifier of the allocation
    from The 'from' number
    to The 'to' number
    call_type Values can be completed, incomplete, call-attempt, client-hangup, etc.
    start_time Start time of the call
    current_time Current time of the request
    dial_call_duration Duration of the second leg of the call
    direction Always incoming
    on_call_duration Duration of the call conversation happened between both parties
    recording_url Recording of the call conversation if enabled
    dial_call_status Second leg status
    source “exotel”
    • Sample Response
    {
    "transaction_id": "random_string",
    "call_sid": "ec44cfd684850a68decc4cebc4e2143u",
    "vn": "+916292134464",
    "greenpin_id": "6447bb53-70c3-40ea-850b-de2fd3c585ee",
    "from": "+917987686144",
    "to": "+916292134471",
    "call_type": "completed",
    "start_time": "2020-03-23T12:58:02+00:00",
    "current_time": "2020-03-23T12:58:22+00:00",
    "dial_call_duration": 20,
    "on_call_duration": 17,
    "direction": "incoming",
    "recording_url": "<S3_bucket_path>",
    "dial_call_status": "completed",
    "source": "exotel"
}

    Deallocation Callback Event

    When deallocation of GreenPin is triggered via the deallocation policy as defined in the Allocation API, this callback will be triggered to let the user know that the deallocation has happened. The callback will also be triggered if the user calls the deallocation API manually.

    Parameter 

    Description

    transaction_id

    transaction_id that was part of the request

    greenpin_id

    The unique identifier of the allocation.

    usage

    Usage as provided in allocation API (the default is twoway)

    aparty_numbers

    List of aparty numbers as provided in allocation api

    bparty_numbers

    List of bparty numbers as provided in allocation api

    aparty_vns

    List of aparty VNs as provided in allocation api

    bparty_vns

    List of bparty VNs as provided in allocation api

    aparty_pins

    List of aparty pins  as provided in allocation api

    bparty_pins

    List of bparty pins as provided  in allocation api
    state

    This is the current state of the allocation which can have the following values

    • “active” - The state when the allocation is active
    • “vault” - The state when the allocation was deallocated

     

    • Sample Response
    {
  "transaction_id": "client's identifier of the allocation",
  "aparty_numbers": [
    "+91798XXXX144"
  ],
  "bparty_numbers": [
    "+91995XXXX625"
  ],
  "aparty_vns": [
    "+91629XXXX471",
    "+9162XXXX4464"
  ],
  "bparty_vns": [
    "+91629XXXX465",
    "+91629XXXX464"
  ],
  "aparty_pins": [
    "713"
  ],
  "bparty_pins": [
    "884"
  ],
  "usage": "twoway",
  "greenpin_id": "a62b5590-XXXX-4X33-a5X-fbaedaa5dd51",
  "state": "active"
}

    Successful Verification Event

    If an unregistered caller calls a VN, he will be prompted to enter the pin number.  If the user identifies himself with the correct pin, we connect him to the other party.  This will trigger an HTTP POST request to a specified endpoint with the HTTP body containing the following parameters.

    Parameter Name Type & Value
    transaction_id The transaction_id as received in the allocate API request
    vn The VN which was used to make this specific call
    greenpin_id The unique identifier of the allocation to which the user has been added
    caller The phone number of the new user.
    pin Pin entered by the user.
    • Sample Response
    {
"caller": "+917XXXXX6144",
"greenpin_id": "XXXXXe3-105f-4fba-89c0-7842df249313",
"vn": "+91629XXXXX71",
"transaction_id": "order-id",
"pin": "4321",
"call_sid": "7d90fXXXXXc1a449bd4b700fce9d165p"
}

     

    Failed Verification Event

    If an unregistered caller fails to verify himself (incorrect pin entry etc.), a failed verification event is triggered.

    Parameter Name Type & Value
    call_sid Unique identifier of the call made by the caller to the VN
    vn The VN to which the caller called
    start_time Start time of the call.
    caller The phone number of the new user.
    pin Pin entered by the user.
    • Sample Response
    {
"start_time": "2021-11-09T10:09:15+05:30",
"caller": "+917XXXXX6144",
"vn": "+9162921XXXXX",
"call_sid": "XXXXfdea48XXX49bd4b700fce9d165p",
"pin": "1234"
}

    Appendix 1

    List of status codes and their definition:

    Status Code Description Http code
    0 Internal Service Error 500
    1 Could not find the given GreenPin 404
    2 One or more unsupported search filters provided 400
    3 One or more mandatory parameters not present in request 400
    4 No free GreenPins are available for allocation 452
    5 Bad or missing parameters in Request 400
    7 Authentication not provided or failed 401
    8 Not permitted to do this operation. 403
    9 Version header not specified or supported for this API 400
    13 All numbers in the group are duplicates 409
    14 a-party numbers and b-party numbers cannot contain the same number for an allocation. 409
    15 The region code specified is not supported 403
    16 Invalid Number Received. 400
    17 Too many allocation requests in bulk. 413
    18 Allocation exists for this connection id 409
    19 One or more of the numbers is already registered with another pin 409
    20 Group and number mapping doesn't exist 404
    22 This green_pin is already deleted 410
    23 An invalid date range was provided in the query 400
    50 An invalid call flow is configured 422