Server Request

Audience: Low-code Engineers

Skill Prerequisites: Actions, Tokens, HTTP, JSON

Sends an HTTP request to a URL and saves the response in tokens. Use it to call REST APIs, SOAP services, webhooks and other web endpoints from your application.

It supports the GET, HEAD, POST, PUT, PATCH and DELETE methods, custom headers, JSON, XML and form bodies, file uploads, cookies, a proxy and client certificates.

This action replaces Server Request (Obsolete).

note

This action requires the Data Integration feature to be licensed. If it isn't, the action fails with a not-licensed error.

Typical Use Cases

• Call a REST API and read the JSON response
• Send form data or a JSON payload to a webhook or an external system
• Upload files to an API as multipart/form-data
• Call a SOAP service with an XML body
• Call a partner API that requires a client certificate (mutual SSL)

Don't use it to

• Read or write files on the server. Use file actions such as Copy File or Save File to Disk.
• Download a file for the user. Use Download File or Send File for Download.

Related Actions

Action Name	Description
Parse JSON Into Tokens	Turns a JSON response into tokens.
Create List from JSON	Turns a JSON array from a response into a list.
Regex	Extracts values from a text response.
Execute Actions Asynchronously	Runs slow requests in the background.
Server Request (Obsolete)	The older version of this action.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
URL	The address to send the request to, for example https://api.example.com/orders/[OrderId]. Can be absolute or relative to the portal, for example /api/....	Yes	http://example.com	Yes
Url Token Encoding	How token values in the URL are encoded. URL Encoding URL-encodes each token value, which is right for values such as search terms or IDs. No Encoding inserts token values as they are. Use it when a token holds a whole URL or a path with /.	No	URL Encoding	No
Enforce SSL	Rewrites the URL to use https instead of http.	No	false	No
Client Certificate (Enterprise-Only)	The thumbprint of a client certificate for mutual SSL. See Client certificates.	Yes	empty string	No
Timeout	How many seconds to wait for the response. Empty or 0 means 100 seconds.	Yes	100	No
Choose an HTTP Method	GET, HEAD, POST, PUT, PATCH or DELETE.	No	GET	Yes
Data	The request data. Its format depends on the method and the Content-Type header. See How Data is sent.	Yes	Sample lines name=[FirstName] and page=[Tab:TabName]	No
Do not escape tokens in Data	For XML bodies only. By default, token values in Data are XML-escaped so they can't break the XML. Check this when a token holds XML that must be inserted as is.	No	false	No
Files	Files to upload, as rows of form key and file. The file can be a file ID or a path. Only shown for POST, PUT and PATCH.	Yes (both columns)	Empty	No
File Identifiers	A comma or semicolon separated list of file IDs or paths to upload. Each file's form key is its file name, for example invoice.pdf. Only shown for POST, PUT and PATCH.	Yes	empty string	No
Disable Referer Header	By default, a Referer header with the current site address is sent. Some APIs reject it. Check this to leave it out.	No	false	No
Headers	Extra request headers, as rows of name and value, for example Authorization = Bearer [ApiToken].	Yes (both columns)	Empty	No
Use DNN Proxy Settings	Sends the request through the proxy set in the DNN host settings.	No	false	No
Add Current Cookies	Sends the current user's browser cookies with the request.	No	false	No
Ignore Errors	Continues with the next actions when the request fails. On Error still runs.	No	false	No
On Error	Actions to run when the request fails. See Error handling.	No	Empty	No

Output Parameters Reference

Parameter	Description
Output Token Name	The name of the token that receives the response body, for example ApiResponse for [ApiResponse]. It's also filled when the server returns an error status.
Output Headers	Response headers to save, as rows of header name and token name. For a token named Location, you get [Location] (first value), [Location:Csv] (all values, comma separated) and [Location:Json] (all values as a JSON array).
Cookie Container	A name for a cookie container that keeps cookies between requests. Give several Server Request actions the same name to share cookies, for example to log in and then call a protected page.

When Output Token Name is set and the request fails, these tokens are also available in On Error:

Token	Description
[<OutputTokenName>:ErrorCode]	The HTTP status code, for example 404. It's 0 if no response was received, for example after a timeout.
[<OutputTokenName>:ErrorResponse]	The response body returned with the error.

How Data is sent

The action picks the body format from the method, the files and the Content-Type header:

Situation	What's sent
GET	Each key=value line in Data is added to the URL's query string. You can also put the query directly in the URL.
DELETE	No body. Data is ignored, so put parameters in the URL.
Files or File Identifiers set	A multipart/form-data body with the files. Each key=value line in Data is added as a text field.
Content-Type contains application/json	Data as is. Token values are inserted without escaping, so a value that contains a double quote or a backslash breaks the JSON. Put quotes around string tokens yourself, for example "name": "[FirstName]", and only use tokens whose values you control, or build the JSON with Context to JSON Object first.
Content-Type contains text/xml, application/xml or application/soap+xml	Data as is. Token values are XML-escaped unless Do not escape tokens in Data is checked.
Anything else	An application/x-www-form-urlencoded body built from the key=value lines. Values are encoded for you, so don't URL-encode them.

