Create an Application

POST

api

Account

{auth_id}

Application

Create an Application

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "app_name": "My Voice Application",
  "answer_url": "https://example.com/answer",
  "answer_method": "POST"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/"

payload = {
    "app_name": "My Voice Application",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST"
}
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    app_name: 'My Voice Application',
    answer_url: 'https://example.com/answer',
    answer_method: 'POST'
  })
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "app_id": "12345678901234567",
  "message": "created"
}

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "app_id": "12345678901234567",
  "message": "created"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/

Creates an application with webhook URLs for call handling. Creating an application is typically the first step - you then attach it to either a number or an endpoint.

Authentication required:

X-Auth-ID - Your account Auth ID
X-Auth-Token - Your account Auth Token
Content-Type: application/json

Parameters

The three required fields are app_name, answer_url, and answer_method.

Field	Type	Required	Description
`app_name`	string	Yes	The name of your application. Allowed values: letters (upper and lower case), numbers (0–9), and only two special characters: `-` (hyphen) and `_` (underscore).
`answer_url`	string	Yes	The URL fetched when a call executes this application. Must return valid VobizXML.
`answer_method`	string	Yes	HTTP method used to call `answer_url`. One of `GET` or `POST`. Defaults to `POST`.
`hangup_url`	string	No	URL notified when the call hangs up. If omitted, defaults to `answer_url` - your answer handler then also receives hangup callbacks.
`hangup_method`	string	No	HTTP method used to call `hangup_url`. One of `GET` or `POST`. Defaults to `POST`.
`fallback_answer_url`	string	No	Invoked by Vobiz only if `answer_url` is unreachable, times out, or returns invalid VobizXML. Must itself return valid VobizXML. With no fallback set, the call drops on `answer_url` failure.
`fallback_method`	string	No	HTTP method used to call `fallback_answer_url`. One of `GET` or `POST`. Defaults to `POST`.
`message_url`	string	No	URL notified when an inbound message is received. Not set by default.
`message_method`	string	No	HTTP method used to call `message_url`. One of `GET` or `POST`. Defaults to `POST`.
`default_number_app`	boolean	No	If `true`, newly created numbers without an `app_id` are routed to this application. Defaults to `false`. Does not retroactively re-route existing numbers.
`default_endpoint_app`	boolean	No	If `true`, newly created endpoints without an `application` are routed to this application. Defaults to `false`. Does not retroactively re-route existing endpoints.
`sub_account`	string	No	`auth_id` of the sub-account this application belongs to. Cannot be changed after creation.
`application_type`	string	No	The type of application. Typically `XML`.
`default_app`	boolean	No	Whether this is the account-level default application. Defaults to `false`.
`enabled`	boolean	No	Whether the application is enabled. Defaults to `true`.
`log_incoming_message`	boolean	No	If `false`, incoming messages to Vobiz phone numbers associated with this application are not logged. Defaults to `true`.
`public_uri`	boolean	No	Whether the application’s `sip_uri` is reachable by external SIP systems. Defaults to `false`.
`sip_transfer_method`	string	No	HTTP method used for SIP transfer callbacks. One of `GET` or `POST`.
`sip_transfer_url`	string	No	URL notified during a SIP transfer.
`sip_uri`	string	No	SIP URI associated with the application.

Creating an application is normally step one. After it returns an app_id, attach a number or set application on an endpoint to start routing calls.

Request Body

JSON

{
  "app_name": "My Voice App",
  "answer_url": "https://example.com/answer",
  "answer_method": "POST",
  "hangup_url": "https://example.com/hangup",
  "hangup_method": "POST",
  "fallback_answer_url": "https://example.com/fallback",
  "fallback_method": "POST",
  "message_url": "https://example.com/message",
  "message_method": "POST",
  "default_number_app": false,
  "default_endpoint_app": false,
  "sub_account": null
}

Response Examples

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "app_id": "12345678901234567",
  "message": "created"
}

{
  "error": "invalid request parameters",
  "details": {
    "app_name": "This field is required",
    "answer_url": "Enter a valid URL"
  }
}

{
  "error": "invalid credentials"
}

A 400 is returned when a required field is missing or a URL is malformed; a 401 when X-Auth-ID/X-Auth-Token are missing or wrong.

cURL Example

cURL

curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "My IVR System",
    "answer_url": "https://myapp.com/ivr/answer",
    "answer_method": "POST"
  }'

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

Body

application/json

app_name

string

required

answer_url

string

required

answer_method

string

required

Response

Success

api_id

string

required

app_id

string

required

message

string

required

Create an Application

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "app_name": "My Voice Application",
  "answer_url": "https://example.com/answer",
  "answer_method": "POST"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/"

payload = {
    "app_name": "My Voice Application",
    "answer_url": "https://example.com/answer",
    "answer_method": "POST"
}
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    app_name: 'My Voice Application',
    answer_url: 'https://example.com/answer',
    answer_method: 'POST'
  })
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Application/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "app_id": "12345678901234567",
  "message": "created"
}

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "app_id": "12345678901234567",
  "message": "created"
}

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

​Parameters

​Request Body

​Response Examples

​cURL Example

Authorizations

Path Parameters

Body

Response

Parameters

Request Body

Response Examples

cURL Example