Ascend Programs API

openapi: 3.0.1
info:
  title: Ascend API V1 Accounts Programs 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: Programs
  description: A collection of insurance quotes pooled to produce 1 checkout link.
paths:
  /v1/programs:
    post:
      summary: Create Program
      tags:
      - Programs
      operationId: createProgram
      security:
      - bearer_auth: []
      parameters: []
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
        '400':
          description: Bad Request
        '422':
          description: Unprocessable entity
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_manager_id:
                  description: The unique identifier of the user belonging to your organization that will be associated as the account manager for the program. This user is listed as the agent on checkout and receives any program communications. This defaults to the producer if not specified.
                  format: uuid
                  type: string
                secondary_account_manager_id:
                  description: The unique identifier of the user belonging to your organization that will be associated as the secondary account manager for the program. This user receives any program communications that the account manager also receives
                  format: uuid
                  type: string
                allowed_payment_methods:
                  type: array
                  description: A list of payment methods that are allowed during checkout.
                  items:
                    type: string
                    enum:
                    - card
                    - ach_debit
                    - ach_credit_transfer
                    - check
                billing_type:
                  type: string
                  enum:
                  - agency_bill
                  - direct_bill
                  description: (MGA only) The type of billing used for this program. If not specified, defaults to the billing type on the organization account.
                due_date:
                  type: string
                  format: date
                  description: Due date of the program payment or downpayment. If not specified, this will default to the earliest effective date plus an additional settlement period if applicable.
                failure_callback_url:
                  description: A URL to send the user back to after failed transaction occurs during the checkout process. This defaults to the organization return url if not specified.
                  type: string
                hidden_payment_options:
                  type: array
                  description: A list of payment options that are hidden during checkout.
                  items:
                    type: string
                    enum:
                    - annual_pay_in_full
                    - monthly_financed
                insured_id:
                  description: The id of the insured associated to the program
                  format: uuid
                  type: string
                is_checkout_overview_page_visible:
                  description: A configuration to let the customer view the overview page during the checkout process. This defaults to false if not specified.
                  type: boolean
                is_checkout_receipt_page_visible:
                  description: A configuration to let the customer view the receipt page during the checkout process. This defaults to false if not specified.
                  type: boolean
                organization_account:
                  type: object
                  description: (MGA only) The billing account associated to the program. This can represent either the wholesaler or the retail agency.
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The unique identifier of the billing account associated to the program
                    users:
                      type: array
                      description: An array of user ids belonging to the billing account who should be associated to the program. Required if billing_type is agency_bill.
                      items:
                        type: string
                        format: uuid
                producer_id:
                  description: The user id associated to the producer of this program. This user is listed on the premium finance agreement.
                  format: uuid
                  type: string
                return_url:
                  description: A URL to send the user back to after dismissing the checkout process. This defaults to the organization return url if not specified.
                  type: string
                success_callback_url:
                  description: A URL to send the user back to after successful transaction occurs during the checkout process. This defaults to the organization return url if not specified.
                  type: string
                metadata:
                  type: object
                  description: Metadata to be associated with the program. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
                  nullable: true
              required:
              - insured_id
              - producer_id
              - account_manager_id
              type: object
    get:
      summary: List Programs
      tags:
      - Programs
      operationId: listPrograms
      security:
      - bearer_auth: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: insured_id
        in: query
        required: false
        description: Filter by associated insured
        schema:
          type: string
      - name: purchased_at
        in: query
        style: deepObject
        explode: true
        description: Only return programs that were purchased 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: updated_at
        in: query
        style: deepObject
        explode: true
        description: Only return programs 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 programs 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: successful
  /v1/programs/{id}:
    parameters:
    - name: id
      in: path
      description: The program identifier
      required: true
      schema:
        type: string
    delete:
      summary: Archive Program
      tags:
      - Programs
      operationId: deleteProgram
      security:
      - bearer_auth: []
      responses:
        '204':
          description: Program archived
        '400':
          description: Bad request
        '404':
          description: Program not found
        '422':
          description: Can't archive program, rolling back
    get:
      summary: Get Program
      tags:
      - Programs
      operationId: getProgram
      security:
      - bearer_auth: []
      parameters:
      - name: include_archived
        required: false
        in: query
        description: Include archived programs
        schema:
          type: boolean
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
        '404':
          description: Program not found
    patch:
      summary: Update program
      tags:
      - Programs
      operationId: updateProgram
      security:
      - bearer_auth: []
      parameters: []
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
        '403':
          description: Forbidden
        '404':
          description: Program not found
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_manager_id:
                  description: The unique identifier of the user belonging to your organization that will be associated as the account manager for the program. This user is listed as the agent on checkout and receives any program communications. This defaults to the producer if not specified.
                  format: uuid
                  type: string
                secondary_account_manager_id:
                  description: The unique identifier of the user belonging to your organization that will be associated as the secondary account manager for the program. This user receives any program communications that the account manager also receives
                  format: uuid
                  type: string
                allowed_payment_methods:
                  type: array
                  description: A list of payment methods that are allowed during checkout.
                  items:
                    type: string
                    enum:
                    - card
                    - ach_debit
                    - ach_credit_transfer
                    - check
                due_date:
                  type: string
                  format: date
                  description: Due date of the program payment or downpayment. This cannot be changed after the program has become active.
                endorsement_due_date:
                  type: string
                  format: date
                  description: Due date of the upcoming endorsement payment. This cannot be changed if there are no unpaid endorsements on the program.
                failure_callback_url:
                  description: A URL to send the user back to after failed transaction occurs during the checkout process. This defaults to the organization return url if not specified.
                  type: string
                hidden_payment_options:
                  type: array
                  description: A list of payment options that are hidden during checkout.
                  items:
                    type: string
                    enum:
                    - annual_pay_in_full
                is_checkout_overview_page_visible:
                  description: A configuration to let the customer view the overview page during the checkout process. This defaults to false if not specified.
                  type: boolean
                is_checkout_receipt_page_visible:
                  description: A configuration to let the customer view the receipt page during the checkout process. This defaults to false if not specified.
                  type: boolean
                organization_account:
                  type: object
                  description: (MGA only) The billing account associated to the program. This can represent either the wholesaler or the retail agency.
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The unique identifier of the billing account associated to the program
                    users:
                      type: array
                      description: An array of user ids belonging to the billing account who should be associated to the program.
                      items:
                        type: string
                        format: uuid
                producer_id:
                  description: The unique identifier of the user associated as the producer of the program. This user is listed on the premium finance agreement. This defaults to the insured assignee user if not specified.
                  format: uuid
                  type: string
                return_url:
                  description: A URL to send the user back to after dismissing the checkout process. This defaults to the organization return url if not specified.
                  type: string
                success_callback_url:
                  description: A URL to send the user back to after successful transaction occurs during the checkout process. This defaults to the organization return url if not specified.
                  type: string
                metadata:
                  type: object
                  description: Metadata to be associated with the program. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
                  nullable: true
              type: object
  /v1/programs/{id}/loan_payoff:
    parameters:
    - name: id
      in: path
      description: Program id
      required: true
      schema:
        type: string
    post:
      summary: Create loan payoff invoice
      tags:
      - Programs
      operationId: createProgramLoanPayoff
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
    get:
      summary: Get loan payoff invoice
      tags:
      - Programs
      operationId: getProgramLoanPayoff
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '204':
          description: no active early payoff invoice
    delete:
      summary: Void loan payoff invoice
      tags:
      - Programs
      operationId: voidProgramLoanPayoff
      security:
      - bearer_auth: []
      responses:
        '204':
          description: no content
        '422':
          description: cannot void invoice
  /v1/programs/{id}/loan_payoff_estimate:
    parameters:
    - name: id
      in: path
      description: the id of the program
      required: true
      schema:
        type: string
    post:
      summary: Loan Payoff Estimate
      tags:
      - Programs
      operationId: createLoanPayoffEstimate
      security:
      - bearer_auth: []
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanPayoffEstimate'
        '404':
          description: Program not found
        '422':
          description: Unprocessable content
        '500':
          description: Internal server error
  /v1/programs/{id}/send:
    parameters:
    - name: id
      in: path
      description: the id of the program
      required: true
      schema:
        type: string
    post:
      summary: Notify User
      tags:
      - Programs
      operationId: notifyInsured
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
        '404':
          description: Program not found
        '422':
          description: Unprocessable content
  /v1/programs/{id}/unarchive:
    parameters:
    - name: id
      in: path
      description: The id of the program
      required: true
      schema:
        type: string
    post:
      summary: Unarchive program
      tags:
      - Programs
      operationId: unarchiveProgram
      security:
      - bearer_auth: []
      responses:
        '200':
          description: Successful
        '404':
          description: Program not found
