← Back to documentation

Query Parameters

Configure endpoints to extract and relay data from URL query parameters using raw key-value pairs or Base64-encoded JSON.

6 min read

Use query parameter formats when senders pass data in the URL instead of the request body.

Purpose

This guide covers:

  • Available query parameter formats and when to use each.
  • Supported data types and value parsing.
  • Base64 JSON mode configuration.
  • Feature interactions with field validation, captcha, and relay targets.

Prerequisites and permissions

  • Endpoint create/edit access.
  • Knowledge of how the sender formats outgoing requests.

Available query parameter formats

None (ignore body)

Select None (ignore body) when the endpoint should accept requests without processing any payload. The request body is completely ignored regardless of content type. This is useful for health checks, simple triggers, or fire-and-forget notifications.

Query Parameters

All query parameters from the URL are parsed into a flat JSON object. Each parameter becomes a key-value pair.

Supported value formats:

URL valueParsed asExample
Plain stringString?name=John → {"name": "John"}
NumberString?count=42 → {"count": "42"}
BooleanString?active=true → {"active": "true"}
Multi-valueArray of strings?tag=a&tag=b → {"tag": ["a", "b"]}
Empty / no valueEmpty string?flag= or ?flag → {"flag": ""}
URL-encodedDecoded string?msg=hello%20world → {"msg": "hello world"}

Example request:

Code Example
GET https://api.payloadrelay.com/relay/abc123?name=John&age=30&active=true

Parsed payload sent to relay targets:

Code Example
{
  "name": "John",
  "age": "30",
  "active": "true"
}

Single query parameter values are parsed as strings. Repeated parameters become arrays of strings.

Query Parameters (Base64 JSON)

A single query parameter contains the entire payload as a Base64-encoded JSON string. This allows sending complex structured data (nested objects, arrays, typed values) through query parameters.

How it works:

  1. The sender Base64-encodes a JSON payload.
  2. The encoded string is sent as a single query parameter.
  3. PayloadRelay decodes the Base64 string and parses the resulting JSON.
  4. The parsed JSON is forwarded to all relay targets.

Encoding support: Both standard Base64 and URL-safe Base64 (using - and _ instead of + and /) are accepted. If standard Base64 includes + or /, percent-encoding is safest in URLs; unescaped + is also tolerated for this encoded payload value.

Configuration:

When selecting this format, two additional settings appear:

  • Query parameter name (required, max 255 characters): The name of the URL parameter containing the encoded payload. Spaces, control characters, #, and ? are rejected. URL-special characters such as + or & can be used when the sender percent-encodes the parameter name in the URL.
  • Required parameter (checked by default): When enabled, requests missing this parameter are rejected with a 400 error. When disabled, missing parameters are treated as an empty payload.

Example:

Given query parameter name data:

Original JSON payload:

Code Example
{"name": "John", "age": 30, "items": ["a", "b"]}

Base64-encoded: eyJuYW1lIjoiSm9obiIsImFnZSI6MzAsIml0ZW1zIjpbImEiLCJiIl19

Request URL:

Code Example
GET https://api.payloadrelay.com/relay/abc123?data=eyJuYW1lIjoiSm9obiIsImFnZSI6MzAsIml0ZW1zIjpbImEiLCJiIl19

The decoded JSON is forwarded to relay targets as-is.

Feature interactions

FeatureNoneQuery ParametersBase64 JSON
Field validationDisabledEnabledObject payloads only
CaptchaDisabledDisabledDisabled
Google Sheets fieldspayload onlyAll fieldsAll fields
Email renderingEmpty payloadJSON renderingJSON rendering
Webhook forwardingEmpty bodyJSON bodyJSON body

Field validation

  • None format has no payload to validate — field validation is disabled.
  • Query Parameters always produce a JSON object and support the standard field validation rules (type checks, required fields, regex patterns).
  • Base64 JSON supports field validation when the decoded JSON root is an object. Arrays and scalar JSON values are forwarded to relay targets, but field validation rules cannot be applied to them.

Captcha verification

Captcha verification is not available with any of these formats. Captcha tokens are typically embedded in JSON, form, or XML request bodies.

Google Sheets

  • None format: only the synthetic payload field is supported.
  • Query Parameters and Base64 JSON: all parsed JSON fields are available for column mapping.

Body handling

When None, Query Parameters, or Query Parameters (Base64 JSON) is selected, the request body is completely ignored regardless of method or content type. The endpoint accepts any Content-Type header.

Error handling

ScenarioOutcome
Missing required Base64 parameterMALFORMED_QUERY_PARAM (400)
Invalid Base64 encodingMALFORMED_QUERY_PARAM (400)
Base64 decodes but is not valid JSONMALFORMED_QUERY_PARAM (400)
Base64 JSON exceeds the plan payload size limitPAYLOAD_TOO_LARGE (413)
Query string exceeds the plan payload size limitPAYLOAD_TOO_LARGE (413)
More than 64 query parameter pairsMALFORMED_QUERY_PARAM (400)
No query parameters (Query Params mode)Empty JSON object {} is forwarded
Optional Base64 parameter missingEmpty payload is forwarded

HTTP method compatibility

  • GET and HEAD methods only support None, Query Parameters, and Query Parameters (Base64 JSON).
  • All other methods support all formats including query parameter formats.

Related guides

← Back to documentation