{ "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/billing/profile": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Profile", "description": "The caller's billing profile: the address their invoices are made out to and the state of their direct debit mandate. Empty (no address, mandate NotStarted) until an address is set or a setup is started.", "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, billing email, address lines, postcode, country), creating the profile on first use. The mandate is untouched. 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" } } } } } } }, "/me/billing/mandate": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Mandate", "description": "The caller's direct debit mandate, its status refreshed from GoCardless (so a setup completed moments ago shows as it is, whether or not the webhook has arrived) and, when it is active, the account holder as GoCardless holds them. 404 until a setup has been started.", "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 (from the setup, and appended by GoCardless to the success URL) with the session token the setup returned. The mandate becomes the caller's, invoices waiting for a mandate are put forward for collection, and the mandate is returned as GET does. A caller who already has an active or in-progress mandate keeps it.", "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" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Cancel Billing Mandate", "description": "Cancels the caller's direct debit mandate with GoCardless. Automatic payments stop; a new setup can be started at any time. 404 when there is no mandate.", "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" } } } } } } }, "/me/billing/mandate-setups": { "post": { "tags": [ "Billing" ], "summary": "Create Mandate Setup", "description": "Starts a direct debit setup with GoCardless. 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, passing the session token it was given here. 409 when the caller already has an active or in-progress mandate; 400 when the caller has no email address or GoCardless refused.", "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 invoiced, across every tenant the caller owns: each monthly return HMRC has accepted, with the subcontractors on it. Invoiced at the end of the month.", "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 CIS Manager, latest first, with the payment status of any pending or failed ones refreshed from GoCardless first.", "operationId": "ListBillingInvoices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoiceDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/me/billing/invoices/{invoice}": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Invoice", "description": "One of the caller's invoices, with its lines. Another user's invoice is not found.", "operationId": "GetBillingInvoice", "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInvoiceDto" } } } }, "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/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 its PDF has not been generated yet (hasPdf).", "operationId": "GetBillingInvoicePdf", "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "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" } } } } } } }, "/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": "Initiates a connection for one of the tenant's contacts: Out shares the tenant's CIS details with the contractor the contact stands for, In invites the subcontractor the contact stands for. The other party is emailed at the given address (and the tenant is told what happens next). 409 when the contact already has a connection on that side.", "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, initiated by the tenant for one of its 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, one created from the details the initiator shared (a supplier and CIS subcontractor when a subcontractor shared its details, a customer when a contractor invited). When the tenant is the contractor, the new 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}/settings/email": { "get": { "tags": [ "EmailSettings" ], "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": [ "EmailSettings" ], "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": [ "EmailSettings" ], "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": [ "EmailSettings" ], "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": [ "EmailSettings" ], "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": [ "EmailSettings" ], "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" } } } } } } }, "/me/hmrc-credentials": { "get": { "tags": [ "HmrcCredentials" ], "summary": "List HMRC Credentials", "description": "The caller's shareable HMRC gateway credentials, which a tenant's HMRC settings can reference as sharedCredentialsId.", "operationId": "ListHmrcCredentials", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HmrcCredentialsDto" } } } } }, "401": { "description": "Unauthorized – Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "HmrcCredentials" ], "summary": "Create HMRC Credentials", "description": "Stores a new set of credentials for the caller.", "operationId": "CreateHmrcCredentials", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateHmrcCredentialsRequest" } ], "description": "New shared credentials." } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcCredentialsDto" } } } }, "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/hmrc-credentials/{credentials}": { "get": { "tags": [ "HmrcCredentials" ], "summary": "Get HMRC Credentials", "description": "One of the caller's credentials.", "operationId": "GetHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HmrcCredentialsDto" } } } }, "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": [ "HmrcCredentials" ], "summary": "Update HMRC Credentials", "description": "Replaces the credentials; a null password keeps the stored one.", "operationId": "UpdateHmrcCredentials", "parameters": [ { "name": "credentials", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateHmrcCredentialsRequest" } ], "description": "A full replacement of shared 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/HmrcCredentialsDto" } } } }, "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": [ "HmrcCredentials" ], "summary": "Delete HMRC Credentials", "description": "Deletes the credentials. A tenant still referencing them falls back to its own settings.", "operationId": "DeleteHmrcCredentials", "parameters": [ { "name": "credentials", "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" } } } } } } }, "/me/hmrc-credentials/{credentials}/test": { "post": { "tags": [ "HmrcCredentials" ], "summary": "Test 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.", "operationId": "TestHmrcCredentials", "parameters": [ { "name": "credentials", "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 shared 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}/settings/hmrc": { "get": { "tags": [ "HmrcSettings" ], "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. 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": [ "HmrcSettings" ], "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. 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/test": { "post": { "tags": [ "HmrcSettings" ], "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" } } } } } }, "put": { "tags": [ "Me" ], "summary": "Update Me", "description": "Replaces the caller's editable profile fields: names, phone number and whether they manage several tenants. 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/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/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/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/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" } } } } } } }, "/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": [ "RemittanceAdvice" ], "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": [ "RemittanceAdvice" ], "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": [ "RemittanceAdvice" ], "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": [ "RemittanceAdvice" ], "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": [ "RemittanceAdvice" ], "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": [ "RemittanceAdvice" ], "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, 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 the owner's billing blocks submissions (the 402 a submit would get), or is null.", "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 becomes Submitted and is polled in the background: HMRC's acceptance or errors land on its status (webhooks return.submitted, return.accepted, return.failed). 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.", "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" } } } } } }, "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": [ "SdcStatements" ], "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}/logo": { "get": { "tags": [ "SdcStatements" ], "summary": "Get Public SDC Statement Logo", "description": "The logo of the tenant that sent the statement, with no credentials; 404 for an unknown code or when the tenant has no logo.", "operationId": "GetPublicSdcStatementLogo", "parameters": [ { "name": "sdc", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "x-order": 400 } ], "responses": { "200": { "description": "OK", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/bmp": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/sdc-statements/{sdc}/signature": { "put": { "tags": [ "SdcStatements" ], "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": [ "SdcStatements" ], "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": [ "SdcStatements" ], "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": [ "SdcStatements" ], "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": [ "SdcStatements" ], "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 and which one is the caller.", "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, and the owner cannot be removed until ownership is transferred (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.", "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.", "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" } } } } } } }, "/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. A contractor tenant of a user who manages several tenants adopts the user's first shared HMRC credentials.", "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" } } } } } } }, "/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.", "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": { "get": { "tags": [ "Tenants" ], "summary": "Get Tenant Logo", "description": "The tenant's logo image; 404 when none is uploaded.", "operationId": "GetTenantLogo", "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": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/bmp": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "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" } } } } } }, "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).", "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" } } } } } } }, "/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" } } } } } } } }, "components": { "schemas": { "AccessLevel": { "enum": [ "None", "Admin" ], "type": "string", "example": "None" }, "AddressDto": { "type": "object", "properties": { "line1": { "maxLength": 35, "type": "string", "description": "Address line 1", "nullable": true }, "line2": { "maxLength": 35, "type": "string", "description": "Address line 2", "nullable": true }, "line3": { "maxLength": 35, "type": "string", "description": "Address line 3", "nullable": true }, "line4": { "maxLength": 35, "type": "string", "description": "Address line 4", "nullable": true }, "postcode": { "maxLength": 10, "type": "string", "description": "Postcode", "nullable": true }, "country": { "maxLength": 35, "type": "string", "description": "Country", "nullable": true } }, "additionalProperties": false, "description": "A postal address." }, "BillingInvoiceDto": { "required": [ "billingDate", "code", "createdDate", "discountPercentage", "hasPdf", "invoiceNumber", "lines", "netAmount", "status", "subtotalAmount", "totalAmount", "totalSubcontractors", "vatAmount", "vatRate" ], "type": "object", "properties": { "code": { "type": "string", "description": "The invoice's identifier", "format": "uuid" }, "invoiceNumber": { "type": "string", "description": "The invoice number" }, "status": { "allOf": [ { "$ref": "#/components/schemas/BillingInvoiceStatus" } ], "description": "Where the invoice is in its payment" }, "billingDate": { "type": "string", "description": "The date the invoice covers usage up to", "format": "date-time" }, "dueDate": { "type": "string", "description": "When payment is due", "format": "date-time", "nullable": true }, "paidDate": { "type": "string", "description": "When it was paid", "format": "date-time", "nullable": true }, "paymentSubmittedDate": { "type": "string", "description": "When the payment was submitted to GoCardless", "format": "date-time", "nullable": true }, "paymentFailureReason": { "type": "string", "description": "Why the payment failed, when it did", "nullable": true }, "totalSubcontractors": { "type": "integer", "description": "The subcontractors charged for", "format": "int32" }, "subtotalAmount": { "type": "number", "description": "The charge before discount and VAT", "format": "double" }, "discountPercentage": { "type": "number", "description": "The discount applied, as a percentage of the subtotal", "format": "double" }, "netAmount": { "type": "number", "description": "The charge after discount, before VAT", "format": "double" }, "vatRate": { "type": "number", "description": "The VAT rate applied, as a percentage", "format": "double" }, "vatAmount": { "type": "number", "description": "The VAT", "format": "double" }, "totalAmount": { "type": "number", "description": "The total including VAT", "format": "double" }, "hasPdf": { "type": "boolean", "description": "Whether the invoice's PDF is available (GET /me/billing/invoices/{invoice}/pdf)" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoiceLineDto" }, "description": "The invoice's lines, one per tenant and tax month" }, "createdDate": { "type": "string", "description": "When the invoice was raised", "format": "date-time" } }, "additionalProperties": false, "description": "A CIS Manager invoice to the caller for their usage." }, "BillingInvoiceLineDto": { "required": [ "description", "isIncremental", "month", "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 charged on this line", "format": "int32" }, "isIncremental": { "type": "boolean", "description": "Whether the line charges only the subcontractors added since the month was last invoiced" }, "description": { "type": "string", "description": "The line as printed" } }, "additionalProperties": false, "description": "One line of a CIS Manager invoice: a tenant's subcontractors on one monthly return." }, "BillingInvoiceStatus": { "enum": [ "Draft", "PaymentPending", "Paid", "PaymentFailed", "Cancelled" ], "type": "string", "description": "Where a CIS Manager invoice is in its payment.", "example": "Draft" }, "BillingMandateDto": { "required": [ "isActive", "reference", "status" ], "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/MandateStatus" } ], "description": "The mandate's state" }, "reference": { "type": "string", "description": "GoCardless's mandate reference" }, "customerId": { "type": "string", "description": "GoCardless's customer identifier", "nullable": true }, "createdDate": { "type": "string", "description": "When the mandate was created", "format": "date-time", "nullable": true }, "isActive": { "type": "boolean", "description": "Whether payments can be collected: the mandate is active" }, "accountHolder": { "type": "string", "description": "The account holder's name, as GoCardless holds it; only for an active mandate", "nullable": true }, "accountHolderEmail": { "type": "string", "description": "The account holder's email address, as GoCardless holds it; only for an active mandate", "nullable": true } }, "additionalProperties": false, "description": "The caller's direct debit mandate, refreshed from GoCardless." }, "BillingProfileDto": { "required": [ "canAcceptPayments", "hasActiveMandate", "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 created, if one was", "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" }, "billingEmail": { "type": "string", "description": "The address invoice notifications go to; 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 }, "addressLine3": { "type": "string", "description": "Billing address, third line", "nullable": true }, "addressLine4": { "type": "string", "description": "Billing address, fourth line", "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 profile: the address their invoices are made out to and the state of their direct debit\nmandate. One per user, covering every tenant they own; empty until an address is set or a mandate is started." }, "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" ], "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": 56, "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." }, "CisSubcontractorType": { "enum": [ "SoleTrader", "Partnership", "Company", "Trust" ], "type": "string", "example": "SoleTrader" }, "CisTaxStatus": { "enum": [ "NetOfHigherDeduction", "NetOfStandardDeduction", "Gross" ], "type": "string", "example": "NetOfHigherDeduction" }, "CompleteMandateSetupRequest": { "required": [ "redirectFlowId", "sessionToken" ], "type": "object", "properties": { "redirectFlowId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The setup's redirect flow identifier, from the setup or from the success URL's redirect_flow_id" }, "sessionToken": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The session token the setup returned" } }, "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 = sharing details to send invoices (the viewer is the subcontractor), In = receiving them\n(the viewer is the contractor)" }, "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\n(and its CIS details when it is sharing them); on one the viewer initiated, the accepting tenant's name once\naccepted", "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. One tenant\ninitiates it for one of its contacts, giving the other party's email address; the other party accepts it by\ncreating (or naming) its own contact for the initiator. direction is relative to the viewer: Out means the\nviewer is the subcontractor sharing its CIS details to send invoices, In means the viewer is the contractor\nreceiving them." }, "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 tenant is sharing (a subcontractor initiating an Out connection); null otherwise", "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" }, "CreateConnectionRequest": { "required": [ "contact", "direction", "email" ], "type": "object", "properties": { "contact": { "minLength": 1, "type": "string", "description": "The tenant's contact for the other party (code)" }, "direction": { "allOf": [ { "$ref": "#/components/schemas/InvoiceDirection" } ], "description": "The tenant's side: Out to share its CIS details with a contractor (the contact is a customer), In to invite a\nsubcontractor (the contact is a supplier)" }, "email": { "maxLength": 150, "minLength": 0, "type": "string", "description": "The other party's email address, where the invitation is sent", "format": "email" } }, "additionalProperties": false, "description": "A new connection, initiated by the tenant for one of its 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": 150, "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": 150, "type": "string", "description": "Email address", "format": "email", "nullable": true }, "telephone": { "maxLength": 25, "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." }, "CreateHmrcCredentialsRequest": { "required": [ "password", "senderId", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The gateway user id" }, "password": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The gateway password" }, "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": "New shared credentials." }, "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 } }, "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." }, "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": 150, "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" } }, "additionalProperties": false, "description": "A new tenant, owned by the caller. Its email address and phone number start as the caller's." }, "DateField": { "enum": [ "Date", "DueDate", "PaidDate", "PaidTaxMonthEnding" ], "type": "string", "example": "Date" }, "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." }, "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." }, "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": 150, "minLength": 0, "type": "string", "description": "The agent's company name", "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." }, "HmrcCredentialsDto": { "required": [ "code", "createdDate", "displayName", "hasPassword", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "code": { "type": "string", "description": "The credentials' identifier (what a tenant's HMRC settings reference as sharedCredentialsId)", "format": "uuid" }, "displayName": { "type": "string", "description": "The agent's company (and id) or the sender id, for picking them" }, "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 credentials were created", "format": "date-time" }, "updatedDate": { "type": "string", "description": "When they were last changed", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "A set of HMRC gateway credentials the caller owns and can share across the tenants they manage. The password\nis never returned." }, "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 (their code on /me/hmrc-credentials)", "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" }, "officeNumber": { "type": "string", "description": "The HMRC office number (the first part of the PAYE reference)", "nullable": true }, "payeReference": { "type": "string", "description": "The employer PAYE reference (the second part)", "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": [ "redirectFlowId", "redirectUrl", "sessionToken" ], "type": "object", "properties": { "redirectFlowId": { "type": "string", "description": "GoCardless's identifier for the setup (its redirect flow); GoCardless also appends it to the success URL" }, "redirectUrl": { "type": "string", "description": "The GoCardless page to send the customer's browser to" }, "sessionToken": { "type": "string", "description": "The secret that proves the completing client started the setup; hold it (not in a URL) until completion" } }, "additionalProperties": false, "description": "A started direct debit setup: where to send the customer, and what the client must hold to complete it." }, "MandateStatus": { "enum": [ "NotStarted", "PendingCustomerApproval", "PendingSubmission", "Submitted", "Active", "Failed", "Cancelled", "Expired" ], "type": "string", "description": "The state of the caller's direct debit mandate with GoCardless.", "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\")" }, "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" } }, "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), Submitted (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 tenant's owner cannot submit returns just now (their billing: outstanding invoices with no direct\ndebit, or a block placed by CIS Manager), or null when they can. Set on GET; submit answers 402 with it.", "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" ], "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." }, "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." }, "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": {} }, "PublicSdcStatementDto": { "required": [ "code", "contactName", "hasLogo", "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" }, "hasLogo": { "type": "boolean", "description": "Whether the tenant has a logo, served at `/sdc-statements/{sdc}/logo`" } }, "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." }, "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." }, "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." }, "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." }, "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." }, "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" }, "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." }, "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": { "type": "string", "description": "Address line 1", "nullable": true }, "line2": { "type": "string", "description": "Address line 2", "nullable": true }, "line3": { "type": "string", "description": "Address line 3", "nullable": true } }, "additionalProperties": false, "description": "A tenant's postal address: three free-text lines, as HMRC's contractor record holds it." }, "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 } }, "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" } }, "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" } }, "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 } }, "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." }, "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 shared 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 }, "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": "The address invoice notifications go to; blank for 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": 100, "type": "string", "description": "Billing address, first line", "nullable": true }, "addressLine2": { "maxLength": 100, "type": "string", "description": "Billing address, second line", "nullable": true }, "addressLine3": { "maxLength": 100, "type": "string", "description": "Billing address, third line", "nullable": true }, "addressLine4": { "maxLength": 100, "type": "string", "description": "Billing address, fourth line", "nullable": true }, "postcode": { "maxLength": 20, "type": "string", "description": "Billing address postcode", "nullable": true }, "country": { "maxLength": 50, "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": 150, "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": 150, "type": "string", "description": "Email address", "format": "email", "nullable": true }, "telephone": { "maxLength": 25, "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." }, "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." }, "UpdateHmrcCredentialsRequest": { "required": [ "senderId", "senderType", "testInLive", "useTestGateway" ], "type": "object", "properties": { "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 100, "minLength": 0, "type": "string", "description": "The gateway user id" }, "password": { "maxLength": 200, "minLength": 0, "type": "string", "description": "The gateway password; null keeps the stored one", "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 shared credentials. The password is optional: omitted or null keeps the stored one." }, "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 /me/hmrc-credentials); required with useSharedCredentials", "format": "uuid", "nullable": true }, "senderType": { "allOf": [ { "$ref": "#/components/schemas/RtiSenderType" } ], "description": "Employer, agent or acting in capacity" }, "senderId": { "maxLength": 100, "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 }, "officeNumber": { "maxLength": 10, "minLength": 0, "type": "string", "description": "The HMRC office number", "nullable": true }, "payeReference": { "maxLength": 20, "minLength": 0, "type": "string", "description": "The employer PAYE reference", "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": { "required": [ "managesMultipleTenants" ], "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 }, "managesMultipleTenants": { "type": "boolean", "description": "Whether the user manages several tenants (shows the overview and multi-tenant features)" } }, "additionalProperties": false, "description": "A full replacement of the caller's editable profile fields." }, "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": 150, "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": 150, "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": 150, "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": 150, "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)." }, "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" } }, "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." } }, "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": "Billing", "description": "What CIS Manager charges the authenticated user, across every tenant they own (no tenant in the route): the billing profile (invoice address and mandate state), the direct debit mandate with its GoCardless setup (start a setup, send the customer to GoCardless, complete it), the invoices with their PDFs, and the usage not yet invoiced. Reads refresh the mandate and pending payments from GoCardless." }, { "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": "RemittanceAdvice", "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": "SdcStatements", "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": "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 = sharing CIS details to send invoices, In = receiving them). A tenant initiates a connection for one of its contacts and emails the other party; the other party accepts by setting its side (a contact 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. No module gate." }, { "name": "HmrcSettings", "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 the owner's shared credentials. Passwords are never returned; a PUT without one keeps the stored one. A test sends a dummy verification through the gateway." }, { "name": "HmrcCredentials", "description": "The caller's shareable HMRC gateway credentials, under /me: a user who manages several tenants keeps one set here and points each tenant's HMRC settings at it. Passwords are never returned." }, { "name": "EmailSettings", "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": "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." } ] }