> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Application API

> Create and manage applications to control incoming calls and messages

An `Application` is a set of Answer, Hangup, and Message URLs that help you control your incoming calls and messages.

**API Endpoint**

```
https://api.plivo.com/v1/Account/{auth_id}/Application/
```

***

## The Application Object

### Attributes

**app\_id** `string`

Unique identifier for the application.

**app\_name** `string`

A friendly name for your Plivo application.

**answer\_url** `string`

URL requested when an incoming call is received. Must return valid Plivo XML.

**answer\_method** `string`

HTTP method for the answer\_url. Values: `GET` or `POST`.

**hangup\_url** `string`

URL notified when the call hangs up.

**hangup\_method** `string`

HTTP method for the hangup\_url.

**fallback\_answer\_url** `string`

URL requested when answer\_url fails or returns invalid XML.

**fallback\_method** `string`

HTTP method for the fallback\_answer\_url.

**message\_url** `string`

URL notified when an inbound SMS is received.

**message\_method** `string`

HTTP method for the message\_url.

**default\_app** `boolean`

Whether this is the default app.

**enabled** `boolean`

Whether the application is enabled.

**public\_uri** `boolean`

Whether the app can be called from external SIP services.

**sip\_uri** `string`

SIP URI of the application.

**sip\_auth\_type** `string`

