Workflows

Workflows chain enrichment lookups into an automated pipeline. A trigger starts a run, each step enriches or reshapes the data, and an export step sends the result where you need it.

Building a workflow is a dashboard operation. Creating, updating, running, cancelling, uploading files, templates, and integrations are all available at app.encrata.com only. On https://developer.encrata.com they return 404.An API key can read workflows and runs: GET /api/workflows, GET /api/workflows/{id}, GET /api/workflows/runs, GET /api/workflows/runs/{id}, plus DELETE on the last two.To trigger a workflow from code, give it a webhook trigger and post to its ingest URL. The examples below that use https://api.encrata.com need a dashboard session, not an API key.

Concepts

Concept	Description
Workflow	A reusable automation with a trigger and a sequence of steps
Trigger	What starts a run: `manual`, `webhook`, `schedule`, `file_upload`, or `monitor_event`
Step	An action in the pipeline: a lookup, condition, delay, webhook, transform, or export
Run	A single execution of a workflow, with input data and step results
Integration	A connected app (HubSpot, Salesforce, Google Sheets, and more) an export step writes to
Template	A pre-built workflow whose steps you can copy into a new one

Step types

Type	Description
`email_lookup`	Look up an email (`mode`: `validity`, `identity`, `breaches`, or `password-breaches`)
`condition`	Branch on a previous step’s output (if/else)
`delay`	Wait a set duration before continuing
`webhook`	Send an HTTP request to an external URL
`transform`	Map or reshape data between steps
`export`	Send enriched results to CSV, a webhook, or a connected app

Trigger types

Type	Description
`manual`	Triggered via the API or a dashboard button
`webhook`	Triggered by an incoming HTTP POST to a unique ingest URL
`schedule`	Runs on a cron schedule
`file_upload`	Triggered when a file is uploaded
`monitor_event`	Triggered when a monitor detects a change

Build a workflow

Create the workflow

Define a trigger and an ordered list of steps. Reference earlier data with {{trigger.<field>}} and {{steps.<id>.result.<path>}} templates. New workflows start as draft - activate them before they run.

curl -X POST "https://api.encrata.com/api/workflows" \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enrich new leads",
    "trigger": { "type": "webhook" },
    "steps": [
      { "id": "1", "type": "email_lookup", "config": { "input": "{{trigger.email}}", "mode": "validity" } },
      { "id": "2", "type": "condition", "config": { "field": "steps.1.result.status", "operator": "equals", "value": "valid" } },
      { "id": "3", "type": "email_lookup", "config": { "input": "{{trigger.email}}", "mode": "identity" } },
      { "id": "4", "type": "export", "config": { "provider": "webhook", "url": "https://hooks.example.com/new-lead" } }
    ]
  }'

See Create workflow for every field.

Run it

Post the trigger fields at the top level of the body - the whole body becomes the run’s trigger_data, so {{trigger.email}} only resolves if email is a top-level key. Pass an Idempotency-Key so a retry never creates a duplicate run.

curl -X POST "https://api.encrata.com/api/workflows/6f1c2e94-2b6a-4a1e-9b3a-6c9f0f2a1d77/run" \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@company.com" }'

The run starts as pending. Runs are capped at 60 per minute per user.

Read the result

Fetch the run to see per-step output, timing, and status. This one does work with an API key.

curl "https://developer.encrata.com/api/workflows/runs/d4e5f6a1-7b8c-4d9e-8f10-1a2b3c4d5e6f" \
  -H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

The response is { "run": {...}, "steps": [...] }. A finished run reports status: "completed".

Version history and the audit trail of who created, changed, and ran each workflow are available in the dashboard.

Manage workflows and runs

Full request and response schemas live in the API reference:

List, get, and delete workflows with an API key.

Runs

List runs and read a run with an API key.

Templates

Browse pre-built step sequences. Dashboard-only.

Run a workflow

Trigger manually, or via a public webhook ingest token.

Bulk enrichment from a file

Upload a list of identifiers (emails, one per row in .csv, .txt, .md, .xls, .xlsx, .docx, or .pdf; max 32 MiB) and the workflow enriches every row, then produces a downloadable CSV of the results. This reuses the same lookup steps as a single run.

File upload and download are dashboard operations. With an API key, use Bulk operations instead.

Upload a file

POST /api/workflows/files

Send the file as multipart form data in the file field. The response includes an id, the detected row_count, and the identifier_type. Uploads are capped at 10 per minute.

curl -X POST "https://api.encrata.com/api/workflows/files" \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -F "file=@leads.csv"

Run over every row

Trigger the run with the returned file id in a file_ids array. The worker enriches each row, charges credits per row (cache hits are free), and writes a CSV.

curl -X POST "https://api.encrata.com/api/workflows/6f1c2e94-2b6a-4a1e-9b3a-6c9f0f2a1d77/run" \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "file_ids": ["8c2d4e71-33a9-4f60-9c1b-7e5f0a2b4c88"] }'

