Ascend Billables API

openapi: 3.2.0
info:
  title: Ascend API V1 Accounts Billables API
  version: v1
  description: 'Ascend REST API for insurance financial operations: billing & invoicing, premium financing, payments, installment plans, insureds, programs, loans, payouts, and refunds.'
servers:
- url: https://sandbox.api.useascend.com
  description: Test server
- url: https://api.useascend.com
  description: Production server
tags:
- name: Billables
  description: Represents an insurance quote or endorsement to be billed to the insured.
paths:
  /v1/billables:
    post:
      summary: Create Billable
      tags:
      - Billables
      operationId: createBillable
      security:
      - bearer_auth: []
      parameters: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Billable'
        '400':
          description: Conflicting commission parameters
        '404':
          description: Record not Found
        '422':
          description: Not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An insurance quote or endorsement to be billed to the insured.
              properties:
                agency_fees_cents:
                  type: integer
                  minimum: 0
                  description: Fee collected by your agency or by your partner, if you are a MGA. Fully earned, not financeable, and will be funded directly to your agency or partner.
                attachments:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The Attachment ID
                    required:
                    - id
                billable_identifier:
                  type: string
                  description: The identifier assigned to the quote/endorsement by the issuing carrier or wholesaler.
                broker_fee_cents:
                  type: integer
                  minimum: 0
                  description: Fee collected by the wholesaler. Fully earned, not financeable, and funded directly to the wholesaler.
                carrier_identifier:
                  type: string
                  description: The identifier of the carrier who issued this quote. Required when billable is of type quote. When the billable is an endorsement the carrier will be inherited from the parent billable.
                commission_terms:
                  type: array
                  deprecated: true
                  description: 'Deprecated: use `organization_account_commission_cents` or `organization_account_commission_rate` instead.'
                  items:
                    type: object
                    properties:
                      organization_account_id:
                        type: string
                        description: The organization account to receive the commission. If null the commission will be funded to your organization.
                      commission_cents:
                        type:
                        - number
                        - 'null'
                        format: integer
                        description: The commission amount for this entity in cents. One of `commission_cents` or `commission_rate` is required.
                      commission_rate:
                        type:
                        - number
                        - 'null'
                        format: float
                        description: The commission rate for this entity. One of `commission_cents` or `commission_rate` is required.
                coverage_identifier:
                  type: string
                  description: The identifier of coverage type the quote/endorsement covers.
                description:
                  type: string
                  description: For endorsements, add a short description to explain to the insured what is changing.
                effective_date:
                  type: string
                  format: date
                  description: 'The date upon the quote/endorsement goes into effect. Expected format: YYYY-MM-DD.'
                expiration_date:
                  type: string
                  format: datetime
                  description: 'The date when the quote/endorsement is no longer active. Expected format: YYYY-MM-DD'
                metadata:
                  type:
                  - object
                  - 'null'
                  description: Metadata to be associated with the billable. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
                min_earned_rate:
                  type: number
                  format: float
                  description: If there is a mininum earned on the policy, this field is required.
                organization_account_commission_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: For MGAs, set this field for your partner's commission amount. You must set one of `organization_account_commission_cents` or `organization_account_commission_rates`
                organization_account_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: For MGAs, set this field for your partner's commission rate. You must set one of `organization_account_commission_cents` or `organization_account_commission_rates`
                organization_commission_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: Your commission amount for this policy. If you're an agency, you must set one of `organization_commission_cents` or `organization_commission_rates`
                organization_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: Your commission rate for this policy. If you're an agency, you must set one of `organization_commission_cents` or `organization_commission_rates`
                other_fees_cents:
                  type: integer
                  minimum: 0
                  description: Any additional fees that come with the policy. This fee is treated as non-refundable & fully earned.
                parent_billable_id:
                  type: string
                  format: uuid
                  description: To create a premium increasing endorsement, set this to the billable ID of the policy you are endorsing. Should only be used if the intent is to create a premium increasing endorsement.
                policy_fee_cents:
                  type: integer
                  minimum: 0
                  description: Any policy fees that come with the quote. This fee is treated as non-refundable & fully earned.
                policy_number:
                  type: string
                  description: The number assigned to the policy once it has been bound.
                premium_cents:
                  type: integer
                  minimum: 0
                  description: The amount to pay for the quote or endorsement.
                program_id:
                  type: string
                  format: uuid
                  description: The id of the program the billable should be a part of.
                seller_commission_amount_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: 'Deprecated: use `organization_commission_cents` instead. Your commission amount for this policy. If you''re an agency, you must set one of `seller_commission_amount_cents` or `seller_commission_rate`. If MGA or Wholesaler, set commission_terms.'
                  deprecated: true
                seller_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: 'Deprecated: use `organization_commission_rate` instead. Your commission rate for this policy. If you''re an agency, you must set one of `seller_commission_amount_cents` or `seller_commission_rate`. If MGA or Wholesaler, set commission_terms.'
                  deprecated: true
                surplus_lines_tax_cents:
                  type: integer
                  minimum: 0
                  description: 'If you are filing surplus lines taxes & fees, set this field. These fees are financeable and will be funded to you. Note: This field is only supported for organizations with surplus lines tax functionality enabled. Contact developers@useascend.com to enable this feature.'
                taxes_and_fees_cents:
                  type: integer
                  minimum: 0
                  description: Any taxes & unearned fees. Taxes and fees are financed.
                wholesaler_identifier:
                  type: string
                  description: The identifier of the wholesaler or MGA that issued this quote. Required if you're an MGA or Wholesaler. When the billable is an endorsement the wholesaler will be inherited from the parent billable.
              required:
              - billable_identifier
              - carrier_identifier
              - coverage_identifier
              - effective_date
              - expiration_date
              - premium_cents
              - program_id
              - billable_type
    get:
      summary: List Billables
      tags:
      - Billables
      operationId: listBillables
      security:
      - bearer_auth: []
      parameters:
      - name: program_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Filter by the ID of the associated program
      - name: updated_at
        in: query
        style: deepObject
        explode: true
        description: Only return billables that were updated during the given date interval. The date should be defined as an ISO-8601 datetime.
        required: false
        schema:
          type: object
          properties:
            lt:
              type: string
              format: date-time
              description: Maximum value to filter by (exclusive).
            gte:
              type: string
              format: date-time
              description: Minimum value to filter by (inclusive).
      - name: created_at
        in: query
        style: deepObject
        explode: true
        description: Only return billables that were created during the given date interval. The date should be defined as an ISO-8601 datetime.
        required: false
        schema:
          type: object
          properties:
            lt:
              type: string
              format: date-time
              description: Maximum value to filter by (exclusive).
            gte:
              type: string
              format: date-time
              description: Minimum value to filter by (inclusive).
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Billable'
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                      next:
                        type:
                        - string
                        - 'null'
                      prev:
                        type:
                        - string
                        - 'null'
  /v1/billables/{id}:
    parameters:
    - name: id
      in: path
      description: The billable identifier
      required: true
      schema:
        type: string
    delete:
      summary: Delete Billable
      tags:
      - Billables
      operationId: deleteBillable
      security:
      - bearer_auth: []
      responses:
        '204':
          description: Billable deleted
        '404':
          description: Billable not found
    get:
      summary: Get Billable
      tags:
      - Billables
      operationId: getBillable
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Billable found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Billable'
        '404':
          description: Billable not found
    patch:
      summary: Update Billable
      tags:
      - Billables
      operationId: updateBillable
      security:
      - bearer_auth: []
      parameters: []
      responses:
        '200':
          description: Billable updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Billable'
        '400':
          description: Billable type does not belong in checkout session
        '404':
          description: Billable not found
        '422':
          description: Unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: An insurance quote or endorsement to be billed to the insured.
              properties:
                attachments:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The Attachment ID
                    required:
                    - id
                agency_fees_cents:
                  type: integer
                  minimum: 0
                  description: Fee collected by your agency or by your partner, if you are a MGA. Fully earned, not financeable, and will be funded directly to your agency or partner.
                billable_identifier:
                  type: string
                  description: The identifier assigned to the quote/endorsement by the issuing carrier or wholesaler.
                broker_fee_cents:
                  type: integer
                  minimum: 0
                  description: Fee collected by the wholesaler. Fully earned, not financeable, and funded directly to the wholesaler.
                carrier_identifier:
                  type: string
                  description: The identifier of the carrier who issued this quote. Required when billable is of type quote. When the billable is an endorsement the carrier will be inherited from the parent billable.
                commission_terms:
                  type: array
                  deprecated: true
                  description: 'Deprecated: use `organization_account_commission_cents` or `organization_account_commission_rate` instead.'
                  items:
                    type: object
                    properties:
                      organization_account_id:
                        type: string
                        description: The account to receive the commission. If null the commission will be funded to your organization.
                      commission_cents:
                        type: number
                        format: integer
                        description: The commission amount for this entity in cents. One of `commission_cents` or `commission_rate` is required.
                      commission_rate:
                        type: number
                        format: float
                        description: The commission rate for this entity.
                coverage_identifier:
                  type: string
                  description: The identifier of coverage type the quote/endorsement covers.
                description:
                  type: string
                  description: A short description to explain to the insured what they are purchasing.
                effective_date:
                  type: string
                  format: date
                  description: 'The date upon the quote/endorsement goes into effect. Expected format: YYYY-MM-DD.'
                expiration_date:
                  type: string
                  format: datetime
                  description: 'The date when the quote is no longer active. Expected format: YYYY-MM-DD.'
                is_auditable:
                  type: boolean
                  description: Determines if the carrier can audit customer raising premium significantly. Cannot be set when billable is of type endorsement.
                is_filed:
                  type: boolean
                  description: Determines if specific lines of business are filed with other bureaus which they have to notify on cancelation. Cannot be set when billable is of type endorsement.
                is_short_rate:
                  type: boolean
                  description: Determines if the policy is fined by 10% on top of earned premium when insured cancels. Cannot be set when billable is of type endorsement.
                metadata:
                  type:
                  - object
                  - 'null'
                  description: Metadata to be associated with the billable. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
                min_days_to_cancel:
                  type: integer
                  description: Set state determined extended cancelation period for the policy.
                min_earned_rate:
                  type: number
                  format: float
                  description: The minimum rate to charge insureds when they decide to finance.
                organization_account_commission_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: For MGAs, set this field for your partner's commission amount. You must set one of `organization_account_commission_cents` or `organization_account_commission_rates`
                organization_account_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: For MGAs, set this field for your partner's commission rate. You must set one of `organization_account_commission_cents` or `organization_account_commission_rates`
                organization_commission_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: Your commission amount for this policy. If you're an agency, you must set one of `organization_commission_cents` or `organization_commission_rates`
                organization_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: Your commission rate for this policy. If you're an agency, you must set one of `organization_commission_cents` or `organization_commission_rates`
                other_fees_cents:
                  type: integer
                  minimum: 0
                  description: Any additional fees that come with the policy. This fee is treated as non-refundable & fully earned.
                parent_billable_id:
                  type: string
                  format: uuid
                  description: The id of the billable to be endorsed.
                policy_fee_cents:
                  type: integer
                  minimum: 0
                  description: Any policy fees that come with the quote. This fee is treated as non-refundable & fully earned.
                policy_number:
                  type: string
                  description: The number assigned to the policy once it has been bound.
                premium_cents:
                  type: integer
                  minimum: 0
                  description: The amount to pay for the quote or endorsement.
                seller_commission_amount_cents:
                  type:
                  - number
                  - 'null'
                  format: integer
                  description: 'Deprecated: use `organization_commission_cents` instead. Your commission amount for this policy. If you''re an agency, you must set one of `seller_commission_amount_cents` or `seller_commission_rate`. If MGA or Wholesaler, set commission_terms.'
                  deprecated: true
                seller_commission_rate:
                  type:
                  - number
                  - 'null'
                  format: float
                  description: 'Deprecated: use `organization_commission_rate` instead. Your commission rate for this policy. If you''re an agency, you must set one of `seller_commission_amount_cents` or `seller_commission_rate`. If MGA or Wholesaler, set commission_terms.'
                  deprecated: true
                taxes_and_fees_cents:
                  type: integer
                  minimum: 0
                  description: Any taxes & unearned fees. Taxes and fees are financed.
                surplus_lines_tax_cents:
                  type: integer
                  minimum: 0
                  description: 'If you are filing surplus lines taxes & fees, set this field. These fees are financeable and will be funded to you. Note: This field is only supported for organizations with surplus lines tax functionality enabled. Contact developers@useascend.com to enable this feature.'
                wholesaler_identifier:
                  type: string
                  description: The identifier of the wholesaler that issued this quote. When the billable is an endorsement the wholesaler will be inherited from the parent billable.
