Calling an HTTP API

getdialed__http__request sends one HTTPS request and puts the response into your flow. You choose the method, the address, the headers, the query parameters and the body. You authenticate by selecting a stored credential, which the platform applies to the request for you.

{
  "task_id": "task_fetch_contact",
  "task_name": "Fetch the contact record",
  "platform_id": "getdialed",
  "service_id": "getdialed__http",
  "action_id": "getdialed__http__request",
  "connection_id": "cred_e5f6g7h8",
  "parameters": {
    "method": "GET",
    "url": "https://api.example.com/v2/contacts",
    "query": { "email": "{{ input.email }}" }
  }
}

The step reports status, headers and body — see the response.

When to reach for it

This is the long-tail fallback. Where a provider has purpose-built steps, use those: they know the provider’s quirks, they are paced against that provider’s published rate budget, and they report per-row outcomes. Browse them in the catalog. Reach for this step when the endpoint you need has no purpose-built action — an internal-facing SaaS API, a customer’s own service, a provider nobody has integrated yet. It is one request per step, not one per record: if you need a request per row, put this step inside a flow that the platform already runs per record.

Because the platform cannot know the rate limits of an address you typed, requests from this step are not rate-paced by GetDialed. Respecting the provider’s own limits is yours to arrange — space the work out with schedules, or reduce the set first with a record transform.

Authentication is selection, never a pasted secret

The step never names a header and never holds a token. It carries a connection_id — the id of a credential — and the platform applies that credential to the request when it runs. The consequence is worth stating plainly, because the first instinct is to reach for a header:

Authorization, Proxy-Authorization and Cookie cannot be set in headers at all — not as literal text, not as a template, not from an account variable. Neither can the header or query parameter that your selected credential injects into. All of them are refused when you save the flow, not when it runs.There is no way around this and it is not a gap. Authentication reaches the request by credential selection and by no other route, which is what keeps a secret out of the flow definition, out of the API responses that return it, and out of every run record.

Every other header name is yours, and a header value may use variables and expressions freely:

{
  "action_id": "getdialed__http__request",
  "parameters": {
    "method": "GET",
    "url": "https://api.example.com/v2/contacts",
    "headers": {
      "Accept": "application/json",
      "X-Correlation-Id": "{{ input.trace_id }}"
    }
  }
}

Where the key goes is declared once, on the credential — a header name with an optional scheme, or a query-parameter name — so every step using that credential authenticates identically. See declaring where an API key goes.

The credential is optional

A public API that needs no authentication needs no credential. Leave connection_id off and the request goes out unauthenticated. This is the one action where a missing credential is a legitimate configuration rather than a 422 — but a credential you do supply is still checked for compatibility when you save.

The address

Two rules, and the second reads stricter than it is. Only https is accepted. A plain http:// address is refused when you save, and refused again if one is ever reached at run time. A credential sent over an unencrypted connection is exposed by definition, so there is no carve-out — not for an unauthenticated call, not for a host on your own network. Any port may be named (https://api.example.com:8443/v2/orders is fine). The scheme, host and port must be written out literally. They cannot come from a variable, an earlier step or a record field. That is what makes a saved flow auditable: reading it tells you every address it can reach. The path and the query string may template freely — which is what makes pagination and per-record resource ids work:

{
  "action_id": "getdialed__http__request",
  "parameters": {
    "method": "GET",
    "url": "https://api.example.com/v2/contacts/{{ input.contact_id }}/notes",
    "query": {
      "since": "{{ step_previous.output.body.cursor }}",
      "per_page": "100"
    }
  }
}

