> For the complete documentation index, see [llms.txt](https://docs.valorx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valorx.com/valorx-fusion/design-studio/tasks/dynamic-api.md). # Dynamic API Dynamic API brings Postman-style API configuration directly into Fusion workflows. It lets you configure API endpoints, authentication, parameters, headers, and request bodies in Design Studio, while dynamically binding values from Excel cells, named ranges, workflow Data Intakes, Maps, and API Variables. At runtime, Fusion resolves these values using the current workbook and workflow data, sends the API request, and stores the response in Excel or an API Variable for use in subsequent tasks. This lets you integrate with external APIs and build dynamic workflows without writing custom code. You can access it from the **Dynamic API** tab in the **Tasks** menu. By clicking the 'New Dynamic API Task' button, the Dynamic API Task screen appears as shown in the image below:

*** ## Creating a Dynamic API task To create a new task, click **New Dynamic API Task**, then work through the following steps. {% stepper %} {% step %} #### Name The Dynamic API Task. Give it a clear, unique name in the Task Name field at the top of the window.

{% endstep %} {% step %} #### Choose The Method Choose the HTTP method: **GET**, **POST**, **PUT**, **PATCH**, or **DELETE** based on what the external system expects. Then, enter the web address (URL) of the external system. * *For more information, see* [*Method and URL*](#method-and-url)*.*

{% endstep %} {% step %} #### **Configure The Request Tabs.** Work through **Params, Authorization, Headers, Body,** and **Settings** as needed for your API.\ *For more information, see* [*Params*](#params)*,* [*Authorization*](#authorization)*,* [*Headers*](#headers)*,* [*Body*](#body)*, and* [*Settings*](#settings)*.*

{% endstep %} {% step %} #### Configure The Response. Click **Next** to choose where the response should be saved and, optionally, which fields to keep.\ *For more information, see* [*Response Configuration*](#response-configuration)*.*

{% endstep %} {% step %} #### Save Once you've configured the request, click **Save**. The task appears in the Dynamic API task list and is ready to be added to a workflow.

{% endstep %} {% endstepper %} *** ## The Task Window

Control	What it does
Variables	Opens the API Variables panel. The number shown is how many variables your app has. See “Using API Variables”.
✕ / Cancel	Closes the task without saving. If you have unsaved changes, you’ll be asked to confirm.
Next	Checks your request and moves to the response screen.
Back	Returns from the response screen to the request tabs.
Save	Checks everything and saves the task into your app.

*** ## Method and URL

Type the address into the URL field. As you add parameters on the **Params** tab, they appear after the URL as a live preview, so you can see the whole address at a glance. * Pasting a full URL that already has a query string works too, Fusion splits it automatically into the address and individual Params rows. * Don’t type a “?” yourself. Query parameters belong on the Params tab so their values can stay dynamic. * HTTPS only. A plain “http\://” address, or one with a username/password baked in, isn’t accepted. The address plus its query string needs to stay under 2,048 characters ### Where Values Come From Almost every value you enter, a parameter, a header, a field in the body, a password, has a Source next to it. This decides whether the value is fixed or read fresh every time the task runs.

Source	You pick	At run time
Constant	Type the value in	Sent exactly as typed, every run.
Cell	A worksheet cell	Read live from that cell each time.
Range	A named range	Read live, one value or several if the field allows a list.
Field	An object and one of its fields	Read from a dataset the workflow supplies. You’ll choose which dataset when you add the task to a workflow.
API Variable	A saved variable, or one field inside it	Read from the value stored by an earlier task or sign-in.

When you select **Field** as the source, Fusion retrieves the value from the results of a query task elsewhere in your [workflow](/valorx-fusion/design-studio/workflow-and-ux/dynamic-api.md). For example, you can use a specific field from an **Account** or **Opportunity** record. Because the query results are available only when the workflow runs, you must specify which query result the field should come from. Configure this on the [workflow](/valorx-fusion/design-studio/workflow-and-ux/dynamic-api.md) screen. *** ## Params A grid of query parameters, one row per parameter. Add a row with the + icon; remove one with the bin icon.

Column	Notes
Checkbox	Untick to leave a row out of the request without deleting it.
Key	The parameter name.
Source	Constant, Cell, Range, Field, or API Variable.
Value	Changes to match the source you picked.
Description	Your own notes. Never sent.

*** ## Authorization Choose the authorization type required by the external system. Dynamic API supports the following authorization: * **None -** Executes the API request without authentication. Use this option when the external API does not require you to sign in or provide credentials. * **Basic Authentication -** Authenticates using a username and password. Enter the credentials required by the external API. * **Bearer Token -** Sends an access token with the API request. Enter the token provided by the external API. * **API Key -** Authenticates using an API key provided by the target API. Depending on the API, the key may be sent in the request headers or as part of the URL. * **OAuth 2.0 -** Supports token-based authorization for APIs that use OAuth 2.0. Depending on the API, you may need to sign in through a secure authentication window to authorize access.

### OAuth 2.0 OAuth is set up once as a named token and then reused across tasks. Give the token a name and choose whether it should be Persistent (saved for future sessions) or Session (cleared when Excel closes), then pick a grant type:

Grant type	Required fields	Sign-in
Client Credentials	Access Token URL, Client ID, Client Secret	Silent
Password Credentials	Access Token URL, Client ID, Client Secret, Username, Password	Silent
Authorization Code	Callback URL, Auth URL, Access Token URL, Client ID, Client Secret	Browser window
Authorization Code (With PKCE)	Same as above, plus Code Challenge Method and Code Verifier	Browser window
None	No fields, for providers that don’t need a token exchange	—

At execution, Fusion uses an explicitly configured token first. If no token is configured, it uses the selected **Authentication** variable. If the token has expired and refresh is enabled, Fusion attempts to refresh it. If the refresh fails, Fusion acquires a new token. For **Authorization Code** and **PKCE**, this may open the sign-in window. Once created, the token is saved as an API Variable, so other tasks in the app can reuse it instead of signing in again. *** ## Headers A grid of request headers, in the same style as Params, but with an extra Data Type column since header values are often typed more strictly by the receiving system. Alongside the source, you’ll also set a **Data Type** (String, Number, Boolean, Object, or Null). This is what keeps the outgoing request correctly formatted rather than treating everything as plain text.


Key	The header name.
Source	Constant, Cell, Range, Field, or API Variable.
Value	Changes to match the source you picked.
Data Type	String, Number, Boolean, Object, or Null.
Description	Your own notes. Never sent.
Checkbox	Untick to leave a row out of the request without deleting it.

Setting a Content-Type header here overrides the default used for a JSON body. *** ## Body Choose how the request body is built on the left of the Body tab.

Mode	What you get	Reach for it when
None	No body sent	GET and DELETE calls
Form Data	A key/value grid, sent as multipart form data	The API expects an HTML-form style upload
URL Encoded	A key/value grid, sent as an encoded form	Older endpoints expecting application/x-www-form-urlencoded
JSON	A structured payload you build field by field, in either a Tree or Editor view	Most modern APIs, this is the most flexible option
Reference	The whole payload comes from a Cell, Range, or API Variable you point at	The JSON is already built somewhere else, like an earlier task’s response

### Building a JSON Body A JSON body isn’t just typed text, it’s built as a structure of fields, each with its own name, type, and source. There are two ways to work on it: * **Editor view** shows the same body as JSON text. It’s the fastest way to get a shape in: paste a sample request from the API’s documentation, then switch to Tree to wire individual fields up to cells or datasets.

* **Tree view** is where you set sources, types, and build repeating sections (for example, one line item per row of a dataset).

A reliable way to build a body: 1. In Editor, paste a sample request (two or three example rows if it includes a repeating list). 2. Switch to Tree and confirm the types and array settings look right. 3. Set the Source on each field that should come from your workbook. 4. Switch back to Editor for a final check, live fields show as placeholders so you can see exactly what will be sent. ### Reference mode Skip building the body field by field and point at where the finished payload already lives:

Source	What will be sent
Cell	The text in that one cell, read fresh each run.
Range	The text the named range resolves to.
API Variable	Whatever the variable currently holds.

The value has to be valid JSON (an object or array, not a single number or word) or the step will fail with a message telling you which cell, range, or variable to check. If your payload could be very long, use an API Variable rather than a single cell, since a worksheet cell can only hold up to 32,767 characters. *** ## Settings Configure additional options that control how the task behaves.

Setting	Options	What it controls
Type mismatch handling for referenced values	Runtime Error / Use Null	What happens when a cell, range, or field value doesn’t match the data type you declared, fail the run, or send a blank value and carry on.
Fetch access token using refresh token	Yes / No	Whether an expired sign-in is renewed automatically in the background before asking anyone to sign in again.
Always prompt for authentication	Yes / No	Off by default, the task reuses a saved sign-in. Turn on to require fresh credentials every run.
Maximum number of redirects	A number	How many redirects the request will follow before giving up.

*** ## Response Configuration Clicking Next takes you to Response Configuration, where you choose where the response should be saved. * **Cell** - A specific worksheet cell. * **Range** - A named range. * **API Variable** - A saved variable, so a later task can read the answer. You can create one right here.

By default, the whole response is written to your chosen destination. If you only want specific fields, define a Response Schema using the same Editor/Tree approach as the request body, paste a sample response to get the shape, then trim it down to just what you need. *** ## Using API Variables An **API Variable** is a named holder for a value that can be reused across Dynamic API tasks. You can use API Variables to store values such as authentication tokens, IDs returned by one API call and used by another, or a base URL that you want to define in one place. API Variables belong to the app rather than to a single task, allowing multiple tasks to use the same value.

To configure an API Variable, click **Variables** at the top of the task editor. When creating a variable, configure the following: * **Shape** - Determines the type of data the variable stores: * **Scalar** - Stores a single value, such as text, a number, or a country code. * **JSON** - Stores structured data, such as the response returned by an API. * **Scope** - Determines how long the variable remains available: * **Persistent** - Keeps the value available across sessions. * **Session** - Keeps the value available only for the current session and clears it when Excel closes. * **Populated by** - Determines how the variable gets its value: * **Constant** - A value that you enter manually. * **Response** - Data returned by an API call. A variable that’s currently being used elsewhere in your app is protected, editing it may be limited to just its name and scope, and deleting it is blocked until it’s no longer in use. #### Using a variable Anywhere you see a Source, choose API Variable. Scalar variables appear as single entries; JSON variables expand so you can pick a field inside them. The picker only offers variables that fit the field you’re filling. #### Filling a variable Values arrive two ways: you typed them in as a Constant, or a run wrote them via a task’s Response Configuration. A value written by one task is visible to the next task in the same run. #### Scope and lifetime

Scope	Lives for	Choose it when
Persistent	Across Excel restarts, encrypted on your own machine.	You don’t want to sign in every morning.
Session	Only while Excel is open, never written to disk.	Your organization’s policy forbids credentials at rest.

*** ## What’s Next? After creating and saving your Dynamic API Task, **Designers must configure the task in the Workflow** to make it executable at runtime. 👉 Go to Workflow Configuration *(*[*Dynamic API*](/valorx-fusion/design-studio/workflow-and-ux/dynamic-api.md)*)* > 💡 Tasks that are not added to a workflow will not run in the app.