components:
  schemas:
    Program:
      type: object
      description: A collection of insurance quotes pooled to produce 1 checkout link.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the program
        account_manager:
          $ref: '#/components/schemas/User'
        secondary_account_manager:
          $ref: '#/components/schemas/User'
          nullable: true
        allowed_payment_methods:
          type: array
          description: A list of payment methods that are allowed during checkout.
          items:
            type: string
            enum:
            - card
            - ach_debit
            - ach_credit_transfer
            - check
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: The date the program was archived. The date uses UTC and is represented in the iso8601 format.
        autopay_enabled:
          type: boolean
          description: Whether autopay is enabled for the program.
          readOnly: true
        billing_type:
          type: string
          enum:
          - agency_bill
          - direct_bill
          description: The type of billing used for this policy.
          readOnly: true
        checkedout_at:
          type: string
          nullable: true
          format: date-time
          description: The date the program was checked out. The date uses UTC and is represented in the iso8601 format.
        created_at:
          type: string
          format: date-time
          description: The date the program was created. The date uses UTC and is represented in the iso8601 format.
        due_date:
          type: string
          format: date
          description: Due date of the program payment or downpayment.
          nullable: true
        endorsement_due_date:
          type: string
          format: date
          description: Due date of the most recent endorsement payment.
          nullable: true
        failure_callback_url:
          type: string
          nullable: true
          description: A URL to send the user back to after failed transaction occurs during the checkout process.
        hidden_payment_options:
          type: array
          description: A list of payment options that are hidden during checkout.
          items:
            type: string
            enum:
            - annual_pay_in_full
        insured:
          $ref: '#/components/schemas/Insured'
        premium_cents:
          type: integer
          description: The total premium that the insured should pay for the program. This represents the premium sum of each quote associated to this program. The value is represented in cents.
        producer:
          $ref: '#/components/schemas/User'
        program_url:
          type: string
          description: A URL to complete the checkout process.
        return_url:
          type: string
          nullable: true
          description: A URL to send the user back to after completing the checkout process.
        selected_payment_option_type:
          type: string
          nullable: true
          description: The payment option chosen by the insured during the checkout process.
        status:
          type: string
          enum:
          - archived
          - purchased
          - checked_out
          - elected
          - ready_for_checkout
          - created
          description: The state of the program
        sub_total_cents:
          type: integer
          description: The amount to be payed by the insured including all premium and fees applicable to the program. The value is represented in cents.
        success_callback_url:
          type: string
          nullable: true
          description: A URL to send the user back to after successful transaction occurs during the checkout process.
        updated_at:
          type: string
          format: date-time
          description: The date the program was last updated. The date uses UTC and is represented in the iso8601 format.
        metadata:
          type: object
          description: Metadata associated with the program.
          nullable: true
    PaymentMethod:
      type: object
      description: It represents the payment instrument used by an insured.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the payment method.
          readOnly: true
        payment_type:
          type: string
          enum:
          - card
          - ach_debit
          - ach_credit_transfer
          - us_bank_account
          - check
          description: The type of payment method.
          readOnly: true
        card:
          type: object
          description: Detailed information about the card.
          properties:
            last_four_digits:
              type: string
              description: The last four digits of the card.
            brand:
              type: string
              description: The card brand.
          required:
          - brand
          - last_four_digits
        ach_debit:
          type: object
          description: Detailed information about the ach method.
          properties:
            last_four_digits:
              type: string
              description: The last four digits of the account number.
            bank_name:
              type: string
              description: The name of the bank institution.
          required:
          - bank_name
          - last_four_digits
        ach_credit:
          type: object
          description: Detailed information about the ach credit method.
          properties:
            bank_name:
              type: string
              description: The name of the bank institution.
          required:
          - bank_name
    Insured:
      type: object
      description: Represents the person or business entity that is purchasing the collection of insurance quotes.
      properties:
        id:
          type: string
          description: Unique identifier for the insured
        email:
          type: string
          format: email
          description: The email for the insured
          nullable: true
        first_name:
          type: string
          nullable: true
          description: First name of the insured.
        last_name:
          type: string
          nullable: true
          description: Last name of the insured.
        business_name:
          type: string
          nullable: true
          description: Business name. Either first + last name or business name is required.
        is_business:
          type: boolean
          description: Determines if the insured is a business entity. If it is not it will be assumed that the insured is a person.
        formatted_address:
          type: string
          nullable: true
          description: complete address of the insured
        phone:
          type: string
          description: Phone number of the insured
          nullable: true
        mailing_address_street_one:
          type: string
          nullable: true
          description: Mailing Street address
        mailing_address_street_two:
          type: string
          nullable: true
          description: Suite or unit
        mailing_address_city:
          type: string
          nullable: true
          description: Mailing city
        mailing_address_state:
          nullable: true
          $ref: '#/components/schemas/StateAnsiCodes'
        mailing_address_zip_code:
          type: string
          nullable: true
          description: Mailing zip code
      required:
      - id
      - email
      - is_business
      - phone
      - mailing_address_street_one
      - mailing_address_city
      - mailing_address_state
      - mailing_address_zip_code
    LoanPayoffEstimate:
      type: object
      description: Loan payoff estimate for a financed program
      properties:
        pay_off_amount_cents:
          type: integer
          description: The amount in cents needed to pay off the loan.
          minimum: 0
          example: 19775000
          readOnly: true
        program_id:
          type: string
          format: uuid
          description: The program unique identifier.
          readOnly: true
      required:
      - pay_off_amount_cents
      - program_id
    InvoiceItem:
      type: object
      description: Representation of a line item on the invoice.
      properties:
        amount_cents:
          type: integer
          description: The total amount charged.
          minimum: 0
          example: 10000
        title:
          type: string
          description: Information about the invoice item.
          example: Policy Tax
      required:
      - amount_cents
      - title
    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
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the user
        email:
          type: string
          format: email
          description: The email for the user
        first_name:
          type: string
          description: First name of the user.
        last_name:
          type: string
          description: Last name of the user.
        phone:
          type: string
          nullable: true
          description: 'Phone number. Formatted: 5555555555'
      required:
      - email
      - phone
    Invoice:
      type: object
      description: A document representing a transaction between the insured and Ascend.
      properties:
        id:
          type: string
          format: uuid
          description: The invoice unique identifier.
          readOnly: true
        account_manager_id:
          type: string
          format: uuid
          description: The unique identifier of the user associated as the account manager for the invoice. This user is listed as the agent on checkout and receives any invoice communications
        agent_invoice_docs:
          type: array
          nullable: true
          description: A collection of documents associated with the invoice.
          items:
            type: object
            properties:
              title:
                type: string
                description: The display name of the static asset.
                nullable: true
              url:
                type: string
                description: The url to access the static asset.
        checkout_url:
          type: string
          nullable: true
          readOnly: true
          description: The checkout url of the invoice.
        due_date:
          type: string
          format: date
          nullable: true
          description: The date by which the invoice should be paid.
        installment_id:
          type: string
          format: uuid
          description: The unique identifier of the installment the invoice is attached to. Only present for installment plan invoices.
          nullable: true
          readOnly: true
        installment_plan_id:
          type: string
          format: uuid
          description: The unique identifier of the installment plan the invoice is attached to.
          nullable: true
          readOnly: true
        insured_id:
          type: string
          format: uuid
          description: The unique identifier of the insured invoice is attached to.
        invoice_items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceItem'
        invoice_number:
          type: string
          description: A number assigned to uniquely identify the invoice.
          example: I909821
          readOnly: true
        invoice_url:
          type: string
          description: The url of the invoice document.
          example: http://res.cloudinary.com/useascend.pdf
          nullable: true
          readOnly: true
        issued_at:
          type: string
          format: date-time
          nullable: true
          description: The date when the invoice was shared with the insured.
          readOnly: true
        memo:
          type: string
          description: Information about the invoice shown to the insured.
          nullable: true
          example: Additional premium for auto policy
        one_time_payment_id:
          type: string
          format: uuid
          description: The unique identifier of the one-time payment the invoice is attached to. Only present for one-time payment invoices.
          nullable: true
          readOnly: true
        paid_at:
          type: string
          format: date-time
          nullable: true
          description: The date when the invoice was paid by the insured.
          readOnly: true
        payer_name:
          type: string
          description: The name of the insured/business paying for the invoice.
          example: Auto Sales Inc.
        payment_method:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/PaymentMethod'
        program_id:
          type: string
          format: uuid
          nullable: true
          description: The unique identifier of the program invoice is attached to.
          readOnly: true
        status:
          type: string
          description: The current state of the invoice.
          example: draft
          readOnly: true
          enum:
          - draft
          - awaiting_payment
          - overdue
          - processing_payment
          - paid
          - void
        total_amount_cents:
          type: integer
          description: The total amount charged.
          minimum: 0
          example: 10000
          readOnly: true
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer