Ascend Billables API
Represents an insurance quote or endorsement to be billed to the insured.
OpenAPI Specification
openapi: 3.0.1
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
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 of earned premium when insured cancels. Cannot be set when billable is of type endorsement.
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_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
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: 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
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
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
description: Mailing Street address
nullable: true
mailing_address_street_two:
type: string
description: Suite or unit
nullable: true
mailing_address_city:
type: string
description: Mailing city
nullable: true
mailing_address_state:
$ref: '#/components/schemas/StateAnsiCodes'
nullable: true
mailing_address_zip_code:
type: string
description: Mailing zip code
nullable: true
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
nullable: true
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
format: date
nullable: true
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
description: The display name of the static asset.
nullable: true
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
nullable: true
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
nullable: true
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
format: float
nullable: true
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:
nullable: true
allOf:
- $ref: '#/components/schemas/Wholesaler'
metadata:
type: object
description: Metadata associated with the billable.
nullable: true
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.
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
description: Mailing Street address
nullable: true
mailing_address_street_two:
type: string
description: Suite or unit
nullable: true
mailing_address_city:
type: string
description: Mailing city
nullable: true
mailing_address_state:
$ref: '#/components/schemas/StateAnsiCodes'
nullable: true
mailing_address_zip_code:
type: string
description: Mailing zip code
nullable: true
securitySchemes:
bearer_auth:
type: http
scheme: bearer