API filing outcomes, polling and retries

Current outcomes, documents and retries

A 202 response means admitted for processing. Read GET /filings/{id} for each requested part, its authority, status, reason, receipt and errors. One long-period CT600 can be accepted while the other is rejected. Read GET /filings/{id}/documents for scoped download links. Links expire and must be fetched again when needed. A staged filing without a job has an empty document list.

For Companies House accounts, send the customer's choice in chProfitAndLossPublication. If publication is unavailable, the API asks you to correct that choice before filing.

Repeat an identical request with its original idempotency key to get its current state. Reusing a key for different data returns a conflict. To deliberately send an unchanged filing again, send a new idempotency key and retry_of identifying the earlier operation, with fresh credentials. The filing data must remain unchanged. This sends every selected return again, including accepted or unconfirmed returns. The authority decides whether to accept it. Each filing shows only its own attempt and receipt. See credentials and retry rules.

A community interest company uses POST /filings/accounts to prepare its existing customer-upload ZIP. The response has package_only: true and customer_action.type upload_cic_package. Completion means the package is ready to download. The customer uploads it through the linked Companies House CIC service. It is never reported as accepted by Companies House.

Polling and authority reasons

Poll GET /filings/{id}. A pending response includes Retry-After: 30 seconds. If an authority poll has run out, this GET restarts the existing poll schedule at most once an hour per part. It returns immediately. If a restart cannot be queued, the current filing result and accepted receipts remain available. The exhausted part stays unconfirmed. Check this filing again to retry the restart. A resumed part reports reason polling. A receipt without a pollable identifier stays unconfirmed. Webhooks are not offered yet.

Each rejected part has an errors array with the authority's code and authority_message. Known codes also have a title and explanation, and HMRC codes may have a help_url. Check each return separately. An earlier acceptance does not hide a retry rejection: HMRC error 3304 means an original return was already received for that period (see the HMRC validation rules). A retry is always your explicit instruction. Checking status never sends a return again.

Companies House retains its seven-day polling limit measured from submission. After that, a restart makes one check and stops again if the answer is still pending. Further GET requests can restart that check at most hourly. A final answer is kept.