Partner Filing API endpoints

Latest version
Version 1.2.0 Beta
Last updated
10 November 2026
API type
REST
Sandbox base URL
Provided with sandbox access
Production base URL
https://www.simplecompanytax.co.uk/api/v1
Developer documentation

Filings

Prepare filings, poll each requested return and download documents.

Prepare or submit the selected HMRC CT600 filing

Send prepared figures and the applicable declaration. A dry run never submits. A complete request is admitted asynchronously and a long period retains both return outcomes. Repeat the same request with the same idempotency key to read its current view. A completed replay can contain the final dry-run results.

POST/api/v1/filings/ct600

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstringUse 1 to 200 printable non-space characters. Repeat the same key only with the same request. A deliberately new filing uses a new key.

Request body

application/json, schema FilingRequest

NameTypeDescription
formRequiredobjectShared filing fields
declarantRequiredobject
declarant.forenameRequiredstring1 to 120 characters
declarant.surnameRequiredstring1 to 120 characters
declarant.accounts_approval_datestring
declarant.original_accounts_approval_datestring
declarant.club_signatory_statusstringUp to 80 characters
credentialsobject
credentials.hmrcobject
credentials.hmrc.user_idRequiredstring1 to 200 characters
credentials.hmrc.passwordRequiredstring1 to 500 characters
credentials.company_auth_codestring1 to 50 characters
dry_runbooleanDefault false
retry_ofstring (uuid)
amendmentobject
amendment.sourceRequired"internal"
amendment.original_engagement_idstring (uuid)
amendment.original_filing_idstring (uuid)
amendment.setupobject
amendment.reasonstringUp to 500 characters
amendment.method"replacement"Default "replacement"
amendment.approval_datestring
amendment.ch_filing_kind"revision" | "full_accounts" | "original"
amendment.sourceRequired"external"
amendment.setupobject
amendment.reasonstringUp to 500 characters
amendment.method"replacement"Default "replacement"
amendment.approval_datestring
amendment.ch_filing_kind"revision" | "full_accounts" | "original"

Responses

  • 200Incomplete dry run. Supply the named answers and any customer-entered allocations. No filing operation is created.Body: IncompleteDryRunEnvelope · Headers: X-Request-Id
  • 202Operation admitted or replayed. Read the current view, which may already be final on a same-key replay. Admission does not mean authority acceptance.Body: FilingEnvelope · Headers: X-Request-Id
  • 400
    • INVALID_REQUEST: Check the request fields.
    • INPUT_REQUIRED: Complete the named fields before filing.
    • IDEMPOTENCY_KEY_REQUIRED: Send an Idempotency-Key of 1 to 200 printable characters.
    • RETRY_NOT_AVAILABLE: Only an unchanged filing from the same operation and environment can be sent again with retry_of.
    Body: Error · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 402
    • FILING_SLOT_UNAVAILABLE: An active Practice plan with an available filing slot is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 409
    • DRAFT_CHANGED: The saved filing changed. Review it and submit with a new idempotency key.
    • IDEMPOTENCY_KEY_CONFLICT: This idempotency key was already used with a different request.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Prepare or submit Companies House accounts

Send prepared figures and the applicable declaration for the Companies House operation. Dry runs do not submit. A CIC uses its existing customer-upload package route. Read package_only and customer_action before deciding whether completion means authority acceptance or a package ready for customer upload.

POST/api/v1/filings/accounts

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstringUse 1 to 200 printable non-space characters. Repeat the same key only with the same request. A deliberately new filing uses a new key.

Request body

application/json, schema FilingRequest

