Getting Started

Quickstart

Enhance your first contact in under 5 minutes

This guide walks through the full enhancement flow: submit a contact, poll for completion, and retrieve the enriched donor profile.

Prerequisites

Step 1: Submit a contact for enhancement

Send a PUT / request with the person’s details. Each person consumes one credit.

curl -X PUT https://api.donoratlas.com/v1/partners/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persons": [
      {
        "tracking_id": "contact_001",
        "name": { "first": "John", "last": "Smith" },
        "addresses": ["123 Main St, Boston, MA 02101"],
        "employers": ["Acme Corporation"]
      }
    ]
  }'

Response (HTTP 202):

{
  "status": 202,
  "message": "Jobs submitted",
  "tracking_id_to_job_id": {
    "contact_001": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  },
  "meta": {
    "requested": 1,
    "processed": 1
  }
}

Save the job_id — you’ll need it to check progress and retrieve results.

Step 2: Poll for progress

Enhancement takes a few seconds to a couple of minutes. Poll the progress endpoint:

curl -X GET https://api.donoratlas.com/v1/partners/progress/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "status": 200,
  "message": "Progress retrieved successfully",
  "job_state": {
    "progress": { "status": "processing", "pct_done": 45 },
    "error": null
  }
}

Keep polling until status is "completed" or "failed". A reasonable interval is every 2-5 seconds.

For batch workflows, use POST /progress to check up to 1,000 job IDs in a single request.

Step 3: Retrieve the result

Once the job is complete, fetch the enriched donor profile:

curl -X POST https://api.donoratlas.com/v1/partners/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_ids": ["a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"]
  }'

Response:

{
  "status": 200,
  "message": "Results retrieved successfully",
  "job_id_to_state": {
    "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4": {
      "progress": { "status": "completed", "pct_done": null },
      "result": {
        "id": "b7c0bc58fb754fa6883ac7bbd6526584",
        "name": { "first": "John", "middle": "A", "last": "Smith" },
        "donoratlas_url": "https://app.donoratlas.com/donor/b7c0bc58fb754fa6883ac7bbd6526584",
        "age": 52,
        "net_worth_range": [1000000, 5000000],
        "political_stats": { "capacity": 85000, "..." : "..." },
        "nonprofit_stats": { "capacity": 125000, "..." : "..." },
        "education": [ { "institution_name": "Harvard University", "..." : "..." } ],
        "work": [ { "company_name": "Acme Corporation", "..." : "..." } ],
        "bio": ["Philanthropist and tech executive based in Boston"],
        "..." : "..."
      }
    }
  }
}

The result field contains the full APIDonor profile. See the API Reference for the complete schema.

Next steps

  • Search for donors — use POST /search to find donors with plain English or structured filters
  • Build a network — add your board members and contacts to a network, then discover which prospects they’re connected to
  • Organize donors into lists — use the Lists endpoints to create and manage collections
  • Export data — use POST /exports to download donor data as CSV or XLSX
  • Understand credits — read Credits & Billing