> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.wealthatlas.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.wealthatlas.com/_mcp/server.

# Quickstart

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

## Prerequisites

* A valid API key (see [Authentication](/getting-started/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.

```bash
curl -X PUT https://api.wealthatlas.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):

```json
{
  "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:

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

**Response:**

```json
{
  "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.

> **Tip**
>
> 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 profile:

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

**Response:**

```json
{
  "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.wealthatlas.com/person/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 `APIPerson` profile. See the [API Reference](/api-reference) for the complete schema.

## Next steps

* **Search for people** -- use `POST /search` to find people with plain English or structured filters
* **Build a network** -- add your board members and contacts to a [network](/guides/network), then discover which prospects they're connected to
* **Organize people into lists** -- use the Lists endpoints to create and manage collections
* **Export data** -- use `POST /exports` to download person data as CSV or XLSX
* **Understand credits** -- read [Credits & Billing](/guides/credits)