# Lead forms and leads

> A Page's lead forms, or one form's submissions.

Canonical: <https://www.tryadeli.com/docs/api/ads/list-leads>

`GET https://app.tryadeli.com/api/v1/ads/leads`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

Without `formId`, the lead generation forms belonging to the connected Page.
With it, that form's submissions, including the field data and the campaign, ad
set and ad each lead came from.

> **Note:**
>
> Adeli does not store lead data. Submissions are read from Facebook when you ask
> for them and are not retained after the response.

**Query parameters**

| Name        | Type     | Required | Description                                                                                     |
| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
| `formId`    | `string` |          | A lead form id. Omit to list the Page's forms.                                                  |
| `accountId` | `uuid`   |          | A connected Facebook account.                                                                   |
| `profileId` | `uuid`   |          | Required unless you pass accountId, which names its profile. If you pass both, they must agree. |

## Request examples

**cURL**

```bash
curl --fail-with-body "https://app.tryadeli.com/api/v1/ads/leads?formId=555666777888999&accountId=00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/ads/leads?formId=555666777888999&accountId=00000000-0000-0000-0000-000000000000", {
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
  },
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://app.tryadeli.com/api/v1/ads/leads",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "formId": "555666777888999",
        "accountId": "00000000-0000-0000-0000-000000000000",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "facebook",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "profileId": "00000000-0000-4000-8000-000000000002",
  "leads": [
    {
      "id": "1029384756473829",
      "createdAt": "2026-10-08T18:22:41+0000",
      "fields": [
        { "name": "full_name", "values": ["Jordan Lee"] },
        { "name": "email", "values": ["jordan@example.com"] }
      ],
      "campaignName": "Fall launch",
      "adSetName": "Fall launch — ad set",
      "adName": "Fall launch — ad"
    }
  ],
  "fetchedAt": "2026-10-09T16:00:00.000Z"
}
```

### 403

```json
{
  "error": {
    "code": "ads_permission_required",
    "message": "This connection has not granted the Facebook ads permissions",
    "details": { "missingScopes": ["leads_retrieval"] }
  }
}
```