In key=value lines, the first = separates the key from the value. Spaces around both are trimmed. A line without = is sent as a key with an empty value.

Error handling

The request fails when it can't be sent, times out, or the server returns a status outside the 2xx range. Then:

1. The response body goes into [<OutputTokenName>], and the error tokens are set.
2. The On Error actions run. If one of them ends execution, for example Display Error Message, that's the result.
3. Otherwise, if Ignore Errors is checked, the next actions run. If not, the action fails. Administrators see the error and the URL. Other users see Server request to the following URL failed: followed by the URL.

[<OutputTokenName>:ErrorResponse] is removed after On Error runs. [<OutputTokenName>:ErrorCode] stays.

Some problems happen before the request is sent and fail the action straight away, without On Error or Ignore Errors. For example, a client certificate or upload file that can't be found, or a relative URL when there's no portal context.

Client certificates

Use Client Certificate when the API requires your server to identify itself with a certificate (mutual SSL):

1. Import the certificate, with its private key, into the Local Machine certificate store of the web server.
2. Make sure the IIS application pool identity can read the private key.
3. Copy the certificate's thumbprint into Client Certificate. Spaces and hidden characters are removed automatically.

Only valid certificates are found. If no match is found, the action fails with Certificate with thumbprint ... could not be found.

Considerations

• Clear the sample Data. Data starts with sample lines. With GET, they're added to the query string, so delete them if you don't need them.
• Set Content-Type for JSON and XML. Without a Content-Type header, Data is sent as form data.
• Portal context. Relative URLs and the Referer header need a portal, such as in forms or Automation. Relative URLs are resolved against the portal's default alias using http, so check Enforce SSL if the site only accepts https. Where there's no portal, use an absolute URL and check Disable Referer Header.
• Tokens in the URL. With URL Encoding, a token holding a full URL such as https://api.example.com is encoded and won't work. Use No Encoding in that case.
• Content headers aren't returned. Output Headers reads response headers such as Location or ETag. Content headers such as Content-Type and Content-Length aren't available.
• Output headers and cookies are saved only on success.
• Keep secrets out of the action. Put API keys and passwords in tokens, for example [ApiToken], not as plain text.
• Parse the response. The response is saved as text. Use Parse JSON Into Tokens to read values from JSON.
• TLS 1.2 is used for https requests. Gzip and deflate responses are decompressed automatically.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Get a record from a REST API

This action gets an order and saves the JSON response in [OrderResponse]. The Data lines are added to the query string, so the URL becomes https://api.example.com/orders/[OrderId]?include=items.

{
    "Title": "Server Request",
    "ActionType": "ServerRequestHttpClient",
    "Description": "Get an order from the API",
    "Parameters": {
        "URL": "https://api.example.com/orders/[OrderId]",
        "UrlTokenContext": "Url",
        "HttpMethod": "GET",
        "Data": "include=items",
        "Headers": [
            {
                "name": "Authorization",
                "value": "Bearer [ApiToken]"
            },
            {
                "name": "Accept",
                "value": "application/json"
            }
        ],
        "OutputTokenName": "OrderResponse"
    }
}

2. Post JSON and handle errors

This action creates a customer by posting JSON. The new record's address is saved from the Location header. If the API returns an error, On Error logs the status code and the response, and Ignore Errors lets the next actions run.

{
    "Title": "Server Request",
    "ActionType": "ServerRequestHttpClient",
    "Description": "Create a customer in the CRM",
    "Parameters": {
        "URL": "https://api.example.com/customers",
        "HttpMethod": "POST",
        "Timeout": "30",
        "Headers": [
            {
                "name": "Content-Type",
                "value": "application/json"
            },
            {
                "name": "Authorization",
                "value": "Bearer [ApiToken]"
            }
        ],
        "Data": "{\n    \"firstName\": \"[FirstName]\",\n    \"lastName\": \"[LastName]\",\n    \"email\": \"[Email]\"\n}",
        "OutputTokenName": "CustomerResponse",
        "OutputHeaders": [
            {
                "name": "Location",
                "value": "CustomerUrl"
            }
        ],
        "IgnoreErrors": true,
        "OnError": [
            {
                "Title": "Log Error",
                "ActionType": "LogError",
                "Parameters": {
                    "Message": "Create customer failed with status [CustomerResponse:ErrorCode]: [CustomerResponse:ErrorResponse]"
                }
            }
        ]
    }
}

3. Upload a file with form fields

This action uploads the file in [InvoiceFileId] under the form key document, together with two text fields. The body is sent as multipart/form-data.

{
    "Title": "Server Request",
    "ActionType": "ServerRequestHttpClient",
    "Description": "Upload an invoice",
    "Parameters": {
        "URL": "https://api.example.com/documents",
        "HttpMethod": "POST",
        "Headers": [
            {
                "name": "Authorization",
                "value": "Bearer [ApiToken]"
            }
        ],
        "Data": "customerId=[CustomerId]\ndescription=Invoice [InvoiceNumber]",
        "FormFiles": [
            {
                "name": "document",
                "value": "[InvoiceFileId]"
            }
        ],
        "OutputTokenName": "UploadResponse"
    }
}

Revised 09/26/2026