Quickstart

This walkthrough runs a complete enrichment in Python. You need an API key from your DataLane workspace settings and the requests package (pip install requests).

1. Set up a client

import os
import time

import requests

BASE_URL = "https://api.datalane.com"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DATALANE_API_KEY']}"


def api(path: str, body: dict | None = None) -> dict:
    response = session.post(f"{BASE_URL}{path}", json=body or {})
    payload = response.json()
    if payload["error"] is not None:
        raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
    return payload["data"]

Every endpoint is a POST returning the same envelope, so one helper covers the whole API: it returns data on success and raises the error code otherwise. Keep the key server-side and out of source control.

2. Check your organization

org = api("/v1/org/describe")
print(org["credits"]["smb"])

Response

{
  "data": {
    "organization": {
      "id": "org_8fKtVbW3nQzYxP2cMjHu4",
      "name": "Acme Robotics"
    },
    "credits": {
      "smb": 1000,
      "researchAgents": 500
    },
    "enrichment": {
      "enrichingAccounts": 0,
      "maxEnrichingAccounts": 10000
    }
  },
  "error": null
}

Enrichment consumes one SMB credit per eligible account, so credits.smb is the budget for everything that follows. credits.researchAgents is a separate balance for Research Agent runs. enrichment.enrichingAccounts counts accounts currently enriching across the organization; new launches must fit within enrichment.maxEnrichingAccounts.

3. Create a campaign

campaign = api("/v1/campaigns/create", {
    "name": "July target accounts",
    "accountIds": [
        "9feafba5-78e5-4e19-b577-1455b0d2018c",
        "ae46f8b8-4b9d-43ee-96e5-744943f6863a",
    ],
    "excludeEnrichedWithinDays": 30,
})
campaign_id = campaign["id"]

Response

{
  "data": {
    "id": "camp_4Zw7kQhX2mRfT9pJcN3Ld",
    "status": "draft",
    "createdVia": "api",
    "name": "July target accounts",
    "accounts": {
      "requested": 2,
      "eligible": null,
      "excluded": null
    },
    "credits": { "charged": 0, "remaining": 1000 },
    "excludeEnrichedWithinDays": 30,
    "lastEnrichment": null,
    "createdAt": "2026-07-21T14:00:00.000Z"
  },
  "error": null
}

Account IDs must be UUIDs; duplicates are counted once in accounts.requested. The campaign starts as a draft; nothing is charged, and accounts.eligible and accounts.excluded stay null until enrichment evaluates the list. excludeEnrichedWithinDays tells the launch to skip accounts enriched within the last 30 days; it can be changed with /v1/campaigns/update while the campaign is still a draft.

4. Start enrichment

campaign = api("/v1/campaigns/enrich", {"campaignId": campaign_id})

Response

{
  "data": {
    "id": "camp_4Zw7kQhX2mRfT9pJcN3Ld",
    "status": "enriching",
    "createdVia": "api",
    "name": "July target accounts",
    "accounts": {
      "requested": 2,
      "eligible": 2,
      "excluded": {
        "total": 0,
        "invalid": 0,
        "recentlyEnriched": 0,
        "crmExcluded": 0
      }
    },
    "credits": { "charged": 2, "remaining": 998 },
    "excludeEnrichedWithinDays": 30,
    "lastEnrichment": null,
    "createdAt": "2026-07-21T14:00:00.000Z"
  },
  "error": null
}

DataLane validates the list, applies the campaign’s recency exclusion, charges one credit per remaining account, and starts finding contacts. The call returns once the campaign is enriching. If it raises enrichment_pending, the launch is still in progress. Repeat the same call after a short backoff.

5. Poll until enriched

delay = 2
while campaign["status"] == "enriching":
    time.sleep(delay)
    delay = min(delay * 2, 60)
    campaign = api("/v1/campaigns/get", {"campaignId": campaign_id})
    print("status:", campaign["status"])

The loop ends on enriched:

Response

{
  "data": {
    "id": "camp_4Zw7kQhX2mRfT9pJcN3Ld",
    "status": "enriched",
    "createdVia": "api",
    "name": "July target accounts",
    "accounts": {
      "requested": 2,
      "eligible": 2,
      "excluded": {
        "total": 0,
        "invalid": 0,
        "recentlyEnriched": 0,
        "crmExcluded": 0
      }
    },
    "credits": { "charged": 2, "remaining": 998 },
    "excludeEnrichedWithinDays": 30,
    "lastEnrichment": null,
    "createdAt": "2026-07-21T14:00:00.000Z",
    "completedAt": "2026-07-21T14:06:12.000Z",
    "resultsExpireAt": "2027-01-21T23:59:59.999Z",
    "results": {
      "totalAccounts": 2,
      "totalContactsFound": 9,
      "pctAccountsWithContact": 1,
      "pctAccountsWithMobile": 0.5
    }
  },
  "error": null
}

Results stay exportable until resultsExpireAt. If the loop ends on draft instead, the attempt failed or was canceled. lastEnrichment reports what happened and whether its credits were refunded. See Campaign lifecycle.

6. Export a CSV

export = api("/v1/campaigns/export", {
    "campaignId": campaign_id,
    "maxContactsPerAccount": 5,
})

download = requests.get(export["url"], timeout=300)
download.raise_for_status()
with open("campaign.csv", "wb") as file:
    file.write(download.content)

Response

{
  "data": {
    "campaignId": "camp_4Zw7kQhX2mRfT9pJcN3Ld",
    "url": "https://storage.datalane.com/exports/...",
    "urlExpiresAt": "2026-07-21T15:06:30.000Z",
    "rows": { "accounts": 2, "contacts": 9 },
    "file": { "format": "csv", "encoding": "utf-8-bom" }
  },
  "error": null
}

url is presigned. Fetch it with a plain requests.get, without an Authorization header, and treat it as a secret. It stays valid for one hour; each export call builds a fresh file, so call it again to change filters or get a new URL. See Export results for contact caps and filters.

Next steps

Campaign lifecycle: states, safe retries, and polling guidance
Errors and retries: every error code and which ones to retry
API reference: full schemas and an interactive playground

Get started

Build with DataLane

1. Set up a client

2. Check your organization

3. Create a campaign

4. Start enrichment

5. Poll until enriched

6. Export a CSV

Next steps

​1. Set up a client

​2. Check your organization

​3. Create a campaign

​4. Start enrichment

​5. Poll until enriched

​6. Export a CSV

​Next steps

1. Set up a client

2. Check your organization

3. Create a campaign

4. Start enrichment

5. Poll until enriched

6. Export a CSV

Next steps