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

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.

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.

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

 


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>

Replace <your_sid> with your tenant ID and <greenvn_id> with the same received in the allocation 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:
{
    "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>

Replace with your tenant ID and with the same received in the allocation 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:
{
    "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>

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

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.  
{
  "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 Lead Assist solution provides for the events happening on the allocation.

Call Completed Event

On every call that happens in an allocation, Lead Assist 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”
{
    "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_backet_path>",
    "dial_call_status": "la-null",
    "source": "exotel"
}

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