{ "openapi": "3.0.4", "info": { "title": "CIS Manager API", "description": "The CIS Manager API. Every request is authenticated with an 'x-api-key' header or an Auth0 bearer token. Resources are scoped to a tenant: the {tenant} route parameter is the organisation's code.", "version": "v1" }, "paths": { "/me/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List My API Keys", "description": "The caller's API keys, newest first, expired ones included. The keys themselves are not returned: a key is shown once, when it is issued.", "operationId": "ListMyApiKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MyApiKeyDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create My API Key", "description": "Issues the caller an API key, which acts as them on every tenant they are a member of. The key is returned this once and cannot be read back. Bearer token only: 403 with an API key. 400 for an expiry date that is not in the future.", "operationId": "CreateMyApiKey", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateMyApiKeyRequest" } ], "description": "Issues the caller an API key (`POST /me/api-keys`)." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyNewApiKeyDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/api-keys/{key}": { "delete": { "tags": [ "API Keys" ], "summary": "Delete My API Key", "description": "Deletes the key: it stops authenticating at once. Bearer token only: 403 with an API key. 404 when the caller has no key with the code.", "operationId": "DeleteMyApiKey", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/profile": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Profile", "description": "The caller's billing details from their Account Hub billing account: the address invoices are made out to and the state of their Direct Debit. An account the caller already pays Sodium on is theirs here too (isShared: shown, changed in Sodium). Empty (no address, mandate NotStarted) until there is an account.", "operationId": "GetBillingProfile", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingProfileDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Billing" ], "summary": "Update Billing Profile", "description": "Replaces the caller's billing address (company name, invoice email, address, postcode, country) on their Account Hub billing account, making the account on first use. The mandate is untouched. 409 when the account also pays for Sodium. Returns the profile as GET does.", "operationId": "UpdateBillingProfile", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateBillingProfileRequest" } ], "description": "The billing address to put on the caller's invoices (`PUT /me/billing/profile`). A full replacement of\nthe address; the mandate is untouched." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingProfileDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/mandate": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Mandate", "description": "The caller's Direct Debit mandate, its status refreshed from GoCardless through Account Hub. 404 until there is one.", "operationId": "GetBillingMandate", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingMandateDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Billing" ], "summary": "Complete Mandate Setup", "description": "Completes a Direct Debit setup the customer has finished on GoCardless: the redirect_flow_id GoCardless appended to the success URL. Returns the mandate as GET does; invoices waiting for a mandate are then collected by Account Hub.", "operationId": "CompleteMandateSetup", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CompleteMandateSetupRequest" } ], "description": "Completes a Direct Debit setup the customer has finished on GoCardless (`PUT /me/billing/mandate`)." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingMandateDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Cancel Billing Mandate", "description": "Cancels the caller's Direct Debit mandate. Automatic payments stop; a new setup can be started at any time. 404 when there is no mandate; 409 when the account also pays for Sodium.", "operationId": "CancelBillingMandate", "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/mandate-setups": { "post": { "tags": [ "Billing" ], "summary": "Create Mandate Setup", "description": "Starts a Direct Debit setup with GoCardless through Account Hub, making the billing account on first use. Send the customer's browser to the returned redirectUrl; GoCardless sends it back to the successRedirectUrl with redirect_flow_id appended, and the client completes the setup with PUT /me/billing/mandate. 400 when the caller already has a mandate or GoCardless refused; 409 when the account also pays for Sodium.", "operationId": "CreateMandateSetup", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateMandateSetupRequest" } ], "description": "Starts a Direct Debit setup (`POST /me/billing/mandate-setups`)." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateSetupDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "List Billing Usage", "description": "The usage not yet charged, across every tenant the caller owns: each monthly return HMRC has accepted, with the subcontractors on it. Charged at the end of the month, on the next invoice.", "operationId": "ListBillingUsage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingUsageDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "List Billing Invoices", "description": "The caller's invoices from Sodium (Account Hub), latest first: their CIS Manager charges, with any other Sodium products the same billing account pays for, and CIS Manager's invoices from before the switch.", "operationId": "ListBillingInvoices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountInvoiceDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/invoices/{invoice}/pdf": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Invoice PDF", "description": "The invoice as the PDF that was emailed. 404 when the invoice is not the caller's or has no PDF yet (hasPdf).", "operationId": "GetBillingInvoicePdf", "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cis-details-requests/{request}": { "get": { "tags": [ "CIS Details Requests" ], "summary": "Get Public CIS Details Request", "description": "The request as the subcontractor sees it on the public form, with no credentials: who asked, whom, whether the details have been sent, the SDC statement to carry on to and, while unanswered, what the tenant already holds to start the form from (how they trade and their names, never a UTR or National Insurance number). It never returns the details sent. An unknown code is 404.", "operationId": "GetPublicCisDetailsRequest", "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCisDetailsRequestDto" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/cis-details-requests/{request}/details": { "put": { "tags": [ "CIS Details Requests" ], "summary": "Submit CIS Details", "description": "Sends the subcontractor's CIS details from the public form, with no credentials. They are held on the request for the tenant to review (the contact is not changed) and the tenant is told by email. 400 when a reference is malformed or what HMRC needs for the type is missing, 409 when the details have already been sent.", "operationId": "SubmitCisDetails", "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SubmitCisDetailsRequest" } ], "description": "The subcontractor's CIS details, from the public form. What is required depends on the type: a sole trader's\nfirst name, last name and UTR; a company's name and its UTR or company number; a trust's name and UTR; a\npartnership's name and UTR." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCisDetailsRequestDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/cis-details-requests": { "get": { "tags": [ "CIS Details Requests" ], "summary": "List Tenant CIS Details Requests", "description": "The tenant's CIS details requests in one status across all its subcontractors, the latest change first. The status defaults to Submitted: the details waiting for the tenant to review.", "operationId": "ListTenantCisDetailsRequests", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsRequestStatus" } ] }, "x-order": 200 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/cis-details-requests": { "get": { "tags": [ "CIS Details Requests" ], "summary": "List CIS Details Requests", "description": "The contact's CIS details requests, newest first. At most one is unfinished (Pending or Submitted).", "operationId": "ListCisDetailsRequests", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "CIS Details Requests" ], "summary": "Create CIS Details Request", "description": "Creates a pending request for the subcontractor and emails them a link to the public form where they enter their CIS details, with no account. With sdcStatementTitle, a pending SDC statement is created as well: the same email asks for both and the form leads on to the statement. 400 when the contact is not a CIS subcontractor, 409 when it already has an unfinished request.", "operationId": "CreateCisDetailsRequest", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateCisDetailsRequestRequest" } ], "description": "A new request for a subcontractor's CIS details. Creating it emails the subcontractor the link to the form." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/cis-details-requests/{request}": { "get": { "tags": [ "CIS Details Requests" ], "summary": "Get CIS Details Request", "description": "One of the contact's requests, with the details the subcontractor sent once they have.", "operationId": "GetCisDetailsRequest", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "CIS Details Requests" ], "summary": "Delete CIS Details Request", "description": "Cancels a pending request (the emailed link stops working) or discards details awaiting review. An SDC statement sent with it stays among the contact's statements. 409 for an accepted request.", "operationId": "DeleteCisDetailsRequest", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/cis-details-requests/{request}/emails": { "post": { "tags": [ "CIS Details Requests" ], "summary": "Send CIS Details Request Email", "description": "Sends the link to the form again, to the given address, which becomes the request's emailedTo; 202 with the request. 409 once the subcontractor has sent their details.", "operationId": "SendCisDetailsRequestEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendCisDetailsRequestEmailRequest" } ], "description": "A request to send the link to the CIS details form again." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/cis-details-requests/{request}/acceptance": { "put": { "tags": [ "CIS Details Requests" ], "summary": "Accept CIS Details Request", "description": "Puts the details the subcontractor sent onto the contact: its CIS identity and, where they gave one, the person's name. The contact's verification is untouched (request it from HMRC separately). 409 unless the request is Submitted; 400 when the contact does not validate with the details applied.", "operationId": "AcceptCisDetailsRequest", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CisDetailsRequestDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/connections": { "get": { "tags": [ "Connections" ], "summary": "List Connections", "description": "With contact: the connections in which that contact is the tenant's side, at most one per direction (the contact page's lookup). Without: the connections sent to the tenant (matched by the caller's email or the tenant's) that it has not yet accepted or rejected, newest first; direction narrows either list.", "operationId": "ListConnections", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "x-order": 400 }, { "name": "direction", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/InvoiceDirection" } ] }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Connections" ], "summary": "Create Connection", "description": "Shares the tenant's CIS details with the contractor one of its contacts stands for. The contractor is emailed the details at the given address (and the tenant is told what happens next). 409 when the tenant has already shared its details with the contact.", "operationId": "CreateConnection", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateConnectionRequest" } ], "description": "A new connection: the tenant shares its CIS details with one of its contractor contacts." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/connections/{connection}": { "get": { "tags": [ "Connections" ], "summary": "Get Connection", "description": "The connection as the tenant sees it: one it initiated, one it accepted, or one sent to it. A connection the tenant is on neither side of is not found.", "operationId": "GetConnection", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Connections" ], "summary": "Delete Connection", "description": "Rejects a connection sent to the tenant that it has not accepted (the initiator keeps its record, marked rejected); removes any other connection the tenant is a side of, for both sides.", "operationId": "DeleteConnection", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/connections/{connection}/counterparty": { "put": { "tags": [ "Connections" ], "summary": "Accept Connection", "description": "Accepts a connection sent to the tenant by setting the tenant's side: the given contact, or, with no contact, a supplier and CIS subcontractor created from the details the initiator shared. The subcontractor's HMRC verification is started. The connection is then Connected for both sides.", "operationId": "SetConnectionCounterParty", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SetConnectionCounterPartyRequest" } ], "description": "The accepting tenant's side of a connection sent to it." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List Contacts", "description": "Lists all Contacts for the given tenant.", "operationId": "ListContacts", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/ContactSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 }, { "name": "search", "in": "query", "description": "Search contacts by name, code or email address, and subcontractors by UTR, NI number, company number or trading name. Terms shorter than 3 characters are ignored.", "schema": { "type": "string", "example": "smith" } }, { "name": "role", "in": "query", "description": "Only contacts with this role: Customer (invoiced by the tenant), Supplier (invoices the tenant; includes CIS subcontractors) or CisSubcontractor. Omitted: all contacts.", "schema": { "enum": [ "Customer", "Supplier", "CisSubcontractor" ], "type": "string", "example": "CisSubcontractor" } }, { "name": "verificationStatus", "in": "query", "description": "Only CIS subcontractors with this verification status (Verified, NotVerified, Error). Contacts without the subcontractor role never match.", "schema": { "enum": [ "All", "Verified", "NotVerified", "Error" ], "type": "string", "example": "Verified" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDtoPagedResult" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Create Contact", "description": "Creates a new Contact for the specified tenant.", "operationId": "CreateContact", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateContactRequest" } ], "description": "Creates a contact. The code is generated from the display name. The role-specific parts may be omitted: a CIS\nsubcontractor without cisDetails gets an empty identity of type SoleTrader, and a supplier without\nsupplierSettings gets a default VAT rate that follows the VAT-registered flag." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}": { "get": { "tags": [ "Contacts" ], "summary": "Get Contact", "description": "Gets a Contact for the specified tenant.", "operationId": "GetContact", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Contacts" ], "summary": "Update Contact", "description": "Updates a Contact for the specified tenant.", "operationId": "UpdateContact", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateContactRequest" } ], "description": "Replaces a contact's editable fields, roles included. The code, external id, last SDC date and verification\nare not editable here and are kept as they are. Changing the roles is a PUT with different flags; removing the\ncustomer or supplier role while invoices exist in that direction is refused with 409. The role-specific parts\nare required for the roles the contact holds after the update: cisDetails for a CIS subcontractor,\nsupplierSettings for a supplier. Removing the subcontractor role keeps its CIS identity and verification on\nrecord; adding the role back restores them." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete Contact", "description": "Deletes a Contact for the specified tenant.", "operationId": "DeleteContact", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/import/analyze": { "post": { "tags": [ "Contacts" ], "summary": "Analyze Contacts", "description": "Validates the import template CSV (multipart/form-data, field 'file'; the template is the one the app downloads, header names are matched loosely and missing columns are allowed) without creating anything: one entry per data row with the subcontractor it would become, or a skip reason (no name, an invalid type, UTR, VAT rate, flag or verification, the CIS details the type requires missing). A file with no rows, or that is not CSV, is 400.", "operationId": "AnalyzeContacts", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactImportRowDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/import": { "post": { "tags": [ "Contacts" ], "summary": "Import Contacts", "description": "Imports the selected rows of the import template CSV (multipart/form-data: the file as 'file' and 'selections', a JSON array of { rowId } from the analysis). The file is analysed again and each selected row becomes a supplier + CIS subcontractor with an import note and, when the row carries a verification number, date and tax status, a manual verification (firing subcontractor.created, as any create); one bad row never aborts the rest, and a selected row with a skip reason fails with that reason. A file with no rows, not CSV, or no selection is 400.", "operationId": "ImportContacts", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file", "selections" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "selections": { "type": "string" } } }, "encoding": { "file": { "style": "form" }, "selections": { "style": "form" } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactImportResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/email-configs": { "get": { "tags": [ "Email Configs" ], "summary": "List Email Configs", "description": "The tenant's email connections, the default first, with their current state.", "operationId": "ListEmailConfigs", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailConfigDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Email Configs" ], "summary": "Create Email Config", "description": "Adds a connection, send only. SMTP takes smtpSettings. Outlook and Gmail take returnUrl and come back awaiting sign-in, with the authorisationUrl to send the user to; the sign-in returns to returnUrl with oauth_status, config_code and oauth_error in its query. The tenant's first connection is its default.", "operationId": "CreateEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateEmailConfigRequest" } ], "description": "A connection to add. SMTP takes `smtpSettings`; Outlook and Gmail take `returnUrl` and answer with the\n`authorisationUrl` to send the user to." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfigDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/email-configs/{code}": { "get": { "tags": [ "Email Configs" ], "summary": "Get Email Config", "description": "One connection, with its SMTP settings (never the password) or the mailbox it signed in as.", "operationId": "GetEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfigDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Email Configs" ], "summary": "Update Email Config", "description": "Changes the sender, the SMTP settings or which connection is the default; a property left out keeps its value, a password left out keeps the stored one. The default is changed by making another connection the default.", "operationId": "UpdateEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateEmailConfigRequest" } ], "description": "Changes to a connection: a property left out keeps its value." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfigDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Email Configs" ], "summary": "Delete Email Config", "description": "Removes the connection. The default can only be removed when it is the last one; the tenant's emails then go through CIS Manager's own sender again.", "operationId": "DeleteEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/email-configs/{code}/test": { "post": { "tags": [ "Email Configs" ], "summary": "Test Email Config", "description": "Sends a test email through the connection. A failure to send is reported in the result, not as an error.", "operationId": "TestEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TestEmailConfigRequest" } ], "description": "Where to send a test email." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEmailConfigResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/email-configs/{code}/reconnect": { "post": { "tags": [ "Email Configs" ], "summary": "Reconnect Email Config", "description": "A fresh sign-in URL for an Outlook or Gmail connection whose sign-in expired or failed. Until the sign-in completes the connection does not send.", "operationId": "ReconnectEmailConfig", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReconnectEmailConfigRequest" } ], "description": "Where an Outlook or Gmail sign-in returns to." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconnectEmailConfigResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/email": { "get": { "tags": [ "Email Settings" ], "summary": "Get Email Settings", "description": "The signature appended to the tenant's emails and whether statements are emailed automatically.", "operationId": "GetEmailSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Email Settings" ], "summary": "Update Email Settings", "description": "Replaces the tenant's email settings.", "operationId": "UpdateEmailSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateEmailSettingsRequest" } ], "description": "A full replacement of the email settings." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSettingsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/email/templates": { "get": { "tags": [ "Email Settings" ], "summary": "List Email Templates", "description": "Every email template the tenant can customise, with the subject and body in use and the defaults.", "operationId": "ListEmailTemplates", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/email/templates/{type}": { "get": { "tags": [ "Email Settings" ], "summary": "Get Email Template", "description": "One template by type.", "operationId": "GetEmailTemplate", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "type", "in": "path", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateType" } ] }, "x-order": 201 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Email Settings" ], "summary": "Update Email Template", "description": "Customises the template's subject and body. A subject and body equal to the defaults leave it un-customised.", "operationId": "UpdateEmailTemplate", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "type", "in": "path", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateType" } ] }, "x-order": 201 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateEmailTemplateRequest" } ], "description": "A customised subject and body for a template. DELETE the template to go back to the defaults." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Email Settings" ], "summary": "Reset Email Template", "description": "Puts the template back to its default subject and body, and returns it.", "operationId": "ResetEmailTemplate", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "type", "in": "path", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateType" } ] }, "x-order": 201 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/hmrc": { "get": { "tags": [ "HMRC Settings" ], "summary": "Get HMRC Settings", "description": "The tenant's HMRC gateway settings: sender, references and flags. hasPassword says whether a password is stored (it is never returned); with useSharedCredentials the sender fields belong to the shared credentials and are left out, sharedCredentialsId names the set (null: the practice's default is followed) and sharedCredentialsName is the set filed with now. needsConfig is true until the settings can submit.", "operationId": "GetHmrcSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcSettingsDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "HMRC Settings" ], "summary": "Update HMRC Settings", "description": "Replaces the tenant's HMRC settings. A null password keeps the stored one; with useSharedCredentials the tenant's own sender id, password and agent are discarded, and a null sharedCredentialsId follows the practice's default. The UTR is validated (400).", "operationId": "UpdateHmrcSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateHmrcSettingsRequest" } ], "description": "A full replacement of the HMRC settings. The password is optional: omitted or null keeps the stored one. With\nuseSharedCredentials the tenant's own sender id, password and agent are discarded." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcSettingsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/hmrc/shared-credentials": { "get": { "tags": [ "HMRC Settings" ], "summary": "List Shared HMRC Credentials", "description": "The shared credentials the tenant's settings can point at (sharedCredentialsId): its practice's sets, the default first. Empty for an organisation in no practice.", "operationId": "ListSharedHmrcCredentials", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SharedHmrcCredentialsDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/hmrc/test": { "post": { "tags": [ "HMRC Settings" ], "summary": "Test HMRC Settings", "description": "Sends a dummy subcontractor verification through the gateway with the stored settings and reports whether HMRC accepted the credentials. Slow: it waits for HMRC.", "operationId": "TestHmrcSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcCredentialsTestResultDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices": { "get": { "tags": [ "Invoices" ], "summary": "List purchase invoices", "description": "Lists the tenant's purchase invoices (received from a supplier or subcontractor), without lines. Filter by contact and by the year and month of dateField (Date, the invoice date, by default; DueDate; PaidDate; PaidTaxMonthEnding, the CIS tax month, 6th to 5th, it was paid in); sort by date (default), number, contact or reference.", "operationId": "ListPurchaseInvoices", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "dateField", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/DateField" } ] }, "x-order": 400 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/InvoiceSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 }, { "name": "contact", "in": "query", "description": "Only invoices of the contact with this code. Omitted: every contact.", "schema": { "type": "string", "example": "SUB001" } }, { "name": "year", "in": "query", "description": "Only invoices whose date field falls in this year. Omitted: every year.", "schema": { "type": "integer", "example": "2026" } }, { "name": "month", "in": "query", "description": "Only invoices whose date field falls in this month (1 to 12) of the year. Omitted or 0: the whole year.", "schema": { "type": "integer", "example": "4" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Create purchase invoice", "description": "Creates a purchase invoice for a contact. The number is allocated in sequence; whether VAT applies follows from the parties' VAT registration; totals and, on a purchase invoice, the CIS deduction and tax status (the subcontractor's) are computed. Payments are recorded separately, on the invoice's payments child.", "operationId": "CreatePurchaseInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateInvoiceRequest" } ], "description": "A new invoice." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/monthly-analysis": { "get": { "tags": [ "Invoices" ], "summary": "PurchaseInvoice monthly analysis", "description": "Invoice counts and totals per month for the months ending in the given year and month (months = 12 for a year of chart data), by the date field, for every contact or one contact.", "operationId": "GetPurchaseInvoiceMonthlyAnalysis", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "x-order": 400 }, { "name": "dateField", "in": "query", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DateField" } ] }, "x-order": 400 }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "months", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthAnalysisDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/summary": { "get": { "tags": [ "Invoices" ], "summary": "PurchaseInvoice summary", "description": "The count, totals and earliest and latest invoice, due and paid dates of the tenant's purchase invoices, or of one contact's. A list filtered to a period with no invoices can use the dates to offer one that has some.", "operationId": "GetPurchaseInvoiceSummary", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicingSummaryDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/{number}": { "get": { "tags": [ "Invoices" ], "summary": "Get purchase invoice", "description": "Returns the purchase invoice with its lines.", "operationId": "GetPurchaseInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Invoices" ], "summary": "Update purchase invoice", "description": "Replaces the purchase invoice's editable fields and lines (a line with an existing code updates it, without a code adds one, a line left out is deleted). Refused when the payments would exceed the new amount payable, or (purchase invoices) a payment falls in a tax month whose CIS return is submitted.", "operationId": "UpdatePurchaseInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateInvoiceRequest" } ], "description": "A full replacement of an invoice's editable fields and lines. The contact, external id and payments are not\nchanged here." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete purchase invoice", "description": "Deletes the purchase invoice and its payments. Refused (400) when a payment falls in a tax month whose CIS return is submitted.", "operationId": "DeletePurchaseInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/{number}/payments": { "get": { "tags": [ "Invoices" ], "summary": "List purchase invoice payments", "description": "The payments recorded against the purchase invoice, oldest first.", "operationId": "ListPurchaseInvoicePayments", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Create purchase invoice payment", "description": "Records a payment against the purchase invoice; the invoice's paid state follows. Refused (400) when the payments would exceed the amount payable, or (purchase invoices) the date falls in a tax month whose CIS return is submitted.", "operationId": "CreatePurchaseInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateInvoicePaymentRequest" } ], "description": "A new payment against an invoice." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/{number}/payments/{payment}": { "get": { "tags": [ "Invoices" ], "summary": "Get purchase invoice payment", "description": "Returns one payment of the purchase invoice.", "operationId": "GetPurchaseInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Invoices" ], "summary": "Update purchase invoice payment", "description": "Replaces the payment's date and amount, under the same rules as creating one.", "operationId": "UpdatePurchaseInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateInvoicePaymentRequest" } ], "description": "A full replacement of a payment's date and amount." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete purchase invoice payment", "description": "Deletes the payment; the invoice's paid state follows. Refused (400) on a purchase invoice when the payment falls in a tax month whose CIS return is submitted.", "operationId": "DeletePurchaseInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/payments": { "get": { "tags": [ "Invoices" ], "summary": "List purchase payments", "description": "Every payment of every purchase invoice dated from and to inclusive, oldest first, each with its invoice's number, dates and references, the contact, the amount and the share of the invoice's CIS deduction it carries.", "operationId": "ListPurchasePayments", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/payments/dates": { "get": { "tags": [ "Invoices" ], "summary": "List purchase payment dates", "description": "The dates from and to inclusive on which purchase invoices were paid, oldest first, each with how many invoices and contacts were paid, the total paid and the CIS deduction carried.", "operationId": "ListPurchasePaymentDates", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDateDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/{number}/emails": { "get": { "tags": [ "Invoices" ], "summary": "List purchase invoice emails", "description": "The emails sent of the purchase invoice, newest first, with their delivery status.", "operationId": "ListPurchaseInvoiceEmails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessageDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Send purchase invoice email", "description": "Queues an email of the purchase invoice (from the tenant's invoice email template), to the given recipient or the contact's own email address, optionally copied to a second address; 202 with the queued email, and the purchase invoice's emailStatus follows it. The caller's own email address must be verified, and there must be a recipient (400).", "operationId": "SendPurchaseInvoiceEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendEmailRequest" } ], "description": "A request to email a document. Every field is optional: the recipient defaults to the contact's email address\nand name." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/timesheets/template": { "get": { "tags": [ "Invoices" ], "summary": "Get Timesheet Template", "description": "The timesheet CSV template: the header row plus one row per CIS subcontractor with their code, name, default hourly rate, one hour, default VAT rate (-2 when not VAT registered) and whether DRC applies by default. The header row only when the tenant has no subcontractors. Fill it in and post it to the analysis, then the import.", "operationId": "GetTimesheetTemplate", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/timesheets/analyze": { "post": { "tags": [ "Invoices" ], "summary": "Analyze Timesheets", "description": "Validates a filled-in timesheet CSV (multipart/form-data, field 'file'; header names are matched case-insensitively and missing columns are allowed) without creating anything: one entry per data row with the purchase invoice it would become, or a skip reason (unknown or non-subcontractor code, bad date or number, invalid VAT rate, a payment date in a tax month whose return is submitted). A file with no rows, or that is not CSV, is 400.", "operationId": "AnalyzeTimesheets", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetImportRowDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/purchase-invoices/timesheets": { "post": { "tags": [ "Invoices" ], "summary": "Import Timesheets", "description": "Imports the selected rows of a timesheet CSV (multipart/form-data: the file as 'file' and 'selections', a JSON array of { rowId } from the analysis). The file is analysed again and each selected row creates a purchase invoice (firing invoice.created, as any create) and, when the row has a payment date, a payment for its full payment amount; one bad row never aborts the rest, and a selected row with a skip reason fails with that reason. A file with no rows, not CSV, or no selection is 400.", "operationId": "ImportTimesheets", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file", "selections" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "selections": { "type": "string" } } }, "encoding": { "file": { "style": "form" }, "selections": { "style": "form" } } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetImportResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices": { "get": { "tags": [ "Invoices" ], "summary": "List sales invoices", "description": "Lists the tenant's sales invoices (issued to a customer), without lines. Filter by contact and by the year and month of dateField (Date, the invoice date, by default; DueDate; PaidDate; PaidTaxMonthEnding, the CIS tax month, 6th to 5th, it was paid in); sort by date (default), number, contact or reference.", "operationId": "ListSalesInvoices", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "dateField", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/DateField" } ] }, "x-order": 400 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/InvoiceSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 }, { "name": "contact", "in": "query", "description": "Only invoices of the contact with this code. Omitted: every contact.", "schema": { "type": "string", "example": "SUB001" } }, { "name": "year", "in": "query", "description": "Only invoices whose date field falls in this year. Omitted: every year.", "schema": { "type": "integer", "example": "2026" } }, { "name": "month", "in": "query", "description": "Only invoices whose date field falls in this month (1 to 12) of the year. Omitted or 0: the whole year.", "schema": { "type": "integer", "example": "4" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Create sales invoice", "description": "Creates a sales invoice for a contact. The number is allocated in sequence; whether VAT applies follows from the parties' VAT registration; totals and, on a purchase invoice, the CIS deduction and tax status (the subcontractor's) are computed. Payments are recorded separately, on the invoice's payments child.", "operationId": "CreateSalesInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateInvoiceRequest" } ], "description": "A new invoice." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/monthly-analysis": { "get": { "tags": [ "Invoices" ], "summary": "SalesInvoice monthly analysis", "description": "Invoice counts and totals per month for the months ending in the given year and month (months = 12 for a year of chart data), by the date field, for every contact or one contact.", "operationId": "GetSalesInvoiceMonthlyAnalysis", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "x-order": 400 }, { "name": "dateField", "in": "query", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/DateField" } ] }, "x-order": 400 }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "months", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthAnalysisDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/summary": { "get": { "tags": [ "Invoices" ], "summary": "SalesInvoice summary", "description": "The count, totals and earliest and latest invoice, due and paid dates of the tenant's sales invoices, or of one contact's. A list filtered to a period with no invoices can use the dates to offer one that has some.", "operationId": "GetSalesInvoiceSummary", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "contact", "in": "query", "schema": { "type": "string" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicingSummaryDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/{number}": { "get": { "tags": [ "Invoices" ], "summary": "Get sales invoice", "description": "Returns the sales invoice with its lines.", "operationId": "GetSalesInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Invoices" ], "summary": "Update sales invoice", "description": "Replaces the sales invoice's editable fields and lines (a line with an existing code updates it, without a code adds one, a line left out is deleted). Refused when the payments would exceed the new amount payable, or (purchase invoices) a payment falls in a tax month whose CIS return is submitted.", "operationId": "UpdateSalesInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateInvoiceRequest" } ], "description": "A full replacement of an invoice's editable fields and lines. The contact, external id and payments are not\nchanged here." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete sales invoice", "description": "Deletes the sales invoice and its payments. Refused (400) when a payment falls in a tax month whose CIS return is submitted.", "operationId": "DeleteSalesInvoice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/{number}/payments": { "get": { "tags": [ "Invoices" ], "summary": "List sales invoice payments", "description": "The payments recorded against the sales invoice, oldest first.", "operationId": "ListSalesInvoicePayments", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Create sales invoice payment", "description": "Records a payment against the sales invoice; the invoice's paid state follows. Refused (400) when the payments would exceed the amount payable, or (purchase invoices) the date falls in a tax month whose CIS return is submitted.", "operationId": "CreateSalesInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateInvoicePaymentRequest" } ], "description": "A new payment against an invoice." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/{number}/payments/{payment}": { "get": { "tags": [ "Invoices" ], "summary": "Get sales invoice payment", "description": "Returns one payment of the sales invoice.", "operationId": "GetSalesInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Invoices" ], "summary": "Update sales invoice payment", "description": "Replaces the payment's date and amount, under the same rules as creating one.", "operationId": "UpdateSalesInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateInvoicePaymentRequest" } ], "description": "A full replacement of a payment's date and amount." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Invoices" ], "summary": "Delete sales invoice payment", "description": "Deletes the payment; the invoice's paid state follows. Refused (400) on a purchase invoice when the payment falls in a tax month whose CIS return is submitted.", "operationId": "DeleteSalesInvoicePayment", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/payments": { "get": { "tags": [ "Invoices" ], "summary": "List sales payments", "description": "Every payment of every sales invoice dated from and to inclusive, oldest first, each with its invoice's number, dates and references, the contact, the amount and the share of the invoice's CIS deduction it carries.", "operationId": "ListSalesPayments", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/payments/dates": { "get": { "tags": [ "Invoices" ], "summary": "List sales payment dates", "description": "The dates from and to inclusive on which sales invoices were paid, oldest first, each with how many invoices and contacts were paid, the total paid and the CIS deduction carried.", "operationId": "ListSalesPaymentDates", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentDateDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/sales-invoices/{number}/emails": { "get": { "tags": [ "Invoices" ], "summary": "List sales invoice emails", "description": "The emails sent of the sales invoice, newest first, with their delivery status.", "operationId": "ListSalesInvoiceEmails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessageDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Invoices" ], "summary": "Send sales invoice email", "description": "Queues an email of the sales invoice (from the tenant's invoice email template), to the given recipient or the contact's own email address, optionally copied to a second address; 202 with the queued email, and the sales invoice's emailStatus follows it. The caller's own email address must be verified, and there must be a recipient (400).", "operationId": "SendSalesInvoiceEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendEmailRequest" } ], "description": "A request to email a document. Every field is optional: the recipient defaults to the contact's email address\nand name." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/email-verifications": { "post": { "tags": [ "Me" ], "summary": "Verify Email Address", "description": "Marks an address verified from the emailed link, with no credentials: a user's own address, or with tenant that tenant's address. 204; 400 when the address, key or tenant do not match.", "operationId": "VerifyEmailAddress", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/VerifyEmailAddressRequest" } ], "description": "The address and key from an emailed verification link." } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } } } } }, "/me": { "get": { "tags": [ "Me" ], "summary": "Get Me", "description": "Returns the authenticated user: profile, application roles and the tenants they are a member of, each with the user's access level and the tenant's modules. With an API key this is the key's owner. A bearer token whose subject is not yet a user signs them up on first use: linked to the user with the token's email address when that user has no sign-in yet, otherwise created; 409 when the address belongs to a user with a different sign-in.", "operationId": "GetMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Me" ], "summary": "Register Me", "description": "Signs up a caller whose bearer token carries no email address (a sign-in provider that gives none), with the address they type in; every other endpoint answers such a caller 403 with errorCode email_required until they have. The address is unverified: a verification link is sent to it, and it is never used to link the sign-in to an existing account. 201 with the new profile; 409 when the address belongs to an existing account or the caller already has one; 401 without a bearer token (an API key cannot register).", "operationId": "RegisterMe", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RegisterMeRequest" } ], "description": "The email address of a caller whose sign-in gave none, to sign them up with." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Me" ], "summary": "Update Me", "description": "Replaces the caller's editable profile fields: names and phone number. Returns the profile as GET does.", "operationId": "UpdateMe", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateMeRequest" } ], "description": "A full replacement of the caller's editable profile fields." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/sodium-practices": { "get": { "tags": [ "Me" ], "summary": "List My Sodium Practices", "description": "The SodiumHQ practices the signed-in user belongs to, by name, read from Account Hub: someone setting up a practice or an organisation here who already runs a practice in SodiumHQ is pointed there, so their clients stay in one place. Matched by the user's sign-in, else by their email address once verified. Empty when there are none, and when Account Hub cannot answer.", "operationId": "ListMySodiumPractices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SodiumPracticeDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/email-verification": { "post": { "tags": [ "Me" ], "summary": "Send My Email Verification", "description": "Emails the caller the link that verifies their email address (again). The link opens the web app.", "operationId": "SendMyEmailVerification", "responses": { "202": { "description": "Accepted" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/connections/{connection}": { "put": { "tags": [ "Me" ], "summary": "Claim My Connection", "description": "Follows an emailed connection link: the pending connection's counterparty becomes the caller, so it is listed on the caller's tenants as sent to them (GET /tenants/{tenant}/connections) for them to accept there. 404 for an unknown code; 409 when the connection has already been accepted, rejected or claimed by another user. A connection already claimed by the caller is left as it is.", "operationId": "ClaimMyConnection", "parameters": [ { "name": "connection", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/invitations": { "get": { "tags": [ "Me" ], "summary": "List My Invitations", "description": "The pending invitations sent to the caller's email address, oldest first.", "operationId": "ListMyInvitations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvitationDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/invitations/{invitation}": { "get": { "tags": [ "Me" ], "summary": "Get My Invitation", "description": "The invitation with the code from an emailed link, whatever its status and whoever it was sent to (the code is the secret). 404 for an unknown code.", "operationId": "GetMyInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInvitationDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Me" ], "summary": "Decline My Invitation", "description": "Declines the invitation; the inviter is told. 404 for an unknown code; 409 when it is no longer pending.", "operationId": "DeclineMyInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/invitations/{invitation}/membership": { "put": { "tags": [ "Me" ], "summary": "Accept My Invitation", "description": "Accepts the invitation for the caller, whichever address it was sent to: the caller becomes a member of the tenant with the offered access level, the inviter is told, and the new membership is returned. 404 for an unknown code; 409 when the invitation is no longer pending (accepted, declined, withdrawn or expired); 400 when the caller is already a member.", "operationId": "AcceptMyInvitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMembershipDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/return-statuses": { "get": { "tags": [ "Metadata" ], "summary": "MonthlyReturnStatus metadata", "description": "The values of MonthlyReturnStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetMonthlyReturnStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/subcontractor-verification-statuses": { "get": { "tags": [ "Metadata" ], "summary": "SubcontractorVerificationStatus metadata", "description": "The values of SubcontractorVerificationStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetSubcontractorVerificationStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/email-delivery-statuses": { "get": { "tags": [ "Metadata" ], "summary": "EmailDeliveryStatus metadata", "description": "The values of EmailDeliveryStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetEmailDeliveryStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/email-config-statuses": { "get": { "tags": [ "Metadata" ], "summary": "EmailConfigStatus metadata", "description": "The values of EmailConfigStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetEmailConfigStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/invitation-statuses": { "get": { "tags": [ "Metadata" ], "summary": "InvitationStatus metadata", "description": "The values of InvitationStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetInvitationStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/connection-statuses": { "get": { "tags": [ "Metadata" ], "summary": "ConnectionStatus metadata", "description": "The values of ConnectionStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetConnectionStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/cis-details-request-statuses": { "get": { "tags": [ "Metadata" ], "summary": "CisDetailsRequestStatus metadata", "description": "The values of CisDetailsRequestStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetCisDetailsRequestStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/mandate-statuses": { "get": { "tags": [ "Metadata" ], "summary": "MandateStatus metadata", "description": "The values of MandateStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetMandateStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/billing-invoice-statuses": { "get": { "tags": [ "Metadata" ], "summary": "BillingInvoiceStatus metadata", "description": "The values of BillingInvoiceStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetBillingInvoiceStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/account-invoice-statuses": { "get": { "tags": [ "Metadata" ], "summary": "AccountInvoiceStatus metadata", "description": "The values of AccountInvoiceStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetAccountInvoiceStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/modules": { "get": { "tags": [ "Metadata" ], "summary": "Modules metadata", "description": "The values of Modules with their display names, descriptions, badge colours and icons.", "operationId": "GetModulesMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/metadata/webhook-delivery-statuses": { "get": { "tags": [ "Metadata" ], "summary": "WebhookDeliveryStatus metadata", "description": "The values of WebhookDeliveryStatus with their display names, descriptions, badge colours and icons.", "operationId": "GetWebhookDeliveryStatusMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnumMetadata" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices": { "get": { "tags": [ "My Practices" ], "summary": "List My Practices", "description": "The practices the caller is a member of, by name.", "operationId": "ListMyPractices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PracticeSummaryDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "My Practices" ], "summary": "Create My Practice", "description": "Creates a practice, managed here, with the caller its first member, and puts the named organisations in it: each one the caller owns (400 otherwise) and in no practice (409 otherwise), checked before anything is created. Their members stay as they are; a contractor organisation with no HMRC credentials of its own files with the practice's default set.", "operationId": "CreateMyPractice", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatePracticeRequest" } ], "description": "A new practice, the caller its first member." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeSummaryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}": { "get": { "tags": [ "My Practices" ], "summary": "Get My Practice", "description": "One of the caller's practices; 404 when the caller is not a member.", "operationId": "GetMyPractice", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeSummaryDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "My Practices" ], "summary": "Rename My Practice", "description": "Replaces the practice's name. 409 for a practice managed in Sodium.", "operationId": "RenameMyPractice", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RenamePracticeRequest" } ], "description": "A practice's new name." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeSummaryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/members": { "get": { "tags": [ "My Practices" ], "summary": "List My Practice Members", "description": "The practice's members, who reach every organisation it runs, by name.", "operationId": "ListMyPracticeMembers", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PracticeMemberDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/members/{user}": { "delete": { "tags": [ "My Practices" ], "summary": "Remove My Practice Member", "description": "Takes a member out of the practice and the organisations it granted them; organisations they are a member of in their own right, and those they own, are kept. 400 for the caller themselves; 404 for a user who is not a member; 409 for a practice managed in Sodium.", "operationId": "RemoveMyPracticeMember", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 214 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/organisations": { "get": { "tags": [ "My Practices" ], "summary": "List My Practice Organisations", "description": "The organisations the practice runs, by name, with their owners.", "operationId": "ListMyPracticeOrganisations", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PracticeOrganisationSummaryDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "My Practices" ], "summary": "Add My Practice Organisation", "description": "Puts one of the caller's organisations in the practice: one they own (400 otherwise) and in no practice (409 otherwise). The practice's members reach it from then on; its own members stay as they are. A contractor organisation with no HMRC credentials of its own files with the practice's default set. 409 for a practice managed in Sodium.", "operationId": "AddMyPracticeOrganisation", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AddPracticeOrganisationRequest" } ], "description": "One of the caller's organisations to put in the practice." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeOrganisationSummaryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/organisations/{tenant}": { "delete": { "tags": [ "My Practices" ], "summary": "Remove My Practice Organisation", "description": "Takes the organisation out of the practice. The practice members named in keep (user codes) keep access as members of the organisation itself, at their current level; every other practice member loses it. Its own members are untouched. Its HMRC settings stop using the practice's credentials (it needs its own before it can submit), and pending invitations to the practice sent from it are withdrawn. To hand it to the client, transfer ownership too (PUT /tenants/{tenant}/owner). 400 when someone to keep is not a member of the practice; 404 when the practice does not run the organisation; 409 for a practice managed in Sodium.", "operationId": "RemoveMyPracticeOrganisation", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "keep", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "x-order": 400 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/hmrc-credentials": { "get": { "tags": [ "My Practices" ], "summary": "List Practice HMRC Credentials", "description": "The practice's HMRC gateway credentials, the default first. Its organisations' HMRC settings can point at any of them (sharedCredentialsId). 404 when the caller is not a member.", "operationId": "ListPracticeHmrcCredentials", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PracticeHmrcCredentialsDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "My Practices" ], "summary": "Create Practice HMRC Credentials", "description": "Adds a set of credentials to the practice: the default when isDefault, or when it is the practice's first. The first set is also given to every contractor client with no HMRC credentials of its own. 409 for a practice managed in Sodium.", "operationId": "CreatePracticeHmrcCredentials", "parameters": [ { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreatePracticeHmrcCredentialsRequest" } ], "description": "A new set of practice credentials." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeHmrcCredentialsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/hmrc-credentials/{credentials}": { "get": { "tags": [ "My Practices" ], "summary": "Get Practice HMRC Credentials", "description": "One of the practice's credentials.", "operationId": "GetPracticeHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeHmrcCredentialsDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "My Practices" ], "summary": "Update Practice HMRC Credentials", "description": "Replaces the credentials; a null password keeps the stored one. isDefault moves the practice's default to them; false leaves the default where it is. 409 for a practice managed in Sodium.", "operationId": "UpdatePracticeHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdatePracticeHmrcCredentialsRequest" } ], "description": "A full replacement of a set of practice credentials. The password is optional: omitted or null keeps the stored one." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeHmrcCredentialsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "My Practices" ], "summary": "Delete Practice HMRC Credentials", "description": "Deletes the credentials. When they were the default, the practice's oldest remaining set becomes it; an organisation filing with them, or following the default, files with the practice's default from then on. 409 for a practice managed in Sodium.", "operationId": "DeletePracticeHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/practices/{practice}/hmrc-credentials/{credentials}/test": { "post": { "tags": [ "My Practices" ], "summary": "Test Practice HMRC Credentials", "description": "Sends a dummy subcontractor verification through the gateway with the credentials, using the named tenant's HMRC references as the context (the caller must be a member; 400 otherwise), and reports whether HMRC accepted them. Allowed for a practice managed in Sodium.", "operationId": "TestPracticeHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 }, { "name": "practice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TestHmrcCredentialsRequest" } ], "description": "A request to test a practice's credentials against the HMRC gateway. A submission needs a tenant as its context, so\none of the caller's tenants is named." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcCredentialsTestResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/notes": { "get": { "tags": [ "Notes" ], "summary": "List Contact Notes", "description": "Lists the contact's notes, newest first by default (sortBy date or createdDate).", "operationId": "ListContactNotes", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/ContactNoteSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Notes" ], "summary": "Create Contact Note", "description": "Records a note against the contact, by the caller. The date defaults to now.", "operationId": "CreateContactNote", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateContactNoteRequest" } ], "description": "A new note for a contact." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/notes/{note}": { "get": { "tags": [ "Notes" ], "summary": "Get Contact Note", "description": "Returns one of the contact's notes.", "operationId": "GetContactNote", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "note", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Notes" ], "summary": "Update Contact Note", "description": "Replaces the note's text and date.", "operationId": "UpdateContactNote", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "note", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateContactNoteRequest" } ], "description": "A full replacement of a note's text and date." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactNoteDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Notes" ], "summary": "Delete Contact Note", "description": "Deletes the note.", "operationId": "DeleteContactNote", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "note", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/remittance-advice": { "get": { "tags": [ "Remittance Advice" ], "summary": "Get Remittance Advice", "description": "The remittance advice for the contact's payments dated from and to inclusive: the parties, each payment with its invoice and deduction, the totals and the deductions summarised by rate. A contact not paid in the period has no advice (404).", "operationId": "GetRemittanceAdvice", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceAdviceDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/remittance-advice/pdf": { "get": { "tags": [ "Remittance Advice" ], "summary": "Get Remittance Advice PDF", "description": "The remittance advice as a PDF, laid out per the tenant's remittance advice settings.", "operationId": "GetRemittanceAdvicePdf", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/remittance-advice/emails": { "get": { "tags": [ "Remittance Advice" ], "summary": "List Remittance Advice Emails", "description": "The emails sent of the contact's remittance advice for exactly this period, newest first, with their delivery status.", "operationId": "ListRemittanceAdviceEmails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmailMessageDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Remittance Advice" ], "summary": "Send Remittance Advice Email", "description": "Generates the PDF of the contact's remittance advice for the period and queues an email of it, to the given recipient or the contact's own email address, optionally copied to a second address; 202 with the queued email. The caller's own email address must be verified, and there must be a recipient (400).", "operationId": "SendRemittanceAdviceEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendEmailRequest" } ], "description": "A request to email a document. Every field is optional: the recipient defaults to the contact's email address\nand name." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessageDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/remittance-advice": { "get": { "tags": [ "Remittance Advice" ], "summary": "Get Remittance Advice Settings", "description": "How the tenant's remittance advices are laid out: the columns shown and the custom texts. The defaults until the tenant saves its own.", "operationId": "GetRemittanceAdviceSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceAdviceSettingsDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Remittance Advice" ], "summary": "Update Remittance Advice Settings", "description": "Replaces the tenant's remittance advice settings. A text whose switch is off is discarded.", "operationId": "UpdateRemittanceAdviceSettings", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateRemittanceAdviceSettingsRequest" } ], "description": "A full replacement of the remittance advice settings. A text whose switch is off is discarded." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemittanceAdviceSettingsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/returns": { "get": { "tags": [ "Returns" ], "summary": "List Returns", "description": "Lists the tenant's monthly returns, latest tax period first by default. Filter by the year the tax month ends in and by status (Open, Submitting, Submitted, Accepted, Error); sort by taxPeriod, status, invoiceCount, contactCount or deductions.", "operationId": "ListReturns", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnStatus" } ] }, "x-order": 200 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 }, { "name": "year", "in": "query", "description": "Only returns for tax months ending in this calendar year. Omitted: every year.", "schema": { "type": "integer", "example": "2026" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Returns" ], "summary": "Create Return", "description": "Opens a return for the tax month ending on the 5th of the given month. It collects the subcontractor invoices paid in that month from then on. A tax month that already has a return is 409.", "operationId": "CreateReturn", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateMonthlyReturnRequest" } ], "description": "A new monthly return for a tax month." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/returns/years": { "get": { "tags": [ "Returns" ], "summary": "List Return Years", "description": "The calendar years the tenant has returns in, latest first: the year values the list can be filtered by.", "operationId": "ListReturnYears", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/returns/{year}/{month}": { "get": { "tags": [ "Returns" ], "summary": "Get Return", "description": "Returns the monthly return for the tax month ending in the given year and month, with its totals, status and, after a rejected submission, HMRC's errors in plain language. submissionBlockedReason says why billing blocks submissions (the 402 a submit would get), or is null. For an organisation of a SodiumHQ-managed practice, whose filing credits pay for its returns, creditsRequired is what a submit would use now (one per subcontractor beyond those already paid for this month; one for a nil return) and creditBalance is the practice's balance.", "operationId": "GetReturn", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/returns/{year}/{month}/breakdown": { "get": { "tags": [ "Returns" ], "summary": "Get Return Breakdown", "description": "The return broken down by subcontractor: identity, rate, invoice counts, labour, materials, gross, deduction, net and VAT, with a total row last (isTotal). A subcontractor paid at two rates in the month has a row per rate.", "operationId": "GetReturnBreakdown", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubcontractorBreakdownRowDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/returns/{year}/{month}/submission": { "get": { "tags": [ "Returns" ], "summary": "Get Return Submission", "description": "The return's latest submission to HMRC: when it was sent and last polled, its correlation id and its polling state. The GovTalk request and response XML are included for callers with the HmrcXmlViewer role. A return that has never been submitted is 404.", "operationId": "GetReturnSubmission", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnSubmissionDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Returns" ], "summary": "Submit Return", "description": "Sends the return to HMRC as a CIS300 with the declarations (that the information is correct is always declared; the employment status and verification declarations are not sent on a nil return). The return is Submitting while it is sent, then Submitted and polled in the background: HMRC's acceptance or errors land on its status (webhooks return.submitted, return.accepted, return.failed). A send HMRC did not confirm (no answer, or an answer that could not be read) leaves it Submitting with the reason as its status message, and it cannot be submitted again until support has checked with HMRC. Only an Open or Error return can be submitted (400). Incomplete HMRC settings are 422. A tenant whose owner's billing blocks submissions is 402 with the reason. For an organisation of a SodiumHQ-managed practice the practice's filing credits pay instead: the credits the return needs are held before it is sent (402 when the balance cannot cover them or the user cannot spend them, 503 when they cannot be checked), spent when HMRC accepts it and given back when HMRC refuses it (kept while it is Submitting).", "operationId": "SubmitReturn", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SubmitMonthlyReturnRequest" } ], "description": "The declarations made when submitting a return to HMRC. That the information is correct is always declared." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Returns" ], "summary": "Re-open Return", "description": "Re-opens an Accepted return (400 otherwise) so the month's payments can be corrected and the return submitted again (webhook return.opened). The submission record itself is kept. Returns the re-opened return.", "operationId": "ReopenReturn", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyReturnDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/sdc-statements/{sdc}": { "get": { "tags": [ "SDC Statements" ], "summary": "Get Public SDC Statement", "description": "The statement as the subcontractor sees it on the public completion page, with no credentials: its title, whether it is completed, the questions to confirm, who sent it and to whom. An unknown code is 404.", "operationId": "GetPublicSdcStatement", "parameters": [ { "name": "sdc", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSdcStatementDto" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/sdc-statements/{sdc}/signature": { "put": { "tags": [ "SDC Statements" ], "summary": "Sign SDC Statement", "description": "Completes the statement from the public page, with no credentials: every current question confirmed, the signer's name and the signature image. The statement keeps the questions as they stood, and the contact's lastSdc follows it. 400 when a question is not confirmed, 409 when it is already completed.", "operationId": "SignSdcStatement", "parameters": [ { "name": "sdc", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignSdcStatementRequest" } ], "description": "The subcontractor's completion of an SDC statement: every question confirmed, their name and their signature." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSdcStatementDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/sdc-statements": { "get": { "tags": [ "SDC Statements" ], "summary": "List SDC Statements", "description": "The contact's SDC statements, newest first, without their signature images.", "operationId": "ListSdcStatements", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SdcStatementDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "SDC Statements" ], "summary": "Create SDC Statement", "description": "Creates a pending statement for the contact and queues an email (from the tenant's SDC statement request template) asking them to complete it on the public page linked from the email.", "operationId": "CreateSdcStatement", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateSdcStatementRequest" } ], "description": "A new SDC statement. Creating it emails the subcontractor a link to complete it." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdcStatementDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/sdc-statements/{sdc}": { "get": { "tags": [ "SDC Statements" ], "summary": "Get SDC Statement", "description": "One of the contact's statements, with its signature image once completed.", "operationId": "GetSdcStatement", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "sdc", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdcStatementDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/sdc-statements/{sdc}/emails": { "post": { "tags": [ "SDC Statements" ], "summary": "Send SDC Statement Email", "description": "Sends the completion request again, to the given address, which becomes the statement's emailedTo; 202 with the statement.", "operationId": "SendSdcStatementEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "sdc", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendSdcStatementEmailRequest" } ], "description": "A request to send (or resend) the completion link for a statement." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdcStatementDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/contacts/{code}/statements/{year}/pdf/stream": { "get": { "tags": [ "Statements" ], "summary": "Stream ContactAnnualStatement PDF", "description": "The contact's annual statement as a PDF through the signed pdfUrl of the statement, with no credentials: the tenant, expiry and token come from the query, and disposition=inline shows it in the browser rather than downloading it. A bad or expired token is 401; a contact not paid in the period is 404.", "operationId": "StreamContactAnnualStatementPdf", "parameters": [ { "name": "tenant", "in": "query", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "disposition", "in": "query", "schema": { "type": "string" }, "x-order": 400 }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "x-order": 400 }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/contacts/{code}/statements/{year}/{month}/pdf/stream": { "get": { "tags": [ "Statements" ], "summary": "Stream ContactStatement PDF", "description": "The contact's statement as a PDF through the signed pdfUrl of the statement, with no credentials: the tenant, expiry and token come from the query, and disposition=inline shows it in the browser rather than downloading it. A bad or expired token is 401; a contact not paid in the period is 404.", "operationId": "StreamContactStatementPdf", "parameters": [ { "name": "tenant", "in": "query", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "disposition", "in": "query", "schema": { "type": "string" }, "x-order": 400 }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "x-order": 400 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/statements": { "get": { "tags": [ "Statements" ], "summary": "List Statements", "description": "Every subcontractor's statement for the tax month ending in the given year and month (the statements behind that monthly return), by subcontractor name. With no month, every subcontractor's annual statement for the tax year ending in the year.", "operationId": "ListStatements", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "query", "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatementDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/statements/pdf": { "get": { "tags": [ "Statements" ], "summary": "Get Statements PDF", "description": "One PDF of every subcontractor's statement for the tax month (or, with no month, of the annual statements for the tax year), generated afresh. A period with no statements is 404.", "operationId": "GetStatementsPdf", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "month", "in": "query", "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements": { "get": { "tags": [ "Statements" ], "summary": "List Contact Statements", "description": "The contact's monthly statements in the tax year ending in the given year (6 April of the year before to 5 April), latest first.", "operationId": "ListContactStatements", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatementDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/years": { "get": { "tags": [ "Statements" ], "summary": "List Contact Statement Years", "description": "The tax years the contact has statements in, by the calendar year each ends in, latest first: the year values the list and the annual statement accept.", "operationId": "ListContactStatementYears", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}": { "get": { "tags": [ "Statements" ], "summary": "Get ContactAnnualStatement", "description": "The contact's annual statement for the tax year ending in the given year: gross, materials, deduction and the amount payable, with the delivery status of the last email of it. A contact not paid in the period has no statement (404).", "operationId": "GetContactAnnualStatement", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}/{month}": { "get": { "tags": [ "Statements" ], "summary": "Get ContactStatement", "description": "The contact's statement for the tax month ending in the given year and month: gross, materials, deduction and the amount payable, with the delivery status of the last email of it. A contact not paid in the period has no statement (404).", "operationId": "GetContactStatement", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}/pdf": { "get": { "tags": [ "Statements" ], "summary": "Get ContactAnnualStatement PDF", "description": "The contact's annual statement for the tax year ending in the given year as a PDF.", "operationId": "GetContactAnnualStatementPdf", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}/{month}/pdf": { "get": { "tags": [ "Statements" ], "summary": "Get ContactStatement PDF", "description": "The contact's statement for the tax month ending in the given year and month as a PDF.", "operationId": "GetContactStatementPdf", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}/emails": { "get": { "tags": [ "Statements" ], "summary": "List ContactAnnualStatement Emails", "description": "The emails sent of the contact's annual statement for the tax year ending in the given year, newest first, with their delivery status. An annual statement keeps no history, so this is always empty.", "operationId": "ListContactAnnualStatementEmails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatementEmailDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Statements" ], "summary": "Send ContactAnnualStatement Email", "description": "Generates the PDF of the contact's annual statement for the tax year ending in the given year and queues an email of it, to the given recipient or the contact's own email address, optionally copied to a second address; 202 with the queued email. The caller's own email address must be verified, and there must be a recipient (400).", "operationId": "SendContactAnnualStatementEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendStatementEmailRequest" } ], "description": "A request to email a statement's PDF. Every field is optional: the recipient defaults to the subcontractor's\nemail address and name." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementEmailDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/statements/{year}/{month}/emails": { "get": { "tags": [ "Statements" ], "summary": "List ContactStatement Emails", "description": "The emails sent of the contact's statement for the tax month ending in the given year and month, newest first, with their delivery status.", "operationId": "ListContactStatementEmails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatementEmailDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Statements" ], "summary": "Send ContactStatement Email", "description": "Generates the PDF of the contact's statement for the tax month ending in the given year and month and queues an email of it, to the given recipient or the contact's own email address, optionally copied to a second address; 202 with the queued email. The caller's own email address must be verified, and there must be a recipient (400).", "operationId": "SendContactStatementEmail", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 }, { "name": "month", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 }, { "name": "year", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SendStatementEmailRequest" } ], "description": "A request to email a statement's PDF. Every field is optional: the recipient defaults to the subcontractor's\nemail address and name." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementEmailDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/members": { "get": { "tags": [ "Team" ], "summary": "List Tenant Members", "description": "The users who are members of the tenant, oldest first, with who owns it, which one is the caller and which are members of its practice (they reach every organisation the practice runs).", "operationId": "ListTenantMembers", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantMemberDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/members/{user}": { "delete": { "tags": [ "Team" ], "summary": "Remove Tenant Member", "description": "Removes the user from the tenant. The caller cannot remove themselves, the owner cannot be removed until ownership is transferred, and a member of the tenant's practice is removed from the practice instead (400).", "operationId": "RemoveTenantMember", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 214 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/owner": { "put": { "tags": [ "Team" ], "summary": "Transfer Tenant Ownership", "description": "Makes another member the tenant's owner. Only the current owner (or a super admin) may do this, and the new owner must be a member (400).", "operationId": "TransferTenantOwnership", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TransferOwnershipRequest" } ], "description": "The member to make the tenant's owner." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/invitations": { "get": { "tags": [ "Team" ], "summary": "List Tenant Invitations", "description": "The tenant's invitations, every status, newest first. Invitations to the tenant's practice are listed for members of the practice only.", "operationId": "ListTenantInvitations", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantInvitationDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Team" ], "summary": "Create Tenant Invitation", "description": "Invites an email address to join the tenant (Admin access unless another role is given) and sends the invitation email. It expires after seven days. With practice, the invitation is to the tenant's whole practice: accepting it reaches every organisation the practice runs (400 for a tenant in no practice, 409 for a practice managed in Sodium).", "operationId": "CreateTenantInvitation", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateInvitationRequest" } ], "description": "A new invitation. It is emailed at once and expires after seven days." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInvitationDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/invitations/{invitation}": { "delete": { "tags": [ "Team" ], "summary": "Delete Tenant Invitation", "description": "Withdraws the invitation.", "operationId": "DeleteTenantInvitation", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/invitations/{invitation}/emails": { "post": { "tags": [ "Team" ], "summary": "Resend Tenant Invitation", "description": "Sends the invitation email again; 202 with the invitation.", "operationId": "ResendTenantInvitation", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInvitationDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants": { "get": { "tags": [ "Tenants" ], "summary": "List Tenants", "description": "Lists the tenants the authenticated user is a member of.", "operationId": "ListTenants", "parameters": [ { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/TenantSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 }, { "name": "search", "in": "query", "description": "Search tenants by name or code (three characters or more)", "schema": { "type": "string", "example": "acme" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Tenants" ], "summary": "Create Tenant", "description": "Creates a tenant owned by the caller, with the given name, VAT status and modules; its email address and phone number start as the caller's. With practice (one of the caller's) or newPracticeName (a new practice, the caller its first member) it is created in that practice: granted to its members, and a contractor tenant files with the practice's default HMRC credentials. 400 for both; 404 for a practice the caller is not in; 409 for a practice managed in Sodium, and for any tenant outside a practice (or in a new one) when the caller is a member of a practice managed in Sodium: its clients are added in Sodium.", "operationId": "CreateTenant", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateTenantRequest" } ], "description": "A new tenant, owned by the caller. Its email address and phone number start as the caller's." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}": { "get": { "tags": [ "Tenants" ], "summary": "Get Tenant", "description": "Returns a tenant the authenticated user is a member of, or (for a support agent) a tenant that has enabled support access; isSupportAccess says which. practice is the practice running it, if any.", "operationId": "GetTenant", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Tenants" ], "summary": "Update Tenant", "description": "Replaces the tenant's details and modules. A changed email address un-verifies the tenant and sends a verification email to the new address.", "operationId": "UpdateTenant", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateTenantRequest" } ], "description": "A full replacement of the tenant's own details, as the settings page edits them. Counts, the logo, the\nverification state and the owner are not part of it (they have their own resources or are read-only)." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/summaries": { "get": { "tags": [ "Tenants" ], "summary": "List Tenant Summaries", "description": "The caller's tenants with their customer and supplier counts and the CIS returns of the current and last tax periods, as the overview page shows them.", "operationId": "ListTenantSummaries", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantSummaryDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/email-verification": { "post": { "tags": [ "Tenants" ], "summary": "Send Tenant Email Verification", "description": "Sends (again) the email that verifies the tenant's email address; 202. 400 when the tenant has no email address.", "operationId": "SendTenantEmailVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/logo": { "put": { "tags": [ "Tenants" ], "summary": "Update Tenant Logo", "description": "Replaces the tenant's logo (multipart/form-data, field 'file'; jpg, png, gif, bmp or svg up to 2 MB). The image is stored publicly and its URL returned as logoUrl.", "operationId": "UpdateTenantLogo", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Tenants" ], "summary": "Remove Tenant Logo", "description": "Clears the tenant's logo; the tenant without one. Nothing to do when it has none.", "operationId": "RemoveTenantLogo", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/export": { "get": { "tags": [ "Tenants" ], "summary": "Export Tenant Data", "description": "The tenant's contacts as a data-config JSON file, which the import takes back (for copying contacts between tenants).", "operationId": "ExportTenantData", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/import": { "post": { "tags": [ "Tenants" ], "summary": "Import Tenant Data", "description": "Creates the contacts in a data-config JSON file (multipart/form-data, field 'file'), skipping codes that already exist unless skipExisting=false. A file that is not a data-config document is 400.", "operationId": "ImportTenantData", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "skipExisting", "in": "query", "schema": { "type": "boolean" }, "x-order": 400 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/settings/cis-details": { "get": { "tags": [ "Tenants" ], "summary": "Get Tenant CIS Details", "description": "The tenant's own CIS identity as a subcontractor (subcontractor module): what it shares with contractors over a connection. Empty, with needsConfig, until saved.", "operationId": "GetTenantCisDetails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCisDetailsDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Tenants" ], "summary": "Update Tenant CIS Details", "description": "Replaces the tenant's CIS details. The UTR, NI number and company number are validated for their format (400).", "operationId": "UpdateTenantCisDetails", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateTenantCisDetailsRequest" } ], "description": "A full replacement of the tenant's CIS details." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCisDetailsDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/verification": { "get": { "tags": [ "Verification" ], "summary": "Get Verification", "description": "Returns the subcontractor's verification: its status (not verified, manual, from HMRC, or failed with HMRC's errors), number, date and deduction rate, and the latest HMRC verification request, if any.", "operationId": "GetVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubcontractorVerificationDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Verification" ], "summary": "Update Verification", "description": "Records a verification obtained from HMRC outside the API (number, date and deduction rate), replacing any manual verification already recorded. A verification obtained through an HMRC request cannot be replaced this way: delete it first (409).", "operationId": "UpdateVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateSubcontractorVerificationRequest" } ], "description": "A verification obtained from HMRC outside the API (by phone or through HMRC online services), recorded\nmanually. A full replacement of any manual verification already recorded." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubcontractorVerificationDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Verification" ], "summary": "Delete Verification", "description": "Removes the subcontractor's verification, manual or from HMRC. Payments are deducted at the higher rate until it is verified again. 404 when there is none.", "operationId": "DeleteVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/contacts/{code}/verification/hmrc-request": { "post": { "tags": [ "Verification" ], "summary": "Request HMRC Verification", "description": "Asks HMRC to verify (or match) the subcontractor. The request is submitted to the HMRC gateway and polled in the background; the outcome lands on the verification, so poll GET (the Location header) until hmrcRequest.status leaves Pending. While a request is pending, another is 409. While the last request is Delayed (HMRC slow to answer), POST resumes polling that request, as HMRC asks. A contact whose CIS details are not complete enough to send is 400, with the reason also stored as its verification error; HMRC settings that are incomplete or rejected are 422.", "operationId": "RequestHmrcVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationRequest" } ], "description": "Asks HMRC to verify or match a subcontractor." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubcontractorVerificationDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Verification" ], "summary": "Cancel HMRC Verification Request", "description": "Cancels the subcontractor's pending or delayed HMRC verification request, so a new one can be submitted. 404 when there is none (a completed or failed request is history, not cancellable).", "operationId": "CancelHmrcVerificationRequest", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "x-order": 2 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/hmrc-verification-requests": { "post": { "tags": [ "Verification" ], "summary": "Request HMRC Verification For Many Contacts", "description": "Submits an HMRC verification (or match) request for each listed contact that can take one, and reports the rest with a reason: unknown, not a subcontractor, already verified, a request already pending, or CIS details too incomplete to send (the message is also stored on the contact). A delayed request is resumed. Requests are polled in the background; watch each contact's verification. HMRC settings that are incomplete or rejected are 422, before anything is sent.", "operationId": "RequestBulkHmrcVerification", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BulkHmrcVerificationRequest" } ], "description": "Asks HMRC to verify or match several subcontractors at once." } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkHmrcVerificationResultDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "The tenant's webhooks, without their secrets. Filter with enabled; sortBy Name, CreatedDate or Enabled.", "operationId": "ListWebhooks", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "enabled", "in": "query", "schema": { "type": "boolean" }, "x-order": 400 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookSortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Adds a webhook and generates its secret. Every delivery carries X-Webhook-Signature (t={unix time},v1={hex HMAC-SHA256 of \"{t}.{body}\" with the secret}) and X-Webhook-Event.", "operationId": "CreateWebhook", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateWebhookRequest" } ], "description": "A webhook to create. Its secret is generated." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks/{webhook}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook", "description": "One webhook, with the secret its deliveries are signed with.", "operationId": "GetWebhook", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Webhooks" ], "summary": "Update Webhook", "description": "Replaces the webhook's name, URL, enabled flag and events; the secret is kept. Setting enabled switches a webhook back on after it was switched off for repeated failures.", "operationId": "UpdateWebhook", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateWebhookRequest" } ], "description": "A webhook's new name, URL, enabled flag and events. The secret is kept." } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Deletes the webhook and its delivery history. To keep the history, disable the webhook instead.", "operationId": "DeleteWebhook", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks/{webhook}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test Webhook", "description": "Queues a test.webhook delivery to an enabled webhook and returns it, still pending: read the delivery to see how the receiver answered. A disabled webhook is refused (400).", "operationId": "TestWebhook", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "webhook", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhook Deliveries", "description": "What was sent to the tenant's webhooks, newest first, without the payloads. Filter by webhook, status, event and the dates the events happened between.", "operationId": "ListWebhookDeliveries", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "status", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryStatus" } ] }, "x-order": 200 }, { "name": "event", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ] }, "x-order": 400 }, { "name": "fromDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "toDate", "in": "query", "schema": { "type": "string", "format": "date-time" }, "x-order": 400 }, { "name": "webhook", "in": "query", "schema": { "type": "string", "format": "uuid" }, "x-order": 400 }, { "name": "offset", "in": "query", "description": "Number of records to skip (default: 0). Use with limit for pagination.", "schema": { "type": "integer", "format": "int32", "example": "0" }, "x-order": 500 }, { "name": "limit", "in": "query", "description": "Maximum number of records to return (default: 10, max: 50)", "schema": { "type": "integer", "format": "int32", "example": "20" }, "x-order": 501 }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Valid values depend on the resource.", "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliverySortField" } ], "example": "Name" }, "x-order": 502 }, { "name": "sortDesc", "in": "query", "description": "Sort in descending order (true) or ascending order (false, default)", "schema": { "type": "boolean", "example": "false" }, "x-order": 503 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDtoPagedResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks/deliveries/{delivery}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook Delivery", "description": "One delivery, with the payload that was sent and what the receiver answered on the last attempt.", "operationId": "GetWebhookDelivery", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDto" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/tenants/{tenant}/webhooks/deliveries/{delivery}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry Webhook Delivery", "description": "Sends a failed delivery once more. Refused (400) unless it failed, or when its webhook is disabled.", "operationId": "RetryWebhookDelivery", "parameters": [ { "name": "tenant", "in": "path", "description": "The tenant code (the organisation's URL stub)", "required": true, "schema": { "type": "string" }, "x-order": 0 }, { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/HttpValidationProblemDetails" } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "AccessLevel": { "enum": [ "None", "Admin" ], "type": "string", "example": "None" }, "AccountInvoiceDto": { "required": [ "code", "date", "hasPdf", "invoiceNumber", "status", "totalAmount" ], "type": "object", "properties": { "code": { "type": "string", "description": "The invoice's code (for its PDF)" }, "invoiceNumber": { "type": "string", "description": "The invoice number" }, "date": { "type": "string", "description": "The invoice date", "format": "date-time" }, "dueDate": { "type": "string", "description": "When payment is due", "format": "date", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/AccountInvoiceStatus" } ], "description": "Where it is in its payment" }, "totalAmount": { "type": "number", "description": "The total, VAT included", "format": "double" }, "hasPdf": { "type": "boolean", "description": "Whether a PDF can be downloaded" } }, "additionalProperties": false, "description": "An invoice to the caller from Sodium (Account Hub): their CIS Manager charges, with any other Sodium products the\nsame billing account pays for. CIS Manager's own invoices from before the switch are among them." }, "AccountInvoiceStatus": { "enum": [ "Issued", "PaymentPending", "Paid", "PaymentFailed", "Cancelled", "Uncollected" ], "type": "string", "description": "Where an invoice from Sodium is in its payment.", "example": "Issued" }, "AddPracticeOrganisationRequest": { "required": [ "tenant" ], "type": "object", "properties": { "tenant": { "minLength": 1, "type": "string", "description": "The tenant code: one the caller owns, in no practice" } }, "additionalProperties": false, "description": "One of the caller's organisations to put in the practice." }, "AddressDto": { "type": "object", "properties": { "line1": { "maxLength": 200, "type": "string", "description": "Address line 1", "nullable": true }, "line2": { "maxLength": 200, "type": "string", "description": "Address line 2", "nullable": true }, "line3": { "maxLength": 100, "type": "string", "description": "Address line 3", "nullable": true }, "line4": { "maxLength": 100, "type": "string", "description": "Address line 4", "nullable": true }, "postcode": { "maxLength": 20, "type": "string", "description": "Postcode", "nullable": true }, "country": { "maxLength": 100, "type": "string", "description": "Country", "nullable": true } }, "additionalProperties": false, "description": "A postal address." }, "BillingMandateDto": { "required": [ "isActive", "status" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/MandateStatus" } ], "description": "The mandate's state" }, "createdDate": { "type": "string", "description": "When the mandate was set up (or taken over by Account Hub)", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "description": "Whether payments can be collected: the mandate is active" } }, "additionalProperties": false, "description": "The caller's Direct Debit mandate, refreshed from GoCardless through Account Hub." }, "BillingProfileDto": { "required": [ "canAcceptPayments", "hasActiveMandate", "isShared", "mandateStatus" ], "type": "object", "properties": { "mandateStatus": { "allOf": [ { "$ref": "#/components/schemas/MandateStatus" } ], "description": "The Direct Debit mandate's state" }, "mandateCreatedDate": { "type": "string", "description": "When the mandate was set up (or taken over by Account Hub), if there is one", "format": "date-time", "nullable": true }, "hasActiveMandate": { "type": "boolean", "description": "Whether payments can be collected: the mandate is active" }, "canAcceptPayments": { "type": "boolean", "description": "Whether a payment could be submitted now: the mandate is active or on its way through the banks" }, "isShared": { "type": "boolean", "description": "The billing account also pays for Sodium: shown here, changed in Sodium (the profile and mandate writes answer 409)" }, "billingEmail": { "type": "string", "description": "Where invoices are also emailed; only the account's email address when blank", "nullable": true }, "companyName": { "type": "string", "description": "The company name invoices are made out to; the user's name when blank", "nullable": true }, "addressLine1": { "type": "string", "description": "Billing address, first line", "nullable": true }, "addressLine2": { "type": "string", "description": "Billing address, second line", "nullable": true }, "city": { "type": "string", "description": "Billing address town or city", "nullable": true }, "postcode": { "type": "string", "description": "Billing address postcode", "nullable": true }, "country": { "type": "string", "description": "Billing address country", "nullable": true } }, "additionalProperties": false, "description": "The caller's billing details, kept on their Account Hub billing account: the address their invoices are made out\nto and the state of their Direct Debit. Empty (no address, mandate NotStarted) until either is set." }, "BillingUsageDto": { "required": [ "billableCount", "month", "returnAcceptedDate", "status", "subcontractorCount", "tenantName", "year" ], "type": "object", "properties": { "tenantName": { "type": "string", "description": "The tenant's name" }, "year": { "type": "integer", "description": "The calendar year the tax month ends in", "format": "int32" }, "month": { "type": "integer", "description": "The calendar month the tax month ends in", "format": "int32" }, "subcontractorCount": { "type": "integer", "description": "The subcontractors on the return", "format": "int32" }, "previouslyBilledCount": { "type": "integer", "description": "The subcontractors already invoiced for the month, when it was re-submitted", "format": "int32", "nullable": true }, "billableCount": { "type": "integer", "description": "The subcontractors this record will be charged for", "format": "int32" }, "returnAcceptedDate": { "type": "string", "description": "When HMRC accepted the return", "format": "date-time" }, "status": { "allOf": [ { "$ref": "#/components/schemas/BillingUsageStatus" } ], "description": "Whether the usage has been invoiced" }, "billedDate": { "type": "string", "description": "When it was invoiced", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Usage recorded for a tenant the caller owns: a monthly return accepted by HMRC and the subcontractors on it." }, "BillingUsageStatus": { "enum": [ "Pending", "Discarded", "Billed", "PaidByCredits" ], "type": "string", "description": "Whether a usage record has been invoiced.", "example": "Pending" }, "BulkHmrcVerificationRequest": { "required": [ "action", "contacts" ], "type": "object", "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationAction" } ], "description": "Verify (the default) or Match, for every contact in the request" }, "contacts": { "maxItems": 100, "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "The codes of the contacts to verify, 1 to 100. Contacts that cannot be sent (unknown, not a subcontractor,\nalready verified, a request pending, incomplete CIS details) are skipped and reported, not refused." } }, "additionalProperties": false, "description": "Asks HMRC to verify or match several subcontractors at once." }, "BulkHmrcVerificationResultDto": { "required": [ "skipped", "submitted" ], "type": "object", "properties": { "submitted": { "type": "array", "items": { "type": "string" }, "description": "The codes of the contacts whose verification request was submitted (or, for a delayed request, resumed)" }, "skipped": { "type": "array", "items": { "$ref": "#/components/schemas/SkippedHmrcVerificationDto" }, "description": "The contacts that were not sent, with the reason" } }, "additionalProperties": false, "description": "The outcome of a bulk HMRC verification request: which contacts were sent to HMRC and which were not, and why." }, "CisDetailsDto": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Type of subcontractor (SoleTrader, Partnership, Company, Trust)" }, "utr": { "maxLength": 10, "pattern": "[0-9]{10}", "type": "string", "description": "Unique Taxpayer Reference (10 digits)", "nullable": true }, "companyNumber": { "maxLength": 8, "pattern": "[A-Za-z]{2}[0-9]{1,6}|[0-9]{1,8}", "type": "string", "description": "Company Registration Number (companies)", "nullable": true }, "niNumber": { "maxLength": 9, "pattern": "^[ABCEGHJKLMNOPRSTWXYZ]{1}[ABCEGHJKLMNPRSTWXYZ]{1}[0-9]{6}[A-D ]{1}$", "type": "string", "description": "National Insurance Number (sole traders)", "nullable": true }, "tradingName": { "maxLength": 200, "pattern": "^[A-Za-z0-9 ~!\"@#$%&'()*+,\\-./:;<=>?\\[\\]\\\\^_{}£€]*$", "type": "string", "description": "Trading name", "nullable": true }, "partnershipName": { "maxLength": 56, "pattern": "^[A-Za-z0-9 ~!\"@#$%&'()*+,\\-./:;<=>?\\[\\]\\\\^_{}£€]*$", "type": "string", "description": "Partnership name (partnerships)", "nullable": true }, "partnershipUtr": { "maxLength": 10, "pattern": "[0-9]{10}", "type": "string", "description": "Partnership UTR (partnerships)", "nullable": true } }, "additionalProperties": false, "description": "The subcontractor's CIS identity: what HMRC verifies them by. The verification outcome (status, verification\nnumber, tax treatment) is read-only and reported separately in CisManager.Api.DTOs.ContactDto.Verification." }, "CisDetailsPrefillDto": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "type": "string", "description": "The trading name; for a company or trust with none recorded, the contact's display name", "nullable": true }, "companyNumber": { "type": "string", "description": "The company registration number (a public record)", "nullable": true }, "partnershipName": { "type": "string", "description": "The partnership's name", "nullable": true } }, "additionalProperties": false, "description": "What the tenant already has on record for the subcontractor, for the public form to start from: how they trade\nand their names. It never carries a UTR or a National Insurance number: whoever holds the link sees this." }, "CisDetailsRequestDto": { "required": [ "code", "contact", "contactName", "createdDate", "emailedTo", "status" ], "type": "object", "properties": { "code": { "type": "string", "description": "The request's identifier, also the key of its public form", "format": "uuid" }, "status": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsRequestStatus" } ], "description": "Pending (waiting for the subcontractor), Submitted (details received, awaiting review) or Accepted" }, "contact": { "type": "string", "description": "The code of the subcontractor the request is for" }, "contactName": { "type": "string", "description": "The subcontractor's display name" }, "emailedTo": { "type": "string", "description": "Where the request was last sent" }, "details": { "allOf": [ { "$ref": "#/components/schemas/SubmittedCisDetailsDto" } ], "description": "What the subcontractor sent; null until they have", "nullable": true }, "sdcStatement": { "type": "string", "description": "The SDC statement sent with the request, when one was", "format": "uuid", "nullable": true }, "submittedDate": { "type": "string", "description": "When the subcontractor sent their details", "format": "date-time", "nullable": true }, "acceptedDate": { "type": "string", "description": "When the tenant accepted them onto the contact", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the request was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When it was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A request for a subcontractor's CIS details: the tenant emails the subcontractor a link to a public form, what\nthey enter is held on the request (not on the contact), and the tenant reviews it and accepts it onto the contact." }, "CisDetailsRequestStatus": { "enum": [ "Pending", "Submitted", "Accepted" ], "type": "string", "example": "Pending" }, "CisSubcontractorType": { "enum": [ "SoleTrader", "Partnership", "Company", "Trust" ], "type": "string", "example": "SoleTrader" }, "CisTaxStatus": { "enum": [ "NetOfHigherDeduction", "NetOfStandardDeduction", "Gross" ], "type": "string", "example": "NetOfHigherDeduction" }, "CompleteMandateSetupRequest": { "required": [ "redirectFlowId" ], "type": "object", "properties": { "redirectFlowId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The setup's redirect flow identifier: the success URL's `redirect_flow_id`" } }, "additionalProperties": false, "description": "Completes a Direct Debit setup the customer has finished on GoCardless (`PUT /me/billing/mandate`)." }, "ConnectionCisDetailsDto": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "type": "string", "description": "The trading name", "nullable": true }, "utr": { "type": "string", "description": "The Unique Taxpayer Reference", "nullable": true }, "niNumber": { "type": "string", "description": "The National Insurance number", "nullable": true }, "companyNumber": { "type": "string", "description": "The company registration number", "nullable": true }, "partnershipName": { "type": "string", "description": "The partnership's name", "nullable": true }, "partnershipUtr": { "type": "string", "description": "The partnership's UTR", "nullable": true } }, "additionalProperties": false, "description": "The CIS identity a subcontractor tenant shares over a connection." }, "ConnectionDto": { "required": [ "code", "createdDate", "direction", "initiatedByMe", "matchedToUser", "status" ], "type": "object", "properties": { "code": { "type": "string", "description": "The connection's identifier, shared by both sides", "format": "uuid" }, "direction": { "allOf": [ { "$ref": "#/components/schemas/InvoiceDirection" } ], "description": "The viewer's side: Out = the subcontractor that shared its details, In = the contractor they were sent to" }, "initiatedByMe": { "type": "boolean", "description": "Whether the viewing tenant initiated the connection" }, "status": { "allOf": [ { "$ref": "#/components/schemas/ConnectionStatus" } ], "description": "Pending, Connected or Rejected" }, "contact": { "type": "string", "description": "The viewer's contact for the other party (code); null on the receiving side until accepted", "nullable": true }, "counterPartyEmail": { "type": "string", "description": "The other party's email address: the one the initiator gave, or the initiating tenant's own", "nullable": true }, "counterParty": { "allOf": [ { "$ref": "#/components/schemas/ConnectionPartyDto" } ], "description": "The other party as far as it is known: on a connection sent to the viewer, the initiating tenant's details and\nthe CIS details it shares; on one the viewer initiated, the accepting tenant's name once accepted", "nullable": true }, "matchedToUser": { "type": "boolean", "description": "Whether the other party was matched to a CIS Manager user by email (rather than, or as well as, to a tenant)" }, "createdDate": { "type": "string", "description": "When the connection was initiated", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When it last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A connection between two CIS Manager tenants (an \"Interlink\"), seen from the viewing tenant's side. A\nsubcontractor tenant initiates it for one of its contractor contacts, sharing its CIS details with the email\naddress it gives; the contractor accepts it by creating (or naming) its own contact for the subcontractor.\ndirection is relative to the viewer: Out means the viewer is the subcontractor that shared its details, In\nmeans the viewer is the contractor they were sent to." }, "ConnectionPartyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The tenant's name", "nullable": true }, "address": { "type": "string", "description": "The tenant's address, one line per row", "nullable": true }, "phone": { "type": "string", "description": "The tenant's phone number", "nullable": true }, "email": { "type": "string", "description": "The tenant's email address", "nullable": true }, "cisDetails": { "allOf": [ { "$ref": "#/components/schemas/ConnectionCisDetailsDto" } ], "description": "The CIS details the initiating subcontractor is sharing; null on a connection the viewer initiated", "nullable": true } }, "additionalProperties": false, "description": "The other tenant on a connection." }, "ConnectionStatus": { "enum": [ "Pending", "Connected", "Rejected" ], "type": "string", "description": "Where a connection stands.", "example": "Pending" }, "ContactDto": { "required": [ "address", "code", "createdDate", "displayName", "invoicing", "isCisSubcontractor", "isCustomer", "isSupplier", "isVatRegistered" ], "type": "object", "properties": { "code": { "type": "string", "description": "Unique code within the tenant (uppercase letters and digits, up to 20). Generated on creation." }, "displayName": { "type": "string", "description": "Display name of the contact" }, "isCustomer": { "type": "boolean", "description": "Whether the tenant invoices this contact" }, "isSupplier": { "type": "boolean", "description": "Whether this contact invoices the tenant. Always true for a CIS subcontractor." }, "isCisSubcontractor": { "type": "boolean", "description": "Whether the tenant pays this contact under the Construction Industry Scheme" }, "title": { "type": "string", "description": "Title (e.g. Mr, Mrs, Ms)", "nullable": true }, "firstName": { "type": "string", "description": "First name", "nullable": true }, "secondName": { "type": "string", "description": "Second (middle) name", "nullable": true }, "lastName": { "type": "string", "description": "Last name", "nullable": true }, "emailAddress": { "type": "string", "description": "Email address", "nullable": true }, "telephone": { "type": "string", "description": "Telephone number", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ], "description": "Postal address" }, "isVatRegistered": { "type": "boolean", "description": "Whether the contact is VAT registered" }, "vatRegistrationNumber": { "type": "string", "description": "VAT registration number", "nullable": true }, "defaultRate": { "type": "number", "description": "Default rate for the contact", "format": "double", "nullable": true }, "externalId": { "type": "string", "description": "Your own identifier for the contact, set on creation", "nullable": true }, "lastSdc": { "type": "string", "description": "Date of the most recent SDC (Supervision, Direction and Control) questionnaire. Maintained by the system.", "format": "date-time", "nullable": true }, "cisDetails": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsDto" } ], "description": "CIS identity details. Present only for a CIS subcontractor.", "nullable": true }, "supplierSettings": { "allOf": [ { "$ref": "#/components/schemas/SupplierSettingsDto" } ], "description": "Defaults for the invoices received from the contact. Present only for a supplier.", "nullable": true }, "verification": { "allOf": [ { "$ref": "#/components/schemas/SubcontractorVerificationDto" } ], "description": "Current CIS verification (read-only). Present only for a CIS subcontractor.", "nullable": true }, "invoicing": { "allOf": [ { "$ref": "#/components/schemas/ContactInvoicingDto" } ], "description": "The invoices received from and issued to the contact (read-only)" }, "createdDate": { "type": "string", "description": "When the contact was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the contact was last updated", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A contact: a person or organisation the tenant does business with, in one or more roles. Customers are\ninvoiced by the tenant; suppliers invoice the tenant; CIS subcontractors are suppliers paid under the\nConstruction Industry Scheme. The role-specific parts (CIS identity and verification, supplier settings) are\npresent only for the roles the contact holds." }, "ContactDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "ContactImportResultDto": { "required": [ "createdCount", "failedCount", "rows" ], "type": "object", "properties": { "createdCount": { "type": "integer", "description": "The number of contacts created", "format": "int32" }, "failedCount": { "type": "integer", "description": "The number of selected rows that were not imported", "format": "int32" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ContactImportResultRowDto" }, "description": "One entry per selected row, in selection order" } }, "additionalProperties": false, "description": "The outcome of a subcontractor import." }, "ContactImportResultRowDto": { "required": [ "name", "rowId", "success" ], "type": "object", "properties": { "rowId": { "minLength": 1, "type": "string", "description": "The row id from the analysis" }, "name": { "minLength": 1, "type": "string", "description": "The name the row gives the contact, as written in the file" }, "success": { "type": "boolean", "description": "Whether the contact was created" }, "code": { "type": "string", "description": "The created contact's code", "nullable": true }, "error": { "type": "string", "description": "Why the row was not imported", "nullable": true } }, "additionalProperties": false, "description": "The outcome of importing one selected row." }, "ContactImportRowDto": { "required": [ "defaultSelected", "isVatRegistered", "name", "rowId" ], "type": "object", "properties": { "rowId": { "minLength": 1, "type": "string", "description": "The row's id (row-{n}, n the 1-based data row; the header is row 0), passed back in the import's selections" }, "name": { "minLength": 1, "type": "string", "description": "The name the row gives the contact (the trading name, else first and last name), as written in the file" }, "subcontractorType": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "The subcontractor type (SoleTrader when the file leaves it blank); null when the row carries no CIS details", "nullable": true }, "utr": { "type": "string", "description": "The UTR", "nullable": true }, "emailAddress": { "type": "string", "description": "The email address", "nullable": true }, "isVatRegistered": { "type": "boolean", "description": "Whether the contact is VAT registered" }, "verificationNumber": { "type": "string", "description": "The HMRC verification number the row carries; the import records it as a manual verification", "nullable": true }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The tax status of that verification", "nullable": true }, "externalId": { "type": "string", "description": "The external id", "nullable": true }, "skipReason": { "type": "string", "description": "Why the row cannot be imported; null when it can", "nullable": true }, "defaultSelected": { "type": "boolean", "description": "Whether a client should pre-select the row (true when it has no skip reason)" } }, "additionalProperties": false, "description": "One data row of a subcontractor import CSV as the analysis sees it: the contact it would become, or why it is skipped." }, "ContactInvoicingDto": { "required": [ "in", "out" ], "type": "object", "properties": { "in": { "allOf": [ { "$ref": "#/components/schemas/InvoicingSummaryDto" } ], "description": "Invoices received from the contact (the supplier side)" }, "out": { "allOf": [ { "$ref": "#/components/schemas/InvoicingSummaryDto" } ], "description": "Invoices issued to the contact (the customer side)" } }, "additionalProperties": false, "description": "A contact's invoicing summaries, one per direction. Read-only; maintained by the invoice resources." }, "ContactNoteDto": { "required": [ "code", "createdDate", "date" ], "type": "object", "properties": { "code": { "type": "string", "description": "The note's identifier within the contact", "format": "uuid" }, "note": { "type": "string", "description": "The note's text", "nullable": true }, "date": { "type": "string", "description": "The date the note is about (defaults to when it was recorded; editable)", "format": "date-time" }, "createdDate": { "type": "string", "description": "When the note was recorded", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the note was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A free-text note recorded against a contact." }, "ContactNoteDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactNoteDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "ContactNoteSortField": { "enum": [ "Date", "CreatedDate" ], "type": "string", "example": "Date" }, "ContactSortField": { "enum": [ "Name", "Code", "Verified", "InvoicesTotal", "PaymentsOutstanding" ], "type": "string", "example": "Name" }, "CreateCisDetailsRequestRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Where to send the request", "format": "email" }, "sdcStatementTitle": { "maxLength": 200, "minLength": 0, "type": "string", "description": "When given, an SDC statement with this title is created for the subcontractor too: the one email asks for\nboth, and the form leads on to the statement once the CIS details are in", "nullable": true } }, "additionalProperties": false, "description": "A new request for a subcontractor's CIS details. Creating it emails the subcontractor the link to the form." }, "CreateConnectionRequest": { "required": [ "contact", "email" ], "type": "object", "properties": { "contact": { "minLength": 1, "type": "string", "description": "The tenant's contact for the contractor (code)" }, "email": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The contractor's email address, where the details are sent", "format": "email" } }, "additionalProperties": false, "description": "A new connection: the tenant shares its CIS details with one of its contractor contacts." }, "CreateContactNoteRequest": { "required": [ "note" ], "type": "object", "properties": { "note": { "minLength": 1, "type": "string", "description": "The note's text" }, "date": { "type": "string", "description": "The date the note is about. Defaults to now (UTC).", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A new note for a contact." }, "CreateContactRequest": { "required": [ "displayName", "isCisSubcontractor", "isCustomer", "isSupplier", "isVatRegistered" ], "type": "object", "properties": { "isCustomer": { "type": "boolean", "description": "Whether the tenant invoices this contact" }, "isSupplier": { "type": "boolean", "description": "Whether this contact invoices the tenant. Required for a CIS subcontractor." }, "isCisSubcontractor": { "type": "boolean", "description": "Whether the tenant pays this contact under the Construction Industry Scheme" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Display name of the contact" }, "title": { "maxLength": 4, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "Title (e.g. Mr, Mrs, Ms)", "nullable": true }, "firstName": { "maxLength": 35, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "First name", "nullable": true }, "secondName": { "maxLength": 35, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "Second (middle) name", "nullable": true }, "lastName": { "maxLength": 35, "pattern": "^[A-Za-z0-9 ,\\.\\(\\)/&\\-']+$", "type": "string", "description": "Last name", "nullable": true }, "emailAddress": { "maxLength": 255, "type": "string", "description": "Email address", "format": "email", "nullable": true }, "telephone": { "maxLength": 50, "type": "string", "description": "Telephone number", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ], "description": "Postal address", "nullable": true }, "isVatRegistered": { "type": "boolean", "description": "Whether the contact is VAT registered" }, "vatRegistrationNumber": { "maxLength": 20, "type": "string", "description": "VAT registration number", "nullable": true }, "defaultRate": { "type": "number", "description": "Default rate for the contact", "format": "double", "nullable": true }, "cisDetails": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsDto" } ], "description": "CIS identity details. Only for a CIS subcontractor.", "nullable": true }, "supplierSettings": { "allOf": [ { "$ref": "#/components/schemas/SupplierSettingsDto" } ], "description": "Defaults for the invoices received from the contact. Only for a supplier.", "nullable": true }, "externalId": { "maxLength": 50, "type": "string", "description": "Your own identifier for the contact, e.g. its id in an external system. Set once, on creation.", "nullable": true } }, "additionalProperties": false, "description": "Creates a contact. The code is generated from the display name. The role-specific parts may be omitted: a CIS\nsubcontractor without cisDetails gets an empty identity of type SoleTrader, and a supplier without\nsupplierSettings gets a default VAT rate that follows the VAT-registered flag." }, "CreateEmailConfigRequest": { "required": [ "fromEmail", "isDefault", "providerType" ], "type": "object", "properties": { "providerType": { "allOf": [ { "$ref": "#/components/schemas/EmailProviderType" } ], "description": "How the connection sends" }, "fromEmail": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The address the emails are from (for Outlook and Gmail, the mailbox that will sign in)", "format": "email" }, "fromName": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The name the emails are from; the tenant's name when left out", "nullable": true }, "isDefault": { "type": "boolean", "description": "Make it the connection the tenant's emails go through. The tenant's first connection always is." }, "smtpSettings": { "allOf": [ { "$ref": "#/components/schemas/EmailSmtpSettingsRequest" } ], "description": "The SMTP settings; required for an SMTP connection", "nullable": true }, "returnUrl": { "maxLength": 500, "minLength": 0, "type": "string", "description": "The page of this application the sign-in returns to, with `oauth_status` (`success` or `error`),\n`config_code` and `oauth_error` added to its query; required for Outlook and Gmail", "nullable": true } }, "additionalProperties": false, "description": "A connection to add. SMTP takes `smtpSettings`; Outlook and Gmail take `returnUrl` and answer with the\n`authorisationUrl` to send the user to." }, "CreateInvitationRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 150, "minLength": 0, "type": "string", "description": "Where to send it", "format": "email" }, "role": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "description": "The access level offered; Admin when omitted", "nullable": true }, "message": { "maxLength": 1000, "minLength": 0, "type": "string", "description": "A personal message for the email", "nullable": true }, "practice": { "type": "boolean", "description": "Invite to the tenant's whole practice (every organisation it runs) rather than the tenant alone. The tenant must\nbe in a practice managed in CIS Manager", "nullable": true } }, "additionalProperties": false, "description": "A new invitation. It is emailed at once and expires after seven days." }, "CreateInvoiceLineRequest": { "required": [ "amount", "quantity", "type", "vatRate" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/InvoiceLineType" } ], "description": "Labour (subject to the CIS deduction) or Materials" }, "description": { "maxLength": 500, "type": "string", "description": "What the line is for", "nullable": true }, "quantity": { "type": "number", "description": "Quantity (hours, units). Values under 1 are treated as 1.", "format": "double" }, "amount": { "type": "number", "description": "Unit amount before VAT", "format": "double" }, "vatRate": { "allOf": [ { "$ref": "#/components/schemas/VatRate" } ], "description": "The VAT rate. Ignored (OutOfScope) when VAT does not apply to the invoice." }, "externalId": { "maxLength": 50, "type": "string", "description": "The caller's own identifier for the line", "nullable": true } }, "additionalProperties": false, "description": "A line of a new invoice." }, "CreateInvoicePaymentRequest": { "required": [ "amount", "date" ], "type": "object", "properties": { "date": { "type": "string", "description": "When it was paid. A purchase invoice payment cannot fall in a tax month whose return is submitted.", "format": "date-time" }, "amount": { "type": "number", "description": "The amount paid. The invoice's payments cannot exceed its amount payable.", "format": "double" } }, "additionalProperties": false, "description": "A new payment against an invoice." }, "CreateInvoiceRequest": { "required": [ "contact", "date", "isDomesticReverseCharge", "lines" ], "type": "object", "properties": { "date": { "type": "string", "description": "The invoice date", "format": "date-time" }, "dueDate": { "type": "string", "description": "When payment is due. Defaults to the invoice date.", "format": "date-time", "nullable": true }, "yourReference": { "maxLength": 50, "type": "string", "description": "The tenant's own reference", "nullable": true }, "theirReference": { "maxLength": 50, "type": "string", "description": "The contact's reference", "nullable": true }, "isDomesticReverseCharge": { "type": "boolean", "description": "Whether the VAT domestic reverse charge applies. Cleared when either party is not VAT registered." }, "deduction": { "type": "number", "description": "Sales invoices only: the CIS deduction the customer made. Ignored on a purchase invoice, where the deduction\nfollows from the labour total and the tax status.", "format": "double", "nullable": true }, "contact": { "minLength": 1, "type": "string", "description": "The contact's code: a supplier for a purchase invoice, a customer for a sales invoice" }, "externalId": { "maxLength": 50, "type": "string", "description": "The caller's own identifier for the invoice", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreateInvoiceLineRequest" }, "description": "The lines" } }, "additionalProperties": false, "description": "A new invoice." }, "CreateMandateSetupRequest": { "required": [ "successRedirectUrl" ], "type": "object", "properties": { "successRedirectUrl": { "maxLength": 500, "minLength": 1, "type": "string", "description": "Where GoCardless sends the customer's browser once they have completed the setup. GoCardless appends\n`redirect_flow_id` to it; the client then completes the setup with PUT /me/billing/mandate.", "format": "uri" } }, "additionalProperties": false, "description": "Starts a Direct Debit setup (`POST /me/billing/mandate-setups`)." }, "CreateMonthlyReturnRequest": { "required": [ "month", "year" ], "type": "object", "properties": { "year": { "maximum": 2100, "minimum": 2000, "type": "integer", "description": "The calendar year the tax month ends in", "format": "int32" }, "month": { "maximum": 12, "minimum": 1, "type": "integer", "description": "The calendar month (1 to 12) the tax month ends in", "format": "int32" } }, "additionalProperties": false, "description": "A new monthly return for a tax month." }, "CreateMyApiKeyRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 100, "minLength": 1, "type": "string", "description": "A name for the key, to tell it from the caller's others" }, "expiresDate": { "type": "string", "description": "When the key expires, which must be in the future; never when blank", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Issues the caller an API key (`POST /me/api-keys`)." }, "CreatePracticeHmrcCredentialsRequest": { "required": [ "isDefault", "name", "password", "senderId", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "name": { "maxLength": 100, "minLength": 0, "type": "string", "description": "What the HMRC settings page offers the set as" }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 30, "minLength": 0, "type": "string", "description": "The gateway user id" }, "testInLive": { "type": "boolean", "description": "Send submissions to the live gateway flagged as tests" }, "useTestGateway": { "type": "boolean", "description": "Send submissions to HMRC's test gateway" }, "agent": { "allOf": [ { "$ref": "#/components/schemas/HmrcAgentDto" } ], "description": "The agent details, when the sender is an agent", "nullable": true }, "password": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The gateway password" }, "isDefault": { "type": "boolean", "description": "Make it the practice's default (the practice's first set is the default whatever this says)" } }, "additionalProperties": false, "description": "A new set of practice credentials." }, "CreatePracticeRequest": { "required": [ "name", "organisations" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The practice's name" }, "organisations": { "type": "array", "items": { "type": "string" }, "description": "The tenants to put in it: each one the caller owns, in no practice" } }, "additionalProperties": false, "description": "A new practice, the caller its first member." }, "CreateSdcStatementRequest": { "required": [ "emailTo", "title" ], "type": "object", "properties": { "title": { "maxLength": 200, "minLength": 0, "type": "string", "description": "What the statement is for" }, "statementDate": { "type": "string", "description": "The date the statement is made for; today when omitted", "format": "date-time", "nullable": true }, "emailTo": { "maxLength": 200, "minLength": 0, "type": "string", "description": "Where to send the completion request", "format": "email" } }, "additionalProperties": false, "description": "A new SDC statement. Creating it emails the subcontractor a link to complete it." }, "CreateTenantRequest": { "required": [ "isVatRegistered", "modules", "name" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The tenant's name" }, "isVatRegistered": { "type": "boolean", "description": "Whether the tenant is VAT registered" }, "vatRegistrationNumber": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The VAT registration number", "nullable": true }, "modules": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Modules" }, "description": "The modules the tenant uses: CisContractor, CisSubcontractor or both" }, "practice": { "type": "string", "description": "One of the caller's practices (managed in CIS Manager) to create the tenant in: its members reach it, and a\ncontractor tenant files with the practice's default HMRC credentials. Leave out for a tenant in no practice", "format": "uuid", "nullable": true }, "newPracticeName": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The name of a new practice to create the tenant in, the caller its first member: an accountant setting up a\nclient. Not with practice", "nullable": true } }, "additionalProperties": false, "description": "A new tenant, owned by the caller. Its email address and phone number start as the caller's." }, "CreateWebhookRequest": { "required": [ "enabled", "events", "name", "url" ], "type": "object", "properties": { "name": { "maxLength": 100, "minLength": 0, "type": "string", "description": "What the webhook is for" }, "url": { "maxLength": 500, "minLength": 0, "type": "string", "description": "The HTTPS URL the events are sent to" }, "enabled": { "type": "boolean", "description": "Whether events are sent" }, "events": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "The events the webhook is sent; at least one" } }, "additionalProperties": false, "description": "A webhook to create. Its secret is generated." }, "DateField": { "enum": [ "Date", "DueDate", "PaidDate", "PaidTaxMonthEnding" ], "type": "string", "example": "Date" }, "EmailConfigDto": { "required": [ "code", "createdDate", "fromEmail", "isDefault", "providerType", "status" ], "type": "object", "properties": { "code": { "type": "string", "description": "The connection's code" }, "providerType": { "allOf": [ { "$ref": "#/components/schemas/EmailProviderType" } ], "description": "How the connection sends" }, "fromEmail": { "type": "string", "description": "The address the emails are from" }, "fromName": { "type": "string", "description": "The name the emails are from", "nullable": true }, "isDefault": { "type": "boolean", "description": "Whether the tenant's emails go through this connection (when it is connected)" }, "status": { "allOf": [ { "$ref": "#/components/schemas/EmailConfigStatus" } ], "description": "The connection's state; only a connected one sends" }, "statusReason": { "type": "string", "description": "Why the connection is not connected, when known", "nullable": true }, "smtpSettings": { "allOf": [ { "$ref": "#/components/schemas/EmailSmtpSettingsDto" } ], "description": "The SMTP settings of an SMTP connection (never the password)", "nullable": true }, "connectedEmail": { "type": "string", "description": "The mailbox an Outlook or Gmail connection signed in as", "nullable": true }, "authorisationUrl": { "type": "string", "description": "Where to send the user to sign in, while an Outlook or Gmail connection awaits it", "nullable": true }, "createdDate": { "type": "string", "description": "When the connection was added", "format": "date-time" } }, "additionalProperties": false, "description": "One of the tenant's own email connections (SMTP, Outlook or Gmail), which it sends its emails through. Send\nonly. With no connected default, the tenant's emails go through CIS Manager's own sender, replies to the tenant." }, "EmailConfigStatus": { "enum": [ "PendingOAuthSetup", "Active", "OAuthFailed", "Deleted", "OAuthExpired", "ConnectionError", "Deleting" ], "type": "string", "example": "PendingOAuthSetup" }, "EmailDeliveryStatus": { "enum": [ "Queued", "Sent", "Failed" ], "type": "string", "example": "Queued" }, "EmailMessageDto": { "required": [ "createdDate", "status" ], "type": "object", "properties": { "to": { "type": "string", "description": "The recipient's address", "nullable": true }, "toName": { "type": "string", "description": "The recipient's name", "nullable": true }, "cc": { "type": "string", "description": "The copy recipient's address, if any", "nullable": true }, "ccName": { "type": "string", "description": "The copy recipient's name", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/EmailDeliveryStatus" } ], "description": "Queued, Sent or Failed" }, "statusDate": { "type": "string", "description": "When the status last changed", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the email was queued", "format": "date-time" } }, "additionalProperties": false, "description": "An email sent of a document (an invoice, a remittance advice) to a contact, with its delivery status." }, "EmailProviderType": { "enum": [ "Smtp", "Microsoft365", "Google" ], "type": "string", "example": "Smtp" }, "EmailSettingsDto": { "required": [ "autoSendStatements" ], "type": "object", "properties": { "signature": { "type": "string", "description": "The signature appended to the tenant's emails", "nullable": true }, "autoSendStatements": { "type": "boolean", "description": "Email subcontractors their statements automatically when a return is accepted" } }, "additionalProperties": false, "description": "The tenant's email settings: the signature appended to every email it sends and whether statements go out\nautomatically." }, "EmailSmtpEncryption": { "enum": [ "Auto", "Ssl", "Tls" ], "type": "string", "example": "Auto" }, "EmailSmtpSettingsDto": { "required": [ "encryption", "hasPassword", "host", "port", "requiresAuthentication" ], "type": "object", "properties": { "host": { "type": "string", "description": "The SMTP server" }, "port": { "type": "integer", "description": "The server's port", "format": "int32" }, "encryption": { "allOf": [ { "$ref": "#/components/schemas/EmailSmtpEncryption" } ], "description": "How the connection is secured" }, "requiresAuthentication": { "type": "boolean", "description": "Whether the server asks for a username and password" }, "username": { "type": "string", "description": "The username", "nullable": true }, "hasPassword": { "type": "boolean", "description": "Whether a password is stored (it is never returned)" } }, "additionalProperties": false, "description": "An SMTP connection's settings as stored." }, "EmailSmtpSettingsRequest": { "required": [ "encryption", "host", "port", "requiresAuthentication" ], "type": "object", "properties": { "host": { "maxLength": 255, "minLength": 0, "type": "string", "description": "The SMTP server" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer", "description": "The server's port", "format": "int32" }, "encryption": { "allOf": [ { "$ref": "#/components/schemas/EmailSmtpEncryption" } ], "description": "How the connection is secured" }, "requiresAuthentication": { "type": "boolean", "description": "Whether the server asks for a username and password" }, "username": { "maxLength": 255, "minLength": 0, "type": "string", "description": "The username", "nullable": true }, "password": { "maxLength": 255, "minLength": 0, "type": "string", "description": "The password. Left out of an update, the stored one is kept.", "nullable": true } }, "additionalProperties": false, "description": "SMTP settings to store." }, "EmailTemplateDto": { "required": [ "isCustomised", "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateType" } ], "description": "Which email the template is for" }, "subject": { "type": "string", "description": "The subject in use", "nullable": true }, "body": { "type": "string", "description": "The body in use", "nullable": true }, "defaultSubject": { "type": "string", "description": "The default subject", "nullable": true }, "defaultBody": { "type": "string", "description": "The default body", "nullable": true }, "isCustomised": { "type": "boolean", "description": "Whether the subject or body differs from the default" } }, "additionalProperties": false, "description": "One of the tenant's email templates: the subject and body in use (the defaults until customised) and the\ndefaults themselves." }, "EmailTemplateType": { "enum": [ "SubcontractorMonthlyStatement", "Invoice", "UserInvitation", "InvitationAccepted", "InvitationRejected", "RemittanceAdvice", "SdcStatementRequest", "SubcontractorAnnualStatement" ], "type": "string", "example": "SubcontractorMonthlyStatement" }, "EnumMetadata": { "required": [ "displayName", "name", "value" ], "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "integer", "format": "int32" }, "displayName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "backgroundColor": { "type": "string", "nullable": true }, "textColor": { "type": "string", "nullable": true }, "group": { "type": "string", "nullable": true }, "order": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "HmrcAgentDto": { "required": [ "addressLines" ], "type": "object", "properties": { "agentId": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The HMRC agent id", "nullable": true }, "company": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The agent's company name (HMRC takes 35 characters: a longer name is cut as the submission is built)", "nullable": true }, "addressLines": { "type": "array", "items": { "type": "string" }, "description": "The agent's address lines" }, "postcode": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The agent's postcode", "nullable": true }, "country": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The agent's country", "nullable": true }, "contact": { "allOf": [ { "$ref": "#/components/schemas/HmrcContactDto" } ], "description": "The agent's contact", "nullable": true } }, "additionalProperties": false, "description": "The agent details sent with a submission when the sender is an agent." }, "HmrcContactDto": { "type": "object", "properties": { "firstName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "First name", "nullable": true }, "lastName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Last name", "nullable": true }, "email": { "maxLength": 150, "minLength": 0, "type": "string", "description": "Email address", "nullable": true }, "telephone": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Telephone number", "nullable": true } }, "additionalProperties": false, "description": "A person HMRC can contact about a submission." }, "HmrcCredentialsTestResultDto": { "required": [ "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether HMRC accepted the credentials" }, "message": { "type": "string", "description": "HMRC's message, or the reason the test could not run", "nullable": true } }, "additionalProperties": false, "description": "The outcome of a credentials test against the HMRC gateway." }, "HmrcError": { "required": [ "errorNumber", "errorType", "location", "technicalMessage", "userMessage" ], "type": "object", "properties": { "errorNumber": { "type": "integer", "format": "int32" }, "errorType": { "type": "string" }, "technicalMessage": { "type": "string" }, "location": { "type": "string" }, "userMessage": { "type": "string" } }, "additionalProperties": false }, "HmrcSettingsDto": { "required": [ "hasPassword", "needsConfig", "senderType", "testInLive", "useSharedCredentials", "useTestGateway" ], "type": "object", "properties": { "useSharedCredentials": { "type": "boolean", "description": "Whether the tenant signs in with one of the owner's shared credentials rather than its own" }, "sharedCredentialsId": { "type": "string", "description": "The shared credentials in use: one of the practice's sets (/settings/hmrc/shared-credentials). Null with\nuseSharedCredentials follows the practice's default", "format": "uuid", "nullable": true }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Whether the tenant submits as the employer, an agent or acting in capacity" }, "senderId": { "type": "string", "description": "The gateway user id", "nullable": true }, "hasPassword": { "type": "boolean", "description": "Whether a gateway password is stored" }, "employerPayeReference": { "type": "string", "description": "The employer PAYE reference, office number and reference in one: \"123/AB45678\"", "nullable": true }, "accountsOfficeReference": { "type": "string", "description": "The accounts office reference", "nullable": true }, "utr": { "type": "string", "description": "The tenant's Unique Taxpayer Reference as a contractor", "nullable": true }, "testInLive": { "type": "boolean", "description": "Send submissions to the live gateway flagged as tests" }, "useTestGateway": { "type": "boolean", "description": "Send submissions to HMRC's test gateway" }, "agent": { "allOf": [ { "$ref": "#/components/schemas/HmrcAgentDto" } ], "description": "The agent details, when the sender is an agent", "nullable": true }, "needsConfig": { "type": "boolean", "description": "True until the settings can be submitted with: own credentials need a sender id and an accounts office reference" } }, "additionalProperties": false, "description": "The tenant's HMRC gateway settings for CIS submissions. The gateway password is never returned: hasPassword\nsays whether one is stored. With useSharedCredentials the sender fields come from the shared credentials and\nare not shown." }, "HmrcSubmissionStatus": { "enum": [ "Pending", "Delayed", "Completed", "Failed" ], "type": "string", "description": "The state of an HMRC submission: pending (polled in the background), delayed (HMRC did not answer within the\npolling window), completed (the outcome landed on the parent), or failed.", "example": "Pending" }, "HmrcVerificationAction": { "enum": [ "Verify", "Match" ], "type": "string", "description": "What to ask HMRC to do with a subcontractor.", "example": "Verify" }, "HmrcVerificationRequest": { "required": [ "action" ], "type": "object", "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationAction" } ], "description": "Verify (the default) or Match. Ignored when the contact's last request is Delayed: that request is resumed as\nsubmitted." } }, "additionalProperties": false, "description": "Asks HMRC to verify or match a subcontractor." }, "HmrcVerificationRequestDto": { "required": [ "status", "submittedDate" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationRequestStatus" } ], "description": "Request status" }, "submittedDate": { "type": "string", "description": "When the request was submitted to HMRC", "format": "date-time" }, "lastPolledDate": { "type": "string", "description": "When HMRC was last polled for the outcome", "format": "date-time", "nullable": true }, "requestXml": { "type": "string", "description": "The GovTalk request sent to HMRC; only for callers with the HmrcXmlViewer role", "nullable": true }, "responseXml": { "type": "string", "description": "HMRC's GovTalk response; only for callers with the HmrcXmlViewer role", "nullable": true } }, "additionalProperties": false, "description": "A subcontractor's latest HMRC verification request. Requests are asynchronous: the API submits them to the HMRC\ngateway and polls for the outcome, which lands on the verification." }, "HmrcVerificationRequestStatus": { "enum": [ "Pending", "Delayed", "Completed", "Failed" ], "type": "string", "description": "Where a subcontractor's latest HMRC verification request stands.", "example": "Pending" }, "HmrcVerificationSkipReason": { "enum": [ "NotFound", "NotSubcontractor", "AlreadyVerified", "RequestPending", "InvalidDetails" ], "type": "string", "description": "Why a contact in a bulk HMRC verification request was not sent to HMRC.", "example": "NotFound" }, "HttpValidationProblemDetails": { "required": [ "errors" ], "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": {} }, "InvitationStatus": { "enum": [ "Pending", "Accepted", "Rejected", "Expired" ], "type": "string", "example": "Pending" }, "InvoiceDirection": { "enum": [ "In", "Out" ], "type": "string", "example": "In" }, "InvoiceDto": { "required": [ "contact", "contactTaxStatus", "createdDate", "date", "deduction", "dueDate", "isDomesticReverseCharge", "isVatApplicable", "number", "paid", "paymentAmount", "taxStatus", "total", "totalLabour", "totalMaterials", "totalOfPayments", "totalVat" ], "type": "object", "properties": { "number": { "type": "integer", "description": "The invoice number, allocated by the tenant in sequence per direction", "format": "int32" }, "contact": { "type": "string", "description": "The contact's code" }, "contactName": { "type": "string", "description": "The contact's display name", "nullable": true }, "date": { "type": "string", "description": "The invoice date", "format": "date-time" }, "dueDate": { "type": "string", "description": "When payment is due", "format": "date-time" }, "yourReference": { "type": "string", "description": "The tenant's own reference", "nullable": true }, "theirReference": { "type": "string", "description": "The contact's reference", "nullable": true }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The CIS deduction rate applied to this invoice's labour. On a purchase invoice it defaults to the\nsubcontractor's rate when the invoice is created." }, "contactTaxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The subcontractor's current CIS deduction rate, so a caller can see when it differs from the invoice's" }, "isVatApplicable": { "type": "boolean", "description": "Whether VAT applies: derived from the VAT registration of the two parties, not settable" }, "isDomesticReverseCharge": { "type": "boolean", "description": "Whether the VAT domestic reverse charge applies (no VAT charged on the invoice)" }, "totalLabour": { "type": "number", "description": "Total of the labour lines, before VAT", "format": "double" }, "totalMaterials": { "type": "number", "description": "Total of the materials lines, before VAT", "format": "double" }, "totalVat": { "type": "number", "description": "Total VAT", "format": "double" }, "total": { "type": "number", "description": "Grand total: labour, materials and VAT", "format": "double" }, "deduction": { "type": "number", "description": "The CIS deduction: computed from the labour total and the tax status on a purchase invoice, recorded by the\ncaller on a sales invoice (what the customer deducted)", "format": "double" }, "paymentAmount": { "type": "number", "description": "The amount payable: the total less the deduction", "format": "double" }, "totalOfPayments": { "type": "number", "description": "The total of the payments recorded against the invoice", "format": "double" }, "paid": { "type": "boolean", "description": "Whether the payments cover the amount payable" }, "paidDate": { "type": "string", "description": "The date of the last payment, when paid", "format": "date-time", "nullable": true }, "monthlyReturnStatus": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnStatus" } ], "description": "On a paid purchase invoice, the status of the CIS monthly return for the tax month it was paid in (Open when\nthe return does not exist yet)", "nullable": true }, "emailStatus": { "allOf": [ { "$ref": "#/components/schemas/EmailDeliveryStatus" } ], "description": "The delivery status of the last email of the invoice, if it was emailed", "nullable": true }, "externalId": { "type": "string", "description": "The caller's own identifier for the invoice (an external system's id), set on create", "nullable": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLineDto" }, "description": "The invoice lines. Present on a single invoice; null on a list.", "nullable": true }, "createdDate": { "type": "string", "description": "When the invoice was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the invoice was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "An invoice: a purchase invoice received from a supplier or subcontractor (the tenant pays it), or a sales invoice\nthe tenant issued to a customer. The number is unique within the tenant and direction." }, "InvoiceDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "InvoiceLineDto": { "required": [ "amount", "code", "quantity", "total", "type", "vatAmount", "vatRate" ], "type": "object", "properties": { "code": { "type": "string", "description": "The line's identifier within the invoice", "format": "uuid" }, "type": { "allOf": [ { "$ref": "#/components/schemas/InvoiceLineType" } ], "description": "Labour (subject to the CIS deduction) or Materials" }, "description": { "type": "string", "description": "What the line is for", "nullable": true }, "quantity": { "type": "number", "description": "Quantity (hours, units); at least 1", "format": "double" }, "amount": { "type": "number", "description": "Unit amount before VAT", "format": "double" }, "vatRate": { "allOf": [ { "$ref": "#/components/schemas/VatRate" } ], "description": "The VAT rate; OutOfScope when VAT does not apply to the invoice" }, "vatAmount": { "type": "number", "description": "The VAT on the line (0 under the domestic reverse charge)", "format": "double" }, "total": { "type": "number", "description": "Quantity times amount, plus VAT", "format": "double" }, "externalId": { "type": "string", "description": "The caller's own identifier for the line", "nullable": true } }, "additionalProperties": false, "description": "A line of an invoice: labour or materials." }, "InvoiceLineType": { "enum": [ "Labour", "Materials" ], "type": "string", "example": "Labour" }, "InvoicePaymentDto": { "required": [ "amount", "code", "createdDate", "date", "monthlyReturnStatus", "percentageOfInvoiceCovered", "taxMonth", "taxYear" ], "type": "object", "properties": { "code": { "type": "string", "description": "The payment's identifier within the invoice", "format": "uuid" }, "date": { "type": "string", "description": "When it was paid", "format": "date-time" }, "amount": { "type": "number", "description": "The amount paid", "format": "double" }, "taxMonth": { "type": "integer", "description": "The CIS tax month (1 = the month ending 5 May) the payment falls in", "format": "int32" }, "taxYear": { "type": "integer", "description": "The CIS tax year the payment falls in", "format": "int32" }, "monthlyReturnStatus": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnStatus" } ], "description": "The status of the CIS monthly return for that tax month (Open when the return does not exist yet)" }, "percentageOfInvoiceCovered": { "type": "number", "description": "The share of the invoice's amount payable this payment covers (0 to 1)", "format": "double" }, "createdDate": { "type": "string", "description": "When the payment was recorded", "format": "date-time" } }, "additionalProperties": false, "description": "A payment recorded against an invoice." }, "InvoiceSortField": { "enum": [ "Date", "Number", "Contact", "YourReference", "TheirReference" ], "type": "string", "description": "Sort fields for an invoice list.", "example": "Date" }, "InvoicingSummaryDto": { "required": [ "count", "total", "unpaid" ], "type": "object", "properties": { "count": { "type": "integer", "description": "Number of invoices", "format": "int32" }, "total": { "type": "number", "description": "Total invoiced", "format": "double" }, "unpaid": { "type": "number", "description": "Total still unpaid", "format": "double" }, "earliestDate": { "type": "string", "description": "Date of the earliest invoice, if any", "format": "date-time", "nullable": true }, "latestDate": { "type": "string", "description": "Date of the latest invoice, if any", "format": "date-time", "nullable": true }, "earliestDueDate": { "type": "string", "description": "The earliest due date", "format": "date-time", "nullable": true }, "latestDueDate": { "type": "string", "description": "The latest due date", "format": "date-time", "nullable": true }, "earliestPaidDate": { "type": "string", "description": "The earliest payment date; null until an invoice is paid", "format": "date-time", "nullable": true }, "latestPaidDate": { "type": "string", "description": "The latest payment date; null until an invoice is paid (the statements page keys off it)", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A summary of the invoices in one direction, a tenant's or one contact's: count, total, what is still\nunpaid and the date range. Read-only; maintained by the invoice resources." }, "MandateSetupDto": { "required": [ "redirectUrl" ], "type": "object", "properties": { "redirectUrl": { "type": "string", "description": "The GoCardless page to send the customer's browser to" } }, "additionalProperties": false, "description": "A started Direct Debit setup: where to send the customer." }, "MandateStatus": { "enum": [ "NotStarted", "PendingCustomerApproval", "PendingSubmission", "Submitted", "Active", "Failed", "Cancelled", "Expired" ], "type": "string", "description": "The state of the caller's Direct Debit mandate with GoCardless (held by Account Hub).", "example": "NotStarted" }, "MeDto": { "required": [ "canAccessBetaFeatures", "email", "fullName", "isEmailVerified", "isSuperAdmin", "isSupportAgent", "managesMultipleTenants", "roles", "tenants" ], "type": "object", "properties": { "code": { "type": "string", "description": "The user's identifier (the same code the tenant's member list shows)", "format": "uuid", "nullable": true }, "email": { "type": "string", "description": "Email address (also the sign-in name)" }, "firstName": { "type": "string", "description": "First name", "nullable": true }, "lastName": { "type": "string", "description": "Last name", "nullable": true }, "phoneNumber": { "type": "string", "description": "Phone number (PUT /me replaces it, so a client editing the profile needs the current value)", "nullable": true }, "fullName": { "type": "string", "description": "First and last name, or the email address when neither is set" }, "isEmailVerified": { "type": "boolean", "description": "Whether the email address has been verified" }, "isSuperAdmin": { "type": "boolean", "description": "Whether the user is a super admin (application-wide administration)" }, "isSupportAgent": { "type": "boolean", "description": "Whether the user is a support agent" }, "canAccessBetaFeatures": { "type": "boolean", "description": "Whether the user can access beta features" }, "managesMultipleTenants": { "type": "boolean", "description": "Whether the user manages several tenants on behalf of others (an accountant or bookkeeper), which changes how the\napplication refers to them (\"clients\" rather than \"organisations\"): a member of a practice" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Application roles (User, SuperAdmin, SupportAgent, BetaTester, HmrcXmlViewer). Every user has User." }, "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/TenantMembershipDto" }, "description": "The tenants the user is a member of, with the user's access level and the tenant's modules" }, "practices": { "type": "array", "items": { "$ref": "#/components/schemas/PracticeSummaryDto" }, "description": "The practices the user is a member of, by name", "nullable": true } }, "additionalProperties": false, "description": "The authenticated user: profile, application roles and the tenants they belong to. The same whichever credential\nauthenticated the request; with an API key it is the key's owner." }, "Modules": { "enum": [ "CisContractor", "CisSubcontractor" ], "type": "string", "example": "CisContractor" }, "MonthAnalysisDto": { "required": [ "contactCount", "invoiceCount", "invoiceTotal", "month", "priorMonthContactCount", "priorMonthInvoiceCount", "priorMonthInvoiceTotal", "year" ], "type": "object", "properties": { "year": { "type": "integer", "description": "The year", "format": "int32" }, "month": { "type": "integer", "description": "The month (1 to 12)", "format": "int32" }, "invoiceCount": { "type": "integer", "description": "Invoices whose date field falls in the month", "format": "int32" }, "invoiceTotal": { "type": "number", "description": "Their total", "format": "double" }, "contactCount": { "type": "integer", "description": "Distinct contacts invoiced in the month", "format": "int32" }, "priorMonthInvoiceCount": { "type": "integer", "description": "The previous month's invoice count", "format": "int32" }, "priorMonthInvoiceTotal": { "type": "number", "description": "The previous month's total", "format": "double" }, "priorMonthContactCount": { "type": "integer", "description": "The previous month's contact count", "format": "int32" } }, "additionalProperties": false, "description": "One month of invoicing activity, with the month before it for comparison." }, "MonthlyReturnDto": { "required": [ "contactCount", "createdDate", "deductions", "dueDate", "hasSubmission", "invoiceCount", "invoicesTotal", "isDue", "isOverdue", "isSubmittable", "labour", "materials", "month", "payments", "status", "year" ], "type": "object", "properties": { "year": { "type": "integer", "description": "The calendar year the tax month ends in", "format": "int32" }, "month": { "type": "integer", "description": "The calendar month (1 to 12) the tax month ends in (on the 5th)", "format": "int32" }, "taxPeriod": { "type": "integer", "description": "Year and month combined (YYYYMM)", "format": "int32", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnStatus" } ], "description": "Open (collecting paid invoices), Submitting (being sent, or sent without HMRC confirming it; see statusMessage),\nSubmitted (awaiting HMRC), Accepted, or Error (HMRC rejected it; see errors)" }, "statusMessage": { "type": "string", "description": "The last status message: HMRC's acceptance receipt, the reason a submission failed, or a note that the return was re-opened", "nullable": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "HMRC's errors from the last submission, translated to plain language; null unless the status is Error", "nullable": true }, "displayName": { "type": "string", "description": "\"Month ending 5th April '26\"", "nullable": true }, "dueDate": { "type": "string", "description": "The date the return must reach HMRC by (the 19th of the month)", "format": "date" }, "isDue": { "type": "boolean", "description": "Whether the tax month has ended and the return is not yet accepted" }, "isOverdue": { "type": "boolean", "description": "Whether the due date has passed and the return is not yet accepted" }, "isSubmittable": { "type": "boolean", "description": "Whether the return can be submitted (Open or Error)" }, "hasSubmission": { "type": "boolean", "description": "Whether the return has been submitted to HMRC at least once (the submission child exists)" }, "submissionBlockedReason": { "type": "string", "description": "Why the return cannot be submitted just now (the owner's billing: outstanding invoices with no direct\ndebit, or a block placed by CIS Manager; or, when the practice's filing credits pay, a balance below what the\nreturn needs), or null when it can. Set on GET; submit answers 402 with it.", "nullable": true }, "creditsRequired": { "type": "integer", "description": "The filing credits a submit would use now: one per subcontractor beyond those already paid for this month,\none for a nil return. Only for a submittable return of an organisation in a SodiumHQ-managed practice, whose\nfiling credits pay for its returns; null otherwise", "format": "int32", "nullable": true }, "creditBalance": { "type": "integer", "description": "The practice's filing credit balance, for an organisation in a SodiumHQ-managed practice; null otherwise or\nwhen it cannot be read just now", "format": "int32", "nullable": true }, "invoicesTotal": { "type": "number", "description": "The total of the invoices paid in the month, before deductions (labour plus materials)", "format": "double" }, "materials": { "type": "number", "description": "The materials on those invoices", "format": "double" }, "labour": { "type": "number", "description": "The labour on those invoices", "format": "double" }, "deductions": { "type": "number", "description": "The CIS deductions made", "format": "double" }, "payments": { "type": "number", "description": "The payments made (invoices total less deductions)", "format": "double" }, "invoiceCount": { "type": "integer", "description": "The number of invoices paid in the month", "format": "int32" }, "contactCount": { "type": "integer", "description": "The number of subcontractors paid in the month", "format": "int32" }, "createdDate": { "type": "string", "description": "When the return was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the return was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A CIS monthly return (CIS300): the payments made to subcontractors in one tax month (the 6th to the 5th) and\nwhat was deducted, submitted to HMRC once the month's invoices are marked paid. Identified by the calendar\nyear and month the tax month ends in." }, "MonthlyReturnDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyReturnDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "MonthlyReturnSortField": { "enum": [ "TaxPeriod", "Status", "InvoiceCount", "ContactCount", "Deductions" ], "type": "string", "example": "TaxPeriod" }, "MonthlyReturnStatus": { "enum": [ "Open", "Submitted", "Accepted", "Error", "Submitting" ], "type": "string", "example": "Open" }, "MonthlyReturnSubmissionDto": { "required": [ "status", "submittedDate" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/HmrcSubmissionStatus" } ], "description": "Pending, Delayed, Completed or Failed; the return's own status carries HMRC's answer" }, "submittedDate": { "type": "string", "description": "When the return was sent to HMRC", "format": "date-time" }, "lastPolledDate": { "type": "string", "description": "When HMRC was last polled for the outcome", "format": "date-time", "nullable": true }, "correlationId": { "type": "string", "description": "HMRC's correlation id for the submission", "nullable": true }, "requestXml": { "type": "string", "description": "The GovTalk request sent to HMRC. Only for callers with the HmrcXmlViewer role; null otherwise.", "nullable": true }, "responseXml": { "type": "string", "description": "HMRC's latest GovTalk response. Only for callers with the HmrcXmlViewer role; null otherwise.", "nullable": true } }, "additionalProperties": false, "description": "The latest submission of a monthly return to HMRC." }, "MyApiKeyDto": { "required": [ "code", "createdDate", "isActive", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "The key's code, used to delete it", "format": "uuid" }, "name": { "type": "string", "description": "The key's name" }, "isActive": { "type": "boolean", "description": "False for a key that has been switched off; it no longer authenticates" }, "lastUsedDate": { "type": "string", "description": "When the key last authenticated a request; blank when it never has", "format": "date-time", "nullable": true }, "expiresDate": { "type": "string", "description": "When the key expires; never when blank", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the key was issued", "format": "date-time" } }, "additionalProperties": false, "description": "One of the caller's API keys (`GET /me/api-keys`). The key itself is never returned after it is issued." }, "MyNewApiKeyDto": { "required": [ "code", "createdDate", "key", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "The key's code, used to delete it", "format": "uuid" }, "key": { "type": "string", "description": "The key, to send as the x-api-key header" }, "name": { "type": "string", "description": "The key's name" }, "expiresDate": { "type": "string", "description": "When the key expires; never when blank", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the key was issued", "format": "date-time" } }, "additionalProperties": false, "description": "A freshly issued key of the caller's. The key itself is shown this once." }, "PaymentDateDto": { "required": [ "amount", "contactCount", "date", "deduction", "invoiceCount" ], "type": "object", "properties": { "date": { "type": "string", "description": "The date", "format": "date-time" }, "invoiceCount": { "type": "integer", "description": "How many invoices were paid on the date", "format": "int32" }, "contactCount": { "type": "integer", "description": "How many contacts were paid on the date", "format": "int32" }, "amount": { "type": "number", "description": "The total paid", "format": "double" }, "deduction": { "type": "number", "description": "The total CIS deduction carried by the payments", "format": "double" } }, "additionalProperties": false, "description": "The payments made on one date, summarised." }, "PaymentDto": { "required": [ "amount", "code", "contact", "contactName", "createdDate", "date", "deduction", "dueDate", "invoice", "invoiceDate", "taxMonth", "taxYear" ], "type": "object", "properties": { "code": { "type": "string", "description": "The payment's identifier within its invoice", "format": "uuid" }, "invoice": { "type": "integer", "description": "The invoice's number", "format": "int32" }, "invoiceDate": { "type": "string", "description": "The invoice's date", "format": "date-time" }, "dueDate": { "type": "string", "description": "The invoice's due date", "format": "date-time" }, "yourReference": { "type": "string", "description": "The invoice's \"your reference\"", "nullable": true }, "theirReference": { "type": "string", "description": "The invoice's \"their reference\"", "nullable": true }, "contact": { "type": "string", "description": "The invoice's contact (code)" }, "contactName": { "type": "string", "description": "The contact's name" }, "date": { "type": "string", "description": "When it was paid", "format": "date-time" }, "amount": { "type": "number", "description": "The amount paid", "format": "double" }, "deduction": { "type": "number", "description": "The share of the invoice's CIS deduction this payment carries", "format": "double" }, "taxYear": { "type": "integer", "description": "The CIS tax year the payment falls in", "format": "int32" }, "taxMonth": { "type": "integer", "description": "The CIS tax month (1 = the month ending 5 May) the payment falls in", "format": "int32" }, "createdDate": { "type": "string", "description": "When the payment was recorded", "format": "date-time" } }, "additionalProperties": false, "description": "A payment of any invoice of a direction, with the invoice and contact it belongs to." }, "PracticeHmrcCredentialsDto": { "required": [ "code", "createdDate", "hasPassword", "isDefault", "name", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "code": { "type": "string", "description": "The set's code (what an organisation's HMRC settings reference as sharedCredentialsId)", "format": "uuid" }, "name": { "type": "string", "description": "What the HMRC settings page offers the set as" }, "isDefault": { "type": "boolean", "description": "The set a new organisation of the practice files with. A practice with sets always has one" }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "type": "string", "description": "The gateway user id", "nullable": true }, "hasPassword": { "type": "boolean", "description": "Whether a gateway password is stored" }, "testInLive": { "type": "boolean", "description": "Send submissions to the live gateway flagged as tests" }, "useTestGateway": { "type": "boolean", "description": "Send submissions to HMRC's test gateway" }, "agent": { "allOf": [ { "$ref": "#/components/schemas/HmrcAgentDto" } ], "description": "The agent details, when the sender is an agent", "nullable": true }, "createdDate": { "type": "string", "description": "When the set was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When it was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "One of a practice's sets of HMRC gateway credentials: its organisations file with it when their HMRC settings point\nat it (sharedCredentialsId), and a new organisation of the practice starts on the default. The password is never\nreturned." }, "PracticeManagedBy": { "enum": [ "Cis", "SodiumHq" ], "type": "string", "example": "Cis" }, "PracticeMemberDto": { "required": [ "accessLevel", "code", "email", "fullName", "isMe", "isRestricted" ], "type": "object", "properties": { "code": { "type": "string", "description": "The user's code", "format": "uuid" }, "email": { "type": "string", "description": "The user's email address" }, "fullName": { "type": "string", "description": "First and last name, else the email address" }, "accessLevel": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "description": "The level they have in each of the practice's organisations" }, "isRestricted": { "type": "boolean", "description": "Restricted in Sodium to some clients: granted the practice's organisations one at a time as they open them there" }, "isMe": { "type": "boolean", "description": "Whether this is the caller" }, "lastLogin": { "type": "string", "description": "When they last signed in", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A member of a practice: they reach every organisation it runs." }, "PracticeOrganisationSummaryDto": { "required": [ "code", "name", "ownerName" ], "type": "object", "properties": { "code": { "type": "string", "description": "The organisation's tenant code" }, "name": { "type": "string", "description": "The organisation's name" }, "ownerName": { "type": "string", "description": "The owner's name" } }, "additionalProperties": false, "description": "One of the organisations a practice runs." }, "PracticeSummaryDto": { "required": [ "code", "managedBy", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "The practice's code, the {practice} of /me/practices/{practice}", "format": "uuid" }, "name": { "type": "string", "description": "The practice's name" }, "managedBy": { "allOf": [ { "$ref": "#/components/schemas/PracticeManagedBy" } ], "description": "Where the practice is edited: Cis here, SodiumHq in Sodium (its members, organisations and credentials are then\nread-only here)" } }, "additionalProperties": false, "description": "A practice: a group of client organisations whose members reach every one of them." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": {} }, "PublicCisDetailsRequestDto": { "required": [ "code", "contactName", "isSubmitted", "organisationName" ], "type": "object", "properties": { "code": { "type": "string", "description": "The request's identifier, from the link", "format": "uuid" }, "isSubmitted": { "type": "boolean", "description": "Whether the details have been sent; they can be sent once" }, "contactName": { "type": "string", "description": "The subcontractor the request was sent to" }, "organisationName": { "type": "string", "description": "The tenant that asked" }, "logoUrl": { "type": "string", "description": "The public URL of the tenant's logo, or null when it has none", "nullable": true }, "sdcStatement": { "type": "string", "description": "The SDC statement the tenant sent with the request and the subcontractor has not signed yet: the key of its\npublic page, where the form sends them next", "format": "uuid", "nullable": true }, "prefill": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsPrefillDto" } ], "description": "What the tenant already holds for the subcontractor, to start the form from; null once the details are sent", "nullable": true } }, "additionalProperties": false, "description": "A CIS details request as the subcontractor sees it on the public form, reached through the link in the request\nemail: no credentials, the request's code is the only key. It never carries the details back." }, "PublicSdcStatementDto": { "required": [ "code", "contactName", "isCompleted", "organisationName", "questions", "statementDate", "title" ], "type": "object", "properties": { "code": { "type": "string", "description": "The statement's identifier, from the link", "format": "uuid" }, "title": { "type": "string", "description": "What the statement is for (an assignment or project)" }, "statementDate": { "type": "string", "description": "The date the statement is made for", "format": "date-time" }, "isCompleted": { "type": "boolean", "description": "Whether it has been completed and signed; a completed statement cannot be signed again" }, "signedName": { "type": "string", "description": "The name typed at signing, or the contact's name to start from while pending", "nullable": true }, "signedDate": { "type": "string", "description": "When it was signed", "format": "date-time", "nullable": true }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SdcQuestion" }, "description": "The questions to confirm: every current question while pending, the questions as they stood once completed" }, "contactName": { "type": "string", "description": "The subcontractor the statement was sent to" }, "organisationName": { "type": "string", "description": "The tenant that sent it, named in several of the questions" }, "logoUrl": { "type": "string", "description": "The public URL of the tenant's logo, or null when it has none", "nullable": true } }, "additionalProperties": false, "description": "An SDC statement as the subcontractor sees it on the public completion page, reached through the link in the\nrequest email: no credentials, the statement's code is the only key." }, "ReconnectEmailConfigRequest": { "required": [ "returnUrl" ], "type": "object", "properties": { "returnUrl": { "maxLength": 500, "minLength": 0, "type": "string", "description": "The page of this application the sign-in returns to" } }, "additionalProperties": false, "description": "Where an Outlook or Gmail sign-in returns to." }, "ReconnectEmailConfigResultDto": { "required": [ "authorisationUrl" ], "type": "object", "properties": { "authorisationUrl": { "type": "string", "description": "The provider's sign-in page" } }, "additionalProperties": false, "description": "Where to send the user to sign in again." }, "RegisterMeRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The caller's email address. It is not trusted until they follow the verification link sent to it.", "format": "email" } }, "additionalProperties": false, "description": "The email address of a caller whose sign-in gave none, to sign them up with." }, "RemittanceAdviceDto": { "required": [ "contact", "contactIsVatRegistered", "contactName", "contractorName", "deductionSummaries", "from", "payments", "to", "totalDeduction", "totalGross", "totalLabour", "totalMaterials", "totalNet", "totalVat" ], "type": "object", "properties": { "contact": { "type": "string", "description": "The subcontractor (contact code)" }, "contactName": { "type": "string", "description": "The subcontractor's name" }, "contactEmail": { "type": "string", "description": "The subcontractor's email address, the default recipient of the advice", "nullable": true }, "contactAddress": { "type": "string", "description": "The subcontractor's address, one line per row", "nullable": true }, "contactUtr": { "type": "string", "description": "The subcontractor's Unique Taxpayer Reference", "nullable": true }, "contactIsVatRegistered": { "type": "boolean", "description": "Whether the subcontractor is VAT registered" }, "from": { "type": "string", "description": "The first payment date covered", "format": "date-time" }, "to": { "type": "string", "description": "The last payment date covered", "format": "date-time" }, "contractorName": { "type": "string", "description": "The tenant's name, as the contractor" }, "contractorAddress": { "type": "string", "description": "The tenant's address", "nullable": true }, "contractorEmployersReference": { "type": "string", "description": "The tenant's HMRC accounts office reference", "nullable": true }, "totalGross": { "type": "number", "description": "Paid plus deducted", "format": "double" }, "totalMaterials": { "type": "number", "description": "The materials within the gross", "format": "double" }, "totalLabour": { "type": "number", "description": "The gross less materials", "format": "double" }, "totalDeduction": { "type": "number", "description": "The CIS deducted", "format": "double" }, "totalNet": { "type": "number", "description": "The amount paid", "format": "double" }, "totalVat": { "type": "number", "description": "The VAT on the invoices covered", "format": "double" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/RemittanceAdvicePaymentDto" }, "description": "The payments, one per invoice payment" }, "deductionSummaries": { "type": "array", "items": { "$ref": "#/components/schemas/RemittanceDeductionSummaryDto" }, "description": "The deductions summarised by the rate applied" } }, "additionalProperties": false, "description": "A remittance advice: what the tenant paid one subcontractor between two dates, invoice by invoice, with the\nCIS deductions taken. Built from the payments when asked for, not stored." }, "RemittanceAdvicePaymentDto": { "required": [ "amount", "date", "deduction", "invoice", "invoiceDate", "isDomesticReverseCharge", "materials", "total" ], "type": "object", "properties": { "invoice": { "type": "integer", "description": "The invoice's number", "format": "int32" }, "invoiceDate": { "type": "string", "description": "The invoice's date", "format": "date-time" }, "yourReference": { "type": "string", "description": "The invoice's \"your reference\"", "nullable": true }, "theirReference": { "type": "string", "description": "The invoice's \"their reference\"", "nullable": true }, "date": { "type": "string", "description": "When it was paid", "format": "date-time" }, "amount": { "type": "number", "description": "The amount paid", "format": "double" }, "deduction": { "type": "number", "description": "The CIS deducted", "format": "double" }, "materials": { "type": "number", "description": "The materials within the payment", "format": "double" }, "total": { "type": "number", "description": "Paid plus deducted", "format": "double" }, "isDomesticReverseCharge": { "type": "boolean", "description": "Whether the invoice is under the VAT domestic reverse charge" } }, "additionalProperties": false, "description": "One payment on a remittance advice." }, "RemittanceAdviceSettingsDto": { "required": [ "includeContractorRef", "includeFooterSummary", "includeInvoiceDate", "includeInvoiceNumber", "includeSubcontractorRef", "includeSubcontractorUtr", "useCustomDrcText", "useCustomFooterText", "useCustomPaymentText" ], "type": "object", "properties": { "useCustomPaymentText": { "type": "boolean", "description": "Whether paymentText replaces the default \"The above amount has been paid by BACS.\"" }, "paymentText": { "type": "string", "description": "The custom payment text; null unless useCustomPaymentText", "nullable": true }, "useCustomFooterText": { "type": "boolean", "description": "Whether footerText is printed" }, "footerText": { "type": "string", "description": "The custom footer text; null unless useCustomFooterText", "nullable": true }, "includeInvoiceNumber": { "type": "boolean", "description": "Show the invoice number column" }, "includeInvoiceDate": { "type": "boolean", "description": "Show the invoice date column" }, "includeContractorRef": { "type": "boolean", "description": "Show the contractor's reference column" }, "contractorRefHeaderText": { "type": "string", "description": "The contractor's reference column heading (default \"Reference\"); null unless includeContractorRef", "nullable": true }, "includeSubcontractorRef": { "type": "boolean", "description": "Show the subcontractor's reference column" }, "subcontractorRefHeaderText": { "type": "string", "description": "The subcontractor's reference column heading (default \"Your Ref\"); null unless includeSubcontractorRef", "nullable": true }, "includeSubcontractorUtr": { "type": "boolean", "description": "Print the subcontractor's UTR" }, "includeFooterSummary": { "type": "boolean", "description": "Print the deduction summary in the footer" }, "useCustomDrcText": { "type": "boolean", "description": "Whether drcText replaces the default domestic reverse charge note" }, "drcText": { "type": "string", "description": "The custom domestic reverse charge note; null unless useCustomDrcText", "nullable": true } }, "additionalProperties": false, "description": "How the tenant's remittance advices are laid out: which columns they show and the custom texts they carry.\nA tenant that has never saved settings gets the defaults." }, "RemittanceDeductionSummaryDto": { "required": [ "amountDeducted", "amountLiableToDeduction", "taxStatus" ], "type": "object", "properties": { "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The CIS tax status the rate belongs to" }, "amountLiableToDeduction": { "type": "number", "description": "The amount the rate was applied to", "format": "double" }, "amountDeducted": { "type": "number", "description": "The amount deducted", "format": "double" } }, "additionalProperties": false, "description": "The deductions on a remittance advice at one CIS rate." }, "RenamePracticeRequest": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The practice's name" } }, "additionalProperties": false, "description": "A practice's new name." }, "RtiSenderType": { "enum": [ "ActingInCapacity", "Agent", "Bureau", "Company", "Employer", "Government", "Individual", "Other", "Partnership", "Trust" ], "type": "string", "example": "ActingInCapacity" }, "SdcQuestion": { "enum": [ "NoSickPay", "NoHolidayPay", "NoPensionScheme", "NoObligationForOngoingWork", "NoPayForCancelledWork", "CanEndAssignment", "DecideWorkMethod", "WorkWithoutSupervision", "ResponsibleForWorkStandard", "ResponsibleForDefectiveWork", "ControlWorkSchedule", "CanRefuseReassignment", "PayTravelExpenses", "ProvideOwnTools", "PayOwnNI", "CompleteSelfAssessment", "PublicLiabilityInsurance", "RightOfSubstitution", "WorkForMultipleClients" ], "type": "string", "example": "NoSickPay" }, "SdcStatementDto": { "required": [ "code", "createdDate", "isCompleted", "questions", "statementDate", "title" ], "type": "object", "properties": { "code": { "type": "string", "description": "The statement's identifier, also the key of its public completion page", "format": "uuid" }, "title": { "type": "string", "description": "What the statement is for (an assignment or project), to tell several statements apart" }, "statementDate": { "type": "string", "description": "The date the statement is made for", "format": "date-time" }, "emailedTo": { "type": "string", "description": "Where the completion request was last sent", "nullable": true }, "isCompleted": { "type": "boolean", "description": "Whether the subcontractor has completed and signed it" }, "signedName": { "type": "string", "description": "The name typed at signing (the contact's name until then)", "nullable": true }, "signedDate": { "type": "string", "description": "When it was signed", "format": "date-time", "nullable": true }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/SdcQuestion" }, "description": "The questions confirmed, as they stood when the statement was completed (every question is confirmed on a\ncompleted statement; a pending one lists the current questions)" }, "signature": { "type": "string", "description": "The signature image as a base64 data URI; on the single statement only", "nullable": true }, "createdDate": { "type": "string", "description": "When the statement was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When it was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A Supervision, Direction and Control (SDC) statement: a questionnaire the tenant sends a subcontractor to\ncomplete and sign, recording their employment status under the CIS rules. Pending until the subcontractor\ncompletes it on the public page linked from the email." }, "SendCisDetailsRequestEmailRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Where to send it; becomes the request's emailedTo", "format": "email" } }, "additionalProperties": false, "description": "A request to send the link to the CIS details form again." }, "SendEmailRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "The recipient's address; the contact's when omitted", "format": "email", "nullable": true }, "name": { "type": "string", "description": "The recipient's name; the contact's when omitted", "nullable": true }, "ccEmail": { "type": "string", "description": "An address to copy the email to", "format": "email", "nullable": true }, "ccName": { "type": "string", "description": "The copy recipient's name", "nullable": true } }, "additionalProperties": false, "description": "A request to email a document. Every field is optional: the recipient defaults to the contact's email address\nand name." }, "SendSdcStatementEmailRequest": { "required": [ "email" ], "type": "object", "properties": { "email": { "maxLength": 200, "minLength": 0, "type": "string", "description": "Where to send it; becomes the statement's emailedTo", "format": "email" } }, "additionalProperties": false, "description": "A request to send (or resend) the completion link for a statement." }, "SendStatementEmailRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "The recipient's address; the subcontractor's when omitted", "format": "email", "nullable": true }, "name": { "type": "string", "description": "The recipient's name; the subcontractor's when omitted", "nullable": true }, "ccEmail": { "type": "string", "description": "An address to copy the email to", "format": "email", "nullable": true }, "ccName": { "type": "string", "description": "The copy recipient's name", "nullable": true } }, "additionalProperties": false, "description": "A request to email a statement's PDF. Every field is optional: the recipient defaults to the subcontractor's\nemail address and name." }, "SetConnectionCounterPartyRequest": { "type": "object", "properties": { "contact": { "type": "string", "description": "An existing contact (code) to link as the other party; omitted, a contact is created from the details the\ninitiator shared", "nullable": true } }, "additionalProperties": false, "description": "The accepting tenant's side of a connection sent to it." }, "SharedHmrcCredentialsDto": { "required": [ "code", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "The credentials' code, for sharedCredentialsId", "format": "uuid" }, "name": { "type": "string", "description": "The practice set's name" } }, "additionalProperties": false, "description": "One of the practice's sets a tenant's HMRC settings can point at." }, "SignSdcStatementRequest": { "required": [ "confirmedQuestions", "signature", "signedName" ], "type": "object", "properties": { "confirmedQuestions": { "type": "array", "items": { "$ref": "#/components/schemas/SdcQuestion" }, "description": "The questions the subcontractor answered Yes to; must be every current question" }, "signedName": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The signer's full name" }, "signature": { "maxLength": 2000000, "minLength": 0, "pattern": "^data:image/(png|jpeg);base64,[A-Za-z0-9+/=]+$", "type": "string", "description": "The signature drawn on the page, as a PNG or JPEG data URI" } }, "additionalProperties": false, "description": "The subcontractor's completion of an SDC statement: every question confirmed, their name and their signature." }, "SkippedHmrcVerificationDto": { "required": [ "code", "reason" ], "type": "object", "properties": { "code": { "type": "string", "description": "The contact's code as given in the request" }, "reason": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationSkipReason" } ], "description": "Why it was skipped" }, "message": { "type": "string", "description": "The detail for InvalidDetails", "nullable": true } }, "additionalProperties": false, "description": "A contact a bulk HMRC verification request did not send." }, "SodiumPracticeDto": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The practice's name in SodiumHQ" } }, "additionalProperties": false, "description": "A SodiumHQ practice the signed-in user belongs to (`GET /me/sodium-practices`)." }, "StatementDto": { "required": [ "amountDeducted", "amountLiableToDeduction", "amountPayable", "costOfMaterials", "deductionIsAtUnmatchedRate", "grossAmount", "invoiceCount", "isAnnual", "year" ], "type": "object", "properties": { "contact": { "type": "string", "description": "The subcontractor's contact code", "nullable": true }, "contactName": { "type": "string", "description": "The subcontractor's name", "nullable": true }, "contactEmail": { "type": "string", "description": "The subcontractor's email address, the default recipient when the statement is emailed", "nullable": true }, "year": { "type": "integer", "description": "The calendar year the tax month ends in; for an annual statement, the calendar year the tax year ends in", "format": "int32" }, "month": { "type": "integer", "description": "The calendar month (1 to 12) the tax month ends in; null for an annual statement", "format": "int32", "nullable": true }, "isAnnual": { "type": "boolean", "description": "Whether this is the annual statement for the tax year" }, "displayName": { "type": "string", "description": "\"April '26\", or \"'25/26 Full Year\"", "nullable": true }, "grossAmount": { "type": "number", "description": "The total paid before deductions", "format": "double" }, "costOfMaterials": { "type": "number", "description": "The cost of materials, not liable to deduction", "format": "double" }, "amountLiableToDeduction": { "type": "number", "description": "Gross amount less the cost of materials", "format": "double" }, "amountDeducted": { "type": "number", "description": "The CIS deduction", "format": "double" }, "amountPayable": { "type": "number", "description": "Gross amount less the deduction", "format": "double" }, "invoiceCount": { "type": "integer", "description": "The number of invoices in the statement", "format": "int32" }, "deductionIsAtUnmatchedRate": { "type": "boolean", "description": "Whether the deduction was at the unmatched (higher) rate" }, "emailStatus": { "allOf": [ { "$ref": "#/components/schemas/EmailDeliveryStatus" } ], "description": "The delivery status of the last email of the statement; null when it has not been emailed", "nullable": true }, "pdfUrl": { "type": "string", "description": "A signed, short-lived (an hour by default) link to the statement's PDF that needs no credentials, for viewers\nthat fetch the file themselves (an in-page PDF viewer, Google's). Append `&disposition=inline` to show\nit rather than download it. Set on the single statement only, not on the lists.", "nullable": true } }, "additionalProperties": false, "description": "A CIS payment and deduction statement: what one subcontractor was paid and had deducted in one tax month\n(the 6th to the 5th), or, for an annual statement, in one tax year (6 April to 5 April). A statement exists\nonce an invoice of the subcontractor is paid in the period." }, "StatementEmailDto": { "required": [ "createdDate", "status" ], "type": "object", "properties": { "to": { "type": "string", "description": "The recipient's address", "nullable": true }, "toName": { "type": "string", "description": "The recipient's name", "nullable": true }, "cc": { "type": "string", "description": "The copy recipient's address, if any", "nullable": true }, "ccName": { "type": "string", "description": "The copy recipient's name", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/EmailDeliveryStatus" } ], "description": "Queued, Sent or Failed" }, "statusDate": { "type": "string", "description": "When the status last changed", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the email was queued", "format": "date-time" } }, "additionalProperties": false, "description": "An email of a statement's PDF to the subcontractor." }, "SubcontractorBreakdownRowDto": { "required": [ "cisDeduction", "drcInvoiceCount", "drcNetAmount", "grossPayment", "invoiceCount", "invoiceTotalIncVat", "isTotal", "labour", "materials", "netPayment", "vat" ], "type": "object", "properties": { "contact": { "type": "string", "description": "The subcontractor's contact code; null on the total row", "nullable": true }, "contactName": { "type": "string", "description": "The subcontractor's name", "nullable": true }, "isTotal": { "type": "boolean", "description": "Whether this is the total row" }, "utr": { "type": "string", "description": "The subcontractor's unique taxpayer reference", "nullable": true }, "verificationNumber": { "type": "string", "description": "The subcontractor's HMRC verification number", "nullable": true }, "taxDeductionPercentage": { "type": "integer", "description": "The deduction rate applied (0, 20 or 30)", "format": "int32", "nullable": true }, "isVatRegistered": { "type": "boolean", "description": "Whether the subcontractor is VAT registered", "nullable": true }, "vatRegistrationNumber": { "type": "string", "description": "The subcontractor's VAT registration number", "nullable": true }, "invoiceCount": { "type": "integer", "description": "The number of invoices paid", "format": "int32" }, "drcInvoiceCount": { "type": "integer", "description": "How many of them were domestic reverse charge invoices", "format": "int32" }, "labour": { "type": "number", "description": "Labour paid", "format": "double" }, "materials": { "type": "number", "description": "Materials paid", "format": "double" }, "grossPayment": { "type": "number", "description": "Labour plus materials", "format": "double" }, "cisDeduction": { "type": "number", "description": "The CIS deduction", "format": "double" }, "netPayment": { "type": "number", "description": "Gross payment less the deduction", "format": "double" }, "drcNetAmount": { "type": "number", "description": "The net amount of the domestic reverse charge invoices", "format": "double" }, "vat": { "type": "number", "description": "VAT on the invoices", "format": "double" }, "invoiceTotalIncVat": { "type": "number", "description": "The invoice total including VAT", "format": "double" } }, "additionalProperties": false, "description": "One subcontractor's share of a monthly return (a subcontractor paid at two rates in the month appears twice),\nplus a final total row." }, "SubcontractorVerificationDto": { "required": [ "status", "taxStatus" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/SubcontractorVerificationStatus" } ], "description": "Verification status" }, "number": { "type": "string", "description": "Verification number (V followed by 10 digits and up to 2 letters). Present for Manual and HmrcVerified.", "nullable": true }, "date": { "type": "string", "description": "Date of the verification. Present for Manual and HmrcVerified.", "format": "date-time", "nullable": true }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The deduction rate that applies to the subcontractor's payments" }, "recordedDate": { "type": "string", "description": "When the verification was recorded: entered by a user, or received from HMRC. Present for Manual and HmrcVerified.", "format": "date-time", "nullable": true }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/HmrcError" }, "description": "HMRC's errors from the last verification request, or the reason the contact could not be sent to HMRC.\nPresent for HmrcFailed.", "nullable": true }, "hmrcRequest": { "allOf": [ { "$ref": "#/components/schemas/HmrcVerificationRequestDto" } ], "description": "The contact's latest HMRC verification request. Reported by the verification resource only; null on a contact.", "nullable": true } }, "additionalProperties": false, "description": "The subcontractor's current CIS verification. On a contact it is read-only: it changes through the contact's\nverification resource (manual entry, or an HMRC verification request), not through the contacts resource." }, "SubcontractorVerificationStatus": { "enum": [ "NotVerified", "Manual", "HmrcVerified", "HmrcFailed" ], "type": "string", "description": "Where a subcontractor stands with HMRC verification.", "example": "NotVerified" }, "SubmitCisDetailsRequest": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "maxLength": 4, "minLength": 0, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "maxLength": 35, "minLength": 0, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "maxLength": 35, "minLength": 0, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "maxLength": 35, "minLength": 0, "pattern": "^[A-Za-z0-9 ,\\.\\(\\)/&\\-']+$", "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "maxLength": 200, "minLength": 0, "pattern": "^[A-Za-z0-9 ~!\"@#$%&'()*+,\\-./:;<=>?\\[\\]\\\\^_{}£€]*$", "type": "string", "description": "The trading name (the company's or trust's name)", "nullable": true }, "utr": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The Unique Taxpayer Reference: 10 digits (spaces are ignored)", "nullable": true }, "niNumber": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The National Insurance number (spaces are ignored)", "nullable": true }, "companyNumber": { "maxLength": 8, "minLength": 0, "pattern": "[A-Za-z]{2}[0-9]{1,6}|[0-9]{1,8}", "type": "string", "description": "The company registration number", "nullable": true }, "partnershipName": { "maxLength": 56, "minLength": 0, "pattern": "^[A-Za-z0-9 ~!\"@#$%&'()*+,\\-./:;<=>?\\[\\]\\\\^_{}£€]*$", "type": "string", "description": "The partnership's name", "nullable": true }, "partnershipUtr": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The partnership's UTR: 10 digits (spaces are ignored)", "nullable": true } }, "additionalProperties": false, "description": "The subcontractor's CIS details, from the public form. What is required depends on the type: a sole trader's\nfirst name, last name and UTR; a company's name and its UTR or company number; a trust's name and UTR; a\npartnership's name and UTR." }, "SubmitMonthlyReturnRequest": { "required": [ "employmentStatus", "inactivity", "verification" ], "type": "object", "properties": { "employmentStatus": { "type": "boolean", "description": "The employment status of every subcontractor on the return has been considered (not sent on a nil return)" }, "verification": { "type": "boolean", "description": "Every subcontractor on the return has been verified with HMRC where required (not sent on a nil return)" }, "inactivity": { "type": "boolean", "description": "The contractor will not pay subcontractors in the next six months (an inactivity request)" } }, "additionalProperties": false, "description": "The declarations made when submitting a return to HMRC. That the information is correct is always declared." }, "SubmittedCisDetailsDto": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "type": "string", "description": "The trading name (the company's or trust's name)", "nullable": true }, "utr": { "type": "string", "description": "The Unique Taxpayer Reference", "nullable": true }, "niNumber": { "type": "string", "description": "The National Insurance number", "nullable": true }, "companyNumber": { "type": "string", "description": "The company registration number", "nullable": true }, "partnershipName": { "type": "string", "description": "The partnership's name", "nullable": true }, "partnershipUtr": { "type": "string", "description": "The partnership's UTR", "nullable": true } }, "additionalProperties": false, "description": "The CIS details a subcontractor provided in answer to a request, as they entered them." }, "SupplierSettingsDto": { "required": [ "defaultToDrc", "defaultVatRate" ], "type": "object", "properties": { "defaultVatRate": { "allOf": [ { "$ref": "#/components/schemas/VatRate" } ], "description": "Default VAT rate for the subcontractor's invoices" }, "defaultToDrc": { "type": "boolean", "description": "Whether Domestic Reverse Charge (DRC) applies by default" } }, "additionalProperties": false, "description": "Defaults applied to invoices received from a supplier (CIS subcontractors included)." }, "TenantAddressDto": { "type": "object", "properties": { "line1": { "maxLength": 200, "type": "string", "description": "Address line 1", "nullable": true }, "line2": { "maxLength": 200, "type": "string", "description": "Address line 2", "nullable": true }, "line3": { "maxLength": 100, "type": "string", "description": "Address line 3", "nullable": true }, "line4": { "maxLength": 100, "type": "string", "description": "Address line 4", "nullable": true }, "postcode": { "maxLength": 20, "type": "string", "description": "Postcode", "nullable": true }, "country": { "maxLength": 100, "type": "string", "description": "Country", "nullable": true } }, "additionalProperties": false, "description": "A tenant's postal address, in the same parts as a contact's." }, "TenantCisDetailsDto": { "required": [ "isSaved", "needsConfig", "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "type": "string", "description": "The trading name", "nullable": true }, "utr": { "type": "string", "description": "The Unique Taxpayer Reference", "nullable": true }, "niNumber": { "type": "string", "description": "The National Insurance number", "nullable": true }, "companyNumber": { "type": "string", "description": "The company registration number", "nullable": true }, "partnershipName": { "type": "string", "description": "The partnership's name", "nullable": true }, "partnershipUtr": { "type": "string", "description": "The partnership's UTR", "nullable": true }, "needsConfig": { "type": "boolean", "description": "True until a UTR, company number or partnership UTR is set: the details cannot be shared yet" }, "isSaved": { "type": "boolean", "description": "Whether the tenant has saved any details yet (false: the defaults, never edited)" } }, "additionalProperties": false, "description": "The tenant's own CIS identity as a subcontractor: what it shares with contractors over a connection and what\ngoes on its invoices. Empty (needsConfig) until the tenant fills it in." }, "TenantCountsDto": { "required": [ "acceptedReturns", "contacts", "customers", "purchaseInvoices", "purchasePayments", "returns", "salesInvoices", "salesPayments", "subcontractors", "suppliers", "unverifiedSubcontractors" ], "type": "object", "properties": { "contacts": { "type": "integer", "description": "All contacts (subcontractors, customers and suppliers)", "format": "int32" }, "customers": { "type": "integer", "description": "Contacts the tenant invoices", "format": "int32" }, "suppliers": { "type": "integer", "description": "Contacts that invoice the tenant", "format": "int32" }, "subcontractors": { "type": "integer", "description": "Contacts paid under CIS", "format": "int32" }, "unverifiedSubcontractors": { "type": "integer", "description": "Subcontractors not yet verified with HMRC", "format": "int32" }, "purchaseInvoices": { "type": "integer", "description": "Purchase invoices (the ones the tenant pays)", "format": "int32" }, "purchasePayments": { "type": "integer", "description": "Payments recorded against purchase invoices", "format": "int32" }, "salesInvoices": { "type": "integer", "description": "Sales invoices (the ones the tenant sends to get paid)", "format": "int32" }, "salesPayments": { "type": "integer", "description": "Payments recorded against sales invoices", "format": "int32" }, "returns": { "type": "integer", "description": "Monthly (CIS 300) returns", "format": "int32" }, "acceptedReturns": { "type": "integer", "description": "Monthly returns accepted by HMRC", "format": "int32" } }, "additionalProperties": false, "description": "A tenant's entity counts, maintained by the application as records are created and deleted." }, "TenantDto": { "required": [ "address", "code", "counts", "createdDate", "isEmailVerified", "isSupportAccess", "isSupportAccessEnabled", "isVatRegistered", "modules", "name", "shareDetailsDefault" ], "type": "object", "properties": { "code": { "type": "string", "description": "Tenant code: the value of the {tenant} route parameter" }, "name": { "type": "string", "description": "Tenant name (the contractor's or subcontractor's trading name as registered with HMRC)" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/Modules" }, "description": "The modules enabled for the tenant" }, "emailAddress": { "type": "string", "description": "Contact email address", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Whether the contact email address has been verified" }, "phoneNumber": { "type": "string", "description": "Contact telephone number", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/TenantAddressDto" } ], "description": "Postal address" }, "isVatRegistered": { "type": "boolean", "description": "Whether the tenant is VAT registered" }, "vatRegistrationNumber": { "type": "string", "description": "VAT registration number", "nullable": true }, "shareDetailsDefault": { "type": "boolean", "description": "Whether new contacts default to sharing their details with the counterparty" }, "isSupportAccessEnabled": { "type": "boolean", "description": "Whether the tenant has allowed CIS Manager support staff to access its data" }, "isSupportAccess": { "type": "boolean", "description": "Whether the caller reached this tenant through support access (a support agent, with the tenant's permission)\nrather than membership. Support access is not a membership: such a tenant is absent from the caller's tenant\nlist and from `GET /me`." }, "logoUrl": { "type": "string", "description": "URL of the tenant's logo, if one has been uploaded", "nullable": true }, "counts": { "allOf": [ { "$ref": "#/components/schemas/TenantCountsDto" } ], "description": "Entity counts, as shown on the tenant's dashboard" }, "createdDate": { "type": "string", "description": "When the tenant was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the tenant was last updated", "format": "date-time", "nullable": true }, "practice": { "allOf": [ { "$ref": "#/components/schemas/PracticeSummaryDto" } ], "description": "The practice running the tenant; null when it is in none. Set by GET /tenants/{tenant} and POST /tenants only", "nullable": true } }, "additionalProperties": false, "description": "A tenant: a CIS Manager organisation the caller is a member of. What the application needs on every request about\nthe organisation being worked in: identity, contact details, VAT and module settings, and the entity counts its\ndashboard shows." }, "TenantDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TenantDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "TenantInvitationDto": { "required": [ "code", "createdDate", "email", "expiryDate", "isExpired", "role", "status" ], "type": "object", "properties": { "code": { "type": "string", "description": "The invitation's identifier", "format": "uuid" }, "email": { "type": "string", "description": "Where it was sent" }, "role": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "description": "The access level offered" }, "message": { "type": "string", "description": "The personal message in the email", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/InvitationStatus" } ], "description": "Pending, Accepted, Rejected or Expired" }, "expiryDate": { "type": "string", "description": "When the invitation stops being acceptable", "format": "date-time" }, "isExpired": { "type": "boolean", "description": "Whether the expiry date has passed" }, "invitedBy": { "type": "string", "description": "Who sent it", "nullable": true }, "createdDate": { "type": "string", "description": "When it was sent", "format": "date-time" }, "isPractice": { "type": "boolean", "description": "An invitation to the tenant's whole practice: accepting it reaches every organisation the practice runs", "nullable": true } }, "additionalProperties": false, "description": "An invitation to join the tenant." }, "TenantMemberDto": { "required": [ "code", "createdDate", "email", "fullName", "isMe", "isOwner" ], "type": "object", "properties": { "code": { "type": "string", "description": "The user's identifier", "format": "uuid" }, "email": { "type": "string", "description": "The user's email address" }, "firstName": { "type": "string", "description": "The user's first name", "nullable": true }, "lastName": { "type": "string", "description": "The user's last name", "nullable": true }, "fullName": { "type": "string", "description": "The user's display name" }, "isOwner": { "type": "boolean", "description": "Whether the user owns the tenant (the owner cannot be removed; ownership is transferred)" }, "isMe": { "type": "boolean", "description": "Whether the user is the caller" }, "lastLogin": { "type": "string", "description": "When the user last signed in", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the user registered", "format": "date-time" }, "isPracticeMember": { "type": "boolean", "description": "A member of the tenant's practice, who reaches every one of its organisations: removed from the practice, not from\none organisation", "nullable": true }, "isPracticeGrant": { "type": "boolean", "description": "Reaches the tenant only through its practice's grant, not as a member in their own right: moving the tenant out of\nthe practice takes their access unless they are kept", "nullable": true } }, "additionalProperties": false, "description": "A user who is a member of the tenant." }, "TenantMembershipDto": { "required": [ "accessLevel", "code", "modules", "name" ], "type": "object", "properties": { "code": { "type": "string", "description": "Tenant code: the value of the {tenant} route parameter" }, "name": { "type": "string", "description": "Tenant name" }, "accessLevel": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "description": "The user's access level within the tenant" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/Modules" }, "description": "The modules enabled for the tenant" }, "logoUrl": { "type": "string", "description": "URL of the tenant's logo, if one has been uploaded", "nullable": true }, "isOwner": { "type": "boolean", "description": "Whether the user owns the tenant", "nullable": true }, "practice": { "type": "string", "description": "The code of the practice running the tenant; null when it is in none", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "One of the authenticated user's tenant memberships, as reported by `GET /me`." }, "TenantSortField": { "enum": [ "Name", "CreatedDate" ], "type": "string", "example": "Name" }, "TenantSummaryDto": { "required": [ "code", "customerCount", "isContractor", "isSubcontractor", "name", "supplierCount" ], "type": "object", "properties": { "code": { "type": "string", "description": "The tenant code" }, "name": { "type": "string", "description": "The tenant's name" }, "logoUrl": { "type": "string", "description": "The logo's storage URL, when one is uploaded", "nullable": true }, "isContractor": { "type": "boolean", "description": "Whether the tenant has the contractor module" }, "isSubcontractor": { "type": "boolean", "description": "Whether the tenant has the subcontractor module" }, "customerCount": { "type": "integer", "description": "How many customers the tenant has", "format": "int32" }, "supplierCount": { "type": "integer", "description": "How many suppliers the tenant has", "format": "int32" }, "thisPeriodReturn": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnDto" } ], "description": "The CIS return for the current tax period, when there is one", "nullable": true }, "lastPeriodReturn": { "allOf": [ { "$ref": "#/components/schemas/MonthlyReturnDto" } ], "description": "The CIS return for the last tax period, when there is one", "nullable": true } }, "additionalProperties": false, "description": "One of the caller's tenants as the overview page shows them: counts and the returns of this and the last tax\nperiod." }, "TestEmailConfigRequest": { "required": [ "recipientEmail" ], "type": "object", "properties": { "recipientEmail": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The address to send the test email to", "format": "email" } }, "additionalProperties": false, "description": "Where to send a test email." }, "TestEmailConfigResultDto": { "required": [ "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the connection sent the email" }, "message": { "type": "string", "description": "The outcome in words" }, "error": { "type": "string", "description": "What the mail server or provider said, when it failed", "nullable": true } }, "additionalProperties": false, "description": "The outcome of a test email." }, "TestHmrcCredentialsRequest": { "required": [ "tenant" ], "type": "object", "properties": { "tenant": { "minLength": 1, "type": "string", "description": "The tenant (code) whose HMRC references the test submission uses" } }, "additionalProperties": false, "description": "A request to test a practice's credentials against the HMRC gateway. A submission needs a tenant as its context, so\none of the caller's tenants is named." }, "TimesheetImportResultDto": { "required": [ "createdCount", "failedCount", "rows" ], "type": "object", "properties": { "createdCount": { "type": "integer", "description": "The number of invoices created", "format": "int32" }, "failedCount": { "type": "integer", "description": "The number of selected rows that were not imported", "format": "int32" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetImportResultRowDto" }, "description": "One entry per selected row, in selection order" } }, "additionalProperties": false, "description": "The outcome of a timesheet import." }, "TimesheetImportResultRowDto": { "required": [ "rowId", "subcontractorCode", "success" ], "type": "object", "properties": { "rowId": { "minLength": 1, "type": "string", "description": "The row id from the analysis" }, "subcontractorCode": { "minLength": 1, "type": "string", "description": "The subcontractor code as written in the file" }, "success": { "type": "boolean", "description": "Whether the invoice was created" }, "number": { "type": "integer", "description": "The created invoice's number", "format": "int32", "nullable": true }, "date": { "type": "string", "description": "The created invoice's date", "format": "date", "nullable": true }, "error": { "type": "string", "description": "Why the row was not imported, or, on a created invoice, why its payment was not recorded", "nullable": true } }, "additionalProperties": false, "description": "The outcome of importing one selected row." }, "TimesheetImportRowDto": { "required": [ "defaultSelected", "isDomesticReverseCharge", "rowId", "subcontractorCode", "subcontractorMatched" ], "type": "object", "properties": { "rowId": { "minLength": 1, "type": "string", "description": "The row's id (row-{n}, n the 1-based data row; the header is row 0), passed back in the import's selections" }, "subcontractorCode": { "minLength": 1, "type": "string", "description": "The subcontractor code as written in the file" }, "subcontractorName": { "type": "string", "description": "The matched subcontractor's name, when the code is a CIS subcontractor of the tenant", "nullable": true }, "subcontractorMatched": { "type": "boolean", "description": "Whether the code matched a CIS subcontractor of the tenant" }, "invoiceDate": { "type": "string", "description": "The invoice date", "format": "date", "nullable": true }, "dueDate": { "type": "string", "description": "The due date (the invoice date when the file leaves it blank)", "format": "date", "nullable": true }, "totalLabour": { "type": "number", "description": "The labour total before VAT", "format": "double", "nullable": true }, "totalMaterials": { "type": "number", "description": "The materials total before VAT", "format": "double", "nullable": true }, "totalVat": { "type": "number", "description": "The VAT total", "format": "double", "nullable": true }, "total": { "type": "number", "description": "The invoice total", "format": "double", "nullable": true }, "deduction": { "type": "number", "description": "The CIS deduction", "format": "double", "nullable": true }, "paymentAmount": { "type": "number", "description": "The amount payable (total less deduction), which is also the payment amount when a payment date is given", "format": "double", "nullable": true }, "isDomesticReverseCharge": { "type": "boolean", "description": "Whether the domestic reverse charge applies" }, "paymentDate": { "type": "string", "description": "The payment date when the row carries one; the import then records a payment for the full payment amount", "format": "date", "nullable": true }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The CIS rate the invoice is taken at: the CisHeldBack column on a paid row, else the subcontractor's. Null when\nthe row is skipped", "nullable": true }, "skipReason": { "type": "string", "description": "Why the row cannot be imported; null when it can", "nullable": true }, "defaultSelected": { "type": "boolean", "description": "Whether a client should pre-select the row (true when it has no skip reason)" } }, "additionalProperties": false, "description": "One data row of a timesheet CSV as the analysis sees it: the purchase invoice it would become, or why it is skipped." }, "TransferOwnershipRequest": { "required": [ "user" ], "type": "object", "properties": { "user": { "type": "string", "description": "The user's code; must be a member", "format": "uuid" } }, "additionalProperties": false, "description": "The member to make the tenant's owner." }, "UpdateBillingProfileRequest": { "type": "object", "properties": { "billingEmail": { "maxLength": 150, "type": "string", "description": "Where invoices are also emailed; blank for only the account's email address", "format": "email", "nullable": true }, "companyName": { "maxLength": 200, "type": "string", "description": "The company name invoices are made out to; blank for the user's name", "nullable": true }, "addressLine1": { "maxLength": 200, "type": "string", "description": "Billing address, first line", "nullable": true }, "addressLine2": { "maxLength": 200, "type": "string", "description": "Billing address, second line", "nullable": true }, "city": { "maxLength": 100, "type": "string", "description": "Billing address town or city", "nullable": true }, "postcode": { "maxLength": 20, "type": "string", "description": "Billing address postcode", "nullable": true }, "country": { "maxLength": 100, "type": "string", "description": "Billing address country", "nullable": true } }, "additionalProperties": false, "description": "The billing address to put on the caller's invoices (`PUT /me/billing/profile`). A full replacement of\nthe address; the mandate is untouched." }, "UpdateContactNoteRequest": { "required": [ "date", "note" ], "type": "object", "properties": { "note": { "minLength": 1, "type": "string", "description": "The note's text" }, "date": { "type": "string", "description": "The date the note is about", "format": "date-time" } }, "additionalProperties": false, "description": "A full replacement of a note's text and date." }, "UpdateContactRequest": { "required": [ "displayName", "isCisSubcontractor", "isCustomer", "isSupplier", "isVatRegistered" ], "type": "object", "properties": { "isCustomer": { "type": "boolean", "description": "Whether the tenant invoices this contact" }, "isSupplier": { "type": "boolean", "description": "Whether this contact invoices the tenant. Required for a CIS subcontractor." }, "isCisSubcontractor": { "type": "boolean", "description": "Whether the tenant pays this contact under the Construction Industry Scheme" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Display name of the contact" }, "title": { "maxLength": 4, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "Title (e.g. Mr, Mrs, Ms)", "nullable": true }, "firstName": { "maxLength": 35, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "First name", "nullable": true }, "secondName": { "maxLength": 35, "pattern": "^[A-Za-z][A-Za-z'\\-]*$", "type": "string", "description": "Second (middle) name", "nullable": true }, "lastName": { "maxLength": 35, "pattern": "^[A-Za-z0-9 ,\\.\\(\\)/&\\-']+$", "type": "string", "description": "Last name", "nullable": true }, "emailAddress": { "maxLength": 255, "type": "string", "description": "Email address", "format": "email", "nullable": true }, "telephone": { "maxLength": 50, "type": "string", "description": "Telephone number", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ], "description": "Postal address", "nullable": true }, "isVatRegistered": { "type": "boolean", "description": "Whether the contact is VAT registered" }, "vatRegistrationNumber": { "maxLength": 20, "type": "string", "description": "VAT registration number", "nullable": true }, "defaultRate": { "type": "number", "description": "Default rate for the contact", "format": "double", "nullable": true }, "cisDetails": { "allOf": [ { "$ref": "#/components/schemas/CisDetailsDto" } ], "description": "CIS identity details. Only for a CIS subcontractor.", "nullable": true }, "supplierSettings": { "allOf": [ { "$ref": "#/components/schemas/SupplierSettingsDto" } ], "description": "Defaults for the invoices received from the contact. Only for a supplier.", "nullable": true } }, "additionalProperties": false, "description": "Replaces a contact's editable fields, roles included. The code, external id, last SDC date and verification\nare not editable here and are kept as they are. Changing the roles is a PUT with different flags; removing the\ncustomer or supplier role while invoices exist in that direction is refused with 409. The role-specific parts\nare required for the roles the contact holds after the update: cisDetails for a CIS subcontractor,\nsupplierSettings for a supplier. Removing the subcontractor role keeps its CIS identity and verification on\nrecord; adding the role back restores them." }, "UpdateEmailConfigRequest": { "type": "object", "properties": { "fromEmail": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The address the emails are from (SMTP only: Outlook and Gmail send from the mailbox that signed in)", "format": "email", "nullable": true }, "fromName": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The name the emails are from", "nullable": true }, "isDefault": { "type": "boolean", "description": "True makes it the connection the tenant's emails go through, in place of the current one", "nullable": true }, "smtpSettings": { "allOf": [ { "$ref": "#/components/schemas/EmailSmtpSettingsRequest" } ], "description": "The SMTP settings (SMTP only)", "nullable": true } }, "additionalProperties": false, "description": "Changes to a connection: a property left out keeps its value." }, "UpdateEmailSettingsRequest": { "required": [ "autoSendStatements" ], "type": "object", "properties": { "signature": { "maxLength": 4000, "minLength": 0, "type": "string", "description": "The signature appended to the tenant's emails", "nullable": true }, "autoSendStatements": { "type": "boolean", "description": "Email subcontractors their statements automatically when a return is accepted" } }, "additionalProperties": false, "description": "A full replacement of the email settings." }, "UpdateEmailTemplateRequest": { "required": [ "body", "subject" ], "type": "object", "properties": { "subject": { "maxLength": 500, "minLength": 0, "type": "string", "description": "The subject" }, "body": { "minLength": 1, "type": "string", "description": "The body" } }, "additionalProperties": false, "description": "A customised subject and body for a template. DELETE the template to go back to the defaults." }, "UpdateHmrcSettingsRequest": { "required": [ "senderType", "testInLive", "useSharedCredentials", "useTestGateway" ], "type": "object", "properties": { "useSharedCredentials": { "type": "boolean", "description": "Use one of the owner's shared credentials" }, "sharedCredentialsId": { "type": "string", "description": "The shared credentials to use (a code from /settings/hmrc/shared-credentials); null with useSharedCredentials\nfollows the practice's default, whichever set that is when the tenant files", "format": "uuid", "nullable": true }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 30, "minLength": 0, "type": "string", "description": "The gateway user id", "nullable": true }, "password": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The gateway password; null keeps the stored one", "nullable": true }, "employerPayeReference": { "maxLength": 20, "minLength": 0, "pattern": "^\\s*[0-9]{3}/[A-Za-z0-9]{1,10}\\s*$", "type": "string", "description": "The employer PAYE reference, office number and reference in one: \"123/AB45678\" (upper-cased on save)", "nullable": true }, "accountsOfficeReference": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The accounts office reference", "nullable": true }, "utr": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The tenant's UTR", "nullable": true }, "testInLive": { "type": "boolean", "description": "Send submissions to the live gateway flagged as tests" }, "useTestGateway": { "type": "boolean", "description": "Send submissions to HMRC's test gateway" }, "agent": { "allOf": [ { "$ref": "#/components/schemas/HmrcAgentDto" } ], "description": "The agent details, when the sender is an agent", "nullable": true } }, "additionalProperties": false, "description": "A full replacement of the HMRC settings. The password is optional: omitted or null keeps the stored one. With\nuseSharedCredentials the tenant's own sender id, password and agent are discarded." }, "UpdateInvoiceLineRequest": { "required": [ "amount", "quantity", "type", "vatRate" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/InvoiceLineType" } ], "description": "Labour (subject to the CIS deduction) or Materials" }, "description": { "maxLength": 500, "type": "string", "description": "What the line is for", "nullable": true }, "quantity": { "type": "number", "description": "Quantity (hours, units). Values under 1 are treated as 1.", "format": "double" }, "amount": { "type": "number", "description": "Unit amount before VAT", "format": "double" }, "vatRate": { "allOf": [ { "$ref": "#/components/schemas/VatRate" } ], "description": "The VAT rate. Ignored (OutOfScope) when VAT does not apply to the invoice." }, "externalId": { "maxLength": 50, "type": "string", "description": "The caller's own identifier for the line", "nullable": true }, "code": { "type": "string", "description": "The code of the line to update, or null for a new line", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "A line of an invoice being replaced: with the code of an existing line it updates that line, without one it adds\na line. Lines of the invoice not in the request are deleted." }, "UpdateInvoicePaymentRequest": { "required": [ "amount", "date" ], "type": "object", "properties": { "date": { "type": "string", "description": "When it was paid. A purchase invoice payment cannot fall in a tax month whose return is submitted.", "format": "date-time" }, "amount": { "type": "number", "description": "The amount paid. The invoice's payments cannot exceed its amount payable.", "format": "double" } }, "additionalProperties": false, "description": "A full replacement of a payment's date and amount." }, "UpdateInvoiceRequest": { "required": [ "date", "isDomesticReverseCharge", "lines", "taxStatus" ], "type": "object", "properties": { "date": { "type": "string", "description": "The invoice date", "format": "date-time" }, "dueDate": { "type": "string", "description": "When payment is due. Defaults to the invoice date.", "format": "date-time", "nullable": true }, "yourReference": { "maxLength": 50, "type": "string", "description": "The tenant's own reference", "nullable": true }, "theirReference": { "maxLength": 50, "type": "string", "description": "The contact's reference", "nullable": true }, "isDomesticReverseCharge": { "type": "boolean", "description": "Whether the VAT domestic reverse charge applies. Cleared when either party is not VAT registered." }, "deduction": { "type": "number", "description": "Sales invoices only: the CIS deduction the customer made. Ignored on a purchase invoice, where the deduction\nfollows from the labour total and the tax status.", "format": "double", "nullable": true }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The CIS deduction rate applied to the invoice's labour" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateInvoiceLineRequest" }, "description": "The lines, keyed by code: an existing code updates that line, no code adds one, and a line left out is deleted" } }, "additionalProperties": false, "description": "A full replacement of an invoice's editable fields and lines. The contact, external id and payments are not\nchanged here." }, "UpdateMeRequest": { "type": "object", "properties": { "firstName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "First name", "nullable": true }, "lastName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Last name", "nullable": true }, "phoneNumber": { "maxLength": 50, "minLength": 0, "type": "string", "description": "Phone number", "nullable": true } }, "additionalProperties": false, "description": "A full replacement of the caller's editable profile fields." }, "UpdatePracticeHmrcCredentialsRequest": { "required": [ "isDefault", "name", "senderId", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "name": { "maxLength": 100, "minLength": 0, "type": "string", "description": "What the HMRC settings page offers the set as" }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 30, "minLength": 0, "type": "string", "description": "The gateway user id" }, "testInLive": { "type": "boolean", "description": "Send submissions to the live gateway flagged as tests" }, "useTestGateway": { "type": "boolean", "description": "Send submissions to HMRC's test gateway" }, "agent": { "allOf": [ { "$ref": "#/components/schemas/HmrcAgentDto" } ], "description": "The agent details, when the sender is an agent", "nullable": true }, "password": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The gateway password; null keeps the stored one", "nullable": true }, "isDefault": { "type": "boolean", "description": "Make it the practice's default. False leaves the default where it is: the default moves only by naming another" } }, "additionalProperties": false, "description": "A full replacement of a set of practice credentials. The password is optional: omitted or null keeps the stored one." }, "UpdateRemittanceAdviceSettingsRequest": { "required": [ "includeContractorRef", "includeFooterSummary", "includeInvoiceDate", "includeInvoiceNumber", "includeSubcontractorRef", "includeSubcontractorUtr", "useCustomDrcText", "useCustomFooterText", "useCustomPaymentText" ], "type": "object", "properties": { "useCustomPaymentText": { "type": "boolean", "description": "Whether paymentText replaces the default \"The above amount has been paid by BACS.\"" }, "paymentText": { "type": "string", "description": "The custom payment text; null unless useCustomPaymentText", "nullable": true }, "useCustomFooterText": { "type": "boolean", "description": "Whether footerText is printed" }, "footerText": { "type": "string", "description": "The custom footer text; null unless useCustomFooterText", "nullable": true }, "includeInvoiceNumber": { "type": "boolean", "description": "Show the invoice number column" }, "includeInvoiceDate": { "type": "boolean", "description": "Show the invoice date column" }, "includeContractorRef": { "type": "boolean", "description": "Show the contractor's reference column" }, "contractorRefHeaderText": { "type": "string", "description": "The contractor's reference column heading (default \"Reference\"); null unless includeContractorRef", "nullable": true }, "includeSubcontractorRef": { "type": "boolean", "description": "Show the subcontractor's reference column" }, "subcontractorRefHeaderText": { "type": "string", "description": "The subcontractor's reference column heading (default \"Your Ref\"); null unless includeSubcontractorRef", "nullable": true }, "includeSubcontractorUtr": { "type": "boolean", "description": "Print the subcontractor's UTR" }, "includeFooterSummary": { "type": "boolean", "description": "Print the deduction summary in the footer" }, "useCustomDrcText": { "type": "boolean", "description": "Whether drcText replaces the default domestic reverse charge note" }, "drcText": { "type": "string", "description": "The custom domestic reverse charge note; null unless useCustomDrcText", "nullable": true } }, "additionalProperties": false, "description": "A full replacement of the remittance advice settings. A text whose switch is off is discarded." }, "UpdateSubcontractorVerificationRequest": { "required": [ "date", "number", "taxStatus" ], "type": "object", "properties": { "number": { "minLength": 1, "pattern": "^V[0-9]{10}[A-HJ-NP-Z]{0,2}$", "type": "string", "description": "The verification number HMRC issued: V followed by 10 digits and up to 2 uppercase letters (not I or O)" }, "date": { "type": "string", "description": "The date HMRC verified the subcontractor", "format": "date-time" }, "taxStatus": { "allOf": [ { "$ref": "#/components/schemas/CisTaxStatus" } ], "description": "The deduction rate HMRC gave" } }, "additionalProperties": false, "description": "A verification obtained from HMRC outside the API (by phone or through HMRC online services), recorded\nmanually. A full replacement of any manual verification already recorded." }, "UpdateTenantCisDetailsRequest": { "required": [ "type" ], "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/CisSubcontractorType" } ], "description": "Sole trader, partnership, company or trust" }, "title": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The person's title", "nullable": true }, "firstName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The person's first name", "nullable": true }, "secondName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The person's second name", "nullable": true }, "lastName": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The person's last name", "nullable": true }, "tradingName": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The trading name", "nullable": true }, "utr": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The Unique Taxpayer Reference", "nullable": true }, "niNumber": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The National Insurance number", "nullable": true }, "companyNumber": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The company registration number", "nullable": true }, "partnershipName": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The partnership's name", "nullable": true }, "partnershipUtr": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The partnership's UTR", "nullable": true } }, "additionalProperties": false, "description": "A full replacement of the tenant's CIS details." }, "UpdateTenantRequest": { "required": [ "isSupportAccessEnabled", "isVatRegistered", "modules", "name", "shareDetailsDefault" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The tenant's name" }, "address": { "allOf": [ { "$ref": "#/components/schemas/TenantAddressDto" } ], "description": "The postal address", "nullable": true }, "phoneNumber": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The phone number", "nullable": true }, "emailAddress": { "maxLength": 255, "minLength": 0, "type": "string", "description": "The tenant's email address. Changing it un-verifies it and sends a verification email to the new address.", "format": "email", "nullable": true }, "isVatRegistered": { "type": "boolean", "description": "Whether the tenant is VAT registered" }, "vatRegistrationNumber": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The VAT registration number", "nullable": true }, "shareDetailsDefault": { "type": "boolean", "description": "Whether new subcontractors default to sharing their details" }, "isSupportAccessEnabled": { "type": "boolean", "description": "Whether CIS Manager support agents may access the tenant" }, "modules": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/Modules" }, "description": "The modules the tenant uses: CisContractor, CisSubcontractor or both" } }, "additionalProperties": false, "description": "A full replacement of the tenant's own details, as the settings page edits them. Counts, the logo, the\nverification state and the owner are not part of it (they have their own resources or are read-only)." }, "UpdateWebhookRequest": { "required": [ "enabled", "events", "name", "url" ], "type": "object", "properties": { "name": { "maxLength": 100, "minLength": 0, "type": "string", "description": "What the webhook is for" }, "url": { "maxLength": 500, "minLength": 0, "type": "string", "description": "The HTTPS URL the events are sent to" }, "enabled": { "type": "boolean", "description": "Whether events are sent" }, "events": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "The events the webhook is sent; at least one" } }, "additionalProperties": false, "description": "A webhook's new name, URL, enabled flag and events. The secret is kept." }, "UserInvitationDto": { "required": [ "code", "createdDate", "email", "expiryDate", "isExpired", "role", "status", "tenant", "tenantName" ], "type": "object", "properties": { "code": { "type": "string", "description": "The invitation's identifier", "format": "uuid" }, "tenant": { "type": "string", "description": "The code of the tenant the invitation joins" }, "tenantName": { "type": "string", "description": "The tenant's name" }, "email": { "type": "string", "description": "The email address it was sent to (accepting it joins the caller whatever their address)" }, "role": { "allOf": [ { "$ref": "#/components/schemas/AccessLevel" } ], "description": "The access level offered" }, "message": { "type": "string", "description": "The personal message in the email", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/InvitationStatus" } ], "description": "Pending, Accepted, Rejected or Expired" }, "expiryDate": { "type": "string", "description": "When the invitation stops being acceptable", "format": "date-time" }, "isExpired": { "type": "boolean", "description": "Whether the expiry date has passed" }, "invitedBy": { "type": "string", "description": "Who sent it", "nullable": true }, "createdDate": { "type": "string", "description": "When it was sent", "format": "date-time" }, "practiceName": { "type": "string", "description": "For an invitation to a whole practice, the practice's name: accepting it reaches every organisation the practice\nruns, tenant among them", "nullable": true } }, "additionalProperties": false, "description": "An invitation to join a tenant, as the invited user sees it. The code is the one in the emailed link." }, "VatRate": { "enum": [ "Zero", "Reduced", "Standard", "OutOfScope", "Exempt" ], "type": "string", "example": "Zero" }, "VerifyEmailAddressRequest": { "required": [ "email", "key" ], "type": "object", "properties": { "email": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The address being verified" }, "key": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The verification key from the link" }, "tenant": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The tenant whose address is being verified; omitted for the user's own address", "nullable": true } }, "additionalProperties": false, "description": "The address and key from an emailed verification link." }, "WebhookDeliveryDto": { "required": [ "attemptCount", "code", "createdDate", "event", "status", "url", "webhookCode" ], "type": "object", "properties": { "code": { "type": "string", "description": "The delivery's code (the id in the payload)", "format": "uuid" }, "webhookCode": { "type": "string", "description": "The webhook it was sent to", "format": "uuid" }, "event": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "description": "The event" }, "url": { "type": "string", "description": "The URL it was sent to" }, "status": { "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryStatus" } ], "description": "Whether it is waiting, delivered, being retried or has failed" }, "attemptCount": { "type": "integer", "description": "How many times it has been sent", "format": "int32" }, "httpStatusCode": { "type": "integer", "description": "The receiver's HTTP status on the last attempt", "format": "int32", "nullable": true }, "deliveredDate": { "type": "string", "description": "When it was delivered", "format": "date-time", "nullable": true }, "nextRetryDate": { "type": "string", "description": "When it is sent again, while it is being retried", "format": "date-time", "nullable": true }, "createdDate": { "type": "string", "description": "When the event happened", "format": "date-time" }, "payload": { "type": "string", "description": "The JSON that was sent. On the single GET only.", "nullable": true }, "responseBody": { "type": "string", "description": "What the receiver answered on the last attempt. On the single GET only.", "nullable": true } }, "additionalProperties": false, "description": "One event sent, or being sent, to a webhook: what was sent, how often it was tried and how the receiver answered." }, "WebhookDeliveryDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "WebhookDeliverySortField": { "enum": [ "CreatedDate" ], "type": "string", "example": "CreatedDate" }, "WebhookDeliveryStatus": { "enum": [ "Pending", "Success", "Retrying", "Failed" ], "type": "string", "example": "Pending" }, "WebhookDto": { "required": [ "code", "createdDate", "enabled", "events", "name", "url" ], "type": "object", "properties": { "code": { "type": "string", "description": "The webhook's code", "format": "uuid" }, "name": { "type": "string", "description": "What the webhook is for" }, "url": { "type": "string", "description": "The HTTPS URL the events are sent to" }, "secret": { "type": "string", "description": "The secret the deliveries are signed with (the X-Webhook-Signature header). Set when the webhook is created\nand on the single GET only, never in the list.", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether events are sent. A webhook is switched off automatically after repeated failed deliveries." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "The events the webhook is sent" }, "createdDate": { "type": "string", "description": "When the webhook was created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When the webhook was last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "One of the tenant's webhooks: an HTTPS URL that is sent the events it subscribes to, each signed with the\nwebhook's secret." }, "WebhookDtoPagedResult": { "required": [ "data", "hasMore", "limit", "offset" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDto" } }, "totalCount": { "type": "integer", "format": "int32", "nullable": true }, "offset": { "type": "integer", "format": "int32" }, "limit": { "type": "integer", "format": "int32" }, "hasMore": { "type": "boolean" } }, "additionalProperties": false }, "WebhookEvent": { "enum": [ "TestWebhook", "SubcontractorCreated", "SubcontractorUpdated", "SubcontractorDeleted", "SubcontractorVerified", "SubcontractorVerificationFailed", "SubcontractorVerificationRemoved", "InvoiceCreated", "InvoiceUpdated", "InvoiceDeleted", "ReturnOpened", "ReturnSubmitted", "ReturnAccepted", "ReturnFailed", "WebhookAutoDisabled" ], "type": "string", "example": "TestWebhook" }, "WebhookSortField": { "enum": [ "Name", "CreatedDate", "Enabled" ], "type": "string", "example": "Name" } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "API Key required in 'x-api-key' header", "name": "x-api-key", "in": "header" }, "OAuth2": { "type": "oauth2", "description": "OAuth2 implicit flow", "flows": { "implicit": { "authorizationUrl": "https://id.sodiumhq.com/authorize", "scopes": { "openid": "OpenID Connect", "profile": "User profile", "email": "Email address" } } } } } }, "security": [ { "ApiKey": [] }, { "OAuth2": [ "openid", "profile", "email" ] } ], "tags": [ { "name": "Me", "description": "The authenticated user: profile, application roles and the tenants they are a member of, with the user's access level and each tenant's modules; and what reaches them by email: their verification link, invitations to join tenants and connection links. Works identically with an API key (the key's owner) and a bearer token; a bearer token whose subject is new signs the user up on first use." }, { "name": "API Keys", "description": "The caller's own API keys, under /me: a key belongs to a user and acts as them on every tenant they are a member of. The key itself is shown once, when it is issued; the list carries its name, dates and whether it is still active. Issuing and deleting need a bearer token (403 with an API key), so a key cannot issue or delete keys." }, { "name": "Billing", "description": "What CIS Manager charges the authenticated user, across every tenant they own (no tenant in the route): kept in Account Hub, which invoices and collects: the billing details (invoice address and Direct Debit state), the Direct Debit mandate with its GoCardless setup through Account Hub (start a setup, send the customer to GoCardless, complete it), the Account Hub invoices with their PDFs, and the usage not yet charged." }, { "name": "Tenants", "description": "The tenants (organisations) the authenticated user is a member of: the {tenant} code used in every other route, the tenant's modules, contact and VAT details, and its dashboard counts. A tenant the caller is not a member of is not found. Also creating a tenant, replacing its details (a changed email address is re-verified), its logo, its own CIS details as a subcontractor, the data-config export and import, and the caller's tenant summaries." }, { "name": "Contacts", "description": "Manage a tenant's contacts: the people and organisations it does business with, in one or more roles. Customers are invoiced by the tenant, suppliers invoice the tenant, and CIS subcontractors are suppliers paid under the Construction Industry Scheme. One contact, one code, whatever its roles; filter the list with role. A subcontractor carries its CIS identity (UTR, NI number, company number), invoice defaults and the current HMRC verification, and must be verified with HMRC before payments can be processed." }, { "name": "Verification", "description": "A CIS subcontractor's verification with HMRC, as a child of the contact (contractor module only). The verification is the outcome: not verified, entered manually (PUT), obtained from HMRC, or failed with HMRC's errors. Asking HMRC is a separate child, hmrc-request: POST submits a verify or match request, which is polled in the background, and the outcome lands on the verification; POST again while it is delayed to resume polling, DELETE to cancel it. Webhooks report each outcome (subcontractor.verified, subcontractor.verification_failed, subcontractor.verification_removed)." }, { "name": "Notes", "description": "Free-text notes recorded against a contact, as a child of the contact: a date (what the note is about, defaulting to when it was written), the text, and who wrote it (recorded, not exposed). Any contact of the tenant can carry notes." }, { "name": "Invoices", "description": "Purchase invoices (received from suppliers and subcontractors, paid by the tenant; contractor module) and sales invoices (issued to customers; subcontractor module), numbered in sequence per direction. Lines are part of the invoice; totals, VAT applicability and a purchase invoice's CIS deduction are computed. Payments are a child of the invoice and drive its paid state; a purchase invoice's payments must fall in a tax month whose CIS return is not yet submitted. A monthly analysis serves charts. Webhooks: invoice.created, invoice.updated, invoice.deleted." }, { "name": "Returns", "description": "CIS monthly returns (CIS300; contractor module only), one per tax month (the 6th to the 5th), identified by the calendar year and month the tax month ends in. An Open return collects the subcontractor invoices paid in its month; its totals, invoice and subcontractor counts and a per-subcontractor breakdown follow the payments. The submission child sends it to HMRC (POST), which is polled in the background until HMRC accepts it or reports errors (translated onto the return), and re-opens an accepted return (DELETE). Webhooks: return.submitted, return.accepted, return.failed, return.opened." }, { "name": "Statements", "description": "CIS payment and deduction statements (contractor module only): what one subcontractor was paid and had deducted in a tax month, or in a tax year (the annual statement). A statement exists once one of the subcontractor's invoices is paid in the period and lives under the contact, with its PDF and the emails sent of it; the tenant-wide list gives every subcontractor's statement for a period, with a combined PDF." }, { "name": "Remittance Advice", "description": "Remittance advices (contractor module only): what the tenant paid one subcontractor between two dates, invoice by invoice, with the CIS deductions taken. An advice is built from the payments when asked for and lives under the contact, identified by its from and to dates, with its PDF and the emails sent of it. The tenant's layout settings (columns, custom texts) are under /settings." }, { "name": "SDC Statements", "description": "Supervision, Direction and Control statements (contractor module only), as a child of the subcontractor: questionnaires the tenant sends a subcontractor to complete and sign on a public page, recording their employment status under the CIS rules. Creating one emails the request; the statement is pending until signed, and the contact's lastSdc follows its completed statements." }, { "name": "CIS Details Requests", "description": "Requests for a subcontractor's CIS details (contractor module only), as a child of the subcontractor: the tenant emails the subcontractor a link to a public form, what they enter (type, name, UTR, National Insurance number, company number) is held on the request, and the tenant reviews it and accepts it onto the contact. An SDC statement can go with the request, and the form then leads on to it. The public form's calls need no credentials: the request's code is the key." }, { "name": "Connections", "description": "Connections between two CIS Manager tenants (Interlinks), one resource seen from the viewing tenant's side: direction is relative to the viewer (Out = the subcontractor that shared its CIS details, In = the contractor they were sent to). A subcontractor tenant shares its details with one of its contractor contacts, who is emailed them; the contractor accepts by setting its side (a subcontractor created from the shared details, or an existing one), which connects both; a pending connection sent to a tenant can be rejected, any other deleted. A contractor asks a subcontractor for its details with a CIS details request instead. No module gate." }, { "name": "HMRC Settings", "description": "The tenant's HMRC gateway settings for CIS submissions (contractor module only): sender, references, test flags and agent details, or a reference to one of its practice's sets of credentials. Passwords are never returned; a PUT without one keeps the stored one. A test sends a dummy verification through the gateway." }, { "name": "My Practices", "description": "The practices the caller is a member of, under /me: a practice is a group of client organisations whose members reach every one of them. Its HMRC gateway credentials (several sets, one the default) are what its organisations' HMRC settings share. A practice managed in Sodium is read-only here (409); SodiumHQ keeps it. Passwords are never returned." }, { "name": "Email Settings", "description": "The tenant's email signature, whether statements are emailed automatically, and the templates of the emails it sends (one per type, customised with PUT, back to the default with DELETE)." }, { "name": "Email Configs", "description": "The tenant's own email connections (SMTP, Outlook or Gmail), send only. The tenant's statements, invoices, remittance advice and SDC requests go through its default connection while that is connected, from the connection's own address; with none, they go through CIS Manager's sender with replies to the tenant. Passwords and tokens are never returned. Outlook and Gmail connect by sending the user to authorisationUrl." }, { "name": "Webhooks", "description": "The tenant's webhooks: HTTPS URLs sent the events they subscribe to (subcontractor, verification, invoice and return events, and webhook.auto_disabled). Each delivery is a POST of the event as JSON, signed with the webhook's secret in X-Webhook-Signature and named in X-Webhook-Event; one that fails is retried with increasing delays, and a webhook whose deliveries keep failing is switched off and its tenant emailed. The secret is returned when the webhook is created and on its single GET. Deliveries are the history: what was sent, how often, and the receiver's answer; a failed one can be sent again." }, { "name": "Team", "description": "The tenant's members (the users who belong to it), its owner, and the invitations it has sent by email. The owner cannot be removed; ownership is transferred to another member." } ] }