Tasks

API Call

Calls external APIs from a Stubber action and returns data for later tasks. Useful for REST integrations, data lookup, webhooks, and service-to-service automation.

# Use cases

• Integrate seamlessly with a REST API endpoint.
• Perform a POST request with a specified body.
• Trigger an API call upon executing a specific action.
• Retrieve data from third-party systems.
• Call an API endpoint requiring client certificate authentication.
• Invoke a webhook on a stub.

# Basic usage

# Parameters

# apiurl

required

string

The endpoint that the task will invoke.

# query_params

optional

object

Query string parameters to append to the URL. Each key-value pair is added as a query parameter. This is an alternative to embedding query strings directly in apiurl.

Example:

# method

optional

string

The HTTP method to be used for the API call.
For example you can use GET, POST, PUT, DELETE, PATCH. Any HTTP verbs are supported.

Default: GET

# headers

optional

object

Any headers that you wish to include in the request.

To authenticate, prefer org_credentials over putting a token in an Authorization header yourself. A credential keeps the secret out of the template, and OAuth tokens are refreshed for you.

When a Basic Authentication, Bearer Token or Generic OAuth credential is used, its Authorization header replaces any authorization header set here, whatever its casing.

Default:

# body

optional

object

The body in JSON that you would like to send as part of the request. The body would typically use variable substitution to bring in data values from the stub or stubpost.data.

# body_mode

optional

string

Set to binary to send a file's raw bytes as the request body, using the file in body_binary. body is not needed in this mode and is ignored.

Use this for APIs that take the file itself as the body, such as Microsoft Graph's /content upload endpoint or S3 presigned URLs. If the API expects a form upload with named fields, use multipart/form-data instead (see the multipart upload example below). Sending a multipart body to an API that expects raw bytes stores the multipart wrapper inside the file.

Set the Content-Type header to the file's type, for example text/csv. If it is not set, it defaults to application/json.

Binary bodies are not sent with GET or HEAD requests, unless allow_body_on_get is true.

# body_binary

optional

object

The file to send when body_mode is binary. Required in that mode.

# allow_body_on_get

optional

boolean

When true, allows a body to be sent with a GET request. This is technically valid HTTP but uncommon — some APIs (particularly older or non-standard ones) require it. Has no effect on other HTTP methods.

Default: false

Example:

# timeout_seconds

optional

number

The seconds after which the apicall will time out.

Default: 15

# org_credentials

optional

object

The org credentials to use for an API call. This requires setting up the org credentials on the Credentials page of Stubber Console. See Credentials for the available types.

The keys are names of your choice, and the values are orgcredentialuuids. Credentials are applied in the order they are listed, so more than one can be used on the same call, for example a certificate together with a token.

• Generic Body credentials are merged into the request body. See the example below.
• With a Generic OAuth credential, a 401 Unauthorized response is retried once with a new token. See Retrying after a 401.

Credential values never appear in the task result.

Example:

# response_merge

optional

object

An object that is deep-merged into the apiresult after the API call completes, before the result is made available to subsequent tasks or stub/stubpost data. This allows you to overwrite, hide, or transform fields in the response.

# response_options

optional

object

Configuration options that control what is included in the apiresult returned by the task.

Example:

# Result

# Properties

apiresult.status

The status code indicating the outcome of the API call.

apiresult.statusText

A textual description of the result status.

apiresult.body

Contains the body of the API result, providing the actual data retrieved from the external API. The type depends on the API response but is typically a JSON object or array.

apiresult.retried_after_token_refresh

Only present when the first request got a 401 Unauthorized response and was retried with a new Generic OAuth token. The rest of apiresult is the result of the retried request. See Retrying after a 401.

request

The apiurl, body and options (method and headers) of the request, for debugging. These show the request as the template defined it, before credentials were applied, so credential values are never included. Any Authorization header is masked, showing only its scheme and first four characters, for example Bearer eyJh****.

# Retrying after a 401

When a request that uses a Generic OAuth credential gets a 401 Unauthorized response, the token may have been revoked by the provider before it expired. The task then requests a new token and sends the request once more, and the result includes apiresult.retried_after_token_refresh: true.

• The request is retried only once. If the retry also gets a 401, that result is returned.
• Only a 401 is retried, not other errors such as 403 Forbidden.
• Requests with a multipart/form-data body are not retried.
• If the new token cannot be fetched, the original 401 result is returned.
• The call is charged once, even when it is retried.

# Examples

These are some more complex examples

# Request with body

Include a body in your apicall request

# Request with headers

Include custom headers in your apicall request

# Upload file with multipart/formdata

Upload a file as part of a multipart/form-data request

# Upload a file as the raw request body

Upload a file's raw bytes with body_mode set to binary, for example to a SharePoint document library through Microsoft Graph

# Custom Header Org Credential

This requires the Custom Header credential to be created in the organization's Credentials page of Stubber Manage.

# Response merge

Use response_merge to overwrite fields in the API response before they are exposed to the rest of the template. This is useful for hiding sensitive data or limiting what gets stored in stub/stubpost data.

In this example, meta and reviews are removed from the result and price is replaced with its MD5 hash using the apicall interpolator, which has access to payload.apiresult.

# NTLM Org Credential

This requires the NTLM credential to be created in the organization's Credentials page of Stubber Manage. Typically used for authenticating with older Microsoft systems.

# Generic Body Org Credential

This requires the Generic Body credential to be created in the organization's Credentials page of Stubber Manage.

If the credential stores { "client_secret": "s3cret", "auth": { "api_key": "abc123" } }, the request below is sent with the body { "customer": "...", "auth": { "account": "main", "api_key": "abc123" }, "client_secret": "s3cret" }. The credential's values win when a key exists in both.

The body must be sent as JSON, form URL encoded or XML. A Generic Body credential cannot be used with GET or HEAD requests, or with multipart/form-data or binary bodies.

# OAuth Org Credential

This requires the Generic OAuth credential to be created in the organization's Credentials page of Stubber Manage.