> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a contact list, add contacts and read analytics in three requests.

<Steps>
  <Step title="Set up your shell">
    Export the key PowerDialer issued you and define the headers every call uses.

    ```bash theme={null}
    export API_KEY="pd_live_..."
    BASE=https://api.migration.powerdialer.ai/api/public/v1
    AUTH=(-H "Authorization: Bearer $API_KEY" -H "x-user-email: rep@company.com")
    ```
  </Step>

  <Step title="Create a list with contacts">
    One call creates the list and seeds it. Contacts go through the same path as a CSV upload, including background enrichment.

    ```bash theme={null}
    curl -X POST "$BASE/contact-lists" "${AUTH[@]}" -H "Content-Type: application/json" \
      -d '{
        "name": "Partner leads October",
        "groupName": "Partner",
        "contacts": [
          { "name": "Ada Lovelace", "phoneNumber": "+15550100" },
          { "name": "Grace Hopper", "phoneNumber": "+15550101", "metadata": { "company": "Acme" } }
        ]
      }'
    ```

    ```json Response · 201 Created theme={null}
    {
      "id": 4821,
      "name": "Partner leads October",
      "groupName": "Partner",
      "contactsCount": 2,
      "orgId": "org_2xyz...",
      "createdAt": "2026-10-06T12:00:00.000Z",
      "updatedAt": "2026-10-06T12:00:00.000Z"
    }
    ```

    Keep the returned `id` — every other call uses it. Names are not unique.
  </Step>

  <Step title="Add more contacts later">
    Batches of up to 10,000, append-only. Numbers already in the list are skipped, not updated.

    ```bash theme={null}
    curl -X POST "$BASE/contact-lists/4821/contacts" "${AUTH[@]}" -H "Content-Type: application/json" \
      -d '{"contacts":[{"name":"Margaret Hamilton","phoneNumber":"+15550102"}]}'
    ```

    ```json Response · 200 OK theme={null}
    { "contactListId": 4821, "received": 1, "added": 1, "skippedExisting": 0, "duplicatesInPayload": 0 }
    ```
  </Step>

  <Step title="Read the user's analytics">
    Pass the user's timezone so day boundaries match what they see in the app.

    ```bash theme={null}
    curl "$BASE/analytics/summary?startDate=2026-10-01&endDate=2026-10-07&timezone=America/New_York" "${AUTH[@]}"
    ```

    The response includes `calls.total`, `calls.connected`, `calls.conversations`, `rates.connectRate` and more — see [Analytics](/guides/analytics).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Contact lists" icon="list" href="/guides/contact-lists">Rename, regroup and delete lists.</Card>
  <Card title="Contacts" icon="address-book" href="/guides/contacts">Contact shape, batch semantics, removal by phone.</Card>
  <Card title="Errors and limits" icon="triangle-exclamation" href="/reference/errors-and-limits">Status codes, rate limit, payload caps.</Card>
  <Card title="API Reference" icon="code" href="/api-reference/create-contact-list">Every endpoint with a live playground.</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.