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:
                - Virtual Office Subscription
            summary: Create New Virtual Office Subscription
            description: 'Creates a new virtual office subscription along with the
                customer details, based on the JSON document provided in the request
                body. The `members` array contains the customer company’s Ultimate
                Beneficial Owners (UBOs), who are required to complete KYC/AML
                onboarding. These are not Customer Portal Team Members and adding them
                does not create Customer Portal users or grant access to the
                application.


                `subscription.start_date` can be in the past, but cannot be changed once
                the subscription is created. `subscription.end_date` is ignored on
                create: to end a subscription, use the Stop Virtual Office Subscription
                endpoint. See https://docs.hoxtonmix.com/api/subscription-lifecycle.'
            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:
                - Virtual Office Subscription
            operationId: api_v1_subscription_read
            summary: Get a Virtual Office Subscription
            description:
                Retrieves the details of an existing virtual office subscription using
                the provided `external_id`. This endpoint returns information about the
                virtual office subscription, including customer details, product
                information, and company UBOs recorded as members for KYC/AML
                onboarding.
            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:
                - Virtual Office Subscription
            summary: Update Virtual Office Subscription
            description: Updates the details of an existing virtual office 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 with this endpoint.
                Attempting to change the `product_id` will result in a 400 error. To
                move a subscription between its monthly and yearly plan, use the Change
                Virtual Office Subscription Plan endpoint.
            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:
                - Virtual Office Subscription
            summary: Stop Virtual Office Subscription
            description:
                'Stops the current virtual office subscription. Until the specified
                `end_date`, post is handled and billing continues as normal. After it,
                no further mail is processed for this virtual office subscription.
                Backdated stops are not supported: `end_date` must be now or in the
                future. To reactivate a stopped subscription, use the Start Virtual
                Office Subscription endpoint. See
                https://docs.hoxtonmix.com/api/subscription-lifecycle.'
            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:
                      'When the subscription stops receiving service. Either a UTC
                      timestamp, now or in the future, in exactly the format
                      `YYYY-MM-DDTHH:MM:SSZ` (e.g. `2021-03-02T10:23:04Z`, with no
                      fractional seconds or timezone offset), or `END_OF_TERM` to stop
                      the subscription at the end of the current billing term (23:59:59
                      UTC on its next billing date). Any other format returns a 400.'
                  required: true
                  schema:
                      type: string
                      example: END_OF_TERM
                - name: cancellation_reason
                  in: path
                  description:
                      The reason for the customer cancelling the virtual office
                      subscription.
                  required: true
                  schema:
                      type: string
                      enum: ['Requested', 'Defaulted']
            responses:
                '200':
                    description: OK
                    content: {}
                '400':
                    description:
                        Bad request - `end_date` is not in a valid format,
                        `cancellation_reason` is not valid, or `END_OF_TERM` cannot be
                        worked out for the subscription's billing period.
                    content: {}
                '404':
                    description: The specified `external_id` could not be found.
                    content: {}
    /subscription/{external_id}/start:
        post:
            tags:
                - Virtual Office Subscription
            summary: Start Virtual Office Subscription
            description:
                Initiates the specified virtual office subscription. If the virtual
                office 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}/change-product:
        post:
            tags:
                - Virtual Office Subscription
            summary: Change Virtual Office Subscription Plan
            description: 'Moves a virtual office subscription between the monthly and
                yearly plan of the same product, for example from monthly to yearly. The
                subscription keeps its `external_id`, mail and KYC/AML checks, so the
                customer does not need to be cancelled and created again.


                The new product takes effect straight away, but the new price starts at
                the end of the period that has already been paid for. Nothing is
                credited or charged for the change itself. A yearly customer moving to
                monthly keeps the year already paid for, and monthly billing starts when
                it ends. See
                https://docs.hoxtonmix.com/api/subscription-lifecycle#changing-between-monthly-and-yearly.'
            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/ChangeProduct'
                required: true
            responses:
                '200':
                    description: OK - the updated subscription
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SubscriptionReadOnly'
                '400':
                    description:
                        Bad request - the subscription has been stopped or has a stop
                        scheduled, or the new `product_id` is the current product, is
                        not one of your products, is not the monthly or yearly plan of
                        the same product, or has no price on your pricing tiers.
                    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 the mail items associated with the specified subscription,
                newest first. The response is paginated: use the `page` and `page_size`
                query parameters to move through the results, or follow the `next` and
                `previous` links. See [Paging](/api/paging) for details.


                The `ai_metadata` object will only be populated with data if our Partner
                arrangement includes it. If not, its text fields are empty strings and
                its list fields are empty lists. `ai_metadata` is `null` when the item
                has no metadata.


                The `url`, `url_envelope_front` and `url_envelope_back` fields are
                signed links that expire 24 hours after the request. Request the list
                again to get fresh links. Each is `null` when that scan does not exist.


                Mail items can only be actioned, for example forwarded, within 30 days
                of being received.
            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: page
                  in: query
                  description: The page number to return, starting at 1.
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      default: 1
                - name: page_size
                  in: query
                  description: The number of mail items to return per page.
                  required: false
                  schema:
                      type: integer
                      minimum: 1
                      default: 10
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    count:
                                        type: integer
                                        example: 23
                                        description:
                                            The total number of mail items across all
                                            pages
                                    next:
                                        type: string
                                        format: uri
                                        nullable: true
                                        example: 'https://api.hoxtonmix.com/api/v2/subscription/sdv-12jlw-znew/mail?page=2'
                                        description:
                                            URL of the next page, or null on the last
                                            page
                                    previous:
                                        type: string
                                        format: uri
                                        nullable: true
                                        example: null
                                        description:
                                            URL of the previous page, or null on the
                                            first page
                                    results:
                                        type: array
                                        description:
                                            The mail items on this page, newest first
                                        items:
                                            $ref: '#/components/schemas/PartnerMailItem'
                '401':
                    description: Authentication credentials are missing or invalid
                    content: {}
                '403':
                    description:
                        No subscription with this external ID belongs to your account
                    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.


                **Mail expiry:** Mail items can only be forwarded within 30 days of
                being received. A request to forward an item that is older than 30 days
                is rejected with a 400 response.
            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 - the mail item may have already been forwarded, or
                        it is older than 30 days and can no longer be actioned.
                    content: {}
    /whatsapp-number/{external_id}:
        get:
            tags:
                - WhatsApp For Business
            summary: List WhatsApp For Business Numbers
            description:
                Retrieves all WhatsApp For Business mobile numbers assigned to the
                specified subscription. Cancelled numbers are included, with their
                status and end date.
            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: WhatsApp For Business numbers for the subscription
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/WhatsAppForBusinessNumber'
                '404':
                    description: The specified `external_id` could not be found
                    content: {}
    /whatsapp-number:
        post:
            tags:
                - WhatsApp For Business
            summary: Create WhatsApp For Business Number
            description: Provisions a new WhatsApp For Business mobile number for the
                customer with the given `external_id`. When no subscription exists for
                the `external_id`, the company and customer details are required and a
                new customer is created.


                Messages received on the number are delivered to your webhook as an
                `sms.received` event when you have a webhook configured, and are
                otherwise emailed to the `forwarding_email_address`. See
                https://docs.hoxtonmix.com/api/webhooks for details.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WhatsAppForBusinessNumberCreateRequest'
            responses:
                '200':
                    description: WhatsApp For Business number created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppForBusinessNumber'
                '400':
                    description:
                        Bad request - invalid parameters supplied. Also returned when no
                        subscription exists for the `external_id` and the company and
                        customer details were not provided, when the `product_id` is not
                        a WhatsApp For Business product assigned to your account, or
                        when your account does not handle KYC for its customers.
                    content: {}
    /whatsapp-number/{external_id}/{phone_number}:
        put:
            tags:
                - WhatsApp For Business
            summary: Update WhatsApp For Business Number
            description:
                Updates the nickname and/or forwarding email address for an existing
                WhatsApp For Business mobile number.
            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: phone_number
                  in: path
                  description:
                      The WhatsApp For Business mobile number to update, formatted in
                      E.164 notation (e.g. +447700900000).
                  required: true
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                nickname:
                                    type: string
                                    description:
                                        Friendly label used to identify the user of the
                                        WhatsApp For Business number.
                                    example: Derek Trotter
                                forwarding_email_address:
                                    type: string
                                    format: email
                                    description:
                                        Destination email address used to forward
                                        messages received on the number. Only used when
                                        you do not have a webhook configured - when you
                                        do, messages are delivered to your webhook as an
                                        `sms.received` event instead. See
                                        https://docs.hoxtonmix.com/api/webhooks.
                                    example: support@trotters.traders
            responses:
                '200':
                    description: WhatsApp For Business number updated successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WhatsAppForBusinessNumber'
                '400':
                    description:
                        Bad request - invalid parameters supplied. The request body must
                        contain at least one of `nickname` and
                        `forwarding_email_address`, and a released number cannot be
                        updated.
                    content: {}
                '404':
                    description:
                        The specified subscription or WhatsApp For Business number could
                        not be found
                    content: {}
        delete:
            tags:
                - WhatsApp For Business
            summary: Delete WhatsApp For Business Number
            description:
                Cancels an existing WhatsApp For Business mobile number at the end of
                its current billing period by setting its end date. The number keeps
                working until then, and cancelled numbers cannot be reactivated.
            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: phone_number
                  in: path
                  description:
                      The WhatsApp For Business mobile number to remove, formatted in
                      E.164 notation (e.g. +447700900000).
                  required: true
                  schema:
                      type: string
            responses:
                '200':
                    description: WhatsApp For Business number cancelled
                    content: {}
                '400':
                    description:
                        Bad request - the number is already cancelled or released.
                    content: {}
                '404':
                    description:
                        The specified subscription or WhatsApp For Business number could
                        not be found
                    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. It cannot be changed with the update endpoint. To
                        move between the monthly and yearly plan, use the Change Virtual
                        Office Subscription Plan endpoint.
                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
                            format: date-time
                            description:
                                'When the subscription started, as an ISO 8601
                                timestamp. It can be in the past to backdate the
                                subscription. It is saved exactly as sent and cannot be
                                changed later through the API: a different value sent on
                                an update is ignored. The grace period is counted from
                                this date, not from when the request was sent. See
                                https://docs.hoxtonmix.com/api/subscription-lifecycle.'
                            example: 2020-03-02T10:23:04Z
                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. It cannot be changed with the update endpoint. To
                        move between the monthly and yearly plan, use the Change Virtual
                        Office Subscription Plan endpoint.
                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
                            format: date-time
                            example: 2020-03-02T10:23:04Z
                        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'
        ChangeProduct:
            required:
                - product_id
            type: object
            properties:
                product_id:
                    type: integer
                    example: 2247
                    description:
                        The ID of the plan to move to. It must be the monthly or yearly
                        plan of the subscription's current product, and one of the
                        products provided to you by The Hoxton Mix Team.
        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 customer company's Ultimate Beneficial Owners (UBOs)
                who are required to complete KYC/AML onboarding. Member records are used
                for customer verification only; they are not Customer Portal Team
                Members and do not create Customer Portal users or grant application
                access."
        WhatsAppForBusinessNumberCreateRequest:
            required:
                - external_id
                - product_id
                - nickname
                - forwarding_email_address
            type: object
            properties:
                external_id:
                    type: string
                    description:
                        The unique external ID that your platform uses to reference the
                        account. This can be the same as a Virtual Office Subscription's
                        external_id.
                    example: 9XJJ02eZvKYlo2ClwuJ
                product_id:
                    type: integer
                    description:
                        The WhatsApp for Business product assigned to your account.
                    example: 2251
                nickname:
                    type: string
                    description:
                        Friendly label used to identify the user of the WhatsApp For
                        Business number.
                    example: Derek Trotter
                forwarding_email_address:
                    type: string
                    format: email
                    description:
                        Destination email address used to forward messages received on
                        the number. Only used when you do not have a webhook configured
                        - when you do, messages are delivered to your webhook as an
                        `sms.received` event instead. See
                        https://docs.hoxtonmix.com/api/webhooks.
                    example: support@trotters.traders
                company:
                    $ref: '#/components/schemas/Company'
                    description:
                        Required when the external_id does not exist yet, in which case
                        a new customer is created.
                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. Required when the external_id
                        does not exist yet, in which case a new customer is created.
        WhatsAppForBusinessNumber:
            required:
                - phone_number
                - nickname
                - forwarding_email_address
                - external_id
                - status
            type: object
            properties:
                phone_number:
                    type: string
                    description:
                        The WhatsApp For Business mobile number provisioned in E.164
                        format.
                    example: '+447700900123'
                nickname:
                    type: string
                    description:
                        Friendly label associated with the WhatsApp For Business number.
                    example: Customer Support Line
                forwarding_email_address:
                    type: string
                    format: email
                    description:
                        Destination email address used to forward messages received on
                        the number. Only used when you do not have a webhook configured
                        - when you do, messages are delivered to your webhook as an
                        `sms.received` event instead. See
                        https://docs.hoxtonmix.com/api/webhooks.
                    example: support@trotters.traders
                external_id:
                    type: string
                    description:
                        The unique external ID that your platform uses to reference the
                        account.
                    example: 9XJJ02eZvKYlo2ClwuJ
                status:
                    type: string
                    description:
                        Current status of the WhatsApp For Business number's
                        subscription.
                    example: ACTIVE
                end_date:
                    type: string
                    format: date-time
                    nullable: true
                    description:
                        Set when the number has been cancelled; the date at which it
                        stops working.
                    example: 2020-04-02T10:23:04.000Z
        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
        PartnerMailItem:
            type: object
            properties:
                id:
                    type: string
                    description:
                        The unique ID of the mail item. Use it as the `item_id` when
                        forwarding the item.
                    example: '1296480'
                event:
                    type: string
                    description:
                        The event name, matching the `mail.scanned` webhook payload.
                        Always `mail.scanned`.
                    enum:
                        - mail.scanned
                    example: mail.scanned
                external_id:
                    type: string
                    description:
                        The unique external ID that your platform uses to reference the
                        account.
                    example: sdv-12jlw-znew
                url:
                    type: string
                    format: uri
                    nullable: true
                    description:
                        Signed link to the scanned contents. Expires 24 hours after the
                        request. Null when the item has no content scan.
                    example: 'https://hoxtonmix-scans-production.s3.amazonaws.com/29iheg8ht80qy22tgiwh0wougher0'
                url_envelope_front:
                    type: string
                    format: uri
                    nullable: true
                    description:
                        Signed link to the scan of the front of the envelope. Expires 24
                        hours after the request. Null when there is no front envelope
                        scan.
                    example: 'https://hoxtonmix-scans-production.s3.amazonaws.com/oaeg20ha34pghowegowiehg0'
                url_envelope_back:
                    type: string
                    format: uri
                    nullable: true
                    description:
                        Signed link to the scan of the back of the envelope. Expires 24
                        hours after the request. Null when there is no back envelope
                        scan.
                    example: 'https://hoxtonmix-scans-production.s3.amazonaws.com/weg203tajaerahgshrauhgr'
                file_name:
                    type: string
                    nullable: true
                    description:
                        File name of the scanned contents. Null when the item has no
                        content scan.
                    example: 'the_a_team_limited_1296480.pdf'
                created_at:
                    type: string
                    format: date-time
                    description: Timestamp when the mail item was created
                    example: '2023-05-15T14:30:00Z'
                ai_metadata:
                    type: object
                    nullable: true
                    description:
                        Details extracted from the scan. Only populated if your Partner
                        arrangement includes AI metadata; otherwise the text fields are
                        empty strings and the list fields are empty lists. Null when the
                        item has no metadata.
                    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
                            description:
                                Important data points extracted from the document. An
                                empty list if your Partner arrangement does not include
                                AI metadata.
                            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',
                                    },
                                ]
    securitySchemes:
        api_key:
            type: apiKey
            in: header
            name: Authorization

x-original-swagger-version: '2.0'
