DocumentationAPI Reference

Jobs

Create async bulk job

Creates one logical async job for a supported bulk operation. Prefer server-side scope (+ optional exclusions) over inline ID batches. Running concurrency is capped at 3 jobs per account; additional jobs remain queued. Poll GET /v1/jobs/{id}; cancel with POST /v1/jobs/{id}/cancel. One operation-specific *.completed webhook is emitted when the job finishes successfully.

POST/v1/jobs

Authorization

bearerAuth
AuthorizationBearer <token>

Use an account API key in the Authorization header: Authorization: Bearer f_....

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

operationstring

Value in

  • "api_lead_import"
  • "add_to_campaign"
  • "remove_from_campaign"
  • "remove_from_all_campaigns"
  • "pause_enrollments"
  • "resume_enrollments"
  • "add_to_lead_list"
  • "remove_from_lead_list"
  • "export_leads"
  • "csv_lead_import_staged"
campaign_id?string
Formatuuid
global_lead_ids?array<string>
list_id?string
Formatuuid
target_list_id?string
Formatuuid
source_campaign_id?string
Formatuuid
upload_id?string
Formatuuid
scope?BulkScope

Server-side population selector. Prefer list/campaign/staged scopes for bulk work.

kindstring

Value in

  • "selection"
  • "explorer_view"
  • "saved_list"
  • "saved_list_filtered"
  • "campaign"
  • "staged_upload"
global_lead_ids?array<string>
list_id?string
Formatuuid
campaign_id?string
Formatuuid
upload_id?string
Formatuuid
query?object
exclusions?BulkExclusions

People to exclude from a scoped bulk mutation.

list_id?string
Formatuuid
campaign_id?string
Formatuuid
global_lead_ids?array<string>
emails?array<string>
preview_id?string
expected_count?integer
projection?string

Value in

  • "full"
  • "compact"
filename_base?string
column_layout?array<object>
leads?array<LeadCreate>
Itemsitems <= 1000
curl -X POST "https://example.com/v1/jobs" \  -H "Content-Type: application/json" \  -d '{    "operation": "add_to_campaign",    "campaign_id": "1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb",    "scope": {      "kind": "saved_list",      "list_id": "7c0d0f5a-2f61-4a2a-9f1d-1b2c3d4e5f60"    }  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",    "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",    "created_by_api_key_id": "16a8c1ea-aaaf-49f0-9266-c657c48ceff3",    "status": "uploading",    "progress": 0,    "cursor": 0,    "input": {      "operation": "api_lead_import",      "global_lead_ids": [        "string"      ],      "saved_list_id": "66dbf949-b2e8-4ab0-88f6-7819d41ad41e",      "source_campaign_id": "2640cdba-4b3e-4560-9225-0360dc4a4884",      "target_list_id": "e020bfe9-7c71-4403-800b-700dad22bfd2",      "upload_id": "f2ef591b-135b-46fa-a604-3d4fda5bfbfb",      "list_id": "430bbdbc-9d7f-4d06-a273-67ca4ba4ae4b",      "leads": [        {          "email": "user@example.com",          "name": "string",          "first_name": "string",          "last_name": "string",          "company_name": "string",          "website": "string",          "linkedin_url": "string",          "company_linkedin_url": "string",          "phone_number": "string",          "mobile_phone_number": "string",          "custom_lead_data": {},          "tags": [            "string"          ],          "email_verification": {            "status": "ok",            "quality": "string",            "provider": "string",            "verified_at": "2019-08-24T14:15:22Z",            "is_free": true,            "is_role": true          }        }      ],      "total_count": 0,      "source": "string",      "exclusions": {        "list_id": "430bbdbc-9d7f-4d06-a273-67ca4ba4ae4b",        "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",        "global_lead_ids": [          "string"        ],        "emails": [          "user@example.com"        ]      },      "preview_id": "string",      "expected_count": 0,      "projection": "full",      "query": {},      "column_layout": [        {}      ],      "filename_base": "string"    },    "result": {      "created": 0,      "updated": 0,      "enrolled": 0,      "skipped": 0,      "incomplete": 0,      "failed": 0,      "paused": 0,      "resumed": 0,      "removed": 0,      "added": 0,      "rows_exported": 0,      "imported": 0,      "errors": [        {          "globalLeadId": "string",          "index": 0,          "message": "string"        }      ]    },    "errors": [      {        "globalLeadId": "string",        "index": 0,        "message": "string"      }    ],    "cancel_requested_at": "2019-08-24T14:15:22Z",    "started_at": "2019-08-24T14:15:22Z",    "completed_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}
{  "error": {    "type": "invalid_request_error",    "code": "invalid_flow",    "message": "Flow validation failed"  },  "details": [    {      "path": "nodes[1].data.variants[0].id",      "code": "invalid_variant_id",      "message": "Email variants must have a stable UUID id."    }  ]}
{  "error": {    "type": "authentication_error",    "code": "invalid_api_key",    "message": "A valid Furnace API key is required"  }}
{  "error": {    "type": "invalid_request_error",    "code": "campaign_not_found",    "message": "Campaign not found"  }}
{  "error": {    "type": "rate_limit_error",    "code": "rate_limit_exceeded",    "message": "Rate limit exceeded for this account"  }}
{  "error": {    "type": "api_error",    "code": "internal_error",    "message": "Internal server error"  }}