openapi: 3.0.0 info: version: 2.0.0 title: Platform API description: 'With Platform API, you can add communication features to your applications and websites' contact: name: Apifonica Support email: info@apifonica.com servers: - url: 'https://api.apifonica.com/v2' tags: - name: Accounts description: | These requests allow you view and update your account details - name: Applications description: | These requests are used to create, update and delete applications - name: Numbers description: | These requests are used to select and rent local/virtual phone numbers, and manage the numbers you have - name: Messages description: | These requests are used to send messages, view message history ## Callback URL / Webhook URL In order to receive message reports and status updates (e.g. `sent`, `delivered`), you will need to provide a callback URL and subscribe to them. This can be done by [configuring Apifonica Application](#operation/createApplication). After you've successfully created an Application, specify its SID as a `msg_app_sid` parameter in [Send message](#operation/sendMessage) requests. Alternatively, you can set the `msg_app_sid` parameter on your number/alpha-name using [Change number properties](#operation/changeNumberProperties) request. This will also allow receiving updates about inbound messages (if you have a mobile number with inbound SMS features rented in Apifonica). - name: Text-to-call description: |- Transform text messages into voice calls via API. Reach audiences worldwide, whether they are on mobile or landline devices. Apifonica converts the written text to speech, calls the recipient and reads the message to them. Schedule message delivery retries for busy recipients, making up to 10 attempts within customizable timeframes. Multiple languages & voices: Amazon, Azure, Google and Yandex text to speech engines. Find the API reference at: https://docs.apifonica.com/text-to-call/ - name: Calls description: | These requests are used to initiate voice calls, modify live calls, and view call history and details of specific calls - name: Recordings description: | These requests are used to get call recordings list and view details of the specific recording - name: Pools description: | These requests are used to organize a group of rented virtual landline/mobile numbers into pools - name: Endpoints description: | These requests are used to organize forwarding of the inbound calls on the static IP address * To link endpoint to the number you need to update number properties with defined endpoint_sid (see `Change number properties`) * To unlink endpoint from the number you need to update number properties with empty value of endpoint_sid - name: Payments & Expenses description: | These requests are used to manage the account balance and track records on your expenses - name: Notification-Settings description: | There are requests for manage of account notifications - name: XML description: | > Apifonica XML is a set of instructions that provides management capabilities for incoming and outgoing calls. Instructions can be combined with each other and form a complex XML structure. --- ## How It Works As you may know, Apifonica Platform is able to send [*call events*](#section/Call-Events) to the preset URL - **Controller**. As a response from **Controller**, Platform expects an XML instructions.
**Instruction** is a Platform predefined command that modifies call session. You may play back audio, send message, create call to another number, etc.
The controller URL can refer either to a static XML instruction or to the web application, which generates an XML response. On a valid response, Platform immediately applies instructions to your call session. **Controller** with its method (POST or GET) forming an [*Application*](#operation/createApplication), that is using for calls in XML mode. **Application** (application sid) can be bind to the number via [*change number properties request*](#operation/changeNumberProperties) or passed as a parameter in [*makeCall request*](#operation/makeCall). ## XML Structure Every XML handler must include a header tag, which specifies the encoding and XML version. The only acceptable encoding is UTF-8. ```xml ``` Everything that follows must be wrapped with the response tag. ```xml AUDIO_URL ``` Please remember that XML is ordered and case-sensitive. Instruction names are specified in *camelCase*. Instructions will be executed in the same order as it provided in XML. ## Supported Instructions - [*wait*](#section/wait) — waits before the next instruction execution; - [*playAudio*](#section/playAudio) — plays an audio file; - [*makeCall*](#section/makeCall) — initiates a new call session to the specified phone number and bridges it with the current session; - [*sendMessage*](#section/sendMessage) — sends a message; - [*getInput*](#section/getInput) — collects an input from a user (DTMF or Speech) and sends results to the preset controller; - [*goTo*](#section/goTo) — bypasses the call control to a different XML instruction; - [*endCall*](#section/endCall) — ends the call. ## wait Waits a specified number of seconds before the next instruction execution. --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:-------------:|--------------------------|:------------:|:--------:|:-----------------:| | **length** | Time to sleep in seconds | No | float | 1 |

### - Example ```xml ``` --- ## playAudio Plays an audio file to the caller. For a better performance, it's recommended to use GET method in your application, when you know that *playAudio* instruction is present. It will make the audio file cacheable. Supported format: **MP3**, **WAV**. --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:-------------:|---------------------------------------------------------------------------------------------------------------------|:------------:|:------------:|:-----------------:| | **loops** | Defines how many times the audio file will be played.
If value is set to **0**, the audio gonna loop endlessly. | No | unsigned int | 1 |

### - Example ```xml AUDIO_URL ``` --- ## makeCall Initiates a new call session to the specified phone number and bridges it with the current session. --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:--------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:------------:|:-----------------:| | **from** | Number, that will be used as a caller (must be rented via Apifonica). It is also possible to specify a `pool_sid` as from, this way call will be made from a randomly selected number from specified Pool. | No | string | - | | **controller** | URL of the controller, where call events will be sent.

If Platform receives a new XML instructions from the controller, flow will be transferred to that set of instructions. In that case any instruction after the **\** in the current XML instructions will be unreachable.

If no controller URL is provided, Platform will proceed processing the current XML instructions. | No | string | - | | string | - | | **method** | HTTP method, that gonna be used in a request to the specified controller.
Supported methods: **GET**, **POST**. | No | string | POST | | **timeout** | The number of seconds to wait for the answer.
If the timeout expires and nobody has answered, Platform finishes call to **\** and moves to the next one. | No | unsigned int | 30 | | **whisper_a** | URL to audio file, that gonna be played to A leg, when the call is answered. | No | string | - | | **whisper_b** | URL to audio file, that gonna be played to B leg, when the call is answered. | No | string | - |
***Note:*** It is possible to use both .mp3 and .wav files with the **whisper_a** and **whisper_b** properties.

### - Nested tags #### *\* This tag specifies a recipient's phone number.
**Important!** It is required to specify at least one *\* element inside *\*. It is possible to include more than one *\* in *\* instruction.
In such case Platform will call to all listed numbers simultaneously. The first answered number will be connected with the calling party and all the rest will be skipped. If there is a need to call different numbers in a sequence, use several *\* commands one after another and specify the timeout attribute.

### - Examples The following example demonstrates how Platform is calling to the first recipient (number 358942782000) and then to the second one (447860000000). The second call will be started right after the first call finish. ```xml 358942782000 447860000000 ``` The following example demonstrates how Platform is calling to the two recipients at the same time (phones will be ringing simultaneously). After one of the recipients picking up, all other connections end. ```xml 358942782000 447860000000 ``` --- ## sendMessage Sends message to the specified phone number. **Only SMS messages** are supported! --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:--------:|:-----------------:| | **from** | Number, that gonna be used as a sender (must be rented via Apifonica). | Yes | string | - | | **to** | Number to what Platform will send the message. | Yes | string | - | | **controller_url** | URL of the controller, where message events will be sent.

If Platform receives a new XML instructions from the controller, flow will be transferred to that set of instructions. In that case any instruction after the **\** in the current XML instructions will be unreachable.

If no controller URL is provided, Platform will proceed processing the current XML instructions.

**Important!** Cannot be used with the *controller_app* simultaneously. | No | string | - | | **method** | HTTP method, that gonna be used in a request to the specified controller.
Supported methods: **GET**, **POST**. | No | string | POST |

### - Example ```xml ``` --- ## getInput Collects the user input (key presses on the device, also known as DTMF) and transfers it to the provided controller. To get more details about **speech collection features**, [**contact us**](https://www.apifonica.com/en/company/contacts/)! --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:------------:|:-----------------:| | **controller** | URL of the controller, where user input will be sent.

If Platform receives a new XML instructions from the controller, flow will be transferred to that set of instructions. In that case any instruction after the **\** in the current XML instructions will be unreachable.

If no controller URL is provided, Platform will proceed processing the current XML instructions. | No | string | - | | string | - | | **method** | HTTP method, that gonna be used in a request to the specified controller.
Supported methods: **GET**, **POST**. | No | string | POST | | **dtmfTimeout** | The number of seconds to wait for the caller to press the next key.

If the caller presses one or more keys and then does nothing, the timeout expires and Platform submits the input data to the handler URL.

If no keys have been pressed at all and the time is over, Platform finishes the **\** command and proceeds with the next command. | No | unsigned int | 5 | | **noInputTimeout** | The number of seconds to wait for the caller to press the first button.

With included **\** instruction, the entire file will be played in case no keys were entered by the user and ***dtmfTimeout*** will be applied afterwards. | No | unsigned int | 5 | | **minSymbols** | Minimum number of symbols, that user can input.
Value limits are from **1** to **128**. | No | unsigned int | 1 | | **maxSymbols** | Maximum number of symbols, that user can input until this action is considered finished.
Value limits are from **1** to **128**. | No | unsigned int | 30 | | **finishOnKey** | Symbol, that ends user input.

**\** instruction ends after the specified symbol is entered. | No | string | \# |

### - Nested tags #### *\* To implement IVR and other use cases, it is possible to insert the [*\*](#section/playAudio) instruction into *\*. ***Note:*** Pressing a key on a user keyboard, interrupts the execution of the included *\*.

### - Examples The following example demonstrates the simplest usage of the *\* instruction. ```xml ``` The following example demonstrates the execution of **\** instruction inside **\**.
Controller is expected to receive from **2** to **4** symbols. By pressing the ending symbol **\***, **\** is going to be interrupted by the **\** instruction. ```xml AUDIO_URL ``` --- ## goTo Stops current XML instructions execution and makes request to the provided URL to get another XML instructions. --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:-------------:|--------------------------------------------------------------------------------------------------------------------|:------------:|:--------:|:-----------------:| | **method** | HTTP method, that gonna be used in a request to the specified controller.
Supported methods: **GET**, **POST** | No | string | POST |

### - Example ```xml https://myhost.com/anotherInstruction.xml ``` --- ## endCall Ends the current call or forbids Platform to answer the call. It's really useful when you'd like to prevent the line from staying busy after all XML instructions execution. --- ### - Attributes
| **Attribute** | **Description** | **Required** | **Type** | **Default Value** | |:-------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------:|:--------:|:-----------------:| | **signal** | Defines the tone, that gonna be played to the caller after the **\** instruction.
Supported tones: **busy**, **reject**, **proxy**.

When set to **busy**, Platform sends to the calling party busy signal.

When set to **reject**, Platform plays the out of service signal.

When set to **proxy**, Platform proxies the signal received from the \ leg, if any. | No | string | busy |

### - Example ```xml ``` --- - name: Events description: | ## What Is It **Apifonica event** is a notification about Call/Message state, that Apifonica Platform sends to a user controller. Some events are interactive and some of them are informative only. To receive events from Apifonica Platform, you must subscribe on them. It's really easy, just fill in the *events* field with an appropriate value during your application creation (see [create a new application](#operation/createApplication)) and use your application in the further actions. Apifonica Platform sends an event as a *query parameters* when user controller implements a GET method. ```http request GET /controllers/demo-controller.php?call_sid=cal32ddf772-8ef2-41d7-b257-000000000000&channel=number&... HTTP/1.1 Host: {endpoint} ``` And sends an event as a *x-www-form-urlencoded* when user controller implements a POST method. ```http request POST /controllers/demo-controller.php HTTP/1.1 Host: {endpoint} Content-Type: application/x-www-form-urlencoded Content-Length: {len} call_sid=cal32ddf772-8ef2-41d7-b257-000000000000&channel=number&... ```
> DISCLAIMER! > > All event examples will be presented as a JSON string for a comfortable reading. > > Please remember that the real event format is different! ## Call Events Call events are interactive events, on which user can reply with an XML instruction and change the call flow. > Note! > > Events will be sent to a user controller only if you set the XML call mode on your number (see [change number properties](#operation/changeNumberProperties))! > > Also, you must specify an application where user controller is defined. ### Event structure
| **Name** | **Description** | **Required** | **Specific for XML instruction** | |:----------------:|:---------------------------------------------------------------------------------------:|:------------:|:--------------------------------:| | **call_sid** | Unique call identifier | Yes | - | | **from** | Caller phone number (conventional or virtual) | Yes | - | | **to** | Recipient’s phone number (conventional or virtual) | Yes | - | | **direction** | Call direction.
May be: **outbound**, **inbound** | Yes | - | | **channel** | Event channel. For call events is always **number** | Yes | - | | **tag** | Custom tag for filtering | Yes | - | | **status** | A-leg status.
See possible statuses in the [Events Flow](#call-events/flow) section | Yes | - | | **created** | Datetime when call was added to the queue | Yes | - | | **event_sid** | Unique event identifier | Yes | - | | **event_time** | Datetime when event was sent | Yes | - | | **pool_sid** | Unique pool identifier.
Presented when caller number located in a Pool | No | - | | **input_type** | Type of the user input.
May be: **dtmf**, **speech** | No | getInput | | **input** | User input. May be a DTMF code or a collected user speech | No | getInput | | **leg_from** | B-leg caller phone number (conventional or virtual) | No | makeCall | | **leg_to** | B-leg recipient’s phone number (conventional or virtual) | No | makeCall | | **leg_status** | B-leg status
See possible statuses in the [Events Flow](#call-events/flow) section | No | makeCall | | **leg_channel** | B-leg event channel. For call events is always **number** | No | makeCall | | **leg_call_sid** | B-leg call unique identifier | No | makeCall |
--- ### Events flow Events flow may vary depending on a call type: - [Outbound call](#call-events/outbound-call) - [Inbound call](#call-events/inbound-call) - [MakeCall](#call-events/makecall) Let's take a closer look at each type. ### Outbound call

outbound_call

> Note! > > User controller can reply on all call events with the XML instructions, but applied they will be only after called party's answer! > > For example controller receives a *queued* event, and replying with *playAudio* instruction. In such case, audio will be played only after recipient's answer. Diagram above represents an outbound call. It's a simple REST call that you can make with a [make voice call request](#operation/makeCall). To receive events with that call type check that: - number *call_outbound_mode* is set to *xml* - application with controller is bind to a number OR application_sid is bypassed via [make voice call request](#operation/makeCall). I. When request was sent, user controller receives a **queued** event. Call is going to be initiated. ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "queued", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` II. **Initiated** event is taking place when the call session was initiated, so we're already trying to reach a called party. ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "initiated", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` III. **Ringing** is an unnecessary event, that may not be presented. Ringing depends on the presence of the 180/183 SIP message. Appears when we're ringing to a called party. ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "ringing", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` IV. On that step, different scenarios may happen. Let's describe them one by one. 
      Busy event is sent when called party is busy.
      
      No_Answer event is sent when called party is not answering.
      
      Rejected event is sent when:
      - Account balance is too low.
      - Number you are calling is not existing.
      - Destination you are calling is not available at the moment.
      - Other cases (please contact support).
      
      Failed event is sent when:
      - User XML instruction is invalid.
      - Internal error occurred in Apifonica Platform.
      - Other cases (please contact support).
      
      Cancelled event is sent when calling party decided to cancel the call.
      
      Answered event is sent when a called party is successfully answered.
Some event examples: ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "rejected", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "answered", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` V. When called party answered the call, user XML instructions going to be executed one by one. In case of getInput XML instruction, Apifonica Platform will send **modified** event with collected input back to the user controller. Instruction getInput may be executed an infinite number of times, so modified event is shown on our diagram as looped. ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "modified", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z", "input_type": "dtmf", "input": "1234" } ``` VI. On call finish, Platform sends a **completed** event. ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "completed", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z" } ``` --- ### Inbound call

inbound_call

Diagram above represents an inbound call. It means that now you are a called party and somebody is calling you. To receive events with that call type check that: - number *call_inbound_mode* is set to *xml* - application with controller is bind to a number For inbound call, **queued** event is absent. Other flow stays the same as for [Outbound call](#call-events/outbound-call). --- ### MakeCall

make_call

Diagram above represents an execution of the makeCall XML instruction. As we talked before, makeCall (like other instructions) executes only after called party's answer. In that case, an additional events for the second leg will be sent, namely: - leg_from - leg_to - leg_status - leg_channel - leg_call_sid Please remember, that the first leg **status** will always be **answered** in such events. Some makeCall event examples: ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "answered", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:09:45.434793905Z", "leg_from": "350000000000", "leg_to": "350000000001", "leg_status": "answered", "leg_channel": "number", "leg_call_sid": "calfcd0b1fe-a781-4def-bbbb-1111111111" } ``` ```json { "call_sid": "calfcd0b1fe-a781-4def-a805-000000000000", "from": "358942780000", "to": "358942780000", "direction": "outbound", "channel": "number", "tag": "", "status": "answered", "created": "2022-05-06 10:09:44", "event_sid": "evefd9c00c2-7026-4949-8f5c-000000000000", "event_time": "2022-05-06T10:19:00.000000001Z", "leg_from": "350000000000", "leg_to": "350000000001", "leg_status": "completed", "leg_channel": "number", "leg_call_sid": "calfcd0b1fe-a781-4def-bbbb-1111111111" } ``` ## Message Events Messaging events are basic HTTP request payloads sent to user-defined webhook for notification/statistics purposes. > In order to subscribe to messaging events, you first need to create an [Application](#operation/createApplication) > and either pass the `application_sid` as the `msg_app_sid` inside [sendMessage request](#operation/sendMessage) > or assign `application_sid` to your messaging number in `msg_app_sid` field, see [Change number properties](#operation/changeNumberProperties). ### Event structure Below is the event payload describing the data sent to an Application. For the full reference on each field with examples, refer to [Message details (in 200 OK response)](#operation/getMessage). Channel-specific fields are outlined in the `Channel` column. All other fields are present in any Message event.
| **Name** | **Description** | **Channel** | |:----------------:|:-----------------------------------------------------------------------------------------------------------------------------:|:-----------:| | **message_sid** | Unique message identifier | | | **account_sid** | Unique account identifier | | | **from** | Sender phone number (including alpha-names) | | | **to** | Recipient phone number (or virtual) | | | **direction** | Message direction | | | **channel** | Message channel | | | **tag** | Custom string tag associated with the message | | | **status** | Message status.
See more on this field below | | | **sms_count** | Number of SMS chunks in the message.
__Note__: this field is named differently in the Message resource (`segment_count`) | sms | | **type** | Message type. Currently not present in `sms` events | rcs | | **created** | Message creation datetime. Currently not present in `sms` events | rcs | | **event_sid** | Unique event identifier. Currently not present in `sms` events | rcs | | **event_time** | Event creation datetime. Currently not present in `sms` events | rcs | | **rcs_payload** | Full RCS payload in the form of a JSON-string | rcs |
--- ### Event status diagram Below you can see the transition flow of Message statuses during its lifecycle. Note that for inbound messages, the only status is `received`. For RCS messages, there is an additional status `seen`, which does not apply to regular SMS.

draw-io source https://drive.google.com/file/d/12Wzy1OD9L9obBAhuMkurr8bwG89Fqt1T/view?usp=sharing

### Statuses description
| **Status** | **Description** | |:----------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **queued** | Message is queued for sending | | **sent** | Message is sent to the carrier. After the message is sent successfully, your account is charged money, regardless of the end message status | | **delivered** | Message is delivered to the recipient | | **seen** | Message has been read by the recipient (only for `rcs`, `whatsapp` channels) | | **rejected** | Message is rejected, not a valid mobile number. Your account is charged full price in this case | | **undeliverable**| Message is sent, but cannot be delivered.
This can happen for several reasons including carrier content filtering, availability of the destination handset, etc. | | **expired** | Message has been sent, but cannot be delivered for 48 hours (recipient unavailable/offline) | | **failed** | Message cannot be sent due to technical or billing reasons (e.g. insufficient balance) | | **received** | Message has been received by Apifonica (only for inbound messages) |
### Event examples Example of a POST event: ``` POST /user-webhook-uri HTTP/1.1 Content-Type: application/x-www-form-urlencoded User-Agent: Go-http-client/1.1 Content-Length: 232 Host: www.userhost.com account_sid=accd00008e2-0000-0000-0000-95c000001f7e&channel=sms&direction=outbound&from=MySenderID&message_sid=msgf0000e27-0000-0000-0000-c0bfe0000dec&sms_count=1&status=received&text=Hello!%20I'm%20new%20customer!&to=1234567890 ``` Example of a GET event: ``` GET /user-webhook-uri?account_sid=accd00008e2-0000-0000-0000-95c000001f7e&channel=sms&direction=outbound&from=MySenderID&message_sid=msgf0000e27-0000-0000-0000-c0bfe0000dec&sms_count=1&status=received&text=Hello!%20I'm%20new%20customer!&to=1234567890 HTTP/1.1 User-Agent: Go-http-client/1.1 Host: www.userhost.com ``` ## Validating Events ### 1. General If you want to validate incoming requests from Apifonica then Apifonica provides mechanism for this. We cryptographically sign requests, so you can validate that request is coming from Apifonica, and not a malicious third party. ### 2. Steps to implement validation To implement this mechanism you need to follow these steps: 1. Prepare Apifonica request payload for validation: - In case of GET request payload is sent in query parameters. - In case of POST request payload is sent in form `application/x-www-form-urlencoded`. 2. Hash the parameters according to the mechanism described below. 3. Apifonica sends http header called `X-Apifonica-Signature`. Extract this value from headers. 4. Compare hash from headers and hash got by hashing the payload. If the hashes match, then the request was validated successfully. ### 3. Validation mechanism #### Algorithm: 1. Take the request payload: - In case of GET request payload is sent in query parameters. - In case of POST request payload is sent in form `application/x-www-form-urlencoded. 2. Sort payload parameters alphabetically (using Unix-style case-sensitive sorting order). 3. Iterate through the sorted list of parameters, and prepare a string concatenating the variable name and value of each row (with no delimiters). 4. Sign the resulting string with HMAC-SHA256 using your AccountToken as the key (remember, your AccountToken's case matters!). 5. Base64 encode the resulting hash value. 6. Compare your hash to ours, submitted in the X-Apifonica-Signature header. If they match, the request is validated successfully. ### 4. Example Let's consider that you receive POST request from Apifonica Here's an example of the request: ```text POST /callback HTTP/1.1 Host: your.site.example Content-Type: application/x-www-form-urlencoded X-Apifonica-Signature: 98xQU+FmyKvhPTjbWJ89nO4Gt+87dhNMwQaSrcBhb2k= Content-Length: 236 account_sid=accff3ba4f1-4bbf-3aef-8ad9-706495e74888&direction=inbound&channel=sms&from=79023365596&status=received&sms_count=1&message_sid=msgafc337f3-db96-4951-920d-1647a114bdd1&text=Hello!%20I'm%20new%20customer!&to=1111111111111&tag= ``` Turn the request payload to the array ``` { "account_sid":"accff3ba4f1-4bbf-3aef-8ad9-706495e74888", "direction":"inbound", "channel":"sms", "from":"79023365596", "status":"received", "sms_count":"1", "message_sid":"msgafc337f3-db96-4951-920d-1647a114bdd1", "text":"Hello! I'm new customer!", "to":"1111111111111", "tag":"" } ``` Sort your payload by the parameter name (using Unix-style case-sensitive sorting order): ``` { "account_sid":"accff3ba4f1-4bbf-3aef-8ad9-706495e74888", "channel":"sms", "direction":"inbound", "from":"79023365596", "message_sid":"msgafc337f3-db96-4951-920d-1647a114bdd1", "sms_count":"1", "status":"received", "tag":"", "text":"Hello! I'm new customer!", "to":"1111111111111" } ``` Next create a string from each payload name and value with no delimiters: ```text account_sidaccff3ba4f1-4bbf-3aef-8ad9-706495e74888channelsmsdirectioninboundfrom79023365596message_sidmsgafc337f3-db96-4951-920d-1647a114bdd1sms_count1statusreceivedtagtextHello! I'm new customer!to1111111111111 ``` Hash the resulting string using **HMAC-SHA256**, using your `AccountToken` as the key. Here's some pseudocode example of function that takes your prepared string as first parameter and AccountToken as a second parameter (e.g. AccountToken = "aut868b28be-38bd-4d25-a856-1bf966e0b037") ``` hmac_sha256( "account_sidaccff3ba4f1-4bbf-3aef-8ad9-706495e74888channelsmsdirectioninboundfrom79023365596message_sidmsgafc337f3-db96-4951-920d-1647a114bdd1sms_count1statusreceivedtagtextHello! I'm new customer!to1111111111111", "aut868b28be-38bd-4d25-a856-1bf966e0b037" ) ``` Then take the result of hashing and encode it using Base64 encoding: ```text 98xQU+FmyKvhPTjbWJ89nO4Gt+87dhNMwQaSrcBhb2k= ``` Finally, compare that to the hash Apifonica sent in the X-Apifonica-Signature HTTP header. If they match, the request is valid! - name: SIP Response Codes description: | Here you can find a mapping of Apifonica call statuses to SIP response codes. If SIP code is not listed in the table below, call status by **default** is equal to **'failed'**. Please note, that Apifonica prioritizes **Q850** over SIP codes. For example, Apifonica recieves '503' SIP code with a '21' Q850 code. In such case, call status will be **'rejected'**, not 'failed'.
| **Call Status** | **Q.850** | **SIP** | | |:---------------:|:---------:|:-------:|:------------------------:| | **busy** | 17 | 486 | USER_BUSY | | **no_answer** | 18 | 408 | NO_USER_RESPONSE | | **no_answer** | 19 | 480 | NO_ANSWER | | **no_answer** | 20 | 480 | SUBSCRIBER_ABSENT | | **no_answer** | 41 | 503 | NORMAL_TEMPORARY_FAILURE | | **no_answer** | 502 | | LOSE_RACE | | **canceled** | 487 | 487 | ORIGINATOR_CANCEL | | **rejected** | 21 | 603 | CALL_REJECTED | | **rejected** | 1 | 404 | UNALLOCATED_NUMBER | | **rejected** | 2 | 404 | NO_ROUTE_TRANSIT_NET | | **rejected** | 3 | 404 | NO_ROUTE_DESTINATION | | **completed** | 16 | | NORMAL_CLEARING | | **completed** | 604 | | MEDIA_TIMEOUT |
paths: '/accounts/{account_sid}': get: summary: Get account info description: Method to get info about account by account_sid operationId: getAccountInfo tags: - Accounts security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/account/account.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml put: summary: Update account info description: Method to update account info by account_sid operationId: updateAccountInfo tags: - Accounts security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Account name example: demo_acc status: $ref: models/account/account-status.yml responses: '200': description: OK content: application/json: schema: $ref: responses/account/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/applications': post: summary: Create a new application description: Application is a user-defined webhook to receive Apifonica events. For calls, the application can also control the business logic via [XML instructions](#tag/XML). operationId: createApplication tags: - Applications security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object required: - controller properties: name: $ref: models/application/application-name.yml controller: $ref: models/application/application-controller.yml method: $ref: models/application/application-method.yml events: $ref: models/application/application-events.yml examples: application-with-all-events: value: name: ListeningToAllEvents controller: https://your-relevant-domain.com/controllers/demo-controller.php method: POST events: all application-with-custom-call-events: value: name: ListeningToCustomCallEvents controller: https://your-relevant-domain.com/controllers/demo-controller.php method: GET events: answered|completed|failed responses: '201': description: Created content: application/json: schema: $ref: responses/application/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: Get applications list description: Method to list all applications that belong to Apifonica account operationId: getApplicationsList tags: - Applications security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: application_sid in: query required: false schema: $ref: models/application/application-sid.yml - name: name in: query required: false schema: $ref: models/application/application-name.yml - name: name_like in: query required: false description: Part of the application name that should be presented (equal to SQL %some_name_part%) example: Demo schema: type: string - name: exclude_default in: query required: false description: > Flag to exclude default applications: * `0` — False * `1` — True example: false schema: type: integer enum: [0, 1] default: 1 - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml applications: type: array items: $ref: models/application/application.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/applications/{application_sid}': get: summary: Get application properties description: Method to get application details by application_sid operationId: getApplication tags: - Applications security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: application_sid in: path required: true description: Unique applicaiton identifier example: appfcd0b1fe-a781-4def-a805-000000000000 schema: type: string responses: '200': description: OK content: application/json: schema: $ref: models/application/application.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml put: summary: Update application properties description: Method to update application properties. Request must contain new values for changeable parameters operationId: updateApplication tags: - Applications security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: application_sid in: path required: true schema: $ref: models/application/application-sid.yml requestBody: required: true content: application/json: schema: type: object properties: name: $ref: models/application/application-name.yml controller: $ref: models/application/application-controller.yml method: $ref: models/application/application-method.yml events: $ref: models/application/application-events.yml responses: '200': description: OK content: application/json: schema: $ref: responses/application/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml delete: summary: Delete application description: Method to delete application operationId: deleteApplication tags: - Applications security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: application_sid in: path required: true schema: $ref: models/application/application-sid.yml responses: '200': description: OK content: application/json: schema: $ref: responses/common/resource-deleted.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/availableNumbers': get: summary: Get list of available countries description: Method to get supported countries list operationId: getAvailableCountries tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml responses: '200': description: OK content: application/json: schema: type: object properties: countries: type: array description: List of countries where it is possible to rent a number for specified account items: $ref: models/country/country.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/availableNumbers/{country_code}': get: summary: Get list of available numbers for specified country description: | The phone numbers are picked out from the whole pool of available numbers for the country in a random manner. If the filtering parameters are specified, the numbers are selected after filtration is applied. The maximum quantity of suggested numbers is 10. operationId: getAvailableNumbersForCountry tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: country_code in: path required: true schema: $ref: models/country/country-code.yml - name: number in: query required: false schema: $ref: models/number/number-number.yml - name: type in: query required: false schema: $ref: models/number/number-type.yml - name: voice in: query required: false schema: $ref: models/number/number-voice.yml - name: messaging in: query required: false schema: $ref: models/number/number-messaging.yml responses: '200': description: OK content: application/json: schema: type: object properties: country_code: $ref: models/country/country-code.yml country_name: $ref: models/country/country-name.yml available_numbers: type: array description: List of numbers available for rent in the specified country for specified account items: $ref: models/number/number-for-rent.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/availableNumbers/virtual': get: summary: Get list of available virtual numbers description: | Virtual (international) numbers are SIP identifiers consisting of numbers; they are treated by Apifonica API as conventional telephone numbers. Virtual numbers do not have the regional identity. All requests work the same way as with conventional phone numbers. operationId: getAvailableVirtualNumbers tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: number in: query required: false schema: $ref: models/number/number-number.yml responses: '200': description: OK content: application/json: schema: type: object properties: country_code: $ref: models/country/country-code.yml country_name: $ref: models/country/country-name.yml available_numbers: type: array description: List of numbers available for rent in specified country for specified account items: $ref: models/number/number-for-rent.yml examples: virtual-number: value: country_code: virtual country_name: virtual available_numbers: - number: '883140000000000' type: sip voice: true messaging: false install_fee: 0 monthly_fee: 0.1 '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/numbers': post: summary: Rent phone number description: | Method to rent a number Please note that only one of the parameters call_app_sid and msg_app_sid can be specified (the other must be null) operationId: rentPhoneNumber tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object required: - number properties: number: $ref: models/number/number-number.yml call_app_sid: type: string description: 'Existing application SID, which will be used for Call operations' example: appfcd0b1fe-a781-4def-a805-000000000000 msg_app_sid: type: string description: 'Existing application SID, which will be used for Message operations' example: appfcd0b1fe-a781-4def-a805-000000000000 responses: '201': description: Created content: application/json: schema: $ref: responses/number/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: Get list of rented numbers description: Method to get numbers rented by customer operationId: getRentedNumbers tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: number in: query required: false schema: $ref: models/number/number-number.yml - name: number_prefix in: query required: false description: Phone number prefix example: '358' schema: type: string - name: name in: query required: false schema: $ref: models/number/number-name.yml - name: name_like in: query required: false description: Part of the number name that should be presented (equal to SQL %some_name_part%) example: Demo schema: type: string - name: country_code in: query required: false schema: $ref: models/country/country-code.yml - name: country_name in: query required: false schema: $ref: models/country/country-name.yml - name: type in: query required: false schema: $ref: models/number/number-type.yml - name: voice in: query required: false schema: $ref: models/number/number-voice.yml - name: messaging in: query required: false schema: $ref: models/number/number-messaging.yml - name: msg_app_sid in: query required: false description: Unique Application identifier for Messages schema: $ref: models/application/application-sid.yml - name: call_app_sid in: query required: false description: Unique Application identifier for Calls schema: $ref: models/call/call-app-sid.yml - name: pool_sid in: query required: false schema: $ref: models/pool/pool-sid.yml - name: endpoint_sid in: query required: false schema: $ref: models/endpoint/endpoint-sid.yml - name: call_outbound_mode in: query required: false schema: $ref: models/call/call-mode.yml - name: call_inbound_mode in: query required: false schema: $ref: models/call/call-mode.yml - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml numbers: type: array items: $ref: models/number/number.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/numbers/{number_sid}': get: summary: Get number details description: Method to get details of the rented number by number_sid operationId: getNumberDetails tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: number_sid in: path required: true schema: $ref: models/number/number-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/number/number.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml put: summary: Change number properties description: | Method to change properties on the rented number The request must contain new values for the listed parameters operationId: changeNumberProperties tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: number_sid in: path required: true schema: $ref: models/number/number-sid.yml requestBody: required: true content: application/json: schema: type: object properties: call_app_sid: type: string description: 'Link to the existing application, which is used for Call operations' example: appfcd0b1fe-a781-4def-a805-000000000000 default: default_call_app_sid msg_app_sid: type: string description: 'Link to the existing application, which is used for Message operations' example: appfcd0b1fe-a781-4def-a805-000000000000 default: default_msg_app_sid sip_password: type: string description: | Password for making calls by using the SIP protocol. This parameter makes sense only for the voice enabled phone numbers example: my_password_12345 minimum: 8 maximum: 32 endpoint_sid: $ref: models/endpoint/endpoint-sid.yml name: $ref: models/number/number-name.yml voice_recording: $ref: models/number/number-voice-recording.yml call_outbound_mode: $ref: models/number/number-outbound-mode.yml call_inbound_mode: $ref: models/number/number-inbound-mode.yml responses: '200': description: OK content: application/json: schema: $ref: responses/number/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml delete: summary: Stop number renting description: Method to discontinue rental of the phone number operationId: deleteNumber tags: - Numbers security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: number_sid in: path required: true schema: $ref: models/number/number-sid.yml responses: '200': description: OK content: application/json: schema: $ref: responses/common/resource-deleted.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/messages': post: summary: Send message description: | Send a message to a mobile phone via one of the available messaging channels. Maximum allowed requests per second for this endpoint is `40`. operationId: sendMessage tags: - Messages security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: $ref: models/message/post-message.yml examples: basic-sms: summary: SMS value: from: "Apifonica" to: "358942782000" channel: "sms" text: "Hello from Apifonica!" text-rcs: summary: RCS (text) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "text" rcs_payload: text_payload: text: "Hello from Apifonica! (now also in RCS)" text-rcs-with-suggestions: summary: RCS (text with suggestions) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "text" rcs_payload: text_payload: text: "Choose your preferred size" suggestions: - id: "option_M" action: "reply" text: "M" - id: "option_L" action: "reply" text: "L" - id: "option_XL" action: "reply" text: "XL" file-rcs: summary: RCS (file) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "file" rcs_payload: file_payload: file: url: "https://xml.apifonica.com/img/red.png" thumbnail: url: "https://xml.apifonica.com/img/red.png" card-rcs: summary: RCS (card) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "card" rcs_payload: card_payload: alignment: left orientation: vertical content: title: "Choose your size" description: Select your preferred T-shirt size media: height: tall file: url: "https://xml.apifonica.com/img/red.png" thumbnail: url: "https://xml.apifonica.com/img/red.png" suggestions: - id: "option_M" action: "reply" text: "M" - id: "option_L" action: "reply" text: "L" - id: "option_XL" action: "reply" text: "XL" carousel-rcs: summary: RCS (carousel) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "carousel" rcs_payload: carousel_payload: card_width: medium contents: - title: "Navy Blue" description: Buy our T-shirt in a deep blue color media: height: tall file: url: "https://xml.apifonica.com/img/blue.png" suggestions: - id: "option_BLUE_M" action: "reply" text: "M" - id: "option_BLUE_L" action: "reply" text: "L" - id: "option_BLUE_XL" action: "reply" text: "XL" - title: "Crimson Red" description: Genuine T-shirt in red color media: height: tall file: url: "https://xml.apifonica.com/img/red.png" suggestions: - id: "option_RED_M" action: "reply" text: "M" - id: "option_RED_L" action: "reply" text: "L" - id: "option_RED_XL" action: "reply" text: "XL" rcs-with-various-suggestions: summary: RCS (with various suggestions) value: from: "Apifonica" to: "358942782000" channel: "rcs" type: "text" rcs_payload: text_payload: text: "Choose one of the options below" suggestions: - id: "1" action: "reply" text: "Tap me" - id: "2" action: "open_url" text: "Visit me" open_url: url: "https://google.com" - id: "3" action: "dial" text: "Call me" dial: phone_number: "358942782001" - id: "4" action: "view_location" text: "View location" view_location: lat_long: latitude: 48.8584 longitude: 2.2945 label: "Meet here" - id: "5" action: "share_location" text: "Share location" - id: "6" action: "create_calendar_event" text: "Schedule a meeting" create_calendar_event: start_time: "2025-03-17T12:00:00Z" end_time: "2025-03-17T13:00:00Z" title: "Meeting" description: "A meeting to discuss very important stuff." whatsapp_template_with_buttons: summary: WhatsApp (template with buttons) value: from: "Apifonica" to: "358942782000" channel: "whatsapp" type: "template" whatsapp_payload: template_payload: name: "apifonica_buttons_reply_url_test" language: "en" variables: 1: "John" buttons: - id: "id-1-reply" type: "quick_reply" - id: "id-2-url" type: "open_url" open_url: suffix: "en/products/voicebot/" whatsapp_template_with_text_header: summary: WhatsApp (template with text header) value: from: "Apifonica" to: "358942782000" channel: "whatsapp" type: "template" whatsapp_payload: template_payload: name: "apifonica_utility_test" language: "en" variables: 1: "100.5" header: text: variables: 1: "John" whatsapp_template_with_image_header: summary: WhatsApp (template with image header) value: from: "Apifonica" to: "358942782000" channel: "whatsapp" type: "template" whatsapp_payload: template_payload: name: "apifonica_header_image_buttons_reply_url_test" language: "en" variables: 1: "Apifonica" header: image: url: "https://xml.apifonica.com/img/home.png" responses: '201': description: Created content: application/json: schema: $ref: responses/message/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: Get message history description: Method that gets message history for the account operationId: getMessages tags: - Messages security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: message_sid in: query required: false schema: $ref: models/message/message-sid.yml - name: from in: query required: false schema: $ref: models/message/message-from.yml - name: to in: query required: false schema: $ref: models/message/message-to.yml - name: to_prefix in: query required: false description: Recipient’s phone number prefix example: '358' schema: type: string - name: channel in: query required: false schema: $ref: models/message/message-channel.yml - name: direction in: query required: false schema: $ref: models/message/message-direction.yml - name: status in: query required: false schema: $ref: models/message/message-status.yml - name: tag in: query required: false schema: $ref: models/message/message-tag.yml - name: created_after in: query required: false description: Messages that were created after this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-01-01' schema: type: string - name: created_before in: query required: false description: Messages that were created before this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-02-01' schema: type: string - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 200 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml messages: type: array items: $ref: models/message/message.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/messages/{message_sid}': get: summary: Get message info description: Method to get message info by message_sid operationId: getMessage tags: - Messages security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: message_sid in: path required: true schema: $ref: models/message/message-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/message/message.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/notification-settings': get: summary: Get notification settings for account description: Get notification settings for account operationId: GetNotificationSettings tags: - Notification-Settings security: - basicAuth: [ ] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/notification-settings/notification-settings.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml put: summary: Put notification settings description: Update notification settings for account operationId: PutNotificationSettings tags: - Notification-Settings security: - basicAuth: [ ] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object properties: settings: $ref: models/notification-settings/settings.yml responses: '200': description: OK content: application/json: schema: $ref: models/notification-settings/notification-settings.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/messages/batch': post: summary: Send message batch description: | Send batch of messages (bulk variant of [Send message](#operation/sendMessage) endpoint). Each message is handled individually. Each message will have a corresponding response structure in the overall response. The order of messages in response body is guaranteed to be the same as in request body. `200 OK` does not guarantee that all messages have been sent. Some messages can be accepted while other ones can fail (e.g. due to validation errors). Refer to request-response examples. Maximum number of messages per batch is `200`. **Note:** his endpoint is for sequential use only. If you need to send messages in parallel, use [Send message](#operation/sendMessage) endpoint. Maximum number of batches per minute is restricted to `6`. operationId: sendMessageBatch tags: - Messages security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: array items: $ref: models/message/post-message.yml examples: basic: summary: SMS batch value: - from: "Apifonica" to: "358942782001" channel: "sms" text: "Hello from Apifonica (1)!" - from: "Apifonica" to: "358942782002" channel: "sms" text: "Hello from Apifonica (2)!" - from: "Apifonica" to: "358942782003" channel: "sms" text: "Hello from Apifonica (3)!" responses: '200': description: Created content: application/json: schema: type: array items: - $ref: responses/message/created.yml - $ref: responses/message/created.yml - $ref: responses/common/validation-failed.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/calls': post: summary: Make voice call description: | Method to make voice call with installed instructions. `call_outbound_mode` of the number must be installed to `xml` and `call_app_sid` must contain a valid application (see Applications) operationId: makeCall tags: - Calls security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object required: - from - to properties: from: type: string description: 'Phone number to be used as a CallerID. This number must be rented from Apifonica. Phone numbers should be formatted with a country code, but without a plus sign. It is also possible to specify a `pool_sid` as from, this way call will be made from a randomly selected number from specified Pool.' example: '358942781000' to: type: string description: 'Recipient’s number or virtual number. Phone numbers should be formatted with a country code, no plus sign' example: '358942782000' call_app_sid: type: string description: 'Link to the existing application, which will be used for Call operations. Important! Please note that the initial connection will be established with the number ''to'' and then with the number, received from the ''call_app_sid'' XML' example: app1520c046-c948-43ad-afab-000000000000 сli: type: string description: Custom caller ID (verified mobile number) used as a number From. Please request *enabling* of these function *via support* example: '358942781000' timeout: type: integer description: 'The number of seconds to wait for the answer of the ''to'' number. If the timeout period has expired and nobody has answered, Apifonica API terminates the call. *Important!* The period starts when you send the request to API' example: 15 default: 60 events: type: string description: 'The call progress events that Apifonica will send webhooks on. Can be ''all'' or ''none''. Events that are sent always: *queued* and *modified*' example: all default: none tag: $ref: models/call/call-tag.yml channel: $ref: models/call/call-channel.yml responses: '200': description: OK content: application/json: schema: $ref: responses/call/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: Get call history description: Method to get account call history operationId: getCalls tags: - Calls security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: call_sid in: query required: false schema: $ref: models/call/call-sid.yml - name: parent_call_sid in: query required: false schema: $ref: models/call/call-parent-call-sid.yml - name: from in: query required: false schema: $ref: models/call/call-from.yml - name: to in: query required: false schema: $ref: models/call/call-to.yml - name: to_prefix in: query required: false description: Recipient’s phone number prefix example: '358' schema: type: string - name: cli in: query required: false schema: $ref: models/call/call-cli.yml - name: direction in: query required: false schema: $ref: models/call/call-direction.yml - name: status in: query required: false schema: $ref: models/call/call-status.yml - name: tag in: query required: false schema: $ref: models/call/call-tag.yml - name: created_after in: query required: false description: | Calls that were created after this date and time. 'dateFormat' => 'YYYY-MM-DD' in UTC. **Default value is one month prior to** `created_before`. example: '2021-01-01' schema: type: string - name: created_before in: query required: false description: | Calls that were created before this date and time. 'dateFormat' => 'YYYY-MM-DD' in UTC. Default value is the current UTC time. Max range difference `created_after` - `created_before` is one year. If it is larger, `created_after` param is adjusted accordingly. example: '2021-02-01' schema: type: string - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 200 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml calls: type: array items: $ref: models/call/call.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/calls/{call_sid}': post: summary: Modify live call description: Method to change application binded to call on the fly operationId: modifyCall tags: - Calls security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: call_sid in: path required: true schema: $ref: models/call/call-sid.yml requestBody: required: true content: application/json: schema: type: object required: - call_app_sid properties: call_app_sid: type: string description: 'Link to the existing application, which will be used for Call operations. Important! Please note that the initial connection will be established with the number ''to'' and then with the number, received from the ''call_app_sid'' XML' example: app1520c046-c948-43ad-afab-000000000000 responses: '200': description: OK content: application/json: schema: $ref: responses/call/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: Get call details description: Method to get call details by call_sid operationId: getCall tags: - Calls security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: call_sid in: path required: true schema: $ref: models/call/call-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/call/call.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/recordings': get: summary: Get list of recordings description: Method to list all recordings for the account operationId: getRecordings tags: - Recordings security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: account_sid in: query required: false schema: $ref: models/account/account-sid.yml - name: call_sid in: query required: false schema: $ref: models/call/call-sid.yml - name: from in: query required: false schema: $ref: models/call/call-from.yml - name: to in: query required: false schema: $ref: models/call/call-to.yml - name: created_after in: query required: false description: Records that were created after this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-01-01' schema: type: string - name: created_before in: query required: false description: Records that were created before this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-02-01' schema: type: string - name: format in: query required: false schema: $ref: models/record/record-format.yml - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml recordings: type: array items: $ref: models/record/record.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/recordings/{record_sid}': get: summary: Get recording details description: Method to get recording details by record_sid operationId: getRecording tags: - Recordings security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: record_sid in: path required: true schema: $ref: models/record/record-sid.yml - name: format in: query required: false schema: $ref: models/record/record-format.yml responses: '200': description: OK content: application/json: schema: $ref: models/record/record.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/pools': post: summary: Create a new pool description: | Method to create a pool of numbers with identical configuration operationId: createPool tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object required: - name properties: name: $ref: models/pool/pool-name.yml call_outbound_mode: $ref: models/number/number-outbound-mode.yml call_inbound_mode: $ref: models/number/number-inbound-mode.yml call_app_sid: $ref: models/call/call-app-sid.yml voice_recording: $ref: models/pool/pool-voice-recording.yml numbers: type: array default: [] items: $ref: models/number/number-number.yml responses: '201': description: Created content: application/json: schema: $ref: responses/pool/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: List pools description: Method to list all created pools operationId: getPools tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: name in: query required: false schema: $ref: models/pool/pool-name.yml - name: name_like in: query required: false description: Part of the pool name that should be presented (equal to SQL %some_name_part%) example: Demo schema: type: string - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml pools: type: array items: $ref: models/pool/pool.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/pools/{pool_sid}': get: summary: View pool description: Method to view pool info by its pool_sid operationId: getPool tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: pool_sid in: path required: true schema: $ref: models/pool/pool-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/pool/pool.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml put: summary: Change pool properties description: | All pool parameters that were changed will be reflected on each number in the pool. "numbers" parameter is not supported for this action. Use "Add number to pool" and "Remove number from pool" instead. operationId: changePoolProperties tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: pool_sid in: path required: true schema: $ref: models/pool/pool-sid.yml requestBody: required: true content: application/json: schema: type: object properties: name: $ref: models/pool/pool-name.yml call_outbound_mode: $ref: models/number/number-outbound-mode.yml call_inbound_mode: $ref: models/number/number-inbound-mode.yml call_app_sid: $ref: models/call/call-app-sid.yml voice_recording: $ref: models/pool/pool-voice-recording.yml responses: '200': description: OK content: application/json: schema: $ref: responses/pool/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml delete: summary: Delete pool description: | Method to delete pool and release all numbers. Each number properties are reset to default values operationId: deletePool tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: pool_sid in: path required: true schema: $ref: models/pool/pool-sid.yml responses: '200': description: OK content: application/json: schema: $ref: responses/common/resource-deleted.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/pools/{pool_sid}/numbers/{number}': put: summary: Add number to pool description: | Method to add a single number to the pool. Following number properties will be immediately updated to match pool configuration: * `name` * `call_outbound_mode` * `call_inbound_mode` * `call_app_sid` * `pool_sid` operationId: addNumberToPool tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: pool_sid in: path required: true schema: $ref: models/pool/pool-sid.yml - name: number in: path required: true schema: $ref: models/number/number-number.yml responses: '200': description: OK content: application/json: schema: $ref: responses/pool/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml delete: summary: Remove number from pool description: | Method to remove a single number from the pool. Following number properties are reset to default values: * `name` * `pool_sid` * `call_app_sid` Notice. Properties `call_inbound_mode` and `call_outbound_mode` remain unchanged. operationId: removeNumberFromPool tags: - Pools security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: pool_sid in: path required: true schema: $ref: models/pool/pool-sid.yml - name: number in: path required: true schema: $ref: models/number/number-number.yml responses: '200': description: OK content: application/json: schema: $ref: responses/common/resource-deleted.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/endpoints': post: summary: Create a new endpoint description: | Method to create endpoint with your static IP address operationId: createEndpoint tags: - Endpoints security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml requestBody: required: true content: application/json: schema: type: object required: - name - ip properties: name: $ref: models/endpoint/endpoint-name.yml ip: $ref: models/endpoint/endpoint-ip.yml port: $ref: models/endpoint/endpoint-port.yml responses: '201': description: Created content: application/json: schema: $ref: responses/endpoint/created.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml get: summary: List endpoints description: Method to list all created endpoints operationId: getEndpoints tags: - Endpoints security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: endpoint_sid in: query required: false schema: $ref: models/endpoint/endpoint-sid.yml - name: name in: query required: false schema: $ref: models/pool/pool-name.yml - name: name_like in: query required: false description: Part of the pool name that should be presented (equal to SQL %some_name_part%) example: Demo schema: type: string - name: ip in: query required: false schema: $ref: models/endpoint/endpoint-ip.yml - name: port in: query required: false schema: $ref: models/endpoint/endpoint-port.yml - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml endpoints: type: array items: $ref: models/endpoint/endpoint.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/endpoints/{endpoint_sid}': get: summary: View endpoint description: Method to view endpoint info by its endpoint_sid operationId: getEndpoint tags: - Endpoints security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: endpoint_sid in: path required: true schema: $ref: models/endpoint/endpoint-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/endpoint/endpoint.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml put: summary: Change endpoint properties description: | Method to chane endpoint properties operationId: changeEndpointProperties tags: - Endpoints security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: endpoint_sid in: path required: true schema: $ref: models/endpoint/endpoint-sid.yml requestBody: required: true content: application/json: schema: type: object properties: name: $ref: models/endpoint/endpoint-name.yml ip: $ref: models/endpoint/endpoint-ip.yml port: $ref: models/endpoint/endpoint-port.yml responses: '200': description: OK content: application/json: schema: $ref: responses/endpoint/updated.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml delete: summary: Delete endpoint description: | Method to delete endpoint operationId: deleteEndpoint tags: - Endpoints security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: endpoint_sid in: path required: true schema: $ref: models/endpoint/endpoint-sid.yml responses: '200': description: OK content: application/json: schema: $ref: responses/common/resource-deleted.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/balance': get: summary: Get account balance description: Method to get your current balance operationId: getBalance tags: - Payments & Expenses security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/payments_expenses/account-balance.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/balance/payments': get: summary: Get payments history description: Method to list all account payments operationId: getPayments tags: - Payments & Expenses security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: status in: query required: false schema: $ref: models/payments_expenses/payment-status.yml - name: payment_sid in: query required: false schema: $ref: models/payments_expenses/payment-sid.yml - name: date_from in: query required: false description: Payments that were created after this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-01-01' schema: type: string - name: date_to in: query required: false description: Payments that were created before this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-02-01' schema: type: string - name: amount in: query required: false description: Amount of the payment example: 100 schema: type: integer - name: amount_from in: query required: false description: Payments that were exceeding a specific amount example: 100 schema: type: integer - name: amount_to in: query required: false description: Payments that were not exceeding a specific amount example: 500 schema: type: integer - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml account_sid: $ref: models/account/account-sid.yml payments_history: type: array items: $ref: models/payments_expenses/payment.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/balance/payments/{payment_sid}': get: summary: Get payment details description: Method to get payment details operationId: getPayment tags: - Payments & Expenses security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: payment_sid in: path required: true schema: $ref: models/payments_expenses/payment-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/payments_expenses/payment.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml '/accounts/{account_sid}/balance/expenses': get: summary: Get expenses history description: Method to list all account expenses operationId: getExpenses tags: - Payments & Expenses security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: status in: query required: false schema: $ref: models/payments_expenses/expense-status.yml - name: expense_sid in: query required: false schema: $ref: models/payments_expenses/expense-sid.yml - name: article in: query required: false schema: $ref: models/payments_expenses/expense-article.yml - name: date_from in: query required: false description: Expenses that were created after this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-01-01' schema: type: string - name: date_to in: query required: false description: Expenses that were created before this date and time. 'dateFormat' => 'YYYY-MM-DD' example: '2021-02-01' schema: type: string - name: amount in: query required: false description: Amount of the expense example: 100 schema: type: integer - name: amount_from in: query required: false description: Expenses that were exceeding a specific amount example: 100 schema: type: integer - name: amount_to in: query required: false description: Expenses that were not exceeding a specific amount example: 500 schema: type: integer - name: limit in: query required: false description: Number of records you want to return per page example: 20 schema: type: integer default: 20 maximum: 20 - name: prev in: query required: false schema: $ref: models/prev.yml - name: next in: query required: false schema: $ref: models/next.yml responses: '200': description: OK content: application/json: schema: type: object properties: limit: $ref: models/limit.yml prev: $ref: models/prev.yml next: $ref: models/next.yml account_sid: $ref: models/account/account-sid.yml expenses_history: type: array items: $ref: models/payments_expenses/expense.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '/accounts/{account_sid}/balance/expenses/{expense_sid}': get: summary: Get expense details description: Method to get expense details operationId: getExpense tags: - Payments & Expenses security: - basicAuth: [] parameters: - name: account_sid in: path required: true schema: $ref: models/account/account-sid.yml - name: expense_sid in: path required: true schema: $ref: models/payments_expenses/expense-sid.yml responses: '200': description: OK content: application/json: schema: $ref: models/payments_expenses/expense.yml '400': description: Data Validation Failed content: application/json: schema: $ref: responses/common/validation-failed.yml '401': description: Unauthorized content: application/json: schema: $ref: responses/common/unauthorized.yml '403': description: Forbidden content: application/json: schema: $ref: responses/common/forbidden.yml '404': description: Not Found content: application/json: schema: $ref: responses/common/resource-not-found.yml components: securitySchemes: basicAuth: type: http scheme: basic description: | * `Username` - equal to your `account_sid` (e.g., acc89ddf772-5df2-41d7-b257-000000000000) * `Password` - equal to your `token` (e.g., auta42e0580-8138-308a-a354-000000000000)