1Fort ascend (v2) API

openapi: 3.2.0
info:
  title: 1Fort API Documentation ascend (v2) ascend (v2) API
  description: '# 1Fort API


    REST API for the 1Fort insurance platform. This document is the authoritative

    map of the API surface; endpoints are grouped in the sidebar by **app** and

    **version**, and large apps are split into per-resource sub-groups.


    ## Authentication


    Almost every endpoint requires a **JWT access token**. Send it in the

    `Authorization` header as either `Bearer <token>` or `JWT <token>`. Tokens may

    also be presented as an HTTP-only cookie. Endpoints documented with no security

    requirement are intentionally public (for example sign-in, OTP and storefront

    endpoints).


    ## Multi-tenancy


    Resources are scoped to a tenant. Nested routes carry the owning resource id in

    the path (for example `/v2/broker/{business_pk}/applications`); a token is only

    authorised for the businesses its user may access. Object-level permissions are

    enforced per endpoint.


    ## Versioning


    `v2` endpoints live under `/apis/v2/...` and are the current surface. `v1`

    endpoints remain documented for compatibility. Endpoints marked **deprecated**

    are scheduled for removal; prefer the documented replacement.

    '
  termsOfService: https://www.1fort.com/
  license:
    name: Privately owned
  version: v1
servers:
- url: https://api.1fort.com/apis/
security:
- Bearer: []
tags:
- name: ascend (v2)
  x-displayName: Ascend (v2)
  description: '**Deprecated.** Legacy Ascend billing/payments; use the Billing (v2) endpoints instead.


    **Access:** requires a JWT access token.'
