Build dynamic query strings for REST API calls in Jitterbit Studio

Introduction

The HTTP v2 connector's Request Parameters UI handles the most common case: a fixed set of parameter names whose values change at runtime. The connector URL-encodes the values automatically. For an introduction to this approach, see Call a REST API using the HTTP v2 connector.

Script-based query string construction is needed when:

• Parameters are included or excluded conditionally based on source data (for example, adding a status filter only when a status value is present).
• Parameter names vary at runtime (for example, filter[contact_type] for one record type and filter[account_type] for another).
• The full URL is assembled from multiple data-driven parts.

This guide covers three techniques for building query strings in script: string concatenation for conditional parameter sets, Replace for fixed-template substitution, and URLEncode for encoding values that contain special characters.

Construct a query string using string concatenation

The basic pattern is:

1. A Script step that runs before the HTTP v2 GET activity builds the URL and assigns it to a global variable.
2. The GET activity's Path field references that global variable.

The operation structure is:

Fixed parameter structure with dynamic names

When the parameter set depends on a runtime condition (such as a record type that determines which filters apply), use an If statement to build the appropriate URL for each case:

// Record type determines which filter parameters apply
If($record_type == "contact",
    $query_url = "/records?type=contact&owner=" & URLEncode($owner_email),
    // Else: account record
    $query_url = "/records?type=account&region=" & URLEncode($region)
);

Optional parameters

When any combination of parameters may or may not be present, build a params string by appending each parameter only when it has a value. Using a leading & prefix on each parameter avoids a trailing separator:

$params = "";
If($start_date != "",
    $params = $params & "&created_after=" & URLEncode($start_date)
);
If($status != "",
    $params = $params & "&status=" & URLEncode($status)
);
If($owner_email != "",
    $params = $params & "&owner=" & URLEncode($owner_email)
);

// Append the query string only when at least one parameter was set.
// Mid(string, 2) strips the leading & from the first parameter.
If($params != "",
    $query_url = "/records?" & Mid($params, 2),
    $query_url = "/records"
);

Mid with a start position of 2 returns the string from the second character onward, removing the leading & left by the first appended parameter. The If check guards the empty case: when no parameters are set, query_url is /records with no trailing ?.

Substitute values using Replace

When the URL structure is fixed and only specific values change, a template string with named placeholders can be cleaner than concatenation. Define the full query string once, then call Replace once per placeholder:

$template = "/contacts?status={status}&created_after={date}&owner={owner}";
$query_url = Replace($template, "{status}", URLEncode($filter_status));
$query_url = Replace($query_url, "{date}",  URLEncode($filter_date));
$query_url = Replace($query_url, "{owner}", URLEncode($owner_email));

Replace substitutes the first matching occurrence of the search string. Reassign query_url on each call to chain the replacements. Choose placeholder names that do not appear elsewhere in the URL (for example, avoid {id} if the path already contains {id} as an HTTP v2 path parameter).

Encode parameter values using URLEncode

When constructing URLs in script, call URLEncode on each parameter value. Without encoding, values that contain reserved characters silently break the request:

• A space character splits the URL at the HTTP layer: the server receives a truncated or malformed parameter and typically returns a 400 error or no results.
• An & inside a value is interpreted as a parameter separator, splitting the value into two separate parameters.
• Other characters that require encoding include #, %, =, +, and ?.

The following table shows common examples:

Do not encode the parameter name, only the value. Parameter names in REST APIs are conventionally ASCII and do not require encoding.

Reference the query string in an HTTP v2 activity

In the GET activity's Path field, enter the global variable that holds the constructed URL (for example, query_url).

The Path field follows these rules:

• A value beginning with https:// or http:// is treated as a complete URL and overrides the Base URL from the connection.
• A value beginning with / is treated as a path suffix and is appended to the Base URL.

Use a path suffix (starting with /) when the base domain and connection credentials are shared with other activities. Use a full URL override when the target endpoint is on a different host than the Base URL, or when no connection Base URL is set.

Verify the integration

1. Deploy and run the operation.

2. Open the operation log and confirm that the GET activity completed with a successful status code.

3. To inspect the exact URL sent, add a WriteToOperationLog call at the end of the pre-operation script:

   WriteToOperationLog("query_url: " & $query_url);
   

   The constructed URL appears in the operation log entry for the script step. Remove the log statement after confirming the URL is correct.

4. If the API returns unexpected results or a 400 error, confirm that URLEncode is applied to all values that may contain spaces or special characters. A missing URLEncode call on a value containing & or = is a common source of silent failures.