Paired Variables

Paired variables combine values from two sources into correlated pairs. This is useful when you need to pass related values together — for example, iterating over users while passing each user's organization ID alongside.

What Are Paired Variables?

A paired variable defines:

An outer source — the primary values (e.g., user IDs)
An inner source — the secondary values (e.g., organization IDs associated with each user)
A pairing mode — how outer and inner values are combined

The result is a set of value pairs where each pair contains one outer value and one inner value. When applied to an endpoint, both values are substituted into their respective parameters for each iteration.

Pairing Modes

Cartesian (Cross Product)

Every outer value is paired with every inner value:

Outer: [A, B]
Inner: [1, 2, 3]

Pairs: (A,1), (A,2), (A,3), (B,1), (B,2), (B,3)

Use when: You need all possible combinations of two independent value sets.

Positional (Zip)

Values are paired by index position:

Outer: [A, B, C]
Inner: [1, 2, 3]

Pairs: (A,1), (B,2), (C,3)

Use when: The two arrays are parallel (same length, matching positions). For example, user IDs and their email addresses from the same API response.

Join

Inner items are matched to outer values using a shared field:

Outer: [user1, user2, user3]  (from users[*].id)
Inner: [{userId: user1, orgId: org-A}, {userId: user2, orgId: org-B}]

Join on: inner.userId === outer value

Pairs: (user1, org-A), (user2, org-B)

Use when: You have two datasets that share a common identifier and need to correlate them.

Nested

For structurally nested data where inner values are children of outer objects:

Response: [
  { id: "team1", members: ["u1", "u2"] },
  { id: "team2", members: ["u3"] }
]

Outer path: [*].id
Inner path: [*].members[*]

Pairs: (team1, u1), (team1, u2), (team2, u3)

Use when: The inner values are nested inside the same objects that provide the outer values (e.g., team IDs with their member IDs).

Creating a Paired Variable

The creation dialog is a 4-step wizard:

Step 1: Outer Source

Choose where outer values come from. The source can be either a source endpoint or an existing variable:

For an endpoint source, choose the JSON path to extract outer values
Preview the extracted values

Step 2: Inner Source

Choose where inner values come from (again, a source endpoint or an existing variable, the same or different from the outer source):

For an endpoint source, choose the JSON path for inner values (an array, or an object's keys/values)
Preview the extracted values

Step 3: Pairing Mode

Select how to combine outer and inner values:

Cartesian: All combinations
Positional: Match by index
Join: Match by field value (requires selecting the join field)
Nested: For structurally nested data

Preview shows the resulting pairs.

Step 4: Configure Variable

Enter a name for the variable
Select the default mode (iterate or first)
Review the pair count and sample pairs

Using Paired Variables

When you apply a paired variable to an endpoint:

The variable creates two mappings — one for the outer value, one for the inner value
Each mapping targets a different parameter on the endpoint
During iteration, both values are substituted together for each pair

Example

Paired Variable: "User-Org Pairs"
  Outer: user IDs from GET /users → users[*].id
  Inner: org IDs from GET /users → users[*].organization_id
  Mode: Positional

Endpoint: GET /orgs/{orgId}/users/{userId}/permissions

For each pair:
  GET /orgs/org-A/users/user1/permissions
  GET /orgs/org-B/users/user2/permissions
  GET /orgs/org-C/users/user3/permissions

Editing Paired Variables

Open the Variables Panel, find the paired variable, and click Edit. You can modify:

Outer and inner sources
Pairing mode
Variable name and default mode

Changes apply to all endpoints using this variable.

Troubleshooting