openapi: 3.0.1 info: title: Ascend API V1 Accounts Insureds 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: Insureds description: Represents the person or business entity that is purchasing the collection of insurance quotes. paths: /v1/insureds: post: summary: Create Insured tags: - Insureds operationId: createInsured security: - bearer_auth: [] parameters: [] responses: '201': description: successful - multiple contact format content: application/json: schema: $ref: '#/components/schemas/Insured' '400': description: Bad Request '404': description: Customer Contact not found requestBody: content: application/json: schema: type: object description: At least one primary insured or agency contact required properties: insured_contacts: type: array items: type: object properties: id: type: string format: uuid description: UUID of the insured contact role: type: string enum: - primary - secondary description: Primary role indicates primary contact for insured account. Only one primary contact is allowed per account. required: - id - role business_name: type: string description: If the insured is a business, the 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. mailing_address_street_one: type: string description: Mailing Street address mailing_address_street_two: type: string description: Suite or unit mailing_address_city: type: string description: Mailing city mailing_address_state: $ref: '#/components/schemas/StateAnsiCodes' mailing_address_zip_code: type: string description: Mailing zip code required: - is_business - mailing_address_city - mailing_address_state - mailing_address_street_one - mailing_address_zip_code get: summary: List Insureds tags: - Insureds operationId: listInsureds security: - bearer_auth: [] parameters: - name: page in: query schema: type: integer - name: email in: query required: false description: Filter by associated email schema: type: string - name: business_name in: query required: false description: Search by business name schema: type: string responses: '200': description: successful /v1/insureds/{id}: parameters: - name: id in: path description: The insured identifier required: true schema: type: string get: summary: Get Insured tags: - Insureds operationId: getInsured security: - bearer_auth: [] responses: '200': description: successful content: application/json: schema: $ref: '#/components/schemas/Insured' patch: summary: Update Insured tags: - Insureds operationId: updateInsured security: - bearer_auth: [] parameters: [] responses: '200': description: successful content: application/json: schema: $ref: '#/components/schemas/Insured' '400': description: Bad Request requestBody: content: application/json: schema: type: object properties: insured_contacts: description: Updating contacts for an insured will override all existing contacts type: array items: type: object properties: id: type: string format: uuid description: UUID of the insured contact role: type: string enum: - primary - secondary description: Primary role indicates primary contact for insured account. Only one primary contact is allowed per account. required: - id - role business_name: type: string 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. mailing_address_street_one: type: string description: Mailing Street address mailing_address_street_two: type: string description: Suite or unit mailing_address_city: type: string description: Mailing city mailing_address_state: $ref: '#/components/schemas/StateAnsiCodes' mailing_address_zip_code: type: string description: Mailing zip code required: - is_business - mailing_address_city - mailing_address_state - mailing_address_street_one - mailing_address_zip_code /v1/insureds/{id}/payment_methods: parameters: - name: id in: path description: The id of the insured required: true schema: type: string format: uuid get: summary: List the insured's last-used payment method tags: - Insureds operationId: listInsuredPaymentMethods security: - bearer_auth: [] parameters: - name: page in: query required: false schema: type: integer - name: items in: query required: false schema: type: integer responses: '200': description: successful - empty when no succeeded payment intent exists content: application/json: schema: $ref: '#/components/schemas/PaymentMethod' '401': description: unauthorized content: application/json: schema: type: object properties: errors: type: array '404': description: insured belongs to another organization content: application/json: schema: type: object properties: errors: type: array components: schemas: 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 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 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 securitySchemes: bearer_auth: type: http scheme: bearer