# Your customers' sign-up cases and «Handled»

`GET /v1/onboarding-cases`

When a customer of one of your links gets stuck and writes on the signup screen, a **case** is born (`A-<n>`, the same `data.caseId` of `onboarding.help_requested`). It carries what they wrote verbatim, Meta's code, the diagnosis (from the catalog or by AI, with its confidence) and whether they uploaded a screenshot.

**List them.** `GET /v1/onboarding-cases?status=open` (default), `acked` or `all`; newest first.

**Mark one handled.** `POST /v1/onboarding-cases/{id}/ack`, once you sorted it out. It is idempotent. A 2xx webhook delivery does **not** count as handled.

**In the dashboard.** **Your clients' sign-ups** (shows in the menu once you created links): one row per link with its state (waiting, failed, connected, expired), the attempts, the last reason, the diagnosis, the text and the screenshot, the «Handled» button and, if it expired, «Generate a new link». Filters: Need attention (default), All, Connected.

## Examples

### cURL

```bash
# 1) the open cases (default status=open; also acked | all)
curl "https://api.waiaconnect.com/v1/onboarding-cases?status=open" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "cases": [ { "id": "A-41", "status": "open", "externalId": "pharmacy-42",
#       "clientText": "…", "metaErrorCode": 3441060, "diagnosis": { "title": "…", "responsible": "client", … } } ] }

# 2) once you sorted it out: mark it handled (idempotent)
curl -X POST https://api.waiaconnect.com/v1/onboarding-cases/A-41/ack -H "Authorization: Bearer wc_live_YOUR_API_KEY"
```

### Node.js

```javascript
const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY" };
const { cases } = await (await fetch("https://api.waiaconnect.com/v1/onboarding-cases?status=open", { headers: H })).json();
for (const c of cases) {
  console.log(c.id, c.externalId, c.diagnosis?.title, c.clientText);
  // … after you helped your customer:
  await fetch(`https://api.waiaconnect.com/v1/onboarding-cases/${c.id}/ack`, { method: "POST", headers: H });
}
```

### PHP

```php
<?php
$h = ["Authorization: Bearer wc_live_YOUR_API_KEY"];
$ch = curl_init("https://api.waiaconnect.com/v1/onboarding-cases?status=open");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h]);
$cases = json_decode(curl_exec($ch), true)["cases"];
foreach ($cases as $c) {
  $ack = curl_init("https://api.waiaconnect.com/v1/onboarding-cases/" . $c["id"] . "/ack");
  curl_setopt_array($ack, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => $h]);
  curl_exec($ack);
}
```

### Python

```python
import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}
cases = requests.get("https://api.waiaconnect.com/v1/onboarding-cases", headers=H, params={"status": "open"}).json()["cases"]
for c in cases:
    print(c["id"], c["externalId"], (c["diagnosis"] or {}).get("title"), c["clientText"])
    requests.post(f"https://api.waiaconnect.com/v1/onboarding-cases/{c['id']}/ack", headers=H)  # after you helped them
```

## Notes

- A case of another account returns the same `404 ONBOARDING_CASE_NOT_FOUND` as one that does not exist.
- A `status` other than `open`, `acked` or `all` returns `400 ONBOARDING_CASE_STATUS_INVALID`.
- `?lang=es|en|pt|it` picks the language of a catalog diagnosis (default: the link's).