NameTypeDescription
formRequiredobjectShared filing fields
declarantRequiredobject
declarant.forenameRequiredstring1 to 120 characters
declarant.surnameRequiredstring1 to 120 characters
declarant.accounts_approval_datestring
declarant.original_accounts_approval_datestring
declarant.club_signatory_statusstringUp to 80 characters
credentialsobject
credentials.hmrcobject
credentials.hmrc.user_idRequiredstring1 to 200 characters
credentials.hmrc.passwordRequiredstring1 to 500 characters
credentials.company_auth_codestring1 to 50 characters
dry_runbooleanDefault false
retry_ofstring (uuid)
amendmentobject
amendment.sourceRequired"internal"
amendment.original_engagement_idstring (uuid)
amendment.original_filing_idstring (uuid)
amendment.setupobject
amendment.reasonstringUp to 500 characters
amendment.method"replacement"Default "replacement"
amendment.approval_datestring
amendment.ch_filing_kind"revision" | "full_accounts" | "original"
amendment.sourceRequired"external"
amendment.setupobject
amendment.reasonstringUp to 500 characters
amendment.method"replacement"Default "replacement"
amendment.approval_datestring
amendment.ch_filing_kind"revision" | "full_accounts" | "original"

Responses

  • 200Incomplete dry run. Supply the named answers and any customer-entered allocations. No filing operation is created.Body: IncompleteDryRunEnvelope · Headers: X-Request-Id
  • 202Operation admitted or replayed. Read the current view, which may already be final on a same-key replay. Admission does not mean authority acceptance.Body: FilingEnvelope · Headers: X-Request-Id
  • 400
    • INVALID_REQUEST: Check the request fields.
    • INPUT_REQUIRED: Complete the named fields before filing.
    • IDEMPOTENCY_KEY_REQUIRED: Send an Idempotency-Key of 1 to 200 printable characters.
    • RETRY_NOT_AVAILABLE: Only an unchanged filing from the same operation and environment can be sent again with retry_of.
    Body: Error · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 402
    • FILING_SLOT_UNAVAILABLE: An active Practice plan with an available filing slot is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 409
    • DRAFT_CHANGED: The saved filing changed. Review it and submit with a new idempotency key.
    • IDEMPOTENCY_KEY_CONFLICT: This idempotency key was already used with a different request.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

List this key environment’s filings

Read up to 50 filings in descending filing ID order. IDs are random UUIDs, so this is not creation order. Pass next_cursor as cursor until it is null. A full final page can be followed by an empty page. This call does not restart exhausted polling.

GET/api/v1/filings

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
cursorquerystringUse next_cursor from the preceding page. Omit it for the first page. The page size is fixed at 50.

Responses

  • 200Current filing views and the continuation cursor.Body: FilingListEnvelope · Headers: X-Request-Id
  • 400
    • INVALID_REQUEST: Check the request fields.
    Body: Error · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Read the filing and each requested part’s current outcome

Poll this filing for dry-run completion or authority outcomes. Inspect every requested return. Pending views include Retry-After: 30. Checking restarts exhausted authority polling at most hourly per part and never resends a return. If a restart cannot be queued, the current view and accepted receipts remain readable.

GET/api/v1/filings/{id}

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
idRequiredpathstringThe filing ID returned by a filing POST in this key environment.

Responses

  • 200The current filing view, including final results when available.Body: FilingEnvelope · Headers: X-Request-Id, Retry-After
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Read environment-scoped document download links

Read documents from this filing’s current job attempt. Links are scoped to the Practice and key environment. An operation without prepared documents returns an empty list. Dry runs expose permitted watermarked draft documents, not submission files. A CIC package becomes available after successful package completion.

GET/api/v1/filings/{id}/documents

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
idRequiredpathstringThe filing ID returned by a filing POST in this key environment.

Responses

  • 200Visible documents and their download URLs, or an empty list.Body: DocumentListEnvelope · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Accounts uploads

Upload customer-prepared accounts and obtain an immutable file reference.

Start a customer-prepared accounts upload

Reserve an accounts object for this Practice and environment. For a live key, PUT the file bytes to url with every returned header within ten minutes. The upload is create-only and must match the declared size. A test key returns SANDBOX_FIXTURE and no upload URL, so go straight to finalisation.

POST/api/v1/uploads/accounts

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Request body

application/json, schema AccountsUploadRequest

NameTypeDescription
companyRequiredobject
company.entity_kind"registered_company" | "unincorporated_club"Default "registered_company"
company.company_numberstringPattern ^[A-Za-z0-9]{8}$
company.utrstringPattern ^\d{10}$
company.nameRequiredstring1 to 160 characters
filenameRequiredstringPattern ^[A-Za-z0-9][A-Za-z0-9_.-]{0,94}\.(pdf|xhtml|html)$
sizeRequiredinteger0 to 15000000

Responses

  • 201Live signed-upload instructions or a sandbox fixture reservation.Body: AccountsUploadEnvelope · Headers: X-Request-Id
  • 400
    • INVALID_REQUEST: Check the request fields.
    Body: Error · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Verify an uploaded accounts object and return its immutable file reference

Finalise the objectName returned by upload creation. Live finalisation reads the uploaded immutable version and checks its size and PDF signature where applicable. Test finalisation returns deterministic fixture metadata. Supply the returned accountsFile reference in the filing request.

PUT/api/v1/uploads/accounts

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Request body

application/json, schema AccountsUploadFinaliseRequest

NameTypeDescription
objectNameRequiredstring1 to 600 characters

Responses

  • 200The immutable accounts file reference for a filing request.Body: AccountsFileEnvelope · Headers: X-Request-Id
  • 400
    • INVALID_REQUEST: Check the request fields.
    Body: Error · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Companies

Read company details and public director suggestions.

Look up company details or a deterministic sandbox company

Read company profile fields and current director suggestions before preparing a filing. Test keys return the deterministic sandbox company. Director suggestions are public register data and do not make the customer’s declaration or establish filing authority.

GET/api/v1/companies/{number}

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Parameters

NameInTypeDescription
numberRequiredpathstringThe eight-character company number. Letters are accepted in either case. Test keys use a documented sandbox number.

Responses

  • 200Company profile fields and director suggestions.Body: CompanyViewEnvelope · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 404
    • NOT_FOUND: The resource was not found.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Account

Read the Practice identity and request limits.

Read the Practice and request limits

Read the Practice associated with this key, its test or live environment and the current request limits. Dry-run limits apply per organisation per day.

GET/api/v1/account

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Responses

  • 200Practice identity, key environment and request limits.Body: AccountViewEnvelope · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Health

Check authenticated access in the key environment.

Check authenticated API health

Check authenticated access for this key environment. This call passes the same key, approval and request-limit boundary as the other endpoints. Its version field identifies the v1 route family.

GET/api/v1/health

Authorisation

Bearer key in the Authorization header: sct_test_<secret> or sct_live_<secret>

Responses

  • 200Authenticated API health in this key environment.Body: HealthViewEnvelope · Headers: X-Request-Id
  • 401
    • INVALID_API_KEY: A valid Bearer API key is required.
    Body: Error · Headers: X-Request-Id
  • 403
    • LIVE_KEYS_NOT_ENABLED: Live API access is not enabled for this Practice.
    Body: Error · Headers: X-Request-Id
  • 429
    • RATE_LIMITED: The API request limit has been reached.
    Body: Error · Headers: X-Request-Id, Retry-After
  • 503
    • SERVICE_UNAVAILABLE: The API is temporarily unavailable.
    Body: Error · Headers: X-Request-Id, Retry-After

Response bodies

IncompleteDryRunEnvelope

NameTypeDescription
dataRequiredIncompleteDryRunMissing answers and allocation suggestions. No filing operation is created.
data.stateRequired"incomplete"incomplete means answers are missing and no filing operation was created.
data.periodsPartnerFilingPeriodContextAccounts dates, Corporation Tax coverage and each return period. A long period can have two returns.
data.periods.accountsRequiredobjectThe accounts coverage.
data.periods.accounts.startRequiredstringAccounts start date.
data.periods.accounts.endRequiredstringAccounts end date.
data.periods.tax_coverageRequiredobjectThe Corporation Tax coverage.
data.periods.tax_coverage.startRequiredstringTax coverage start date.
data.periods.tax_coverage.endRequiredstringTax coverage end date.
data.periods.returnsRequiredarray of objectEach Corporation Tax return in order.
data.periods.returns[].indexRequirednumberZero-based return index.
data.periods.returns[].startRequiredstringReturn start date.
data.periods.returns[].endRequiredstringReturn end date.
data.fieldsRequiredobjectField keys and messages identifying answers the caller can supply or correct.
data.suggested_allocationsRequiredarray of objectSuggested amounts for customer review. They are not confirmed or applied automatically.
data.suggested_allocations[].fieldRequiredstringThe amount needing a customer-entered allocation.
data.suggested_allocations[].returnsRequiredarray of objectThe return periods to which the amounts correspond.
data.suggested_allocations[].returns[].periodStartRequiredstringThe start date of this return.
data.suggested_allocations[].returns[].periodEndRequiredstringThe end date of this return.
data.suggested_allocations[].amountsRequiredarray of numberSuggested amounts in return order. The customer supplies the allocation.
data.previewsRequiredarray of anyEmpty for an incomplete dry run. No filing-ready totals or documents are provided.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

FilingEnvelope

NameTypeDescription
dataRequiredFilingViewThe current filing operation view and each requested return's outcome.
data.idRequiredstringThe filing operation ID used by polling and document endpoints.
data.environmentRequired"test" | "live"The environment bound to the key.
data.operationRequired"ct600" | "accounts"The requested filing operation.
data.dry_runRequiredbooleanTrue for a dry run. A dry run never submits to an authority.
data.package_onlyRequiredbooleanTrue when completion means a customer-upload package is ready rather than authority acceptance.
data.periodsPartnerFilingPeriodContextAccounts dates, Corporation Tax coverage and each return period. A long period can have two returns.
data.periods.accountsRequiredobjectThe accounts coverage.
data.periods.accounts.startRequiredstringAccounts start date.
data.periods.accounts.endRequiredstringAccounts end date.
data.periods.tax_coverageRequiredobjectThe Corporation Tax coverage.
data.periods.tax_coverage.startRequiredstringTax coverage start date.
data.periods.tax_coverage.endRequiredstringTax coverage end date.
data.periods.returnsRequiredarray of objectEach Corporation Tax return in order.
data.periods.returns[].indexRequirednumberZero-based return index.
data.periods.returns[].startRequiredstringReturn start date.
data.periods.returns[].endRequiredstringReturn end date.
data.customer_actionobjectThe customer action for a package-only filing, when applicable.
data.customer_action.typeRequired"upload_cic_package"The required customer action: upload the prepared CIC package.
data.customer_action.urlRequiredstringThe service where the customer uploads the prepared package.
data.statusRequired"pending" | "accepted" | "partially_accepted" | "rejected" | "error" | "complete" | "incomplete"pending: work or an authority outcome is outstanding. accepted: all requested parts accepted. partially_accepted: at least one part accepted and none is pending, but another was unsuccessful. rejected: all requested parts were rejected or failed authentication. error: execution or another non-acceptance error. complete: a dry run or package completed successfully. incomplete: a completed dry run or package is not filing-ready.
data.engagement_idRequiredstringThe associated saved engagement ID.
data.partsRequiredarray of FilingPartCurrent outcomes for this operation’s requested parts. Inspect both returns of a long period.
data.parts[].partRequiredstringThe requested part, such as hmrc:0, hmrc:1 or companies_house.
data.parts[].authorityRequired"hmrc" | "companies_house"The authority associated with this part.
data.parts[].statusRequiredstringCurrent part outcome. Pending, polling, reserved and unknown states do not establish acceptance. accepted is final acceptance. rejected or auth_failed records a refusal. Error or known-unsent states need the reason and receipt to determine the next action.
data.parts[].reasonRequiredstring or nullThe recorded reason for this part’s current outcome, or null.
data.parts[].errorsRequiredarray of objectAuthority codes and text for this attempt, with catalogue explanations where known.
data.parts[].errors[].codeRequiredstring or nullThe authority error code, or null when none was supplied.
data.parts[].errors[].authority_messageRequiredstringThe authority’s original error text.
data.parts[].errors[].titlestringA catalogue title for a known authority code.
data.parts[].errors[].explanationstringA plain explanation for a known authority code.
data.parts[].errors[].help_urlstringAn official help link where supplied by the catalogue.
data.parts[].receiptRequiredobjectThis attempt’s receipt fields. Authority-specific fields remain open.
data.created_atRequiredstringThe operation creation timestamp.
data.resultobjectCompleted dry-run or package results. Not an authority acceptance receipt.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

FilingListEnvelope

NameTypeDescription
dataRequiredFilingListA page of current filing views and its continuation cursor.
data.filingsRequiredarray of FilingViewCurrent filing views in descending filing ID order, up to 50 per page.
data.filings[].idRequiredstringThe filing operation ID used by polling and document endpoints.
data.filings[].environmentRequired"test" | "live"The environment bound to the key.
data.filings[].operationRequired"ct600" | "accounts"The requested filing operation.
data.filings[].dry_runRequiredbooleanTrue for a dry run. A dry run never submits to an authority.
data.filings[].package_onlyRequiredbooleanTrue when completion means a customer-upload package is ready rather than authority acceptance.
data.filings[].periodsPartnerFilingPeriodContextAccounts dates, Corporation Tax coverage and each return period. A long period can have two returns.
data.filings[].periods.accountsRequiredobjectThe accounts coverage.
data.filings[].periods.accounts.startRequiredstringAccounts start date.
data.filings[].periods.accounts.endRequiredstringAccounts end date.
data.filings[].periods.tax_coverageRequiredobjectThe Corporation Tax coverage.
data.filings[].periods.tax_coverage.startRequiredstringTax coverage start date.
data.filings[].periods.tax_coverage.endRequiredstringTax coverage end date.
data.filings[].periods.returnsRequiredarray of objectEach Corporation Tax return in order.
data.filings[].periods.returns[].indexRequirednumberZero-based return index.
data.filings[].periods.returns[].startRequiredstringReturn start date.
data.filings[].periods.returns[].endRequiredstringReturn end date.
data.filings[].customer_actionobjectThe customer action for a package-only filing, when applicable.
data.filings[].customer_action.typeRequired"upload_cic_package"The required customer action: upload the prepared CIC package.
data.filings[].customer_action.urlRequiredstringThe service where the customer uploads the prepared package.
data.filings[].statusRequired"pending" | "accepted" | "partially_accepted" | "rejected" | "error" | "complete" | "incomplete"pending: work or an authority outcome is outstanding. accepted: all requested parts accepted. partially_accepted: at least one part accepted and none is pending, but another was unsuccessful. rejected: all requested parts were rejected or failed authentication. error: execution or another non-acceptance error. complete: a dry run or package completed successfully. incomplete: a completed dry run or package is not filing-ready.
data.filings[].engagement_idRequiredstringThe associated saved engagement ID.
data.filings[].partsRequiredarray of FilingPartCurrent outcomes for this operation’s requested parts. Inspect both returns of a long period.
data.filings[].parts[].partRequiredstringThe requested part, such as hmrc:0, hmrc:1 or companies_house.
data.filings[].parts[].authorityRequired"hmrc" | "companies_house"The authority associated with this part.
data.filings[].parts[].statusRequiredstringCurrent part outcome. Pending, polling, reserved and unknown states do not establish acceptance. accepted is final acceptance. rejected or auth_failed records a refusal. Error or known-unsent states need the reason and receipt to determine the next action.
data.filings[].parts[].reasonRequiredstring or nullThe recorded reason for this part’s current outcome, or null.
data.filings[].parts[].errorsRequiredarray of objectAuthority codes and text for this attempt, with catalogue explanations where known.
data.filings[].parts[].errors[].codeRequiredstring or nullThe authority error code, or null when none was supplied.
data.filings[].parts[].errors[].authority_messageRequiredstringThe authority’s original error text.
data.filings[].parts[].errors[].titlestringA catalogue title for a known authority code.
data.filings[].parts[].errors[].explanationstringA plain explanation for a known authority code.
data.filings[].parts[].errors[].help_urlstringAn official help link where supplied by the catalogue.
data.filings[].parts[].receiptRequiredobjectThis attempt’s receipt fields. Authority-specific fields remain open.
data.filings[].created_atRequiredstringThe operation creation timestamp.
data.filings[].resultobjectCompleted dry-run or package results. Not an authority acceptance receipt.
data.next_cursorRequiredstring or nullPass this value as cursor until it is null. A full final page may be followed by an empty page.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

DocumentListEnvelope

NameTypeDescription
dataRequiredDocumentListVisible documents from this filing's current job attempt.
data.documentsRequiredarray of objectDocuments visible for the current job attempt. The list can be empty.
data.documents[].idRequiredstringThe document artefact ID.
data.documents[].filenameRequiredstring or nullThe download filename, when recorded.
data.documents[].mime_typeRequiredstring or nullThe document MIME type, when recorded.
data.documents[].size_bytesRequirednumber or nullRecorded document size in bytes, or null.
data.documents[].checksumRequiredstring or nullRecorded document checksum, or null.
data.documents[].artefact_typeRequiredstring or nullThe document type. Visibility depends on the filing and server configuration.
data.documents[].urlRequiredstring or nullA signed download URL, or null when no stored object is linked.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

AccountsUploadEnvelope

NameTypeDescription
dataRequiredAccountsUploadLive signed-upload instructions or sandbox fixture instructions.
data.objectNameRequiredstringLive upload reservation. The reserved accounts object name. Use it in the finalise call.
data.filenameRequiredstringLive upload reservation. The declared filename.
data.urlRequiredstringLive upload reservation. Live upload URL. PUT the file bytes with every returned header within ten minutes.
data.headersRequiredobjectLive upload reservation. Send every header with the live PUT. The object must be new and its size must equal the declared size.
data.objectNameRequiredstringSandbox fixture reservation. The reserved fixture object name. Use it in the finalise call.
data.filenameRequiredstringSandbox fixture reservation. The declared filename.
data.upload_urlRequired"null" or nullSandbox fixture reservation. No file upload takes place in the sandbox.
data.methodRequired"SANDBOX_FIXTURE"Sandbox fixture reservation. Go straight to finalisation for the deterministic fixture.
data.messageRequiredstringSandbox fixture reservation. Sandbox fixture instructions.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

AccountsFileEnvelope

NameTypeDescription
dataRequiredAccountsFileAn immutable accounts file reference.
data.accountsFileRequiredobjectSupply this immutable file reference in the filing request.
data.accountsFile.formatRequired"pdf" | "ixbrl"The accounts file format.
data.accountsFile.objectNameRequiredstringThe reserved storage object name.
data.accountsFile.versionRequiredstringThe immutable object generation. The sandbox uses its fixture version.
data.accountsFile.sha256RequiredstringThe SHA-256 digest of the finalised file bytes.
data.accountsFile.filenameRequiredstringThe accounts filename.
data.accountsFile.sizeRequirednumberThe finalised file size in bytes.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

CompanyViewEnvelope