A user name or password written into the address itself (https://user:pass@host/) is refused — that is a pasted secret wearing a different hat.

Query and header names must be literal too, for the same auditability reason. A templated name ({ "{{ input.header_name }}": "..." }) and a wholesale-templated headers object are both refused when you save, because a name that cannot be read off the definition cannot be checked against the names a credential claims. Values template freely in both.

What can be reached, and what cannot

Any address on the public internet may be called. There is no allow-list to maintain and no request to file before pointing a flow at a new provider. An address that resolves into private space is refused before anything is sent. That covers private ranges, loopback, link-local, unique-local, carrier-grade NAT, multicast and reserved space, over both IPv4 and IPv6. The check runs on the address the hostname actually resolves to, and the connection is then pinned to that address — so a name that resolves to something public during the check and something internal a moment later still cannot be reached. Every redirect is re-checked the same way, on every hop. The reason is short: a step that can call any address is a door into the platform’s own network unless that door is closed, so it is closed. An endpoint inside your network, or inside ours, is not reachable from a flow.

An address refusal does not tell you what the address resolved to, and every address refusal reports the same reason. That is deliberate rather than unhelpful: a message that distinguished “that host does not exist” from “that host resolves to something internal” would be a network scanner with an audit trail. If a call you expect to work is refused, check the address from outside — the answer is in DNS, not in the message.

Two things that are deliberately absent

There is no option to skip certificate verification, and no option to route through a proxy. Neither is missing by accident and neither will be added on request.A toggle that turned off certificate checking would make the encryption the https-only rule exists to guarantee decorative, and a proxy setting is an address the private-space check cannot see past. If your endpoint presents a certificate that does not validate, the fix is on the endpoint. If it is only reachable privately, a flow is the wrong caller for it — the mechanism you need is a different one, not a setting on this step.

The response

The step reports three things:

Output	What it holds
`status`	The HTTP status code, always — whether the step succeeded or was configured not to fail on an error status. This is the thing to branch on.
`headers`	The response headers as name/value pairs, with names in lower case. Where a pagination cursor, a rate-limit budget or a `location` comes back. Repeated fields are joined with `,` .
`body`	The parsed body. Empty when the response had none — a `204` and most `DELETE` responses.

Read them like any other step output:

{{ step_call.output.status }}
{{ step_call.output.headers.link }}
{{ step_call.output.body.id }}

How the body is parsed

The body is parsed from the response’s own content type. Names are matched on the media type alone, so application/json; charset=utf-8 and APPLICATION/JSON take the same path.

Content type	You get
`application/json`, and any `+json` suffix (`application/vnd.api+json`, `application/problem+json`)	A value you can read field by field.
`application/x-www-form-urlencoded`	A flat set of keys. A key sent once is a single value; a key sent more than once is a list, in the order it arrived.
`application/xml`, `text/xml`, and any `+xml` suffix	A flat set of keys, with nested elements named using dots (`contact.email`) — the same convention the XML parse step uses.
`text/csv`	Text, deliberately. Rows belong in a record set, not in flow context: a record set is paged and referenced by id, while a parsed CSV in flow context is every row inside one step result. Pass the text to `getdialed__records__parse_csv`, which produces a set.
`text/*`, and anything else including an absent content type	Text.

A parse failure falls back to the text. If a provider claims JSON and returns an HTML error page, you get the page as text and the step carries on — you can look at what actually arrived and pipe it, rather than losing the step to somebody else’s header.

Responses that are refused

A response that is not text is refused, not mangled. A file, an image, a PDF, a multipart/form-data body — the step fails with a reason naming the content type and the byte count, and nothing from the body is repeated.A response that declares a non-UTF-8 character set — iso-8859-1 is the common one — is refused the same way rather than decoded according to that declaration. Today the step reads UTF-8 and only UTF-8.The alternative would be to decode with replacement characters, which produces a string of question marks that looks exactly like a successful parse everywhere downstream. A step that needs the bytes of a response is waiting on file and object storage; until then, call an endpoint that returns JSON, XML, a form encoding or text.

The limits

Limit	Value
Response body	131,072 bytes (128 KiB), measured after decompression
Response headers	8,192 bytes (8 KiB) for the whole set
Request body	1,048,576 bytes (1 MB)
Timeout	30 seconds by default, 60 seconds at most
Redirects followed	5 hops

Every one of these is a refusal, never a truncation. A response over the body cap fails the step — it is not clipped to fit, and the read is abandoned partway rather than completed and then measured. A timeout_seconds above 60 is refused rather than quietly reduced to 60.Both choices are for the same reason. A silently clipped response produces flow context that looks complete to every step after it, and nothing downstream can tell a half-read response from a whole one. A step that appeared to accept a five-minute timeout and did not honour it is worse than one that told you it could not.

The 60-second ceiling exists so that a slow provider produces a clear failure from this step, naming the timeout, rather than an unexplained platform timeout further out with nothing in it to act on. To work with a response larger than the cap, ask the provider for less of it: page it, filter it server-side, or request fewer fields.

When the status is not 2xx

Any status outside 200–299 fails the step by default. The failure names the status code.

The response body is never included in a failure message, and this is not a bug to report. A failure is read in logs and stored in run records, both of which outlive whatever retention rule governed the payload — and a provider’s error body routinely quotes the request that caused it, including the parts a credential was applied to. If you need to see an error body, use fail_on_error_status below and read body as data.

Set fail_on_error_status to false when the status is information you want. The step then succeeds, and status and body are both available to branch on — which is what a “404 means no such record” flow needs:

{
  "step_id": "step_lookup",
  "tasks": [
    {
      "task_id": "task_lookup",
      "task_name": "Look the contact up",
      "platform_id": "getdialed",
      "service_id": "getdialed__http",
      "action_id": "getdialed__http__request",
      "connection_id": "cred_e5f6g7h8",
      "parameters": {
        "method": "GET",
        "url": "https://api.example.com/v2/contacts/{{ input.contact_id }}",
        "fail_on_error_status": false
      }
    }
  ],
  "exit_conditions": [
    {
      "condition": "{{ step_lookup.output.status }} == 404",
      "action": "skip_next_step",
      "reason": "No such contact — nothing to update"
    }
  ]
}

Sending a body

body is text, and body_format says how to label and interpret it:

`body_format`	Sent as	Build it with
`json` (the default)	`application/json`	An expression and the `jsonEncode` pipe, so quoting and escaping are handled for you
`form`	`application/x-www-form-urlencoded`	The `urlEncode` pipe
`raw`	`text/plain`, exactly as given	Whatever the endpoint wants

Set content_type to override the label without changing how the body is built — for a vendor JSON variant, or a versioned media type.

Redirects and retries

Redirects are followed up to 5 hops. Each hop’s address is resolved and checked again, so a redirect toward private space is refused exactly like a first request would be. A chain longer than 5 hops fails rather than being followed further.

Your credential is dropped the moment a redirect leaves the address it was issued for. Scheme, host and port together decide that — a hop to the same hostname on a different port is a different service, and the credential does not follow it. Once dropped it stays dropped for the rest of the chain.If a provider redirects the authenticated part of its API to another host, call the final address directly. A step that silently handed your provider’s secret to whatever host a redirect named would be the more convenient behaviour and the wrong one.

Retry safety is decided by the method. GET, HEAD, PUT and DELETE are safe to repeat by definition, so a transient network failure on one is retried. POST and PATCH are attempted once: a repeated POST can charge a card, send a message or enrol somebody twice. Set idempotent to true to allow a POST or PATCH to be retried — but only if the endpoint takes an idempotency key and you are sending one. That key is what makes the repeat safe; the setting on its own only removes the protection.

What is refused when you save

These are caught when the flow is saved, so you never discover them at 2 a.m. from a run. Each is a 422 naming the field and the step, and none of them echoes the value:

Refused	Because
A `url` that is not `https`	Cleartext exposes a credential by definition
A templated scheme, host or port in `url`	A saved flow must state every address it can reach
A user name or password inside `url`	That is a pasted secret
`Authorization`, `Proxy-Authorization` or `Cookie` in `headers`	Authentication comes from selecting a credential
A header or query name your selected credential injects into	Same reason — and the set depends on which credential you picked
A templated header or query name, or a `headers`/`query` value that is not a set of pairs	A name that cannot be read cannot be checked
A credential that is not compatible with the step	Caught at save rather than at run

Next steps

Credentials

Create the credential this step selects, and declare where its key goes.

Expressions

The templates and pipes that build a path, a query and a body.

Integration catalog

The purpose-built steps to prefer where they exist, and this step’s full parameter reference.

Record transforms

Turn a text response into a record set, and reduce a set before calling per record.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

When to reach for it

Authentication is selection, never a pasted secret

The credential is optional

The address

What can be reached, and what cannot

Two things that are deliberately absent

The response

How the body is parsed

Responses that are refused

The limits

When the status is not 2xx

Sending a body

Redirects and retries

What is refused when you save

Next steps

Credentials

Expressions

Integration catalog

Record transforms

​When to reach for it

​Authentication is selection, never a pasted secret

​The credential is optional

​The address

​What can be reached, and what cannot

​Two things that are deliberately absent

​The response

​How the body is parsed

​Responses that are refused

​The limits

​When the status is not 2xx

​Sending a body

​Redirects and retries

​What is refused when you save

​Next steps

Credentials

Expressions

Integration catalog

Record transforms

When to reach for it

Authentication is selection, never a pasted secret

The credential is optional

The address

What can be reached, and what cannot

Two things that are deliberately absent

The response

How the body is parsed

Responses that are refused

The limits

When the status is not 2xx

Sending a body

Redirects and retries

What is refused when you save

Next steps