Pipeline (One-Flow)

The Pipeline endpoint runs the whole lead-generation flow in a single tracked job: search → suppress → unlock → verify → deliver. You submit criteria once and poll a single track_id (or get pushed via a webhook) instead of orchestrating Search and Unlock yourself.

Endpoint

Method: POST Path: /pipeline/ Full URL: https://backend.ecoreservice.com/api/v1/pipeline/ Auth: Authorization: Token YOUR_API_TOKEN — see Authentication

Request Body

Content-Type: application/json

Field	Type	Required	Description
`criteria`	object	Yes	Search filters — same keys as Search Records query params (`industry`, `job_level`, `keywords`, `keyword_fields`, etc.)
`suppression_ids`	array of strings	No	Suppression list IDs to exclude from the run
`unlock_email`	boolean	No	Unlock email for matched contacts (charges credits)
`unlock_phone`	boolean	No	Unlock phone for matched contacts (charges credits)
`verify_emails`	boolean	No	Verify deliverability of unlocked emails
`max_records`	integer	No	Cap the number of records processed. Hard ceiling: 10,000 per job.

curl -X POST "https://backend.ecoreservice.com/api/v1/pipeline/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "criteria": {"industry":"Software","job_level":"C Level","keywords":"devops","keyword_fields":"job_title"},
        "suppression_ids": ["<supp_id>"],
        "unlock_email": true,
        "unlock_phone": false,
        "verify_emails": true,
        "max_records": 500
      }'

Submit Response

{
  "track_id": "…",
  "status": "pending"
}

Store the track_id — you use it to poll status and fetch results.

Poll Status

Method: GET Path: /pipeline/{track_id}/

curl "https://backend.ecoreservice.com/api/v1/pipeline/<track_id>/" \
  -H "Authorization: Token YOUR_API_TOKEN"

{
  "job": {
    "status": "running",
    "current_stage": "verify",
    "progress": 60,
    "matched_count": 500,
    "unlocked_count": 488,
    "verified_count": 470,
    "credits_charged": 488
  }
}

Field	Type	Description
`status`	string	`pending` → `running` → `completed` \| `failed`
`current_stage`	string	Current pipeline stage (e.g., `search`, `unlock`, `verify`, `deliver`)
`progress`	integer	Percent complete (0–100)
`matched_count`	integer	Contacts matched by the search stage
`unlocked_count`	integer	Contacts whose data was unlocked
`verified_count`	integer	Emails that passed verification
`credits_charged`	integer	Credits charged so far

Fetch Results

Method: GET Path: /pipeline/{track_id}/results/

Available once status is completed.

curl "https://backend.ecoreservice.com/api/v1/pipeline/<track_id>/results/" \
  -H "Authorization: Token YOUR_API_TOKEN"

{
  "count": 488,
  "results": [
    {
      "uuid": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "company_name": "Acme Corp",
      "contact_email": "john@acme.com",
      "email_status": "valid",
      "email_valid": true
    }
  ]
}

Getting Pushed Instead of Polling

If you register a webhook for the pipeline.completed event, you receive a push with the same counts when the job finishes — no polling required. Register pipeline.failed to be notified of failures.

Credits

The pipeline charges the same rates as the underlying operations: 1 credit per email unlock, 5 credits per phone unlock. Suppressed contacts are skipped and not charged. See Credit Costs.

Endpoint​

Request Body​

Submit Response​

Poll Status​

Fetch Results​

Getting Pushed Instead of Polling​

Credits​