> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update the HMRC settings for the current organisation > Updates the HMRC settings for the current organisation ## OpenAPI ````yaml /api-reference/specs/pay-api.yaml post /organisation/hmrc/settings openapi: 3.0.3 info: title: FlowPayroll API description: >- API for payroll management, including payroll upload, lock, HMRC submission, employee management version: 0.1.0 servers: - url: https://api.sandbox.flowpayroll.ai/v1 security: - XAuthToken: [] XOrgId: [] tags: - name: Employees description: >- Create, retrieve, update, and delete employee records, and look them up by NI number or payroll ID. - name: Starters & leavers description: Set and clear starter and leaver details, individually or in bulk. - name: Tax codes description: >- Manage employee tax codes and query the effective tax code and NI category on a given date. - name: NI & identifiers description: Manage NI categories, National Insurance numbers, and payroll IDs. - name: Student loans description: Start and end student and postgraduate loans. - name: Payroll setup description: Assign an employee's payroll config and set opening balances. - name: Payroll - name: Payroll lines - name: PayrollConfig - name: Pay Elements - name: Calculator - name: Payslip - name: RTI - name: YearEnd - name: Organisation paths: /organisation/hmrc/settings: post: tags: - Organisation summary: Update the HMRC settings for the current organisation description: Updates the HMRC settings for the current organisation operationId: updateHmrcSettings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatableHmrcSettingsDto' responses: '200': description: The HMRC settings were updated content: application/json: schema: allOf: - $ref: '#/components/schemas/ResponseBody' - type: object properties: data: $ref: '#/components/schemas/HmrcSettingsDto' '400': description: The request is invalid content: application/json: schema: $ref: '#/components/schemas/ResponseBody' '500': description: An error occurred content: application/json: schema: $ref: '#/components/schemas/ResponseBody' components: schemas: UpdatableHmrcSettingsDto: type: object allOf: - $ref: '#/components/schemas/HmrcSettingsCommonDto' - type: object properties: governmentGatewaySettings: $ref: '#/components/schemas/UpdatableGovernmentGatewaySettingsDto' required: - governmentGatewaySettings ResponseBody: type: object properties: message: $ref: '#/components/schemas/MessageWithTokenResponse' content: type: object properties: data: type: object nullable: true metadata: type: object nullable: true properties: dateFormat: type: string default: yyyy-MM-dd dateTimeFormat: type: string default: yyyy-MM-ddTHH:mm:ss.fffZ paginationToken: type: string nullable: true validationIssues: type: array items: $ref: '#/components/schemas/ValidationIssue' messageToken: type: string HmrcSettingsDto: type: object allOf: - $ref: '#/components/schemas/HmrcSettingsCommonDto' - type: object properties: governmentGatewaySettings: $ref: '#/components/schemas/GovernmentGatewaySettingsDto' organisationId: type: string example: org_123 createdDate: type: string format: date-time example: '2025-01-01T00:00:00Z' createdBy: type: string example: user_123 updatedBy: type: string example: user_456 updatedDate: type: string format: date-time example: '2025-01-02T00:00:00Z' required: - governmentGatewaySettings - organisationId - createdDate - createdBy - updatedBy - updatedDate HmrcSettingsCommonDto: type: object properties: taxReferenceNumbers: $ref: '#/components/schemas/TaxReferenceNumbersDto' isCisContractor: type: boolean description: >- Whether the organisation is a CIS(Construction Industry Scheme) contractor example: false employmentAllowanceSettings: $ref: '#/components/schemas/EmploymentAllowanceSettingsDto' nullable: true apprenticeshipLevySettings: $ref: '#/components/schemas/ApprenticeshipLevySettingsDto' nullable: true payeLiabilitySettings: $ref: '#/components/schemas/PayeLiabilitySettingsDto' nullable: true hasSmallEmployerRelief: type: boolean description: Whether the organisation has a small employer relief example: false bankAccount: $ref: '#/components/schemas/OrganisationBankAccountDto' nullable: true required: - taxReferenceNumbers - isCisContractor - hasSmallEmployerRelief UpdatableGovernmentGatewaySettingsDto: type: object properties: credentials: $ref: '#/components/schemas/CreateGovernmentGatewayCretentialsDto' nullable: true description: >- Organisation credentials. Required when hmrcSubmissionMethod is Direct; omit or null when Agent. hmrcSubmissionMethod: type: string enum: - Agent - Direct example: Direct agentCredentials: $ref: '#/components/schemas/CreateAgentGovernmentGatewayCretentialsDto' nullable: true description: >- Agent credentials. Required when hmrcSubmissionMethod is Agent; omit or null when Direct. required: - hmrcSubmissionMethod MessageWithTokenResponse: type: object properties: text: type: string token: type: string tokenArguments: type: array items: $ref: '#/components/schemas/ValidationIssueArgument' ValidationIssue: type: object description: > Field validation item. `reasonToken` is a stable snake_case key for i18n or custom client messages; `reason` is the default English text from the API. properties: field: type: string description: Dot-path of the field (e.g. name.firstName, address.line1). reason: type: string description: Default human-readable message. reasonToken: type: string description: Machine-readable error identifier (snake_case). reasonTokenArguments: type: array nullable: true items: $ref: '#/components/schemas/ValidationIssueArgument' GovernmentGatewaySettingsDto: type: object properties: credentials: $ref: '#/components/schemas/GovernmentGatewayCretentialsDto' nullable: true description: >- Organisation credentials. Present when hmrcSubmissionMethod is Direct. hmrcSubmissionMethod: type: string enum: - Agent - Direct example: Direct agentCredentials: $ref: '#/components/schemas/AgentGovernmentGatewayCretentialsDto' nullable: true description: Agent credentials. Present when hmrcSubmissionMethod is Agent. required: - hmrcSubmissionMethod TaxReferenceNumbersDto: type: object properties: employerPayeReference: $ref: '#/components/schemas/PayeReferenceNumberDto' accountsOfficeReference: type: string description: Accounts office reference. example: 123PX00123456 selfAssessmentUniqueTaxpayerReference: type: string nullable: true description: Self assessment unique taxpayer reference. example: '1234567890' corporationTaxReferenceUniqueTaxpayerReference: type: string nullable: true description: Corporation tax reference unique taxpayer reference. example: '1234567890' required: - employerPayeReference - accountsOfficeReference EmploymentAllowanceSettingsDto: type: object properties: isEnabled: type: boolean description: Whether the organisation is eligible for employment allowance example: true claimStatus: type: string description: The status of the employment allowance claim enum: - NotClaimed - Claimed - NotEligible example: Claimed deMinimisStateAidSectors: type: array items: type: string enum: - Agriculture - FisheriesAndAquaculture - RoadTransport - Industry - NA description: The sectors that apply for de minimis state aid rules nullable: true example: - Agriculture - Industry required: - isEnabled - claimStatus ApprenticeshipLevySettingsDto: type: object properties: isEnabled: type: boolean description: Whether the organisation has an apprenticeship levy example: true annualAllowanceAmount: type: number format: decimal description: >- The annual apprenticeship levy allowance amount set for the organisation example: 15000 required: - isEnabled - annualAllowanceAmount PayeLiabilitySettingsDto: type: object properties: payFrequency: type: string description: The frequency of PAYE payments enum: - Monthly - Quarterly example: Monthly required: - payFrequency OrganisationBankAccountDto: type: object properties: accountNumber: type: string description: Account number example: '12345678' sortCode: type: string description: Sort code example: 12-34-56 accountHolderName: type: string description: Account holder name example: Acme Corporation Limited buildingSocietyReference: type: string description: Building society reference nullable: true example: BS123456 required: - accountNumber - sortCode - accountHolderName CreateGovernmentGatewayCretentialsDto: type: object properties: userId: type: string description: User id of the gateway credentials. example: user123 password: type: string description: Password of the gateway credentials. example: password123 required: - userId - password CreateAgentGovernmentGatewayCretentialsDto: type: object allOf: - $ref: '#/components/schemas/CreateGovernmentGatewayCretentialsDto' - type: object properties: agentId: type: string nullable: true description: >- Optional agent id (for reference/audit only; not sent in GovTalk envelope). example: agent_123 ValidationIssueArgument: type: object properties: name: type: string value: type: string GovernmentGatewayCretentialsDto: type: object properties: userId: type: string description: User id of the gateway credentials. example: user123 password: type: string description: Omitted or masked in responses; never returned in full. example: '***' hasPassword: type: boolean description: Indicates whether a password is set (informational). example: true required: - userId - hasPassword AgentGovernmentGatewayCretentialsDto: type: object allOf: - $ref: '#/components/schemas/GovernmentGatewayCretentialsDto' - type: object properties: agentId: type: string nullable: true description: Optional agent id (for reference/audit only). example: agent_123 PayeReferenceNumberDto: type: object properties: officeNumber: type: string description: HMRC Office number. example: '123' referenceNumber: type: string description: Company's unique reference number. example: AB12345 required: - officeNumber - referenceNumber securitySchemes: XAuthToken: type: apiKey in: header name: X-Auth-Token description: Access token obtained from OAuth2 client credentials flow XOrgId: type: apiKey in: header name: X-Org-Id description: >- Organisation to scope the request to. Required when the principal can access more than one organisation; optional for single-organisation principals (the authorizer resolves it automatically). ````