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

# Quickstart

> Make your first authenticated request to the Audienceful API in a couple of minutes.

This guide takes you from zero to a working API call. By the end you'll have a key, you'll have listed the contacts in your workspace, and you'll have added a new one.

<Info>The API lives at `https://api.audienceful.com/v2/`. Every request is authenticated with a workspace API key sent in the `X-Api-Key` header.</Info>

## 1. Get an API key

<Steps>
  <Step title="Open your API settings">
    Log in and head to the [API keys](https://app.audienceful.com/settings/api) page under **Settings**.
  </Step>

  <Step title="Generate a key">
    Click **Generate Key**, give it a name, and (optionally) set an expiration and [scopes](/authentication#scopes). Leave scopes empty for full workspace access while you're getting started.
  </Step>

  <Step title="Copy it somewhere safe">
    This is the **only** time the full key is shown. Store it in an environment variable rather than pasting it into code.

    ```bash theme={null}
    export AUDIENCEFUL_API_KEY="<your-api-key>"
    ```
  </Step>
</Steps>

<Warning>Your API key is a workspace secret. Never expose it to a browser or mobile client — call the API from a backend service only.</Warning>

## 2. Make your first request

List the first page of contacts in your workspace. A `200` response means your key works.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.audienceful.com/v2/people' \
  --header "X-Api-Key: $AUDIENCEFUL_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  url = "https://api.audienceful.com/v2/people"
  headers = {"X-Api-Key": os.environ["AUDIENCEFUL_API_KEY"]}

  response = requests.get(url, headers=headers)
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.audienceful.com/v2/people", {
    method: "GET",
    headers: { "X-Api-Key": process.env.AUDIENCEFUL_API_KEY },
  });

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

You'll get back the standard [paginated](/pagination) envelope:

```json theme={null}
{
  "data": [
    {
      "id": "jQKdwqp3YRRtTrwqUJEp7d",
      "email": "person@example.com",
      "tags": ["vip"],
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## 3. Add a contact

Now create a contact by sending a `POST` to the same endpoint. Include an [`Idempotency-Key`](/idempotency) so a retry after a network blip never creates a duplicate.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.audienceful.com/v2/people' \
  --header "X-Api-Key: $AUDIENCEFUL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8' \
  --data-raw '{ "email": "new.person@example.com", "tags": ["from-api"] }'
  ```

  ```python Python theme={null}
  import os
  import requests

  url = "https://api.audienceful.com/v2/people"
  headers = {
      "X-Api-Key": os.environ["AUDIENCEFUL_API_KEY"],
      "Content-Type": "application/json",
      "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
  }
  payload = {"email": "new.person@example.com", "tags": ["from-api"]}

  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.audienceful.com/v2/people", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.AUDIENCEFUL_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": "8f9a1b2c-3d4e-5f60-7182-93a4b5c6d7e8",
    },
    body: JSON.stringify({
      email: "new.person@example.com",
      tags: ["from-api"],
    }),
  });

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  console.log(await response.json());
  ```
</CodeGroup>

That's it — you're integrated. 🎉

## Where to next

<CardGroup cols={2}>
  <Card title="Authentication & scopes" icon="lock" href="/authentication">
    Lock keys down to only the permissions an integration needs.
  </Card>

  <Card title="Handle errors" icon="triangle-exclamation" href="/errors">
    The single error envelope every endpoint returns, and how to react to it.
  </Card>

  <Card title="Stay under rate limits" icon="gauge-high" href="/throttling">
    Per-workspace limits, the headers to watch, and how to back off.
  </Card>

  <Card title="Get webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Be notified when things change instead of polling for updates.
  </Card>
</CardGroup>

<Tip>Prefer to explore interactively? Every endpoint in the **API Reference** has a live playground — drop in your key and send real requests from the browser.</Tip>