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):

1{
2  "status": 202,
3  "message": "Jobs submitted",
4  "tracking_id_to_job_id": {
5    "contact_001": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
6  },
7  "meta": {
8    "requested": 1,
9    "processed": 1
10  }
11}

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:

1{
2  "status": 200,
3  "message": "Progress retrieved successfully",
4  "job_state": {
5    "progress": { "status": "processing", "pct_done": 45 },
6    "error": null
7  }
8}

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:

1{
2  "status": 200,
3  "message": "Results retrieved successfully",
4  "job_id_to_state": {
5    "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4": {
6      "progress": { "status": "completed", "pct_done": null },
7      "result": {
8        "id": "b7c0bc58fb754fa6883ac7bbd6526584",
9        "name": { "first": "John", "middle": "A", "last": "Smith" },
10        "donoratlas_url": "https://app.donoratlas.com/donor/b7c0bc58fb754fa6883ac7bbd6526584",
11        "age": 52,
12        "net_worth_range": [1000000, 5000000],
13        "political_stats": { "capacity": 85000, "..." : "..." },
14        "nonprofit_stats": { "capacity": 125000, "..." : "..." },
15        "education": [ { "institution_name": "Harvard University", "..." : "..." } ],
16        "work": [ { "company_name": "Acme Corporation", "..." : "..." } ],
17        "bio": ["Philanthropist and tech executive based in Boston"],
18        "..." : "..."
19      }
20    }
21  }
22}

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