components:
  schemas:
    Wholesaler:
      type: object
      description: An insurance wholesaler or MGA.
      properties:
        identifier:
          type: string
          description: A human readable unique identifier.
        title:
          type: string
          description: The wholesaler display name.
        mailing_address_street_one:
          type:
          - string
          - 'null'
          description: Mailing Street address
        mailing_address_street_two:
          type:
          - string
          - 'null'
          description: Suite or unit
        mailing_address_city:
          type:
          - string
          - 'null'
          description: Mailing city
        mailing_address_state:
          $ref: '#/components/schemas/StateAnsiCodes'
        mailing_address_zip_code:
          type:
          - string
          - 'null'
          description: Mailing zip code
    StateAnsiCodes:
      type: string
      description: 'A US State represented with their ANSI code. For ex: California = CA'
      enum:
      - AK
      - AL
      - AR
      - AS
      - AZ
      - CA
      - CO
      - CT
      - DC
      - DE
      - FL
      - GA
      - GU
      - HI
      - IA
      - ID
      - IL
      - IN
      - KS
      - KY
      - LA
      - MA
      - MD
      - ME
      - MI
      - MN
      - MO
      - MP
      - MS
      - MT
      - NC
      - ND
      - NE
      - NH
      - NJ
      - NM
      - NV
      - NY
      - OH
      - OK
      - OR
      - PA
      - PR
      - RI
      - SC
      - SD
      - TN
      - TX
      - UM
      - UT
      - VA
      - VI
      - VT
      - WA
      - WI
      - WV
      - WY
    Carrier:
      type: object
      description: An insurance company.
      properties:
        identifier:
          type: string
          description: A human readable unique identifier.
        title:
          type: string
          description: The carrier display name.
        mailing_address_street_one:
          type:
          - string
          - 'null'
          description: Mailing Street address
        mailing_address_street_two:
          type:
          - string
          - 'null'
          description: Suite or unit
        mailing_address_city:
          type:
          - string
          - 'null'
          description: Mailing city
        mailing_address_state:
          $ref: '#/components/schemas/StateAnsiCodes'
        mailing_address_zip_code:
          type:
          - string
          - 'null'
          description: Mailing zip code
    CoverageType:
      type: object
      description: A type of coverage.
      properties:
        identifier:
          type: string
          description: A human readable unique identifier.
        title:
          type: string
          description: The coverage type display name.
    Billable:
      type: object
      description: An insurance quote or endorsement to be billed to the insured.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the billable.
        agency_fees_cents:
          type: integer
          minimum: 0
          description: Fee collected by your agency. Fully earned, not financeable, and funded directly to your agency.
        billable_identifier:
          type: string
          description: The identifier assigned to the quote/endorsement by the issuing carrier or wholesaler.
        broker_fee_cents:
          type: integer
          minimum: 0
          description: Fee collected by the wholesaler. Fully earned, not financeable, and funded directly to the wholesaler.
        carrier:
          $ref: '#/components/schemas/Carrier'
        description:
          type:
          - string
          - 'null'
          description: A short description to explain to the insured what they are purchasing.
        coverage_type:
          $ref: '#/components/schemas/CoverageType'
        effective_date:
          type: string
          format: date
          description: 'The date upon the billable goes into effect. Expected format: YYYY-MM-DD.'
        expiration_date:
          type:
          - string
          - 'null'
          format: date
          description: 'The date when the billable is no longer active. Expected format: YYYY-MM-DD.'
        documents:
          type: array
          description: A collection of documents associated with the billable.
          items:
            type: object
            properties:
              title:
                type:
                - string
                - 'null'
                description: The display name of the static asset.
              url:
                type: string
                description: The url to access the static asset.
        is_auditable:
          type: boolean
          description: Determines if the carrier can audit customer raising premium significantly.
        is_filed:
          type: boolean
          description: Determines if specific lines of business are filed with other bureaus which they have to notify on cancelation.
        is_short_rate:
          type: boolean
          description: 'Determines if the policy is fined by 10% on top of earned premium when insured cancels '
        min_days_to_cancel:
          type: integer
          description: Set state determined extended cancelation period for the policy.
        min_earned_rate:
          type: number
          format: float
          description: The minimum rate to charge insureds when they decide to finance.
        other_fees_cents:
          type: integer
          description: Any additional fees that come with the policy. This fee is treated as non-refundable & fully earned.
        parent_billable_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The unique identifier for the parent billable.
        policy_fee_cents:
          type: integer
          description: Any policy fees that come with the billable. This fee is treated as non-refundable & fully earned.
        policy_number:
          type:
          - string
          - 'null'
          description: The number assigned to the policy once it has been bound.
        premium_cents:
          type: integer
          description: The amount to pay for the insurance policy.
        seller_commission_amount_cents:
          type: number
          format: integer
          description: Your commission amount for this policy.
        seller_commission_rate:
          type:
          - number
          - 'null'
          format: float
          description: Your commission rate for this policy.
        commission_terms:
          type: array
          items:
            type: object
            properties:
              organization_account_id:
                type: string
                description: The organization account to receive the commission. If null the commission will be funded to your organization.
              commission_cents:
                type: number
                description: The commission amount for this entity in cents.
        taxes_and_fees_cents:
          type: integer
          description: Any taxes & unearned fees. Taxes and fees are financed.
        program_id:
          type: string
          format: uuid
          description: The id of the program the billable should be a part of.
        surplus_lines_tax_cents:
          type: integer
          description: The amount of surplus lines tax to be collected.
        wholesaler:
          allOf:
          - $ref: '#/components/schemas/Wholesaler'
        metadata:
          type:
          - object
          - 'null'
          description: Metadata associated with the billable.
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer