openapi: 3.0.1 info: title: The Hoxton Mix Partner API v2 description: Authorisation is provided through an API token, which can be generated by following the instructions at https://docs.hoxtonmix.com/api/managing-api-keys. This token should be included as the username in the Basic Auth parameter of the request. No password is required for this authentication scheme. For further assistance, please contact support@hoxtonmix.com. version: 2.0.0 servers: - url: https://api.hoxtonmix.com/api/v2 security: - api_key: [] paths: /subscription: post: tags: - Subscription summary: Create New Subscription description: 'Creates a new subscription along with the customer details, based on the JSON document provided in the request body.' requestBody: content: application/json: schema: $ref: '#/components/schemas/Subscription' required: false responses: '200': description: OK content: {} '400': description: Bad request - the request body is invalid content: {} x-codegen-request-body-name: subscription /subscription/{external_id}: get: tags: - Subscription operationId: api_v1_subscription_read summary: Get a Subscription description: Retrieves the details of an existing subscription using the provided `external_id`. This endpoint returns information about the subscription, including customer details, product information, and company members. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SubscriptionReadOnly' '404': description: The specified `external_id` could not be found. content: {} post: tags: - Subscription summary: Update Subscription description: Updates the details of an existing subscription. This endpoint can be used for updates such as changes to the company name or directors associated with the account. Note that the `product_id` cannot be updated. Attempting to change the `product_id` will result in a 400 error. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Subscription' required: false responses: '200': description: OK content: {} '400': description: Bad request - the request body is invalid content: {} '404': description: The specified `external_id` could not be found. content: {} x-codegen-request-body-name: subscription /subscription/{external_id}/stop/{end_date}/{cancellation_reason}: post: tags: - Subscription summary: Stop Subscription description: Stops the current subscription. After the specified `end_date`, no further mail will be forwarded to the customer under this subscription. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string - name: end_date in: path description: The timestamp declaring the point in time that the account is to stop receiving service. E.g. 2021-03-02T10:23:04Z. Note that after this date we will stop processing mail for this subscription. You can also supply `end_date=END_OF_TERM` to stop the subscription at the end of the current term. required: true schema: type: string - name: cancellation_reason in: path description: The reason for the customer cancelling the subscription. Can be either "Requested" or "Defaulted" required: true schema: type: string responses: '200': description: OK content: {} '400': description: The specified `external_id` could not be found. content: {} /subscription/{external_id}/start: post: tags: - Subscription summary: Start Subscription description: Initiates the specified subscription. If the subscription is currently in a stopped state, this endpoint will resume it. If the subscription is already active, no action will be taken. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string responses: '200': description: OK content: {} '404': description: The specified `external_id` could not be found. content: {} /subscription/{external_id}/refused: post: tags: - Account summary: Account Refused by Partner description: This endpoint cancels a subscription immediately when triggered. If a subscription is refused by the partner—for example, due to the business being closed, blocked, or failing KYC checks—the subscription will be automatically cancelled with a current timestamp, ending service for the customer at that moment. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string responses: '200': description: OK content: {} '404': description: The specified `external_id` could not be found. content: {} /subscription/{external_id}/certification-letter: get: tags: - Account summary: Download Certification Letter description: >- Downloads a PDF letter of certification for the subscription associated with the provided `external_id`. parameters: - name: external_id in: path description: >- The unique external ID that your platform uses to reference the account. required: true schema: type: string responses: '200': description: OK - PDF letter of certification content: application/pdf: schema: type: string format: binary '404': description: The specified `external_id` could not be found. content: {} /subscription/{external_id}/mail: get: tags: - Mail summary: List Mail Items description: Retrieves a list of mail items associated with the specified subscription. The `ai_metadata` object will only be populated with data if our Partner arrangement includes it. If not, the fields will be empty. parameters: - name: external_id in: path description: The unique external ID that your platform uses to reference the account. required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: type: object properties: id: type: String example: 1296480 external_id: type: String example: sdv-12jlw-znew url: type: string example: 'https://s3.hoxtonmix.com/29iheg8ht80qy22tgiwh0wougher0' url_envelope_front: type: string example: 'https://s3.hoxtonmix.com/oaeg20ha34pghowegowiehg0' url_envelope_back: type: string example: 'https://s3.hoxtonmix.com/weg203tajaerahgshrauhgr' file_name: type: string example: 'the_a_team_limited_1296480.pdf' created_at: type: string format: date-time example: '2023-05-15T14:30:00Z' description: 'Timestamp when the mail item was created' ai_metadata: type: object properties: sender_name: type: string example: 'Trotters Independent Traders' description: 'Detected sender organization or individual' document_title: type: string example: 'Statement of Account' description: 'Title of the document' reference_number: type: string example: 'Statement-679229' description: 'The main reference number found in the document' summary: type: string example: 'Monthly service statement for April 2025' description: 'A brief summary of the document contents' industry: type: string example: 'Professional Services' description: 'Detected industry classification' categories: type: array items: type: string example: [ 'Financial', 'Official / Legal', ] description: 'Primary and secondary categories' sub_categories: type: array items: type: string example: [ 'Regulatory-Communication', 'Legal-Notice', ] description: 'Relevant sub_categories' key_information: type: array items: type: object properties: key: type: string value: type: string example: [ { 'key': 'Our Reference', 'value': '679229', }, { 'key': 'Date of Issue', 'value': '2025-03-08', }, { 'key': 'Invoice Date', 'value': '03/02/2025', }, { 'key': 'Invoice Number', 'value': '1856551', }, { 'key': 'Total Amount', 'value': '£180.00', }, { 'key': 'Contact Email', 'value': 'delboy@trotters.traders', }, { 'key': 'Contact Phone', 'value': '+44 (0) 217 666 6666', }, ] description: 'Important data points extracted from the document' '404': description: The specified subscription could not be found content: {} /subscription/{external_id}/mail/{item_id}/forward: post: tags: - Mail summary: Forward Mail Item description: Requests a specific mail item to be physically forwarded to the customer's address. The `item_id` is obtained from webhook notifications when mail is scanned. **Important:** This endpoint is disabled by default. To enable mail forwarding via the API, please contact the Hoxton Mix team to have it enabled in the ops dashboard. **Billing:** When mail forwarding is enabled, the Partner will be billed for all forwarding charges, not the end customer. Charges will be invoiced to the partner after the mail item has been forwarded. parameters: - name: item_id in: path description: The unique postal item ID received from the webhook notification required: true schema: type: string requestBody: content: application/json: schema: type: object properties: forwarding_address: $ref: '#/components/schemas/Address' description: Address to forward this specific mail item to. responses: '200': description: Mail forwarding request accepted content: {} '404': description: The specified mail item could not be found content: {} '400': description: Bad request - mail item may have already been forwarded content: {} components: schemas: Subscription: required: - company - customer - external_id - shipping_address - subscription type: object properties: external_id: type: string description: The unique external ID that your platform uses to reference the account. example: 9XJJ02eZvKYlo2ClwuJ product_id: type: integer example: 2246 description: This ID will be provided to you by The Hoxton Mix Team when you are onboarded. This can only be set once at the time of creation and cannot be updated. customer: required: - email_address - first_name - last_name type: object properties: first_name: type: string example: Derek middle_name: type: string example: Edward last_name: type: string example: Trotter email_address: type: string example: delboy@hoxtonmix.com description: The lead customer of the company. shipping_address: $ref: '#/components/schemas/Address' description: The address where forwarded mail is to be sent. subscription: required: - start_date type: object properties: start_date: type: string example: 2020-03-02T10:23:04.000Z company: $ref: '#/components/schemas/Company' members: type: array items: $ref: '#/components/schemas/Member' SubscriptionReadOnly: type: object properties: external_id: type: string description: The unique external ID that your platform uses to reference the account. example: 9XJJ02eZvKYlo2ClwuJ product_id: type: integer example: 2246 description: This ID will be provided to you by The Hoxton Mix Team when you are onboarded. This can only be set once at the time of creation and cannot be updated. customer: type: object properties: first_name: type: string example: Derek middle_name: type: string example: Edward last_name: type: string example: Trotter email_address: type: string example: delboy@hoxtonmix.com description: The lead customer of the company. shipping_address: $ref: '#/components/schemas/Address' description: The address where forwarded mail is to be sent. subscription: type: object properties: start_date: type: string example: 2020-03-02T10:23:04.000Z status: type: string description: 'Current status of the subscription. `ACTIVE` means the subscription is in good standing. `CANCELLED` means the subscription has been terminated. `NO_ID` means identity verification is incomplete. `PENDING_CANCELLATION` indicates the subscription is scheduled to be cancelled.' enum: ['CANCELLED', 'NO_ID', 'ACTIVE', 'PENDING_CANCELLATION'] subscription_state: type: string enum: ['INACTIVE', 'ACTIVE', 'PENDING_INACTIVATION'] deprecated: true company: $ref: '#/components/schemas/Company' members: type: array items: $ref: '#/components/schemas/Member' Company: required: - name - trading_name - organisation_type type: object properties: name: type: string example: Delboy and Rodney Ltd trading_name: type: string example: Trotters Independent Traders limited_company_number: type: string example: '4357445' description: UK Companies House number abn_number: type: string example: '88682116112' description: Australian Business Number acn_number: type: string example: '682116113' description: Australian Company Number organisation_type: type: integer description: 'Organisation type code: `1` - Limited company (LTD, LP, LLP, LLC, Corp), `3` - Individual / sole trader, `9` - Unincorporated / not yet registered, `10` - Charity / non-profit, `12` - Trust, foundation or fund, `13` - Association, club or society' example: 1 telephone_number: type: string example: '02037656677' Member: required: - first_name - last_name type: object properties: first_name: type: string example: Derek middle_name: type: string example: Edward last_name: type: string example: Trotter phone_number: type: string example: '02078383838' date_of_birth: type: string example: 1980-03-02T10:23:04.000Z email_address: type: string format: email description: The member's email address, used to invite them to complete KYC identity verification. If omitted, the subscription's customer email address is used instead. example: rodney@hoxtonmix.com enable_kyc_notifications: type: boolean default: true description: Controls the member's KYC notification stream when creating a subscription. When `true` (the default), an invite to complete KYC is sent to the member immediately and reminder emails are enabled. When `false`, both the immediate invite and reminders are suppressed. kyc_checks_passed: type: boolean description: Read-only; returned when retrieving a subscription. `true` only when the member's ID, proof-of-address and AML checks have all passed. url: type: string description: Read-only; returned when retrieving a subscription, for verification-flow members only (partners whose customers complete KYC themselves). The public portal link the member uses to complete verification. Absent for partners who handle their own KYC. example: https://verify.hoxtonmix.com/abc123 description: "Members are the people associated with the company who may be required to complete KYC identity verification — any Persons\ \ of Significant Control (PSCs), Directors or Ultimate beneficial\ \ owners (UBO)." Address: required: - shipping_address_line_1 - shipping_address_city - shipping_address_postcode - shipping_address_country type: object description: A physical mailing address properties: shipping_address_line_1: type: string example: Trotters Independent Traders Ltd shipping_address_line_2: type: string example: 'Flat 23, Nelson Mandela House' shipping_address_line_3: type: string example: Dockside Estate shipping_address_city: type: string example: London shipping_address_postcode: type: string example: SE124BR shipping_address_state: type: string example: England shipping_address_country: type: string description: 2-letter ISO 3166 alpha-2 country code. example: GB securitySchemes: api_key: type: apiKey in: header name: Authorization x-original-swagger-version: '2.0'