Ascend InstallmentPlans API
A payment plan broken down over a seriies of regular installments
OpenAPI Specification
openapi: 3.0.1
info:
title: Ascend API V1 Accounts InstallmentPlans 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: InstallmentPlans
description: A payment plan broken down over a seriies of regular installments
paths:
/v1/installment_plans:
post:
summary: Create installment plan
tags:
- InstallmentPlans
security:
- bearer_auth: []
parameters: []
responses:
'201':
description: created
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
'400':
description: Bad request
'422':
description: Unprocessable entity
requestBody:
content:
application/json:
schema:
type: object
description: An installment plan for a series of payments
properties:
account_manager_id:
type: string
format: uuid
description: Id of the account manager belonging to your organization who will receive email communications for the installment plan
secondary_account_manager_id:
type: string
format: uuid
description: Id of the secondary account manager belonging to your organization who will receive the same email communications for the installment plan as the account manager
attachments:
type: array
nullable: true
items:
type: object
properties:
id:
type: string
format: uuid
description: The unique identifier of the attachment.
required:
- id
billing_type:
type: string
enum:
- agency_bill
- direct_bill
description: (MGA only) The type of billing used for this one time payment. If not specified, defaults to the billing type on the organization account.
installments:
type: array
description: An array of installments
items:
type: object
properties:
amount_cents:
type: integer
description: Total amount to be paid for the installment
due_date:
type: string
format: date
description: 'Due date of the installment. Format: YYYY-MM-DD'
payables:
type: array
description: Payables paid to your organization
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
account_type:
type: string
enum:
- trust_account
- commission_account
description: The type of the bank account that will receive funds
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
required:
- amount_cents
- account_type
- remittance_memo
company_payables:
type: array
description: Payables paid to the issuing or billing company
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
identifier:
type: string
description: Identifier of the issuing or billing company
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
required:
- amount_cents
- identifier
- remittance_memo
organization_account_payables:
type: array
description: Payables to partner agencies
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
organization_account_id:
type: string
description: Organization account id for the partner agency
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
required:
- amount_cents
- organization_account_id
- remittance_memo
required:
- amount_cents
- due_date
minItems: 2
insured_id:
type: string
format: uuid
description: Id of the insured responsible for installment payments
memo:
type: string
description: Short description for the installment plan
maxLength: 50
metadata:
type: object
description: Metadata to be associated with the installment plan. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
nullable: true
organization_account:
type: object
description: (MGA only) The billing account associated to the one time payment. This can represent either the wholesaler or the retail agency.
nullable: true
properties:
id:
type: string
format: uuid
description: The unique identifier of the billing account associated to the one time payment.
users:
type: array
description: An array of user ids belonging to the billing account who should receive communications for the installment plan.
items:
type: string
format: uuid
required:
- insured_id
- account_manager_id
- memo
- installments
/v1/installment_plans/{id}:
parameters:
- name: id
in: path
description: The id of the installment plan
required: true
schema:
type: string
delete:
summary: Archive Installment Plan
tags:
- InstallmentPlans
operationId: archiveInstallmentPlan
security:
- bearer_auth: []
description: Archives a unpurchased installment plan. This will void all installments.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: Installment Plan Archived
'422':
description: unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
get:
summary: Get installment plan
tags:
- InstallmentPlans
security:
- bearer_auth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: success
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
patch:
summary: Update Installment Plan
tags:
- InstallmentPlans
operationId: updateInstallmentPlan
security:
- bearer_auth: []
parameters: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
requestBody:
content:
application/json:
schema:
properties:
account_manager_id:
type: string
format: uuid
description: Id of the account manager who will receive the email communications for the installment plan
metadata:
type: object
description: Metadata to be associated with the installment plan. Keys cannot be longer than 40 characters, cannot contain [] or {}, and the entire metadata object must be less than 5kB.
nullable: true
secondary_account_manager_id:
type: string
format: uuid
description: Id of the secondary account manager who will receive the same email communications for the installment plan as the account manager
organization_account:
type: object
description: (MGA only) The billing account associated to the installment plan. This can represent either the wholesaler or the retail agency.
properties:
users:
type: array
description: An array of user ids belonging to the billing account who should receive communications for the installment plan.
items:
type: string
format: uuid
type: object
/v1/installment_plans/{id}/cancel:
parameters:
- name: id
in: path
description: The id of the installment plan
required: true
schema:
type: string
post:
summary: Cancel Installment Plan
tags:
- InstallmentPlans
operationId: cancelInstallmentPlan
security:
- bearer_auth: []
description: Cancels a purchased installment plan. This will void any unpaid installments, but existing payments will not be reversed.
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
'422':
description: unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/InstallmentPlan'
/v1/installment_plans/{id}/send:
parameters:
- name: id
in: path
description: The id of the installment plan
required: true
schema:
type: string
post:
summary: Notify User
tags:
- InstallmentPlans
operationId: sendInstallmentPlanReminder
security:
- bearer_auth: []
responses:
'200':
description: successful
components:
schemas:
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
InstallmentPlan:
type: object
description: An installment plan for a series of payments
properties:
id:
type: string
format: uuid
description: Id of the installment plan
account_manager:
$ref: '#/components/schemas/User'
secondary_account_manager:
$ref: '#/components/schemas/User'
nullable: true
autopay_enabled:
type: boolean
description: Whether autopay is enabled for the installment plan.
readOnly: true
billing_type:
type: string
enum:
- agency_bill
- direct_bill
description: (MGA only) The type of billing used for this one time payment.
documents:
type: array
nullable: true
description: A collection of documents associated with the installment plan.
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.
installments:
type: array
description: ''
items:
type: object
description: ''
properties:
id:
type: string
format: uuid
description: Id of the installment
status:
type: string
enum:
- awaiting_payment
- processing_payment
- paid
- overdue
- void
description: Status of the installment
due_date:
type: string
format: date
description: 'Due date of the installment. Format: YYYY-MM-DD'
payables:
type: array
description: Payables paid to your organization
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
account_type:
type: string
enum:
- trust_account
- commission_account
description: The type of the bank account that will receive funds
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
company_payables:
type: array
description: Payables paid to the issuing or billing company
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
identifier:
type: string
description: Identifier of the issuing or billing company
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
organization_account_payables:
type: array
description: Payables to partner agencies
items:
type: object
properties:
amount_cents:
type: integer
description: Amount to be paid
organization_account_id:
type: string
description: Organization account id for the partner agency
remittance_memo:
type: string
description: Remittance memo such as the policy number to identify the payable
maxLength: 50
insured_id:
type: string
format: uuid
description: Id of the insured responsible for installment payments
memo:
type: string
description: Short description for the installment plan
maxLength: 50
metadata:
type: object
description: Metadata associated with the installment plan.
nullable: true
organization_account_id:
type: string
format: uuid
description: (MGA only) The unique identifier of the organization account associated with this one time payment.
nullable: true
securitySchemes:
bearer_auth:
type: http
scheme: bearer