Make POST API calls

The API_POST extension sends a POST request to a REST API endpoint and returns the response body as a JSON string that can be stored in a Virtuoso variable.

This is useful when a journey needs to create a record, prepare backend test data, submit a payload to an API, or validate that the API response contains values created from the request body.

Parameters:

• url required, a string containing the REST API endpoint to call. Query parameters can be included directly in the URL when needed;
• body required, a JSON string containing the POST request payload. The extension parses this value with JSON.parse(body) before sending it;
• headers optional, a JSON string containing request headers, such as authorization or content-type headers. Leave it blank when no custom headers are required.

How to apply this to your journey

Use the extension in a journey by calling API_POST with the URL and request body. Pass each value to the matching extension input using as url, as body, and optionally as headers.

API_POST("https://reqres.in/api/users", '{"name":"Virtuoso", "job":"Intelligent Quality Assistant"}') returning $data
assert $data.name equals "Virtuoso"

API_POST("https://reqres.in/api/users", '{"name":"Virtuoso", "job":"Intelligent Quality Assistant"}', '{"Authorization":"Bearer example-token"}') returning $data
assert $data.job equals "Intelligent Quality Assistant"

You can also pass variables into the extension when the endpoint, payload, or headers are created earlier in the journey.

API_POST($apiUrl, $requestBody) returning $data
assert $data.name equals "Virtuoso"

store value "https://reqres.in/api/users" in $apiUrl
store value "Virtuoso" in $request.name
store value "Intelligent Quality Assistant" in $request.job
API_POST($apiUrl, $request) returning $data
assert $data.name equals "Virtuoso"

Advanced API calls

Some APIs require custom request headers, such as authentication tokens, content type, tenant identifiers, or API-version headers. The API_POST extension supports this through the optional headers input. Pass headers as a valid JSON string or as a Virtuoso variable that resolves to a JSON object/string.

Content type example:

store value '{"content-type":"multipart/form-data"}' in $contentTypeHeader
API_POST("https://reqres.in/api/users", '{"name":"Virtuoso", "job":"Intelligent Quality Assistant"}', $contentTypeHeader) returning $data
assert $data.name equals "Virtuoso"

Header authentication example, where the authentication token is already stored in $token:

store value ${'Bearer ' + $token} in $authenticationHeader.Authorization
API_POST("https://reqres.in/api/users", '{"name":"Virtuoso", "job":"Intelligent Quality Assistant"}', $authenticationHeader) returning $data
assert $data.name equals "Virtuoso"

Example output:

{
  "name": "Virtuoso",
  "job": "Intelligent Quality Assistant",
  "id": "123",
  "createdAt": "2021-01-14T17:44:45.000Z"
}

This extension requires the following resources:

• https://cdnjs.cloudflare.com/ajax/libs/axios/0.21.1/axios.min.js 

The extension should be configured as:

• Run asynchronously: Yes
• Scope: Global

Add the extension to your Virtuoso instance

Select the domain that matches your Virtuoso account.

// Last updated: 14/01/2021, 17:44:45 UTC
// Resources:
//   https://cdnjs.cloudflare.com/ajax/libs/axios/0.21.1/axios.min.js

const makeRequest = async (url, body, headers = '') => {
  try {
    const { data } = await axios.post(
        url,
        JSON.parse(body),
        headers ? {headers: JSON.parse(headers)} : {},
    )
    done(JSON.stringify(data))
  } catch (e) {
    doneError(e)
  }
}

if (!url) {
  throw new Error('URL parameter is missing')
}

if (!body) {
  throw new Error('body parameter is missing')
}

makeRequest(url, body, headers)