> ## Documentation Index
> Fetch the complete documentation index at: https://developer.finogates.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail a Document to a Saved Payee

> Mail a document **you supply** to a payee you registered earlier. Name the recipient with `payee_id` and we look the address up, so you do not re-send it on every mailing; `address_id` picks between several. Not a payment: no wallet is named or debited. Your own document backs the face value and only the mailing fee is billed, on your monthly invoice.

This is a `multipart/form-data` request: `document` (and optional `attachments`) are file parts, and `payload` is this JSON, encoded as a string, alongside them.

Sample `payload`:
```json
{
  "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
  "payee_id": "c4b5a6d7-e8f9-0123-4567-890abcdef012",
  "address_id": "d5c6b7e8-f9a0-1234-5678-9abcdef01234",
  "mail_type": "usps_ground_advantage",
  "currency": "USD",
  "description": "Q3 invoice packet",
  "invoice_number": "INV-10432",
  "idempotency_key": "doc-mail-2026-08-24-001"
}
```



## OpenAPI

````yaml POST /v1/platform/payments/document-mailing
openapi: 3.1.0
info:
  title: Finogate Platform API v1
  version: 0.1.0
servers:
  - url: https://api-sandbox.finogates.com
    description: Sandbox
  - url: https://api.finogates.com
    description: Production
security: []
tags:
  - name: auth
  - name: users
  - name: payees
  - name: verification
  - name: bank accounts
  - name: card processing
  - name: digital-assets
  - name: international
  - name: fees
  - name: onboarding
  - name: pending-applications
  - name: wallets
  - name: payments
  - name: document mailing
  - name: merchant onboarding
  - name: catalog
  - name: webhooks
  - name: screening
  - name: Platform - File Scanning
  - name: phone-numbers
  - name: sms
  - name: calls
  - name: listings
  - name: Card Transfers
  - name: embed-tokens
paths:
  /v1/platform/payments/document-mailing:
    post:
      tags:
        - document mailing
      summary: Mail a Document to a Saved Payee
      description: >-
        Mail a document **you supply** to a payee you registered earlier. Name
        the recipient with `payee_id` and we look the address up, so you do not
        re-send it on every mailing; `address_id` picks between several. Not a
        payment: no wallet is named or debited. Your own document backs the face
        value and only the mailing fee is billed, on your monthly invoice.


        This is a `multipart/form-data` request: `document` (and optional
        `attachments`) are file parts, and `payload` is this JSON, encoded as a
        string, alongside them.


        Sample `payload`:

        ```json

        {
          "user_id": "b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4",
          "payee_id": "c4b5a6d7-e8f9-0123-4567-890abcdef012",
          "address_id": "d5c6b7e8-f9a0-1234-5678-9abcdef01234",
          "mail_type": "usps_ground_advantage",
          "currency": "USD",
          "description": "Q3 invoice packet",
          "invoice_number": "INV-10432",
          "idempotency_key": "doc-mail-2026-08-24-001"
        }

        ```
      operationId: create_document_shipping_v1_platform_payments_document_mailing_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_document_shipping_v1_platform_payments_document_mailing_post
      responses:
        '201':
          description: The mailed document, straight after create.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_DocumentShippingRead_'
              example:
                status_code: 201
                data:
                  document_shipping_id: 9b1e6c2a-4f3d-4a8b-9c7e-2d5f1a6b3c4d
                  payment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  status: pending
                  mail_type: usps_ground_advantage
                  amount: 0
                  fee_amount: 12.35
                  total_amount: 12.35
                  currency: USD
                  recipient:
                    name: Dana Reed
                    phone: '+13035550188'
                    line_1: 456 Oak Ave
                    line_2: Suite 200
                    city: Denver
                    state: CO
                    zip: '80202'
                    country: US
                  description: Q3 invoice packet
                  invoice_number: INV-10432
                  intent_status: pending_review
                  created_at: '2026-08-24T14:30:00Z'
                  updated_at: '2026-08-24T14:30:00Z'
                  attachments:
                    - id: 7c4d2e1a-8b3f-4d6c-9a1e-5f2b3c4d5e6f
                      file_name: remittance_advice.pdf
                      page_count: 2
                      byte_size: 184320
                      ordinal: 0
                  attachment_page_count: 2
                  attachment_fee: 0.5
                  document_page_count: 10
                  document_fee: 4.9
                  shipping_fee: 6.95
                  carrier_cost: 5.2
                  markup: 1.75
                query_generated_time: 1712847600000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    Body_create_document_shipping_v1_platform_payments_document_mailing_post:
      properties:
        payload:
          type: string
          title: Payload
          description: JSON-encoded DocumentShippingCreate.
        document:
          type: string
          format: binary
          title: Document
          description: The document itself, as a PDF (<= 7MB).
        attachments:
          items:
            type: string
            format: binary
          type: array
          title: Attachments
          description: Extra PDFs mailed with the document. Charged per page.
          default: []
      type: object
      required:
        - payload
        - document
      title: Body_create_document_shipping_v1_platform_payments_document_mailing_post
    CommonResponse_DocumentShippingRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/DocumentShippingRead'
          description: Payload or error details.
        query_generated_time:
          type: integer
          title: Query Generated Time
          description: >-
            UTC timestamp (milliseconds since epoch) when response was
            generated.
      type: object
      required:
        - status_code
        - data
        - query_generated_time
      title: CommonResponse[DocumentShippingRead]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DocumentShippingRead:
      properties:
        document_shipping_id:
          type: string
          format: uuid
          title: Document Shipping Id
          examples:
            - 9b1e6c2a-4f3d-4a8b-9c7e-2d5f1a6b3c4d
        payment_id:
          type: string
          format: uuid
          title: Payment Id
          examples:
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          title: Status
          examples:
            - mailed
        mail_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mail Type
          examples:
            - usps_ground_advantage
        amount:
          type: number
          title: Amount
          examples:
            - 0
        fee_amount:
          type: number
          title: Fee Amount
          default: 0
          examples:
            - 8.45
        total_amount:
          type: number
          title: Total Amount
          examples:
            - 8.45
        currency:
          type: string
          title: Currency
          examples:
            - USD
        recipient:
          $ref: '#/components/schemas/DocumentShippingRecipient'
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          examples:
            - Q3 invoice packet
        invoice_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Number
          examples:
            - INV-10432
        intent_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent Status
          examples:
            - succeeded
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        attachments:
          items:
            $ref: '#/components/schemas/DocumentMailingAttachmentRead'
          type: array
          title: Attachments
        attachment_page_count:
          type: integer
          title: Attachment Page Count
          default: 0
          examples:
            - 3
        attachment_fee:
          type: number
          title: Attachment Fee
          default: 0
          examples:
            - 0.75
        document_page_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Document Page Count
          examples:
            - 10
        document_fee:
          anyOf:
            - type: number
            - type: 'null'
          title: Document Fee
          examples:
            - 4.9
        shipping_fee:
          anyOf:
            - type: number
            - type: 'null'
          title: Shipping Fee
          examples:
            - 6.2
        carrier_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Carrier Cost
          examples:
            - 4.5
        markup:
          anyOf:
            - type: number
            - type: 'null'
          title: Markup
          examples:
            - 1.7
        tracking:
          anyOf:
            - $ref: '#/components/schemas/DocumentShippingTrackingSummary'
            - type: 'null'
      type: object
      required:
        - document_shipping_id
        - payment_id
        - status
        - amount
        - total_amount
        - currency
        - recipient
      title: DocumentShippingRead
      description: >-
        A document-shipping's current state (sidecar detail over the payment
        intent).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    DocumentShippingRecipient:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          examples:
            - Jane Smith
        phone:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          title: Phone
          examples:
            - '+12125550123'
        line_1:
          type: string
          maxLength: 255
          minLength: 1
          title: Line 1
          examples:
            - 123 Main St
        line_2:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Line 2
          examples:
            - Apt 4B
        city:
          type: string
          maxLength: 120
          minLength: 1
          title: City
          examples:
            - Austin
        state:
          type: string
          maxLength: 120
          minLength: 1
          title: State
          examples:
            - TX
        zip:
          type: string
          maxLength: 20
          minLength: 1
          title: Zip
          examples:
            - '78701'
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          default: US
          examples:
            - US
      type: object
      required:
        - name
        - line_1
        - city
        - state
        - zip
      title: DocumentShippingRecipient
      description: The postal address the physical check is mailed to.
    DocumentMailingAttachmentRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          examples:
            - 7c4d2e1a-8b3f-4d6c-9a1e-5f2b3c4d5e6f
        file_name:
          type: string
          title: File Name
          examples:
            - remittance_advice.pdf
        page_count:
          type: integer
          title: Page Count
          default: 1
          examples:
            - 2
        byte_size:
          type: integer
          title: Byte Size
          default: 0
          examples:
            - 184320
        ordinal:
          type: integer
          title: Ordinal
          default: 0
          examples:
            - 0
      type: object
      required:
        - id
        - file_name
      title: DocumentMailingAttachmentRead
      description: One PDF mailed alongside the check.
    DocumentShippingTrackingSummary:
      properties:
        trackable:
          type: boolean
          title: Trackable
          description: >-
            Whether this shipping service produces a tracking barcode at all.
            False for letter services, which carry a postage indicia instead —
            there is no number to follow and there never will be, so absent
            tracking on one of those is not a fault.
        tracking_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Tracking Number
        carrier:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier
          description: Carrier key.
          examples:
            - fedex
        carrier_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier Label
          description: Carrier name, for display.
          examples:
            - FedEx
        service:
          anyOf:
            - type: string
            - type: 'null'
          title: Service
          description: The shipping service bought.
          examples:
            - FedEx Standard Overnight
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: >-
            Current delivery stage, taken from the most recent scan — not the
            furthest stage reached. A parcel that hit an exception after going
            out for delivery reads `exception`, because that is what is true
            now. Null when no scans have been recorded yet.
          examples:
            - out_for_delivery
        status_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Label
          description: Display form of `status`.
          examples:
            - Out for delivery
        shipped_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Shipped At
          description: When the shipping label was purchased.
        estimated_delivery_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Estimated Delivery At
          description: >-
            The carrier's own delivery estimate, not a commitment from us.
            Present it as the carrier's estimate wherever it is shown.
        delivered_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Delivered At
          description: >-
            When the carrier confirmed delivery. Delivery means the envelope
            reached the address — not that its contents were acted on.
        delivered_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Delivered To
          description: >-
            Who the carrier recorded as accepting the parcel. Null until
            delivered, and on services that capture no signature — most of them
            — so its absence is never evidence of a problem.
          examples:
            - J.SMITH
        synced_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Synced At
          description: >-
            When we last successfully read this shipment's status from the
            carrier. Show it, so how fresh the page is stays visible rather than
            assumed.
        carrier_tracking_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier Tracking Url
          description: The carrier's own tracking page for this shipment.
      type: object
      required:
        - trackable
      title: DocumentShippingTrackingSummary
      description: |-
        Where a shipment is, without the scan list.

        Nested into shipment detail and list responses so a caller rendering a
        status column never has to fetch the full timeline per row.
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````