Quickstart

Enhance your first contact in under 5 minutes

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

A valid API key (see Authentication)
curl or any HTTP client

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     "imports_charged": 1,
11     "imports_remaining": 999,
12     "partial": false,
13     "partial_reason": null
14   }
15 }

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

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

Prerequisites

A valid API key (see Authentication)
curl or any HTTP client

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     "imports_charged": 1,
11     "imports_remaining": 999,
12     "partial": false,
13     "partial_reason": null
14   }
15 }

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

$	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"]
>	}
>	]
>	}'

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	"imports_charged": 1,
11	"imports_remaining": 999,
12	"partial": false,
13	"partial_reason": null
14	}
15	}

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

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

$	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"]
>	}'

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	}