Skip to main content

REST integration — Request

Not yet checked on the product

This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.

The Request tab of the REST integration says where the call goes and how it is sent: the connection, the method, the path and its parameters, query parameters, headers, the timeout, the retries and which statuses count as a success. The request body is built in the Request mapping tab — see Schemas and mapping.

Content statusFrom source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22)

Fields​

FieldWhat it doesRequiredFormat / valuesDefaultValidation messages
ConnectionThe connection the call goes through: base URL, authentication, default headers and maximum timeout. Once chosen, Base URL … · authentication: … shows the connection's address and authentication type. The base URL and the credentials live in the connection, never in the phase. Manage connections opens Connections.YesOne of your company's connectionsChoose a connection (none)Choose a connection. · Could not load the connections. (the list did not load)
MethodThe HTTP methodYesGET, POST, PUT, PATCH, DELETE. GET and DELETE send no body, so the request schema and the Request mapping do not apply to them.POST—
PathAdded to the connection's base URL. Relative to the connection base URL. Each name in curly braces becomes a path parameter. For example /customers/ followed by a name in curly braces creates a path parameter with that name.YesStarts with /; no scheme, host, ? query, # fragment, @, spaces, \, . or .. segments, or encoded slashes; up to 2048 characters. A parameter name starts with a letter or _ and has letters, digits, _ or -.—Fill in the path. · The path must be relative to the connection: no scheme or host. · The path must start with "/" and cannot contain a query (?), a fragment (#), an at sign, spaces, backslashes, "." or ".." segments, or encoded slashes. · A path parameter must be a name in curly braces that starts with a letter or underscore and uses only letters, digits, underscores and hyphens.
Path parametersOne entry per name in curly braces in Path, in order. Entries appear and disappear as you edit the path; they cannot be renamed or removed here. Each entry has a Source and Transforms (see below). The value is URL-encoded before it is placed in the path.One per name in the pathA source, or a first transform that produces a value (constant, concat, coalesce)The path has no parameters.The path parameter … has no rule. · The path parameter … needs a source.
Query parametersAdded to the URL as ?name=value&…, in order. Each has Name, Fixed value (a check box), then either Value (when fixed) or Source and Transforms. Add query parameter adds one; Remove deletes it. An unnamed parameter is titled New parameter. A parameter whose value is empty at run time is left out of the URL.NoUp to 50. Value takes text, a number, true, false or null; wrap it in quotes to force text.No query parameters.Every query parameter needs a name. · The query parameter … needs a source or a fixed value. · The query parameter … looks like a credential: it cannot be set in the phase and is not saved. Use a connection of type API key in the query.
HeadersExtra headers sent with this call. Non-secret headers only. Authentication comes from the connection and cannot be set here. Each has Header name, Header value and Remove; Add header adds one.NoUp to 50; values up to 4096 characters, on one line—Every header needs a name. · The header … cannot be set in the phase: authentication and secrets belong to the connection.
Timeout (seconds)How long one attempt waits for an answer. The connection's timeout is the ceiling: the shorter of the two applies.YesWhole number 1–120, not more than the connection's timeout30The timeout must be between 1 and 120 seconds. · The timeout cannot be longer than the connection's (… seconds).
RetriesHow many times a transient failure is tried again after the first attempt. 0 means no retry.YesWhole number 0–103Retries must be between 0 and 10.
Wait between retries (seconds)The wait before each retry. When the destination answers with a Retry-After longer than this, that wait is used instead, up to 600 seconds.YesWhole number 1–60010The wait between retries must be between 1 and 600 seconds.
Send an Idempotency-Key that stays the same across retriesSends an Idempotency-Key header, the same on every attempt of the same process and phase, so a destination that supports it does not apply the request twice. A correction round of the process sends a new key.—On or offOn—
Success status codesThe statuses that mean the call succeeded. Any other status is classified as described under What happens in a run in REST integration.YesCodes separated by commas or spaces, each between 200 and 299200, 201, 202, 204Enter at least one success status code. · … is not a success status code: success codes must be between 200 and 299.

Below the retry fields, Transient failures (5xx, 408, 429, timeout) are retried up to … times, every … seconds or as the server asks. repeats your settings. Below Success status codes: Success continues the flow; Not found receives lookups that found nothing (see the Result tab); Error receives permanent failures and exhausted retries. An unconnected Not found falls back to Error; with Error unconnected too, the run fails.

Source and transforms of a parameter​

A path or query parameter is filled like a field of the request body, without a target:

  • Source — Search a source path. Typing filters the list (No matching paths when nothing matches); arrow keys move, Enter picks, Escape closes. You can also type a path that is not in the list. The list offers the paths of the Input example and the process data: $form. + a form answer key, $process. + a process key ($process.today always), $doc. + document type + . + field (and the [] form for every document of the type), $run.id, $run.workflowId, $run.tenantId. See Sources in Schemas and mapping.
  • Transforms — applied in order to the value, for example digits_only to strip punctuation from an identifier. No transforms: the value is copied as is. The transforms are described in Schemas and mapping.

A path parameter whose value is missing at run time stops the request before it is sent: the process goes to Error with the kind request_schema. A path parameter whose value is empty, . or .. is refused the same way. A transform that fails on a path or query parameter has the same effect. A query parameter whose value is missing is simply left out.

Names you cannot use​

These names are refused because a credential typed here would be stored in clear in the workflow:

WhereRefused names (any case)
HeadersAuthorization, Proxy-Authorization, Cookie, X-API-Key, Api-Key, Idempotency-Key, and the header that carries the connection's API key
Query parametersapi_key, apikey, api-key, access_token, token, key, password, secret, client_secret, signature, sig

A refused header or query parameter stays visible with its message while you fix it, but it is never saved with the workflow. Put the credential in the connection instead: an API key connection with API key location set to Query string sends the key as a query parameter.

How the request is sent​

  • URL — the connection's base URL, the Path with its parameters filled in, then the query parameters; an API key connection in the query string adds its key last. A request that would leave the connection's host or base path is refused (kind ssrf).
  • Headers, in this order, each replacing an earlier one with the same name: the connection's default headers, the connection's secret headers, the phase's Headers, the authentication of the connection, then Idempotency-Key. Every request asks for application/json.
  • Body — for POST, PUT and PATCH, the JSON object built by the Request mapping, sent as application/json; charset=utf-8. Without mapping rules the body is an empty JSON object.
  • Credentials are decrypted only at the moment of the call and removed from everything the phase keeps: its output, its error excerpt, the test view and the logs.

Common problems​

MessageCauseWhat to do
Could not load the connections.The list of connections did not loadReload the editor; if it persists, contact support.
The connection you need is not in ConnectionIt does not exist yet, or was deletedAsk an administrator to create it in Connections.
The path must be relative to the connection: no scheme or host.Path starts with a scheme such as https: or with //Put the scheme and host in the connection's Base URL; keep only the path here.
The path must start with "/"… in the problem listThe path has no leading /, or carries a query, a fragment or another character the service refusesStart Path with / and move query values to Query parameters.
… is not a success status code…A success code such as 302 or 404Keep only 2xx codes in Success status codes; use Not-found status codes (4xx) in Result for a not-found status.
The timeout cannot be longer than the connection's…Timeout (seconds) is larger than the connection's timeoutLower it, or raise the connection's Timeout (seconds, 1 to 120).
The process waits a long time at the phaseTransient failures are being retriedCheck restCall. node id .error in the process; lower Retries or Wait between retries (seconds) if the wait is too long.

Every message of the REST integration is listed in Messages.

Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation