API Docs / Schemas / SendHmrcAuthorisationRequestDto

SendHmrcAuthorisationRequestDto

Request to send HMRC agent authorisation requests for multiple types at once.
Supports both digital (MTD) and letter-based (SA, CT, PAYE/CIS) flows transparently.

Properties

Name Type Description
authorisationTypes*array of enum

The auth types to request (must have an [HmrcDigitalAuth] attribute)

SelfAssessment CorporationTax PayeForEmployers IndividualPayAsYouEarn VAT ConstructionIndustryScheme TaxCredits HighIncomeChildBenefitCharge MakingTaxDigitalIncomeTax MakingTaxDigitalVat Trusts

The auth types to request (must have an [HmrcDigitalAuth] attribute)

SelfAssessment CorporationTax PayeForEmployers IndividualPayAsYouEarn VAT ConstructionIndustryScheme TaxCredits HighIncomeChildBenefitCharge MakingTaxDigitalIncomeTax MakingTaxDigitalVat Trusts

clientIdstring

The HMRC client identifier (NINO for MTD-IT, VRN for MTD-VAT).
Required for digital flow types. Ignored for letter-based types (resolved from client data).

The HMRC client identifier (NINO for MTD-IT, VRN for MTD-VAT).
Required for digital flow types. Ignored for letter-based types (resolved from client data).

knownFactstring

The known fact for verification (postcode for MTD-IT, VAT reg date for MTD-VAT).
Required for digital flow types. Ignored for letter-based types.

The known fact for verification (postcode for MTD-IT, VAT reg date for MTD-VAT).
Required for digital flow types. Ignored for letter-based types.

recipientEmailsarray of string

Email addresses to send the authorisation links to. Not required if SuppressEmail is true.

Email addresses to send the authorisation links to. Not required if SuppressEmail is true.

postcodestring

The client's postcode. Used for SA and CT letter-based requests (required by HMRC schema).
If not provided, extracted from the client's contact address.

The client's postcode. Used for SA and CT letter-based requests (required by HMRC schema).
If not provided, extracted from the client's contact address.

ninostring

National Insurance number. Used for SA letter-based requests (optional).
If not provided, resolved from the client's main contact.

National Insurance number. Used for SA letter-based requests (optional).
If not provided, resolved from the client's main contact.

accountsOfficeRefstring

Accounts Office Reference. Used for PAYE and CIS letter-based requests.
If not provided, resolved from the client's business details.

Accounts Office Reference. Used for PAYE and CIS letter-based requests.
If not provided, resolved from the client's business details.

companyRegNumberstring

Companies House registration number. Used for CT letter-based requests.
If not provided, resolved from the client's business details.

Companies House registration number. Used for CT letter-based requests.
If not provided, resolved from the client's business details.

yourReferencestring

Your internal reference for this client. Used in all letter-based requests.
If not provided, defaults to InternalReference or client code.

Your internal reference for this client. Used in all letter-based requests.
If not provided, defaults to InternalReference or client code.

suppressEmailboolean

If true, create the invitations with HMRC but do not send the email to the client.

If true, create the invitations with HMRC but do not send the email to the client.

authCodeEntryDelayDaysinteger

For letter-based requests: how many days after this request to email the client the link they
use to enter the code HMRC posts them. 0 sends it as soon as HMRC accept the request.
Null means do not invite the client at all — the practice will collect the code themselves.

For letter-based requests: how many days after this request to email the client the link they
use to enter the code HMRC posts them. 0 sends it as soon as HMRC accept the request.
Null means do not invite the client at all — the practice will collect the code themselves.

JSON Example

{
  "authorisationTypes": [
    "SelfAssessment"
  ],
  "clientId": "string",
  "knownFact": "string",
  "recipientEmails": [
    "string"
  ],
  "postcode": "string"
}

Used By Operations