Set the accounting period from Companies House

POSThttps://app.speybooks.com/api/v1/organisation/accounting-period

Set the organisation's accounting period from Companies House. Supply the company number; the period boundary is read from source at the moment of the write, never taken from the request, so a stale or altered client value cannot reach the sealed boundary.

On a confirmed active company this records the legal form (the entity gate for Corporation Tax), the confirmed company number, and the recurring accounting reference date, and sets the financial period to the next-accounts boundary returned by Companies House.

The period can only be set before any activity is recorded. Once a transaction, opening balance, or invoice journal has posted, the request is refused with organisation_not_empty and nothing is written.

Companies House failures are surfaced for a manual fallback rather than blocking: company_not_found (404) and companies_house_unavailable (503) both leave the period unset so it can be entered by hand; company_not_active (422) declines a company that is not active; invalid_company_number (400) is a malformed number that never reaches Companies House.

Body parameters

companyNumberstringrequired
Companies House number to confirm and seal the accounting period from (e.g. SC889983).

Response

200Accounting period set from the confirmed Companies House profile.
Show response fields
accountingReferenceDateobject
Show child attributes
dayinteger
monthinteger
companyNamestring
companyNumberstring
entityTypestring
periodobject
Show child attributes
yearEndstring
yearStartstring
periodSourcestring

Error codes

400The company number is malformed.
404Companies House has no record of that number.
409The organisation has posted activity; the period can no longer be set.
422The company is not active at Companies House.
503Companies House could not be reached.