# Common Mistakes

This guide captures recurring API integration errors and the fastest correction for each.

| Mistake | Correction |
|--------|------------|
| Using `size` instead of `group_size` | Use `group_size` (1-40). |
| Using `group_id` in study creation body | Use `research_group_uuid` from `response.group.uuid`. |
| Using `text` instead of `question` in ask endpoints | Use `question`. |
| Using full state names (for example `Texas`) | Use 2-letter codes (`TX`, `CA`, `MI`, etc.). |
| Using `ethnicity=Hispanic` | Use full value `ethnicity=Hispanic or Latino`. |
| Using `ethnicity=African American` | Use `ethnicity=Black` (exact full string). |
| Using `labour_status=retired` | Use `labour_status=Not in labor force` and optionally combine with `age_min`. |
| Parsing `response.id` directly after create | Parse nested objects (`response.group.uuid`, `response.study.id`). |
| Using `income` filter | Use `income_annual_usd_min` / `income_annual_usd_max`. |
| Asking multiple study questions in parallel | Ask sequentially: queue one, poll to `finished`, then ask next. |
| Sending `agent_ids` as strings/UUIDs to remove/add endpoints | Send `agent_ids` as `list[int]`. |
| Expecting `response.answer` from job status | Parse `result` payload from `GET /v1/jobs/{job_id}`. |
| Treating `total_count=0` as proof of no data | Verify filter value spelling/full-string match first. |
| Assuming share links require auth | Share links are public while sharing is enabled. |

## Share URL Usage

Recommended UTM conventions for downstream analytics:

- `?utm_source=ce` for cold/programmatic email links
- `?utm_source=blog` for blog/content links

Example:

```text
https://cat.fish.dog/organization/studies/shared/<share_id>?utm_source=ce
```