NameTypeDescription
dataRequiredCompanyViewCompany profile and public director suggestions. Additional register fields remain open.
data.company_numberstringThe company number returned by the lookup.
data.company_namestringThe company name returned by the lookup.
data.company_statusstringThe company status reported by the register.
data.typestringThe company legal type.
data.subtypestringThe company subtype, when supplied.
data.jurisdictionstringThe company jurisdiction.
data.date_of_creationstringThe incorporation date reported by the register.
data.registered_office_addressobjectRegistered office fields supplied by the lookup.
data.registered_office_address.premisesstringPremises name or number.
data.registered_office_address.care_ofstringCare-of name.
data.registered_office_address.po_boxstringPost office box.
data.registered_office_address.address_line_1stringFirst address line.
data.registered_office_address.address_line_2stringSecond address line.
data.registered_office_address.localitystringTown or locality.
data.registered_office_address.regionstringRegion or county.
data.registered_office_address.postal_codestringPostal code.
data.registered_office_address.countrystringCountry.
data.accountsobjectAccounts information reported by the register.
data.accounts.accounting_reference_dateobjectThe accounting reference day and month.
data.accounts.accounting_reference_date.dayRequiredstring or numberReference day.
data.accounts.accounting_reference_date.monthRequiredstring or numberReference month.
data.accounts.last_accountsobjectPrevious accounts information.
data.accounts.last_accounts.period_start_onstringStart date reported by the company register.
data.accounts.last_accounts.period_end_onstringEnd date reported by the company register.
data.accounts.last_accounts.made_up_tostringAccounts made-up-to date, when supplied.
data.accounts.last_accounts.due_onstringFiling due date reported by the register.
data.accounts.last_accounts.typestringAccounts type reported by the register.
data.accounts.last_accounts.overduebooleanWhether the register marks these accounts overdue.
data.accounts.next_accountsobjectNext accounts information.
data.accounts.next_accounts.period_start_onstringStart date reported by the company register.
data.accounts.next_accounts.period_end_onstringEnd date reported by the company register.
data.accounts.next_accounts.made_up_tostringAccounts made-up-to date, when supplied.
data.accounts.next_accounts.due_onstringFiling due date reported by the register.
data.accounts.next_accounts.typestringAccounts type reported by the register.
data.accounts.next_accounts.overduebooleanWhether the register marks these accounts overdue.
data.accounts.next_made_up_tostringNext accounts made-up-to date.
data.accounts.next_duestringNext accounts due date.
data.accounts.overduebooleanWhether accounts are overdue.
data.directorsRequiredarray of objectCurrent director suggestions. They do not establish filing authority.
data.directors[].nameRequiredstringPublic register name. This does not make a filing declaration.
data.directors[].roleRequiredstringPublic register officer role.
data.directors[].appointedOnRequiredstring or nullAppointment date, or null when unavailable.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

AccountViewEnvelope

NameTypeDescription
dataRequiredAccountViewPractice identity and current request limits.
data.organisationRequiredobjectThe Practice associated with this API key.
data.organisation.idRequiredstringThe Practice organisation ID.
data.organisation.nameRequiredstring or nullThe Practice name.
data.environmentRequired"test" | "live"The environment bound to the API key.
data.limitsRequiredobjectThe current API request limits.
data.limits.requests_per_minuteRequirednumberRequests allowed per key per minute.
data.limits.requests_per_dayRequirednumberRequests allowed per key per day.
data.limits.dry_runs_per_organisation_dayRequirednumberDry runs allowed per Practice per day.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

HealthViewEnvelope

NameTypeDescription
dataRequiredHealthViewAuthenticated health and key environment.
data.statusRequired"ok"The authenticated health check succeeded.
data.versionRequired"v1"The API route family, not the contract revision number.
data.environmentRequired"test" | "live"The environment bound to the API key.
request_idRequiredstring (uuid)Request identifier for this HTTP call.

Browse complete request examples or download all complete request examples.

Next: Filing fields