DocumentationAPI Reference

Jobs

Preview a bulk operation

Estimates matched/excluded/actionable counts for a scoped bulk mutation. Pass the returned preview_id when creating the job to bind execution to the preview.

POST/v1/bulk/preview

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
target_list_id?string
Formatuuid
list_id?string
Formatuuid
global_lead_ids?array<string>
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>
curl -X POST "https://example.com/v1/bulk/preview" \  -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"    },    "exclusions": {      "list_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"    }  }'
{  "data": {    "preview_id": "string",    "operation": "string",    "operation_hash": "string",    "expires_at": "2019-08-24T14:15:22Z",    "counts": {      "matched": 0,      "excluded": 0,      "duplicate": 0,      "ineligible": 0,      "actionable": 0    },    "warnings": [      "string"    ],    "scope": {      "kind": "selection",      "global_lead_ids": [        "string"      ],      "list_id": "430bbdbc-9d7f-4d06-a273-67ca4ba4ae4b",      "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",      "upload_id": "f2ef591b-135b-46fa-a604-3d4fda5bfbfb",      "query": {}    },    "exclusions": {      "list_id": "430bbdbc-9d7f-4d06-a273-67ca4ba4ae4b",      "campaign_id": "78614b6c-fe7c-41e2-8e25-c9b3a3c91904",      "global_lead_ids": [        "string"      ],      "emails": [        "user@example.com"      ]    },    "target": {}  }}
{  "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"  }}