API Request

API Request The API Request element allows you to make API calls directly within an IVR workflow. Data returned from the request — such as a customer's account balance or contact details — can then be passed through the IVR and used in subsequent elements

Element Settings

Name and Description: Give the element a clear name and description to help identify it within the IVR workflow. The name is referenced by other elements in the flow, so we recommend keeping it as a single word with no spaces. 

Agents Can See This: When enabled, agents in Contact Hub will see this element as a transfer option under Transfer → IVR.

Supervisor Can See This: When enabled, only users with a Supervisor role will be able to see and transfer interactions to this element. 

Result Code: Select a custom result code for this element, or leave it set to the default. If the default is selected, INBOUND will be applied when a call ends at this element. 

Phrase: Select the audio file(s) to be played to the caller while the API request is being processed. 

Action: Select the type of API request to perform:

• GET. Retrieves existing data without making any changes. Use this to read information such as account details, order history, or record status.
• POST. Creates a new record in the system. Use this when submitting data that doesn't already exist.
• PUT. Updates or replaces an existing record. Use this when you need to modify information that's already stored. 

Timeout (s): Set the maximum time (in seconds) the element will wait for the API to respond before moving on. 

URL: The address of the resource you want to interact with. This tells the API what you're trying to access. You can pull dynamic fields into the URL — see the Advanced section below for more detail. 

Header: Provide the details required for the request to be authenticated and processed, such as an API key or token. If multiple headers are needed, separate them with a comma ( , ). 

Body: Used for POST or PUT requests. This contains the data you want to create or update via the API. For GET requests, the body can be left empty.

Advanced Section - Utilising API Data Within the IVR

This section covers how to use data returned from an API Request in other parts of your IVR, including reading values back to the caller and passing data to other elements. 

Reading API data back to the caller (TTS)

To have a value from your API response read aloud to the caller, use a Text-to-Speech (TTS) element with a fillpoint that references the API Request element. The format is: 

{{Name of API Request element.Result.Name of value within the body}}

The body output of my GET request

The IVR in which TTS has been set up to read out a value from the GET request.

So with the example above, our TTS fillpoint would be formatted as the below. With the name of the API element first, followed by Result and then the name from the body that we wish to be read out.

{{GETAPI.Result.Value}}

You can also use a Set Property element to store the value first and then reference it in the TTS. This is covered in the example setup below. 

Using API data in other elements (Set Property -> Branch)

To use a value from your API response elsewhere in the IVR — such as in a Compare/Branch element or a further API call — we recommend using the Set Property element. 

Within the Set Property element:

• Property Type / Property Name — Define the property that data will be stored against during the interaction.
• Value Type / Value Name — Set the source of the data you want to pull from the API response.

Then within the Branch element, you can set the Source to the Value Name from within the Set Property, to route the call down a specific path based on the value returned from the API.

Example Set Up - MaxContact Lead Web API

The following example walks through using the MaxContact Lead Web API to retrieve a secondary data field and read it back to the caller within an IVR.

Before you begin, make sure the following are in place:

• The inbound call must have matched to a lead (and therefore have a Lead ID). Use a Lookup Lead or Create Lead element earlier in the flow to ensure the correct lead is matched.
• A user account must be configured with MaxContact API permissions. We recommend setting up a dedicated API account for this purpose.
• Test your API call in a tool such as Postman before implementing it in the IVR, to confirm the response is correct and working as expected.

Note: While this example uses the MaxContact API, the API Request element supports calls to external APIs too. Check with your provider whether any whitelisting is required to allow outbound API calls. 

Step 1 - Lead Lookup Element

Ensure the inbound call is matched to the correct lead in the system using the Lookup Lead element before reaching the API Request element.

Step 2 - API Request Element

Configure the element as follows:

Name: GETAPI Keep the name unique and free of spaces, as it will be referenced in later elements.

Action: GET

URL:

https://domain.maxcontact.com/leadservices/api/v2/leads/{{call.leadid}}/fields/fieldvalue

For my example, this gives a full URL of the below.

https://msl.maxcontact.com/leadservices/api/v2/leads/{{call.leadid}}/fields/158

Header: 

Content-Type: application/json,
Authorization: Basic [base64 encoded login:password]

Body: Leave empty — this is a GET request, so no data needs to be submitted. 

Step 3 - Set Property Element

Use a Set Property element to store the API response value for use later in the flow. 

Step 4 - Text-to-Speech

Reference the property created in Step 3 within your TTS element to read the retrieved value back to the caller. A successful call will result in the secondary data field being read aloud. 

Appendix

1.1 Call Variables