Workflows

Overview

Workflows let you chain multiple enrichment steps into automated pipelines. Trigger them manually, on a schedule, or via webhook.

Key concepts

Concept	Description
Workflow	A reusable automation with a trigger and a sequence of steps
Trigger	What starts the workflow: `manual`, `webhook`, `schedule`, or `file_upload`
Step	An action in the pipeline: 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	Pre-built workflow you can clone and customize

Step types

Type	Description
`email_lookup`	Enrich an email address
`condition`	Branch logic (if/else based on previous step output)
`delay`	Wait a specified duration before continuing
`webhook`	Send an HTTP request to an external URL
`transform`	Transform or map data between steps
`export`	Send enriched results to a destination: CSV, webhook, or a connected app

Trigger types

Type	Description
`manual`	Triggered via API or 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

API Endpoints

All workflow endpoints are authenticated with your enc_ API key.

List Workflows

GET /api/workflows

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`status`	string	Filter by status: `active`, `paused`, `draft`

Example:

curl "https://developer.encrata.com/api/workflows?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Workflow

POST /api/workflows

Body:

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	No	Human-readable description
`trigger`	object	No	Trigger configuration
`steps`	array	No	Array of step objects
`template_id`	string	No	Clone from a template

Example:

curl -X POST "https://developer.encrata.com/api/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enrich new leads",
    "description": "Look up email, then company, then send to webhook",
    "trigger": { "type": "webhook" },
    "steps": [
      { "id": "step1", "type": "email_lookup", "config": { "field": "email" } },
      { "id": "step2", "type": "company_lookup", "config": { "field": "step1.company" } },
      { "id": "step3", "type": "webhook", "config": { "url": "https://hooks.example.com/new-lead", "method": "POST" } }
    ]
  }'

Get Workflow

GET /api/workflows/{id}

Returns the full workflow definition including trigger, steps, and metadata.

Update Workflow

PUT /api/workflows/{id}

Updates the workflow. A new version is automatically created before the mutation (immutable version history). Body: Same fields as Create.

Delete Workflow

DELETE /api/workflows/{id}

Permanently deletes a workflow and all its run history.

Trigger a Run

POST /api/workflows/{id}/run

Manually trigger a workflow execution. Supports idempotency. Headers:

Header	Description
`Idempotency-Key`	Optional. Prevents duplicate runs if retried.

Body:

Field	Type	Description
`input`	object	Input data passed to the first step

Example:

curl -X POST "https://developer.encrata.com/api/workflows/wf_abc123/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "email": "jane@company.com" } }'

Version History

GET /api/workflows/{id}/versions

Returns all immutable versions of a workflow (created automatically on each update).

Audit Log

GET /api/workflows/{id}/audit

Returns the audit trail for a workflow (who created, updated, ran it and when).

Webhook Token

GET /api/workflows/{id}/webhook-token
POST /api/workflows/{id}/webhook-token

Get or create a public ingest token. The token enables triggering the workflow via:

POST /api/workflows/ingest/{token}

This public endpoint requires no JWT, so anyone with the token can trigger the workflow.

Runs

List All Runs

GET /api/workflows/runs

Query parameters:

Parameter	Type	Description
`page`	integer	Page number
`limit`	integer	Items per page
`workflow_id`	string	Filter by specific workflow

Get Run Detail

GET /api/workflows/runs/{id}

Returns the run with step-by-step results, timing, and status.

Cancel a Run

POST /api/workflows/runs/{id}/cancel

Cancels a currently executing run.

Delete a Run

DELETE /api/workflows/runs/{id}

Deletes a completed or failed run.

Templates

List Templates

GET /api/workflows/templates

Query parameters:

Parameter	Type	Description
`category`	string	Filter by category

Returns pre-built workflow templates you can clone using template_id in the Create endpoint.

Bulk enrichment from a file

Upload a list of identifiers (emails, one per row in CSV, TXT, MD, XLS, XLSX, DOCX, or PDF; max 60MB) and the workflow enriches every row, then produces a downloadable CSV of the results. This reuses the same lookup steps as a single run.

Upload a file

POST /api/workflows/files

Send the file as multipart form data in the file field. The response includes a file_id, the detected row_count, and the identifier_type.

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

Run over every row

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

curl -X POST "https://developer.encrata.com/api/workflows/wf_abc123/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_id": "file_xyz789" }'

Download the result

Once the run completes, the CSV is available from the Runs page or via:

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

This redirects to a short-lived link 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"
  }
}

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

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

Returns detailed execution logs for a specific run, including per-step timing and outputs.

Rate Limits

Workflow runs are rate-limited to 60 runs per minute per user. Each run has a retry budget of 3 attempts on transient failures.

Credits

Each enrichment step in a workflow consumes credits at the same rate as the corresponding standalone API call. Non-enrichment steps (condition, delay, webhook, transform, export) are free. In a bulk file run, credits are charged per enriched row, and cache hits are free.

Get set up

Run your integration

Examples

Integrations

AI Tools

Agent-Ready Docs

Overview

Key concepts

Step types

Trigger types

API Endpoints

List Workflows

Create Workflow

Get Workflow

Update Workflow

Delete Workflow

Trigger a Run

Version History

Audit Log

Webhook Token

Runs

List All Runs

Get Run Detail

Cancel a Run

Delete a Run

Templates

List Templates

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

​Overview

​Key concepts

​Step types

​Trigger types

​API Endpoints

​List Workflows

​Create Workflow

​Get Workflow

​Update Workflow

​Delete Workflow

​Trigger a Run

​Version History

​Audit Log

​Webhook Token

​Runs

​List All Runs

​Get Run Detail

​Cancel a Run

​Delete a Run

​Templates

​List Templates

​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

Overview

Key concepts

Step types

Trigger types

API Endpoints

List Workflows

Create Workflow

Get Workflow

Update Workflow

Delete Workflow

Trigger a Run

Version History

Audit Log

Webhook Token

Runs

List All Runs

Get Run Detail

Cancel a Run

Delete a Run

Templates

List Templates

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