SIP authentication mode for inbound calls to the application. Values: `ip_acl`, `credential`, `ip_acl_and_credential`, or `""` (empty, no authentication). Inbound auth applies only when the SIP INVITE Request-URI is `sip:{app_id}@app.plivo.com`. Changing to a mode that does not use a credential or IP ACL automatically clears the corresponding `credential_uuid` / `ip_acl_uuid` on the application (e.g., setting to `ip_acl` clears any previously set `credential_uuid`). See [SIP Authentication](https://plivo.com/docs/voice/concepts/sip-authentication.md).

**ip\_acl\_uuid** `string`

UUID (36 characters) of the IP Access Control List assigned to this application. Required when `sip_auth_type` is `ip_acl` or `ip_acl_and_credential`. Create via [SIP Authentication API](https://plivo.com/docs/account/api/sip-authentication.md).

**credential\_uuid** `string`

UUID (36 characters) of the SIP credential assigned to this application. Required when `sip_auth_type` is `credential` or `ip_acl_and_credential`. Create via [SIP Authentication API](https://plivo.com/docs/account/api/sip-authentication.md).

**sub\_account** `string`

Subaccount associated with the application. Null if main account.

**log\_incoming\_messages** `boolean`

Whether incoming message content is logged. Default: `true`.

**resource\_uri** `string`

URI of the application resource.

### Example Object

```json theme={null}
{
  "answer_method": "GET",
  "answer_url": "https://example.com/answer",
  "app_id": "20372631212782780",
  "app_name": "My Application",
  "default_app": false,
  "enabled": true,
  "fallback_answer_url": "",
  "fallback_method": "POST",
  "hangup_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "message_method": "POST",
  "message_url": "",
  "public_uri": false,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/",
  "sip_uri": "sip:20372631212782780@app.plivo.com",
  "sip_auth_type": "ip_acl",
  "ip_acl_uuid": "acl-xyz789-ghi012",
  "credential_uuid": null,
  "sub_account": null,
  "log_incoming_messages": true
}
```

### Answer URL Parameters

When a call is received, Plivo sends these parameters to your answer\_url:

| Parameter | Description |
| - | - |
| CallUUID | Unique identifier for this call |
| From | Caller's phone number with country code |
| To | Called phone number with country code |
| CallStatus | Call status: `ringing`, `in-progress`, or `completed` |
| Direction | Call direction: `inbound` or `outbound` |
| ForwardedFrom | Present only for forwarded calls |
| ALegUUID | First leg UUID for outbound calls |
| ALegRequestUUID | Request UUID for API-initiated outbound calls |

### Hangup URL Parameters

| Parameter | Description |
| - | - |
| CallUUID | Unique identifier for this call |
| From | Caller's phone number |
| To | Called phone number |
| CallStatus | Final call status |
| Direction | Call direction |
| Duration | Call duration in seconds |
| BillDuration | Billed duration in seconds |
| HangupCauseName | Reason for hangup |
| HangupCauseCode | Hangup cause code |
| HangupSource | Entity that triggered hangup |

### Message URL Parameters

| Parameter | Description |
| - | - |
| From | Source number of incoming message |
| To | Your Plivo number that received the message |
| Type | Always `sms` |
| Text | Message content |
| MessageUUID | Unique message identifier |

***

## Create an Application

Creates a new application.

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

### Arguments

**app\_name** `string` *required*

Application name. Allowed: alphanumeric, hyphen (-), underscore (\_).

**answer\_url** `string` *required*

URL fetched when a call executes this application.

**answer\_method** `string`

HTTP method for answer\_url. Default: `POST`.

**hangup\_url** `string`

URL notified when call hangs up. Default: answer\_url.

**hangup\_method** `string`

HTTP method for hangup\_url. Default: `POST`.

**fallback\_answer\_url** `string`

Fallback URL if answer\_url fails.

**fallback\_method** `string`

HTTP method for fallback\_answer\_url. Default: `POST`.

**message\_url** `string`

URL notified for inbound messages.

**message\_method** `string`

HTTP method for message\_url. Default: `POST`.

**default\_number\_app** `boolean`

Make this the default app for new numbers.

**default\_endpoint\_app** `boolean`

Make this the default app for new endpoints.

**subaccount** `string`

Subaccount ID to associate with this application.

**log\_incoming\_messages** `boolean`

Log incoming message content. Default: `true`.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.create(
    app_name='MyApp',
    answer_url='https://example.com/answer')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.create('MyApp', { answerUrl: 'https://example.com/answer' })
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.create(
    'MyApp',
    answer_url: 'https://example.com/answer')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->create(
    'MyApp',
    ['answer_url' => 'https://example.com/answer']);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ApplicationCreateResponse response = Application.creator("MyApp", "https://example.com/answer")
    .create();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Create(
    appName: "MyApp",
    answerUrl: "https://example.com/answer");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Create(plivo.ApplicationCreateParams{
        AppName:   "MyApp",
        AnswerURL: "https://example.com/answer",
    })
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"answer_url": "https://example.com/answer", "app_name": "MyApp"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Application/
```

### Response

**message** `string`

Status of the request. Returns `created` on a successful creation.

**app\_id** `string`

Unique identifier for the application.

**api\_id** `string`

Unique identifier for the API request.

```json theme={null}
{
  "message": "created",
  "app_id": "15784735442685051",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}
```

***

## Retrieve an Application

Get details of a specific application.

```
GET https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/
```

### Arguments

> [!NOTE]
>
> No arguments required.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.get(app_id='15784735442685051')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.get('15784735442685051')
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.get('15784735442685051')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->get('15784735442685051');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

Application response = Application.getter("15784735442685051").get();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Get(appId: "15784735442685051");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Get("15784735442685051")
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/15784735442685051/
```

### Response

**answer\_method** `string`

HTTP method for the answer\_url. Values: `GET` or `POST`.

**answer\_url** `string`

URL requested when an incoming call is received. Must return valid Plivo XML.

**app\_id** `string`

Unique identifier for the application.

**app\_name** `string`

A friendly name for your Plivo application.

**default\_app** `boolean`

Whether this is the default app.

**enabled** `boolean`

Whether the application is enabled.

**fallback\_answer\_url** `string`

URL requested when answer\_url fails or returns invalid XML.

**fallback\_method** `string`

HTTP method for the fallback\_answer\_url.

**hangup\_method** `string`

HTTP method for the hangup\_url.

**hangup\_url** `string`

URL notified when the call hangs up.

**message\_method** `string`

HTTP method for the message\_url.

**message\_url** `string`

URL notified when an inbound SMS is received.

**public\_uri** `boolean`

Whether the app can be called from external SIP services.

**resource\_uri** `string`

URI of the application resource.

**sip\_uri** `string`

SIP URI of the application.

**sub\_account** `string`

Subaccount associated with the application. Null if main account.

**log\_incoming\_messages** `boolean`

Whether incoming message content is logged. Default: `true`.

```json theme={null}
{
  "answer_method": "GET",
  "answer_url": "https://example.com/answer",
  "app_id": "20372631212782780",
  "app_name": "My Application",
  "default_app": false,
  "enabled": true,
  "fallback_answer_url": "",
  "fallback_method": "POST",
  "hangup_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "message_method": "POST",
  "message_url": "",
  "public_uri": false,
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/",
  "sip_uri": "sip:20372631212782780@app.plivo.com",
  "sub_account": null,
  "log_incoming_messages": true
}
```

***

## List All Applications

Returns all applications sorted by creation date.

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

### Arguments

**subaccount** `string`

Filter by subaccount ID.

**app\_name** `string`

Filter by app name prefix.

**limit** `integer`

Results per page. Maximum 20.

**offset** `integer`

Pagination offset.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.list(offset=0, limit=5)
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.list({ offset: 0, limit: 5 })
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.list(limit: 5, offset: 0)
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->list(['limit' => 5, 'offset' => 0]);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ListResponse<Application> response = Application.lister()
    .offset(0)
    .limit(5)
    .list();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.List(limit: 5, offset: 0);
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.List(plivo.ApplicationListParams{
        Offset: 0,
        Limit:  5,
    })
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/
```

### Response

**api\_id** `string`

Unique identifier for the API request.

**meta** `object`

Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching applications).

**objects** `array`

Array of application objects — see [The Application Object](#the-application-object).

```json theme={null}
{
  "api_id": "e5b05b26-10c4-11e4-a2d1-22000ac5040c",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "answer_method": "GET",
      "answer_url": "https://example.com/answer",
      "app_id": "20372631212782780",
      "app_name": "My Application",
      "default_app": false,
      "enabled": true,
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/Application/20372631212782780/"
    }
  ]
}
```

***

## Update an Application

Modify an existing application.

```
POST https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/
```

### Arguments

**answer\_url** `string`

URL fetched when a call executes this application.

**answer\_method** `string`

HTTP method for answer\_url.

**hangup\_url** `string`

URL notified when call hangs up.

**hangup\_method** `string`

HTTP method for hangup\_url.

**fallback\_answer\_url** `string`

Fallback URL if answer\_url fails.

**fallback\_method** `string`

HTTP method for fallback\_answer\_url.

**message\_url** `string`

URL notified for inbound messages.

**message\_method** `string`

HTTP method for message\_url.

**default\_number\_app** `boolean`

Make this the default app for new numbers.

**default\_endpoint\_app** `boolean`

Make this the default app for new endpoints.

**subaccount** `string`

Subaccount ID to associate.

**log\_incoming\_messages** `boolean`

Log incoming message content.

**sip\_auth\_type** `string`

SIP authentication mode for inbound calls. Values: `ip_acl`, `credential`, `ip_acl_and_credential`, or `""` (empty to disable). See [SIP Authentication](https://plivo.com/docs/voice/concepts/sip-authentication.md).

**ip\_acl\_uuid** `string`

UUID of the IP Access Control List to assign. Required when `sip_auth_type` includes `ip_acl`. Create one via the [SIP Authentication API](https://plivo.com/docs/account/api/sip-authentication.md).

**credential\_uuid** `string`

UUID of the SIP credential to assign. Required when `sip_auth_type` includes `credential`. Create one via the [SIP Authentication API](https://plivo.com/docs/account/api/sip-authentication.md).

> [!NOTE]
>
> You cannot delete a credential or IP ACL that is currently assigned to an application. Remove the assignment first by setting `sip_auth_type` to empty.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.update(
    app_id='21686794894743506',
    answer_url='https://updated.answer.url')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.update('15784735442685051', { answerUrl: 'https://updated.answer.url' })
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.update(
    '15784735442685051',
    answer_url: 'https://updated.answer.url')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->update(
    '15784735442685051',
    ['answer_url' => 'https://updated.answer.url']);
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

ApplicationUpdateResponse response = Application.updater("15784735442685051")
    .answerUrl("https://updated.answer.url")
    .update();
System.out.println(response);
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Update(
    appId: "15784735442685051",
    answerUrl: "https://updated.answer.url");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Applications.Update("15784735442685051", plivo.ApplicationUpdateParams{
        AnswerURL: "https://updated.answer.url",
    })
    fmt.Println(response)
}
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"answer_url": "https://updated.answer.url"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/
```

### Response

**message** `string`

Status of the request. Returns `changed` on a successful update.

**api\_id** `string`

Unique identifier for the API request.

```json theme={null}
{
  "message": "changed",
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949"
}
```

***

## Delete an Application

Permanently deletes an application.

```
DELETE https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/
```

### Arguments

**cascade** `boolean`

Delete associated endpoints. Default: `true`.

**new\_endpoint\_application** `string`

App ID to reassign endpoints to when cascade is `false`.

### Example

```python Python theme={null}
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.applications.delete(app_id='21686794894743506')
print(response)
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.applications.delete('15784735442685051')
    .then(response => console.log(response));
```

```ruby Ruby theme={null}
require 'plivo'

client = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = client.applications.delete('15784735442685051')
puts response
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->applications->delete('15784735442685051');
print_r($response);
```

```java Java theme={null}
import com.plivo.api.Plivo;
import com.plivo.api.models.application.Application;

Plivo.init("<auth_id>", "<auth_token>");

Application.deleter("15784735442685051").delete();
System.out.println("Deleted successfully.");
```

```csharp .NET theme={null}
using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Application.Delete(appId: "15784735442685051");
Console.WriteLine(response);
```

```go Go theme={null}
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    err := client.Applications.Delete("15784735442685051")
    if err == nil {
        fmt.Println("Deleted successfully.")
    }
}
```

```bash cURL theme={null}
curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Application/{app_id}/
```

### Response

```
HTTP Status Code: 204
```