How-to

Pre-checks

Run external API validations before placing a call — DND checks, balance verification, and custom gates.

Overview

Pre-checks are validation steps executed before a call is placed. Each pre-check hits an external API and decides whether the call should proceed based on the response. Pre-checks are configured on the CallExecutionConfig via the pre_checks array.

If any pre-check returns a “skip” decision, the lead is marked status=FINISHED, outcome=PRECHECK_FAILED and no call is placed. The failure reason is recorded in metaData.pre_check_results.

PreCheckConfig

Field	Type	Required	Description
`type`	`string`	Yes	Currently only `"external_api"`.
`name`	`string`	Yes	Human-readable name for logging (e.g. `"DND Check"`).
`enabled`	`bool`	No	Defaults to `true`. Set `false` to skip this check without removing it.
`credential_id`	`string`	No	UUID of a stored credential used to resolve placeholders in `http_request`.
`http_request`	`PreCheckHttpRequest`	Yes	The HTTP request to execute.
`response_config`	`PreCheckResponseConfig`	Yes	How to interpret the response to decide proceed vs. skip.
`default_on_failure`	`string`	No	Behaviour when the API call fails: `"proceed"` (default, fail-open) or `"skip"` (fail-closed).

PreCheckHttpRequest

Matches the generic HttpRequestConfig used elsewhere in the platform.

Field	Type	Default	Description
`url`	`string`	—	URL. Supports `{placeholder}` substitution from payload + credentials.
`method`	`string`	`"GET"`	HTTP method.
`headers`	`object`	—	Request headers.
`body`	`object`	—	Request body (typically for POST).
`auth`	`object`	—	Optional auth descriptor.
`query_params`	`object`	—	Query-string params.
`timeout`	`int` (1–30)	`10`	Request timeout in seconds.
`max_retries`	`int` (1–5)	`2`	Retry count on transient failure.

PreCheckResponseConfig

Controls how the API response is evaluated.

Field	Type	Description
`response_field`	`string`	JSON path to the field to compare in the response (e.g. `"blocked"` or `"data.is_dnd"`).
`response_field_value`	`any`	The value that signals proceed.

Semantics are proceed-on-match, not skip-on-match

The call proceeds when the response field equals response_field_value. Otherwise the call is skipped. This is the opposite of what the name suggests — think of it as “expected OK value”. If you want “skip when DND=true”, configure response_field_value: false against a field that indicates DND status.

Failure behaviour

default_on_failure controls what happens when the external API is unreachable, times out, or returns a non-2xx:

Value	Behaviour	Pattern
`proceed`	Continue with the call even if the pre-check fails.	Fail-open (default).
`skip`	Skip the call when the pre-check cannot complete.	Fail-closed.

Pick skip when missing a pre-check is worse than missing the call — regulated industries, compliance gates, credit checks. Pick proceed when availability matters more — most marketing-style campaigns.

Use case: DND check

A common pre-check verifies that a phone number is not on a Do Not Disturb registry. The external API returns {"blocked": false} for callable numbers and {"blocked": true} for DND’d numbers. We want to proceed only when blocked=false.

pre-check-dnd.json

json

{
  "pre_checks": [
    {
      "type": "external_api",
      "name": "DND Check",
      "enabled": true,
      "credential_id": "cred_dnd_provider",
      "http_request": {
        "url": "https://dnd-api.example.com/check?phone={customer_mobile_number}",
        "method": "GET",
        "headers": {
          "Authorization": "Bearer {dnd_api_key}"
        },
        "timeout": 5,
        "max_retries": 2
      },
      "response_config": {
        "response_field": "blocked",
        "response_field_value": false
      },
      "default_on_failure": "proceed"
    }
  ]
}

Variable substitution

Pre-check HTTP requests support variable substitution from the lead payload and the resolved credential secrets. {customer_mobile_number} is the standard destination key; custom payload fields and credential secrets work the same way.

Multiple pre-checks

Pre-checks are evaluated sequentially. The first one that decides “skip” short-circuits — subsequent checks are not run. Ordering matters when later checks depend on earlier ones being green.

What the lead looks like after a skipped pre-check

status: FINISHED
outcome: PRECHECK_FAILED
metaData.pre_check_results: array of per-check outcomes with name, status, and optional reason.

Leads with outcome=PRECHECK_FAILED are still visible in the dashboard and analytics; they do not dial again unless re-pushed.

Next steps

Call execution config Where pre-check settings live.Leads API Inspect PRECHECK_FAILED outcomes.Webhooks Observe pre-check outcomes in real time.

Was this helpful?

Edit on GitHub