Ascend's REST API for insurance financial operations — billing & invoicing, premium financing, installment plans, payments, insureds, programs, billables, loans, payouts, and refunds. Bearer-token authenticated; HMAC-signed webhooks for invoice, payout, and refund events.
openapi: 3.0.1
info:
title: Ascend API V1
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: Attachments
description: Represents a file that is associated with a program.
- name: Billables
description: Represents an insurance quote or endorsement to be billed to the insured.
- name: CancelationReturns
description: Represents the cancelation of an insurance quote
- name: Carriers
description: Represents the carriers Ascend supports for quote creation.
- name: Contacts
description: Represents the contacts that may be associated with an Insured account.
- name: CoverageTypes
description: Represents the coverage types Ascend supports for quote creation.
- name: FinanceEstimate
description: Estimated financing terms.
- name: InstallmentPlans
description: A payment plan broken down over a seriies of regular installments
- name: Installments
description: An single installment on a installment plan
- name: Insureds
description: Represents the person or business entity that is purchasing the collection of insurance quotes.
- name: Invoices
description: Represents records of a transaction between the insured and Ascend.
- name: Loans
description: Loan details for a financed program
- name: OneTimePayments
description: Represents records of a transaction between an insured and an agency or MGA.
- name: Payouts
description: Money transfers between accounts triggered after an insured pays a quote.
- name: PremiumReducingEndorsements (Beta)
description: Represents a premium reducing endorsement for an insurance quote.
- name: Programs
description: A collection of insurance quotes pooled to produce 1 checkout link.
- name: Refunds
description: A collection of refunds to the insured.
- name: Returns
description: A collection of returns on one time payments or installment plans.
- name: Users
description: Represent users that manage programs. They can be analysts, producers, support & admins.
paths:
/v1/accounts:
get:
summary: List Accounts
tags:
- Accounts
security:
- bearer_auth: []
parameters:
- name: updated_at
in: query
style: deepObject
explode: true
description: Only return accounts 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 accounts 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: List accounts
post:
summary: Create Accounts
tags:
- Accounts
security:
- bearer_auth: []
parameters: []
responses:
'201':
description: Create a new account
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'400':
description: Contact email domain matches an owner organization admin's domain
content:
application/json:
examples:
contact_email_domain_matches_owner_admin:
value:
errors:
- status: 400
title: Bad Request
detail: 'Contact email domain ''test.com'' is not allowed: it matches a domain used by an admin of the
owner organization.'
source: {}
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: integer
example: 400
title:
type: string
example: Bad Request
detail:
type: string
source:
type: object
requestBody:
content:
application/json:
schema:
type: object
description: Request schema for an organization account creation or details.
properties:
organization_account:
type: object
properties:
contact:
type: object
properties:
first_name:
type: string
description: Contact person's first name
last_name:
type: string
description: Contact person's last name
email:
type: string
description: Contact person's email address
required:
- first_name
- last_name
- email
agency:
type: object
properties:
name:
type: string
description: Agency's legal name
doing_business_as:
type: string
description: Agency's trade or assumed name used by the agency for business purposes
phone:
type: string
description: Agency's contact phone number
federal_tax_identification_number:
type: string
description: Agency's federal tax identification number
business_type:
type: string
enum:
- sole_proprietorship
- partnership
- corporation
- llc
- non_profit
description: Agency's business type
url:
type: string
description: Agency's website URL
mailing_address:
type: object
properties:
street_one:
type: string
description: Mailing address street line one
street_two:
type: string
description: Mailing address street line two
city:
type: string
description: Mailing address city
state:
type: string
description: Mailing address state
zip_code:
type: string
description: Mailing address zip/postal code
required:
- street_one
- city
- state
- zip_code
required:
- name
- phone
- mailing_address
default_seller_commission_rate:
type: number
description: Default commission rate for the seller, expressed as a decimal (e.g., 0.05 for 5%)
default_account_fees_cents:
type: number
description: Required for Direct bill. Default account fee for the seller. Expressed in cents (e.g.,
1000 for $10.00)
payment_schedule:
type: string
enum:
- daily
- bi-weekly
- weekly
- monthly
description: Required for Direct bill. This is the schedule in which the agency would receive their
commission.
payment_settlement_period_max_days:
type: number
description: Maximum number of days for payment settlement period. Required for Direct bill.
billing_type:
type: string
description: Billing type for the agency
enum:
- agency
- direct
payable_account:
type: object
description: The account where the agency would receive their commissions
properties:
account_holder_name:
type: string
description: Name of the account holder
account_holder_type:
type: string
description: Type of account holder (e.g., individual or company)
enum:
- individual
- company
account_number:
type: string
description: Bank account number
confirm_account_number:
type: string
description: Confirmation of the bank account number
account_type:
type: string
enum:
- bank_account
- check
description: Type of account (e.g., bank account, check)
routing_number:
type: string
description: Bank routing number
required:
- account_holder_name
- account_holder_type
- account_number
- confirm_account_number
- account_type
- routing_number
required:
- contact
- agency
- default_seller_commission_rate
- billing_type
required:
- organization_account
/v1/accounts/{id}:
parameters:
- name: id
in: path
description: Account identifier
required: true
schema:
type: string
get:
summary: Get account
tags:
- Accounts
security:
- bearer_auth: []
responses:
'200':
description: found
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
patch:
summary: Update account
tags:
- Accounts
security:
- bearer_auth: []
parameters: []
responses:
'200':
description: found
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
requestBody:
content:
application/json:
schema:
type: object
properties:
organization_account:
type: object
properties:
default_seller_commission_rate:
type: number
description: Default commission rate for the seller, expressed as a decimal (e.g., 0.05 for 5%)
default_account_fees_cents:
type: number
description: Required for Direct bill. Default account fee for the seller. Expressed in cents (e.g.,
1000 for $10.00)
required:
- organization_account
/v1/attachments:
post:
summary: Create attachment
tags:
- Attachments
operationId: createAttachment
security:
- bearer_auth: []
parameters: []
responses:
'201':
description: Attachment created
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: File to upload
title:
type: string
description: Title of the attachment
visibility:
type: string
enum:
- public
- private
description: Determines who can see this document. When visibility is set to public, anyone with access
to public urls such as checkout url will be able to see these documents. When visibility is set to private,
only users from your organization will be able to see the documents.
required:
- file
- title
- visibility
/v1/attachments/{id}:
parameters:
- name: id
in: path
description: The attachment identifier
required: true
schema:
type: string
delete:
summary: Delete Attachments
security:
- bearer_auth: []
operationId: deleteAttachment
tags:
- Attachments
responses:
'204':
description: Attachment deleted
'404':
description: Attachments not found
get:
summary: Get attachment
tags:
- Attachments
operationId: getAttachment
security:
- bearer_auth: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/Attachment'
'404':
description: Attachment not found
/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
format: integer
nullable: true
description: The commission amount for this entity in cents. One of `commission_cents` or `commission_rate`
is required.
commission_rate:
type: number
format: float
nullable: true
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
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.
nullable: true
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
format: integer
nullable: true
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
format: float
nullable: true
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
format: integer
nullable: true
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
format: float
nullable: true
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
format: integer
nullable: true
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
format: float
nullable: true
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
nullable: true
prev:
type: string
nullable: true
/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
# --- truncated at 32 KB (211 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ascend/refs/heads/main/openapi/ascend-openapi-original.yml