Download the result

Once the run reports status: "completed", the CSV is available from the Runs page or via:

GET /api/workflows/runs/{id}/download

This redirects to a presigned link, valid for 1 hour, to the generated CSV.

Export destinations

The export step sends enriched records to a destination. Set config.provider to one of:

Provider	Description
`csv`	Save results as a downloadable CSV (default for bulk runs)
`webhook`	Deliver each record to an inbound webhook (Zapier, Make, or any CRM)
`nango`	Write to a connected app (HubSpot, Salesforce, Google Sheets, and more)

Field mapping is optional. Leave it empty to write all enriched columns automatically, or map specific fields with {{path}} templates, for example {{steps.email_lookup.result.company}}. For CRMs, mapped fields become record properties. Webhook example:

{
  "id": "step_export",
  "type": "export",
  "config": {
    "provider": "webhook",
    "url": "https://hooks.zapier.com/...",
    "batch_size": 50
  }
}

Authenticating webhook deliveries

Workflow webhook and export (provider webhook) steps send a plain HTTP POST by default, with no signature. This is intentional so they can deliver to Zapier, Make, or any inbound webhook that does not verify a signature. If your receiver verifies authenticity, note that these are a different sender from platform webhooks (configured in Settings, Webhooks), which always sign their deliveries. A receiver that requires a valid X-Encrata-Signature will reject an unsigned workflow delivery with 401. You have two ways to authenticate the workflow delivery:

Signing secret (recommended). Set config.secret on the step. Encrata then signs the request body with an X-Encrata-Signature header (HMAC-SHA256 hex), the same scheme as platform webhooks, so your existing signature-verification code accepts it unchanged.
Custom header. Add an Authorization: Bearer <token> (or any header) under config.headers and check it on your receiver.

Register the exact final receiver URL — correct host (e.g. www.) and no trailing slash. A mismatch triggers a 307 redirect, and clients that drop the body or Authorization header on redirect will produce a signature/token mismatch and a 401, even when the secret is correct.

{
  "id": "step_export",
  "type": "export",
  "config": {
    "provider": "webhook",
    "url": "https://www.example.com/api/webhooks/encrata",
    "secret": "whsec_your_signing_secret"
  }
}

Register the exact receiver URL, including the www host and no trailing slash. A host or slash redirect returns 307, which Encrata records as a failed delivery.

Connected app example:

{
  "id": "step_export",
  "type": "export",
  "config": {
    "provider": "nango",
    "integration_id": "int_abc123",
    "provider_config_key": "hubspot",
    "connection_id": "conn_xyz789"
  }
}

Integrations

Connect the apps your Export steps write to on the Integrations page in the dashboard. Connections use OAuth with automatic token refresh, and Encrata never stores the third-party credentials. To connect an app, open Integrations, pick an app (for example Google Sheets, HubSpot, or Salesforce), and complete the OAuth flow. The connection then appears as a choice in any Export step’s “Connected app” destination. For Google Sheets, the Export step can create a fresh spreadsheet for you with one click, so there is no spreadsheet ID to copy. See the Workflow Integrations API for the underlying endpoints.

Execution logs

Read detailed per-step timing and output for any run:

GET /api/workflows/logs?run_id={run_id}

Rate limits

Workflow runs are limited to 60 runs per minute per user. Each run retries up to 3 times on transient failures.

Credits

Each lookup step charges credits at that lookup’s standard rate. Non-lookup steps (condition, delay, webhook, transform, export) are free. In a bulk file run, credits are charged per enriched row, and cache hits are free. See Credits.

Next steps

Workflows API: Full request and response schemas for every endpoint.
Bulk operations: Run a single lookup over a large list without building a workflow.
Webhooks: Verify and handle deliveries from export steps.
Integrations: Connect the apps your export steps write to.

Account & team

Run your integration

Use cases

Integrations

AI tools

auth.md

Workflows

Concepts

Step types

Trigger types

Build a workflow

Manage workflows and runs

Workflows

Runs

Templates

Run a workflow

Bulk enrichment from a file

Upload a file

Run over every row

Download the result

Export destinations

Authenticating webhook deliveries

Integrations

Execution logs

Rate limits

Credits

Next steps

​Concepts

​Step types

​Trigger types

​Build a workflow

​Manage workflows and runs

Workflows

Runs

Templates

Run a workflow

​Bulk enrichment from a file

​Upload a file

​Run over every row

​Download the result

​Export destinations

​Authenticating webhook deliveries

​Integrations

​Execution logs

​Rate limits

​Credits

​Next steps

Concepts

Step types

Trigger types

Build a workflow

Manage workflows and runs

Bulk enrichment from a file

Upload a file

Run over every row

Download the result

Export destinations

Authenticating webhook deliveries

Integrations

Execution logs

Rate limits

Credits

Next steps