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

# Handling CAC queries

> When CAC asks for changes: what it asked, and how to answer.

CAC sometimes sends a registration back with questions: the name lacks a qualifier, the passport
photograph is unclear, the surname doesn't match the ID. The registration becomes `queried` and a
`registration.queried` webhook fires. Answering costs nothing.

## What CAC asked

`query` on the registration (or `GET /v1/registrations/{id}/query`) lists each item, with the field
to fix as a parameter path:

```json theme={null}
{
  "raised_at": "2026-10-23T22:06:50Z",
  "answered_at": null,
  "items": [
    {
      "field": "proposed_names",
      "code": "qualifier_missing",
      "message": "Proposed name does not include any business name qualifier, please add a qualifier to improve chances of approval. e.g \"ventures\", \"concepts\", \"enterprises\", \"beauty\", \"fashion\"",
      "resolved": false
    },
    {
      "field": "proprietors[0].documents.passport",
      "code": "document_unclear",
      "message": "Passport is not clear or does not match photo on MEANS_OF_ID",
      "resolved": false
    }
  ],
  "object": "registration_query",
  "registration_id": "reg_4z6kpLm5HHqdGMCYHcp1po"
}
```

| Field | Meaning |
| - | - |
| `field` | What to change, e.g. `proposed_names`, `proprietors[0].last_name`, `proprietors[0].documents.passport`. `null` when CAC didn't tie the item to one field. |
| `code` | `name_exists`, `qualifier_missing`, `single_word`, `offensive_language`, `fraudulent_association`, `document_unclear`, `name_mismatch` or `other`. |
| `message` | CAC's own words. Show them to your user. |
| `resolved` | `true` once the field has changed (or the document was replaced) since the query. |

## Answering

**1. Fix each queried field**

`PATCH` the queried fields and upload new versions of queried documents. Only queried fields can
change, because only those go back to CAC:

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "field_not_queried",
    "message": "While queried, only the queried fields can change (proposed_names, proprietors[0].documents.passport).",
    "param": "line_of_business",
    "request_id": "req_G45gH40dPTdn7mi3s9cjj9w7"
  }
}
```

Each item's `resolved` turns `true` as you fix it.

```bash theme={null}
curl -X PATCH https://api.fastcac.com/v1/registrations/$REG_ID \
  -H "Authorization: Bearer $FASTCAC_KEY" -H "Content-Type: application/json" \
  -d '{"proposed_names": ["Ada Foods Concepts"]}'

curl https://api.fastcac.com/v1/registrations/$REG_ID/documents \
  -H "Authorization: Bearer $FASTCAC_KEY" \
  -F kind=passport -F proprietor=0 -F file=@passport-retake.jpg
```

**2. Submit again**

```bash theme={null}
curl -X POST https://api.fastcac.com/v1/registrations/$REG_ID/submit \
  -H "Authorization: Bearer $FASTCAC_KEY"
```

The registration goes back to `submitted` and `query.answered_at` is set. If an item is still
unresolved you get:

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "query_unresolved",
    "message": "Fix every queried field before resubmitting: proposed_names: Proposed name does not include any business name qualifier, please add a qualifier to improve chances of approval. e.g \"ventures\", \"concepts\", \"enterprises\", \"beauty\", \"fashion\"; proprietors[0].documents.passport: Passport is not clear or does not match photo on MEANS_OF_ID",
    "param": "proposed_names",
    "request_id": "req_hQ1hxNsHN98dQ8W3b6MwSsKr"
  }
}
```

CAC may query a registration more than once; each time, `query` holds the latest questions.

## Testing it

Submit with `?simulate=queried&simulate_query=…` to get exactly the items you want to handle. See
[Test mode](https://docs.fastcac.com/test-mode.md#what-happens-after-submit).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.