Endpoint

A Plivo endpoint, also known as SIP endpoint, can be any IP phone, mobile phone, wireless device or PDA, a laptop or desktop PC, that uses the Session Initiation Protocol (SIP) to perform communications operations.

Endpoints are used to receive or make calls from a SIP phone, webSDK and our mobile SDKs. They support use-cases which involve an agent taking to a client, call centers, etc.

The following actions can be performed using the Endpoint API:

BaseURI https://api.plivo.com/v1/Account/{auth_id}/Endpoint/

Create an Endpoint

This API lets you create a new endpoint on Plivo. Check out our tutorial on getting started with SIP endpoints.

POST https://api.plivo.com/v1/Account/{auth_id}/Endpoint/

Arguments

Parameter Description
username (mandatory) The username for the endpoint to be created.
password (mandatory) The password for your endpoint username.
alias (mandatory) Alias for this endpoint
app_id (optional) The app_id of the application that is to be attached to this endpoint.

Response

HTTP Status Code: 201

{
    "username": "zumba131031145958",
    "alias": "zumba",
    "message": "created",
    "endpoint_id": "37371860103666",
    "api_id": "1c13de4c-423d-11e3-9899-22000abfa5d5"
}

Response Attributes

username
string Username of your endpoint. Plivo appends a 12 digit code in front your username.
alias
string Friendly name for your endpoint.
endpoint_id
string A unique ID for your endpoint. All API operations will be performed with this ID

Get Details of a Single Endpoint

This API lets you get details of a single endpoint on your account using the endpoint_id.

 GET https://api.plivo.com/v1/Account/{auth_id}/Endpoint/{endpoint_id}/

Arguments

None

Response

HTTP Status Code: 200

Plivo will respond with the below JSON when the endpoint is not registered on a SIP client.

{
    "alias": "zumba",
    "api_id": "39015de8-4fb3-11e4-a2d1-22000ac5040c",
    "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/379619814477342321/",
    "endpoint_id": "39452475478853",
    "password": "8bc0002a467b8276aaaf47e92bc46b9f",
    "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Endpoint/39452475478853/",
    "sip_registered": "false",
    "sip_uri": "sip:zumba141009125224@phone.plivo.com",
    "sub_account": null,
    "username": "zumba141009125224"
}

When the endpoint is registered with a SIP client, Plivo will return the below response

{
    "alias": "callme",
    "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/33406267401237901/",
    "endpoint_id": "32866729519064",
    "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Endpoint/32866729519064/",
    "sip_contact": "sip:callme140703093224@122.172.71.207:57563;ob",
    "sip_expires": "2014-07-21 19:26:08",
    "sip_registered": "true",
    "sip_uri": "sip:callme140703093944@phone.plivo.com",
    "sip_user_agent": "Telephone 1.1.4",
    "sub_account": null,
    "username": "callme140703093944"
}

Get Details of All Endpoints

This API lets you get details of all endpoints. This is pretty useful in use-cases where you want statuses of your endpoints and whether they have been registered using a SIP client.

GET https://api.plivo.com/v1/Account/{auth_id}/Endpoint/

Arguments

None

Response

HTTP Status Code: 200

{
    "api_id": "30a0c8c2-110c-11e4-bd8a-12313f016a39",
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 11
    },
    "objects": [
        {
            "alias": "callme",
            "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/33406267401237901/",
            "endpoint_id": "32866729519064",
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Endpoint/32866729519064/",
            "sip_contact": "sip:callme140703093224@122.172.71.207:57563;ob",
            "sip_expires": "2014-07-21 19:26:08",
            "sip_registered": "true",
            "sip_uri": "sip:callme140703093944@phone.plivo.com",
            "sip_user_agent": "Telephone 1.1.4",
            "sub_account": null,
            "username": "callme140703093944"
        },
        {
            "alias": "polycom",
            "application": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Application/37961981447734951/",
            "endpoint_id": "17551316589618",
            "resource_uri": "/v1/Account/MANWVLYTK4ZWU1YTY4ZT/Endpoint/17551316589618/",
            "sip_registered": "false",
            "sip_uri": "sip:polycom140506175228@phone.plivo.com",
            "sub_account": null,
            "username": "polycom140506175448"
        }
    ]
}

Response Attributes

username
string Username of your endpoint. Plivo appends a 12 digit code in front your username.
alias
string Friendly name for your endpoint.
endpoint_id
string A unique ID for your endpoint. All API operations will be performed with this ID.
sip_contact
string The contact field contains the address at which the callee can reach the caller for future requests. It is the IP on which the SIP client is registered.
sip_expires
string Time when the SIP registration will expire. Major SIP clients, Plivo WebSDK and Plivo mobile SDKs will re-register the endpoint before the registration expires.
sip_registered
string true if the SIP endpoint is registered on a SIP client.
sip_uri
string The SIP URI of the endpoint. External users will be able to call this endpoint on this SIP URI.
sip_user_agent
string The User Agent of SIP client used to register this endpoint. In the case of WebSDK this field will be plivo-websdk.
sub_account
string The sub account in your Plivo account, if this endpoint belongs to a Plivo sub account.

Modify an Endpoint

This API lets you modify an endpoint’s password, alias or the application attached to it.

 POST https://api.plivo.com/v1/Account/{auth_id}/Endpoint/{endpoint_id}/

Arguments

Parameter Description
password (optional) The password for your endpoint username.
alias (optional) Alias for this endpoint
app_id (optional) The app_id of the application that is to be attached to this endpoint. If app_id is not specified, then the endpoint does not point to any application.

Response

HTTP Status Code: 202

{
  "message": "changed",
  "api_id": "d8f9ea6c-58cc-11e1-86da-adf28403fe48"
}

Delete an Endpoint

This API lets you delete an endpoint. This operation cannot be undone.

 DELETE https://api.plivo.com/v1/Account/{auth_id}/Endpoint/{endpoint_id}/

Arguments

None

Response

HTTP Status Code: 204