# Your first request

Create a key, send it with a request, and read a page of your organization's leads. About five minutes, start to finish.

<Note title="The secret is shown once">
  Copy the key when you create it. LeadUp keeps only a hash of it and can't show it to you again.
</Note>

## Steps

<Steps>

<Step title="Create an organization key">

In the app, open **Settings › API keys**, choose **New key**, name it after the integration that will use it, and give it only the permissions it needs. For this guide, `leads:read` is enough.

</Step>

<Step title="Keep it out of your code">

Store the key in an environment variable or your platform's secret store, never in source control:

```bash title="Shell"
export LEADUP_API_KEY="lup_org_live_…"
```

</Step>

<Step title="Send it as a bearer token">

Every request carries the key in the `Authorization` header.

<CodeGroup>

```bash title="cURL"
curl "https://api.leadup.group/v1/leads?limit=5" \
  -H "Authorization: Bearer $LEADUP_API_KEY"
```

```ts title="Node.js"
const response = await fetch("https://api.leadup.group/v1/leads?limit=5", {
  headers: { Authorization: `Bearer ${process.env.LEADUP_API_KEY}` },
})
const page = await response.json()
```

```python title="Python"
import os, requests

response = requests.get(
    "https://api.leadup.group/v1/leads",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {os.environ['LEADUP_API_KEY']}"},
)
page = response.json()
```

</CodeGroup>

</Step>

<Step title="Read the page that comes back">

Lists return `items` and a `nextCursor`. Send the cursor back as `cursor` to read the next page; it is `null` on the last one.

```json title="200 OK"
{
  "items": [
    {
      "id": "0192f0c1-7a3e-7c51-9d2e-4b7f0a1c2d3e",
      "companyName": "Clínica Sorriso Pleno",
      "segment": "dental",
      "city": "Campinas",
      "region": "SP",
      "stage": "proposal",
      "nextFollowUpAt": "2026-10-14T13:00:00Z"
    }
  ],
  "nextCursor": null
}
```

</Step>

</Steps>

## If it fails

- **401 `auth.unauthenticated`**: the key is missing, mistyped, revoked or expired. The API doesn't say which, on purpose.
- **403 `auth.forbidden`**: the key works but lacks the permission this endpoint needs. Create a key with it.
- **429 `request.rateLimited`**: wait for the seconds in `Retry-After`, then try again. See [rate limits](/guides/rate-limits).

## Next steps

- [Find leads](/guides/find-leads) by stage, city or name.
- [Move a lead](/guides/move-a-lead) through the pipeline.
- Browse every endpoint in the [API reference](/reference).