paths:
  /v2/ascend/payments:
    parameters: []
    get:
      operationId: v2_ascend_payments_list
      summary: Return a list of payments with summary data and applied filters.
      description: ".. deprecated::\n    Prefer ``GET /apis/v2/billing/payments`` (insurance invoice backed).\n    This Ascend program list remains for legacy transition only."
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: A search term.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      deprecated: true
  /v2/ascend/payments/csv:
    parameters: []
    get:
      operationId: v2_ascend_payments_export_csv
      description: 'Export payments to CSV format.

        Returns all filtered payments without pagination (same filters as the list view).'
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: A search term.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            '*/*':
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GenericError'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      summary: Export csv
      deprecated: true
  /v2/ascend/payments/filter-options:
    parameters: []
    get:
      operationId: v2_ascend_payments_filter_options
      description: 'Get available filter options for frontend dropdowns.

        Returns unique values for each filterable field.

        Restricted to broker users and maintainer users via OrPermissions.


        Admin and maintainer users see agency-wide filter options, while member users see only options for data they can access.'
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: A search term.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: The initial index from which to return the results.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - count
                - results
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      summary: Filter options
      deprecated: true
  /v2/ascend/payments/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: v2_ascend_payments_read
      description: 'ViewSet for retrieving payment data from Ascend.

        Provides payment information including premium amounts, due dates,

        broker information, and carrier details.


        Supports filtering by:

        - insured: Filter by insured ID (dropdown selection)

        - quote_status: Filter by quote status (exact match)

        - payment_status: Filter by program status (exact match)

        - primary_agent: Filter by primary agent (team member) BrokerUser ID - supports multi-select with comma-separated BrokerUser IDs (e.g., "123,456,789")

        - status: Filter by program status (exact match) - alias for payment_status

        - carrier: Filter by carrier ID or identifier (partial match)

        - coverage: Filter by coverage type ID or identifier (partial match)


        Supports general search across:

        - insured_name, broker_name, producer_name, carrier_name, coverage_type_name

        Use ?search=term to search across multiple name fields simultaneously'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDetail'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '404':
          description: Object does not exist or caller has insufficient permissions to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIException'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      summary: Retrieve Payment
      deprecated: true
  /v2/ascend/payments/{id}/billables/{billable_id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    - name: billable_id
      in: path
      required: true
      schema:
        type: string
    patch:
      operationId: v2_ascend_payments_update_billable
      description: 'Update a billable (policy) for this payment. Only allowed when not purchased.

        PATCHes the billable in Ascend and syncs the local DB from the response.

        PATCH /apis/v2/ascend/payments/{id}/billables/{billable_id}'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '404':
          description: Object does not exist or caller has insufficient permissions to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIException'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      summary: Update billable
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
        required: true
  /v2/ascend/payments/{id}/due-date:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    patch:
      operationId: v2_ascend_payments_update_due_date
      summary: Update program due date.
      description: 'Saves the due_date to the local database immediately for instant UI feedback,

        then schedules an async task to sync the change to Ascend.


        PATCH /apis/v2/ascend/payments/{id}/due-date'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: Authentication credentials were invalid, absent or insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        '404':
          description: Object does not exist or caller has insufficient permissions to access it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIException'
        '500':
          description: Internal server error.
      tags:
      - ascend (v2)
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
        required: true
components:
  schemas:
    APIException:
      title: Generic API Error
      required:
      - detail
      type: object
      properties:
        detail:
          description: Error details
          type: string
    BillableDetail:
      required:
      - billable_identifier
      - effective_date
      - expiration_date
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        ascend_id:
          title: Ascend id
          type:
          - string
          - 'null'
          maxLength: 255
        billable_type:
          title: Billable type
          type: string
          enum:
          - quote
          - endorsement
        billable_identifier:
          title: Billable identifier
          type: string
          maxLength: 255
          minLength: 1
        policy_number:
          title: Policy number
          type:
          - string
          - 'null'
          maxLength: 255
        effective_date:
          title: Effective date
          type: string
          format: date
        expiration_date:
          title: Expiration date
          type: string
          format: date
        premium:
          title: Premium
          type: string
          readOnly: true
        agency_fees:
          title: Agency fees
          type: string
          readOnly: true
        broker_fee:
          title: Broker fee
          type: string
          readOnly: true
        policy_fee:
          title: Policy fee
          type: string
          readOnly: true
        other_fees:
          title: Other fees
          type: string
          readOnly: true
        taxes_and_fees:
          title: Taxes and fees
          type: string
          readOnly: true
        surplus_lines_tax:
          title: Surplus lines tax
          type: string
          readOnly: true
        total_fees:
          title: Total fees
          type: string
          readOnly: true
        description:
          title: Description
          type:
          - string
          - 'null'
        min_earned_rate:
          title: Min earned rate
          description: Minimum earned premium rate as a decimal (e.g., 0.25 for 25%)
          type:
          - number
          - 'null'
        carrier_detail:
          title: Carrier detail
          type: string
          readOnly: true
        coverage_type_detail:
          title: Coverage type detail
          type: string
          readOnly: true
        wholesaler_detail:
          title: Wholesaler detail
          type: string
          readOnly: true
        quote_detail:
          title: Quote detail
          type: string
          readOnly: true
    Payment:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        insured:
          title: Insured
          type: string
          readOnly: true
        payment_status:
          title: Payment status
          type: string
          readOnly: true
        quote_status:
          title: Quote status
          type: string
          readOnly: true
        quote:
          title: Quote
          type: string
          readOnly: true
        total:
          title: Total
          type: string
          readOnly: true
        due_date:
          title: Due date
          type: string
          readOnly: true
        broker:
          title: Broker
          type: string
          readOnly: true
        producer:
          title: Producer
          type: string
          readOnly: true
        all_agents:
          title: All agents
          type: string
          readOnly: true
        carrier:
          title: Carrier
          type: string
          readOnly: true
        coverage_type:
          title: Coverage type
          type: string
          readOnly: true
        actions:
          title: Actions
          type: string
          readOnly: true
    GenericError:
      title: Generic API Error
      required:
      - detail
      type: object
      properties:
        detail:
          description: Error details
          type: string
    LoanDetail:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        ascend_id:
          title: Ascend id
          type:
          - string
          - 'null'
          maxLength: 255
        status:
          title: Status
          type:
          - string
          - 'null'
          enum:
          - bound
          - canceled
          - completed
          - pending_bind
          - pending_cancel
          - ready
          - missing_terms
        status_display:
          title: Status display
          type: string
          readOnly: true
        allowed_late_days:
          title: Allowed late days
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: 0
        amount_financed:
          title: Amount financed
          type: string
          readOnly: true
        apr:
          title: Apr
          type:
          - string
          - 'null'
          format: decimal
        downpayment:
          title: Downpayment
          type: string
          readOnly: true
        late_charge:
          title: Late charge
          type: string
          readOnly: true
        number_of_payments:
          title: Number of payments
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: 0
        term_payment:
          title: Term payment
          type: string
          readOnly: true
        is_active:
          title: Is active
          type: boolean
        completed_disclosure_url:
          title: Completed disclosure url
          type:
          - string
          - 'null'
          format: uri
          maxLength: 2048
        ascend_created_at:
          title: Ascend created at
          type:
          - string
          - 'null'
          format: date-time
        ascend_updated_at:
          title: Ascend updated at
          type:
          - string
          - 'null'
          format: date-time
    ValidationError:
      title: Validation Error
      type: object
      properties:
        non_field_errors:
          description: List of validation errors not related to any field
          type: array
          items:
            type: string
      additionalProperties:
        description: A list of error messages for each field that triggered a validation error
        type: array
        items:
          type: string
    InvoiceDetail:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        ascend_id:
          title: Ascend id
          type:
          - string
          - 'null'
          maxLength: 255
        status:
          title: Status
          type:
          - string
          - 'null'
          enum:
          - draft
          - awaiting_payment
          - processing_payment
          - paid
          - overdue
          - void
        status_display:
          title: Status display
          type: string
          readOnly: true
        due_date:
          title: Due date
          type:
          - string
          - 'null'
          format: date
        invoice_number:
          title: Invoice number
          type:
          - string
          - 'null'
          maxLength: 255
        issued_at:
          title: Issued at
          type:
          - string
          - 'null'
          format: date-time
        total_amount:
          title: Total amount
          type: string
          readOnly: true
        paid_at:
          title: Paid at
          type:
          - string
          - 'null'
          format: date-time
        invoice_url:
          title: Invoice url
          type:
          - string
          - 'null'
          format: uri
          maxLength: 2048
        checkout_url:
          title: Checkout url
          type:
          - string
          - 'null'
          format: uri
          maxLength: 2048
        payment_method:
          title: Payment method
          type:
          - object
          - 'null'
        payer_name:
          title: Payer name
          type:
          - string
          - 'null'
          maxLength: 255
        memo:
          title: Memo
          type:
          - string
          - 'null'
        invoice_items:
          title: Invoice items
          type: object
        agent_invoice_docs:
          title: Agent invoice docs
          type: object
        download_url:
          title: Download url
          type: string
          readOnly: true
        receipt_url:
          title: Receipt url
          type: string
          readOnly: true
        days_until_due:
          title: Days until due
          type: string
          readOnly: true
        is_overdue:
          title: Is overdue
          type: string
          readOnly: true
    PaymentDetail:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        ascend_id:
          title: Ascend id
          type:
          - string
          - 'null'
          maxLength: 255
        insured:
          title: Insured
          type: string
          readOnly: true
        business:
          title: Business
          type: string
          readOnly: true
        payment_status:
          title: Payment status
          type: string
          readOnly: true
        quote_status:
          title: Quote status
          type: string
          readOnly: true
        quote:
          title: Quote
          type: string
          readOnly: true
        total:
          title: Total
          type: string
          readOnly: true
        premium:
          title: Premium
          type: string
          readOnly: true
        due_date:
          title: Due date
          type: string
          readOnly: true
        broker:
          title: Broker
          type: string
          readOnly: true
        producer:
          title: Producer
          type: string
          readOnly: true
        all_agents:
          title: All agents
          type: string
          readOnly: true
        account_manager:
          title: Account manager
          type: string
          readOnly: true
        carrier:
          title: Carrier
          type: string
          readOnly: true
        coverage_type:
          title: Coverage type
          type: string
          readOnly: true
        actions:
          title: Actions
          type: string
          readOnly: true
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceDetail'
          readOnly: true
        loans:
          type: array
          items:
            $ref: '#/components/schemas/LoanDetail'
          readOnly: true
        billables:
          type: array
          items:
            $ref: '#/components/schemas/BillableDetail'
          readOnly: true
        payout_info:
          title: Payout info
          type: string
          readOnly: true
        payment_methods:
          title: Payment methods
          type: string
          readOnly: true
        payment_options:
          title: Payment options
          type: string
          readOnly: true
        timeline:
          title: Timeline
          type: string
          readOnly: true
        urls:
          title: Urls
          type: string
          readOnly: true
        organization_info:
          title: Organization info
          type: string
          readOnly: true
        metadata:
          title: Metadata
          type:
          - object
          - 'null'
        source:
          title: Source
          type:
          - string
          - 'null'
          maxLength: 50
        selected_payment_option_type:
          title: Selected payment option type
          type:
          - string
          - 'null'
          maxLength: 50
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        updated_at:
          title: Updated at
          type: string
          format: date-time
          readOnly: true
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
      description: JWT access token. Send as `Bearer <token>` or `JWT <token>`.
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: API key. Send as `Api-Key <key>`.
x-tagGroups:
- name: Agent runtime (v2)
  tags:
  - agent_runtime (v2)
- name: Analytics
  tags:
  - analytics
- name: Application
  tags:
  - 'application: applications'
  - 'application: clients'
- name: Application (v2)
  tags:
  - 'application (v2): applications'
  - 'application (v2): coverages'
- name: Ascend
  tags:
  - ascend
- name: Ascend (v2)
  tags:
  - ascend (v2)
- name: Authentication
  tags:
  - Authentication
  - auth
- name: Billing (v2)
  tags:
  - billing (v2)
- name: Broker
  tags:
  - broker
  - broker-ams-integration
  - broker-google
  - broker-office365
  - broker-office365-individual
  - 'broker: ai-customization-types'
  - 'broker: ai-customizations'
  - 'broker: clients'
  - 'broker: email_preferences'
  - 'broker: proposal-preferences'
  - 'broker: take-rates'
  - 'broker: user-ai-customizations'
  - 'broker: users'
  - broker_groups
  - broker_settings
- name: Broker (v2)
  tags:
  - 'broker (v2): applications'
  - 'broker (v2): clients'
  - 'broker (v2): coverages'
  - 'broker (v2): email-templates'
  - 'broker (v2): quote-policies'
  - 'broker (v2): quotes'
  - 'broker (v2): storefront'
  - 'broker (v2): team-users'
- name: Business
  tags:
  - business
  - business-broker-users
  - business-user
  - business_admin
- name: Carrier
  tags:
  - carrier
- name: Checkout
  tags:
  - checkout
- name: Email AI
  tags:
  - email_ai
- name: Email AI (v2)
  tags:
  - 'email_ai (v2): attachments'
  - 'email_ai (v2): carriers'
  - 'email_ai (v2): coverage-types'
  - 'email_ai (v2): emails'
  - 'email_ai (v2): gmail'
  - 'email_ai (v2): office365'
  - 'email_ai (v2): profiles'
  - 'email_ai (v2): wholesalers'
- name: Email AI Agent
  tags:
  - Email AI Agent
  - Email AI Agent - Attachments
  - Email AI Agent - Businesses
  - Email AI Agent - Entities
  - Email AI Agent - Markets
  - Email AI Agent - Profiles
  - Email AI Agent - Reference Data
- name: Google workspace (v2)
  tags:
  - google_workspace (v2)
- name: Herald (v2)
  tags:
  - herald (v2)
- name: Indications (v2)
  tags:
  - indications (v2)
- name: Insurance (v2)
  tags:
  - insurance (v2)
- name: Invite
  tags:
  - invite
- name: Legal
  tags:
  - legal
- name: Market
  tags:
  - Markets
  - Markets - Business
- name: Market (v2)
  tags:
  - market (v2)
- name: Office365 (v2)
  tags:
  - office365 (v2)
- name: Premium finance (v2)
  tags:
  - premium_finance (v2)
- name: Quote
  tags:
  - 'quote: applications'
  - 'quote: clients'
  - 'quote: quotes'
- name: Quote (v2)
  tags:
  - 'quote (v2): application'
  - 'quote (v2): binders'
  - 'quote (v2): checkout'
  - 'quote (v2): cios'
  - 'quote (v2): coverages'
  - 'quote (v2): quote-policies'
  - 'quote (v2): quotes'
  - 'quote (v2): tasks'
  - quote_ai (v2)
- name: Reports
  tags:
  - reports
- name: Reward
  tags:
  - reward
- name: Risk manager
  tags:
  - risk_manager
- name: Sanity check AI
  tags:
  - sanity_check_ai
- name: Storefront (v2)
  tags:
  - storefront (v2)
- name: Stripe
  tags:
  - stripe
- name: Suggestion AI
  tags:
  - suggestion_ai
- name: Treasury (v2)
  tags:
  - treasury (v2)
- name: User
  tags:
  - user
  - 'user: default-access-role'