Canopy Accounts API

openapi: 3.2.0
info:
  title: Canopy Servicing Core Accounts API
  description: 'Canopy allows you to easily manage credit, installment, or other more complex lending programs from a servicing and compliance perspective -

    whether newly launched or migrated from existing systems. using canopy, you can track balances and transactions for each customer of your product, both in real-time and historically.

    You can see how various policy and product changes would impact your customers, and readily generate compliance reports and minimize your risk with all real-time information always on hand.

    Canopy additionally surfaces information around all of your lending activity through its intuitive ui which provides a customer support interface as well as at-a-glance data needed for compliance and insights.

    Simply configure your product`s policies through our create product api endpoint, and then you can immediately begin adding customer accounts and relying on canopy for accurate servicing information.'
  contact:
    name: Canopy Support
    url: https://www.canopyservicing.com/contact
    email: support@canopyservicing.com
  version: 1.0.0
servers:
- url: Contact sales to enable your sandbox
  description: Your private sandbox environment
- url: https://demo-api.us.canopyservicing.com
  description: Demo environment
tags:
- name: Accounts
  description: Manage the way your users use credit products you've launched in Canopy.
paths:
  /core/v1/accounts:
    get:
      tags:
      - Accounts
      summary: Get accounts
      description: 'This endpoint returns a paginated list of accounts.


        Can filter by manual or system generated tags on the account along with being able

        to filter by a text search via the following fields (case-insensitive):

        - account_id

        - borrower''s first name

        - borrower''s last name

        - borrower''s doing_business_as

        - borrower''s business_legal_name'
      operationId: CoreAccountCBV_get_accounts_core_v1_accounts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: starting_after
        in: query
        required: false
        schema:
          type: string
          description: Encoded pagination marker to fetch next page
          title: Starting After
        description: Encoded pagination marker to fetch next page
      - name: ending_before
        in: query
        required: false
        schema:
          type: string
          description: Encoded pagination marker to fetch previous page
          title: Ending Before
        description: Encoded pagination marker to fetch previous page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: Maximum number of records to return
          title: Limit
        description: Maximum number of records to return
      - name: include_tags
        in: query
        required: false
        schema:
          type: boolean
          description: If true, the response will include the tags for each account.
          examples:
          - true
          title: Include Tags
        description: If true, the response will include the tags for each account.
      - name: tag
        in: query
        required: false
        schema:
          type: string
          description: Comma-separated list of tags to filter by, case-insensitive (no whitespaces).
          examples:
          - 1-30 DAYS DELINQUENT,FRAUD
          title: Tag
        description: Comma-separated list of tags to filter by, case-insensitive (no whitespaces).
      - name: text_search
        in: query
        required: false
        schema:
          type: string
          description: Searches by `account_id`, borrower's `name_first`, `name_last`, `doing_business_as` or `business_legal_name`, case-insensitive.
          examples:
          - can_123
          title: Text Search
        description: Searches by `account_id`, borrower's `name_first`, `name_last`, `doing_business_as` or `business_legal_name`, case-insensitive.
      - name: accept
        in: header
        required: false
        schema:
          type: string
          title: Accept
      responses:
        '200':
          description: Returns a paginated list of accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetAccountResponse'
                title: Response Coreaccountcbv Get Accounts Core V1 Accounts Get
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
    post:
      tags:
      - Accounts
      summary: Create a new account
      operationId: CoreAccountCBV_create_account_core_v1_accounts_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
              description: The account to create
      responses:
        '201':
          description: The created account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /core/v1/accounts/{account_id}:
    get:
      tags:
      - Accounts
      summary: Gets the account details for a given account id
      description: Gets the account details for a given account id.
      operationId: AccountCBV_get_account_core_v1_accounts__account_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      responses:
        '200':
          description: The account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountResponse'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /core/v1/accounts/{account_id}/policies:
    get:
      tags:
      - Accounts
      summary: Get policies for a given account
      description: Gets the policies for a given account.
      operationId: AccountCBV_get_account_policies_core_v1_accounts__account_id__policies_get
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: effective_at
        in: query
        required: false
        schema:
          type: string
          title: Effective At
      responses:
        '200':
          description: The account policies and effective date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountPoliciesResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /core/v1/accounts/{account_id}/ownership_transfers:
    post:
      tags:
      - Accounts
      summary: Transfer account ownership to a new organization
      description: Transfer account ownership to a new organization.
      operationId: AccountCBV_post_account_ownership_transfer_core_v1_accounts__account_id__ownership_transfers_post
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAccountOwnershipTransferRequest'
              description: Account Ownership Transfer Information
      responses:
        '200':
          description: Returns details of the updated account organization access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAccountOwnershipTransferResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '409':
          description: Entity already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflictSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
  /core/v1/accounts/{account_id}/payoff_amounts:
    get:
      tags:
      - Accounts
      summary: Get payoff amounts for a given account
      description: Gets the payoff amounts for a given account.
      operationId: AccountCBV_get_account_payoff_amounts_core_v1_accounts__account_id__payoff_amounts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          title: Account Id
      - name: effective_at
        in: query
        required: false
        schema:
          type: string
          title: Effective At
      responses:
        '200':
          description: The account payoff amounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAccountPayoffAmountsResponse'
        '400':
          description: Your request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequestSchema'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFoundSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: A server error has occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrServerErrorSchema'
components:
  schemas:
    TagSchema:
      properties:
        tag_id:
          type: integer
          title: Tag Id
          description: The unique identifier of the tag
          examples:
          - 1
        label:
          type: string
          title: Label
          description: The label of the tag
          examples:
          - Risk review
        description:
          type: string
          title: Description
          description: The description of the tag
          examples:
          - Risky accounts
        color:
          $ref: '#/components/schemas/TagColor'
          description: The color of the tag
          examples:
          - red
        active:
          type: boolean
          title: Active
          description: The active status of the tag
          examples:
          - true
      type: object
      required:
      - label
      - description
      - color
      title: TagSchema
      description: Base response schema for surfacing tag information to the user.
    GetAccountResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The account ID.
          examples:
          - can_123
        effective_at:
          type: string
          title: Effective At
          description: The effective at date of account creation.
          examples:
          - '2021-08-05T20:00:00-04:00'
        external_fields:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: External Fields
          description: The external fields associated with the account.
          examples:
          - external_id: '1234567890'
        borrowers:
          items:
            $ref: '#/components/schemas/GetBorrowerDetailsResponse'
          type: array
          title: Borrowers
          description: The borrowers associated with the account.
        tags:
          items:
            $ref: '#/components/schemas/TagSchema'
          type: array
          title: Tags
          description: The tags associated with the account.
        system_tags:
          items:
            $ref: '#/components/schemas/GetSystemTagResponse'
          type: array
          title: System Tags
          description: The system tags associated with the account.
        originating_organization_name:
          type: string
          title: Originating Organization Name
          description: The name of the organization that originated the account.
          examples:
          - Acme Corporation
        current_owner_organization_name:
          type: string
          title: Current Owner Organization Name
          description: The name of the organization that owns the account.
          examples:
          - Acme Corporation
      type: object
      required:
      - account_id
      - effective_at
      - external_fields
      - borrowers
      - tags
      - system_tags
      title: GetAccountResponse
    CreateAccountRequest:
      properties:
        product_id:
          type: string
          title: Product Id
          description: The product id to use for this account
          examples:
          - can_1
          hidden: false
        account_id:
          type: string
          title: Account Id
          description: The account id to use for this account. If not provided, a new account id will be generated.
          examples:
          - 123e4567-e89b-12d3-a456-426614174000
        template_id:
          type: string
          title: Template Id
          description: The template id to use for this account
          examples:
          - can_1
          hidden: false
        assign_borrowers:
          items:
            $ref: '#/components/schemas/AssignBorrower'
          type: array
          title: Assign Borrowers
          description: The borrowers to assign to this account. If not provided, a secondary call will be needed to assign a borrower to the account.
        external_fields:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: External Fields
          description: The external fields to use for this account. If not provided, a secondary call will be needed to assign external fields to the account.
          examples:
          - lender_system_id: '1234567890'
          hidden: false
        originating_organization_name:
          type: string
          title: Originating Organization Name
          description: The name of the organization that originated the account. If not provided, defaults to the calling user's organization name.
          examples:
          - Acme Corporation
      type: object
      required:
      - product_id
      - template_id
      title: CreateAccountRequest
    AccountFeePolicies:
      properties:
        immediate_late_fee_accrual:
          type: boolean
          title: Immediate Late Fee Accrual
          default: true
        late_fee_cap_percent:
          type: number
          title: Late Fee Cap Percent
        late_fee_cents:
          type: integer
          title: Late Fee Cents
          default: 0
      type: object
      title: AccountFeePolicies
    TagColor:
      type: string
      enum:
      - red
      - orange
      - yellow
      - green
      - blue
      - purple
      - pink
      - sky
      - teal
      - gray
      - black
      title: TagColor
      description: Enum for the colors of tags.
    ErrBadRequestSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Your request is invalid.
      type: object
      required:
      - message
      title: ErrBadRequestSchema
    PayoffAmounts:
      properties:
        payoff_amount_cents:
          type: integer
          title: Payoff Amount Cents
          description: The total payoff amount in cents.
          examples:
          - 100100
        unpaid_amounts_breakdown:
          $ref: '#/components/schemas/BalanceBreakdownCentsOutput'
          description: The unpaid balances.
        unposted_interest_cents:
          type: integer
          title: Unposted Interest Cents
          description: The accrued interest for the current period in cents that has not yet been posted.
          examples:
          - 100
      type: object
      required:
      - payoff_amount_cents
      - unpaid_amounts_breakdown
      - unposted_interest_cents
      title: PayoffAmounts
    PostAccountOwnershipTransferRequest:
      properties:
        new_owner_organization_name:
          type: string
          title: New Owner Organization Name
          description: The name of the new organization to transfer the account to.
          examples:
          - Acme Corporation
      type: object
      required:
      - new_owner_organization_name
      title: PostAccountOwnershipTransferRequest
    BorrowerAccountRole:
      type: string
      enum:
      - PRIMARY
      - SECONDARY
      title: BorrowerAccountRole
    AccountTaggingPolicies:
      properties:
        enable_persistent_debt_evaluation:
          type: boolean
          title: Enable Persistent Debt Evaluation
          default: false
      type: object
      title: AccountTaggingPolicies
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BalanceBreakdownCentsOutput:
      properties:
        principal_amount_cents:
          type: integer
          title: Principal Amount Cents
        interest_amount_cents:
          type: integer
          title: Interest Amount Cents
        fee_amount_cents:
          type: integer
          title: Fee Amount Cents
        total_cents:
          type: integer
          title: Total Cents
          readOnly: true
      type: object
      required:
      - principal_amount_cents
      - interest_amount_cents
      - fee_amount_cents
      - total_cents
      title: BalanceBreakdownCentsOutput
      description: Balance Breakdown exposed to customers in API responses
    ErrConflictSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Entity already exists.
      type: object
      required:
      - message
      title: ErrConflictSchema
    GetSystemTagResponse:
      properties:
        tag_id:
          type: integer
          title: Tag Id
          description: The ID of the tag
          examples:
          - 1
        label:
          type: string
          title: Label
          description: The label of the tag
          examples:
          - 1-30 days delinquent
        description:
          type: string
          title: Description
          description: The description of the tag
          examples:
          - Customer is in the 1-30 days delinquency bucket.
        color:
          $ref: '#/components/schemas/TagColor'
          description: The color of the tag
          examples:
          - yellow
        category:
          $ref: '#/components/schemas/TagCategory'
          description: The category of the tag
          examples:
          - DELINQUENCY_BUCKETS
        active:
          type: boolean
          title: Active
          description: The active status of the tag
          examples:
          - true
      type: object
      required:
      - tag_id
      - label
      - description
      - color
      - category
      - active
      title: GetSystemTagResponse
      description: Response schema for the get system tags endpoint.
    GetBorrowerDetailsResponse:
      properties:
        borrower_id:
          type: string
          title: Borrower Id
          description: The borrower's ID.
          examples:
          - 123e4567-e89b-12d3-a456-426614174000
        external_borrower_id:
          type: string
          title: External Borrower Id
          description: The borrower's external ID.
          examples:
          - 123e4567-e89b-12d3-a456-426614174000
        is_active:
          type: boolean
          title: Is Active
          description: Field to indicate if the borrower is active.
          examples:
          - true
        name_first:
          type: string
          title: Name First
          description: Borrower's first name.
          examples:
          - John
        name_last:
          type: string
          title: Name Last
          description: Borrower's last name.
          examples:
          - Doe
        doing_business_as:
          type: string
          title: Doing Business As
          description: The DBA name of the Business.
          examples:
          - Doe's Auto
        business_legal_name:
          type: string
          title: Business Legal Name
          description: The legal name of the Business.
          examples:
          - Doe's Auto Repair
      type: object
      required:
      - borrower_id
      - external_borrower_id
      - is_active
      title: GetBorrowerDetailsResponse
    PostAccountOwnershipTransferResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The ID of the account that was transferred to a new organization.
          examples:
          - can_123
        new_owner_organization_name:
          type: string
          title: New Owner Organization Name
          description: The name of the organization the account was transferred to.
          examples:
          - Acme Corporation
        previous_owner_organization_name:
          type: string
          title: Previous Owner Organization Name
          description: The name of the organization that previously owned the account.
          examples:
          - Acme Corporation
        originating_organization_name:
          type: string
          title: Originating Organization Name
          description: The name of the organization that originated the account.
          examples:
          - Acme Corporation
        effective_at:
          type: string
          title: Effective At
          description: The effective date of the account ownership transfer.
          examples:
          - '2021-01-01T00:00:00Z'
      type: object
      required:
      - account_id
      - new_owner_organization_name
      - effective_at
      title: PostAccountOwnershipTransferResponse
    TagCategory:
      type: string
      enum:
      - COLLATERAL_LIQUIDATION
      - CREDIT_UTILIZATION
      - DELINQUENCY_BUCKETS
      - DISPUTE_STATUS
      - GRADUATION
      - MISSED_PAYMENT
      - PAYMENT_DEFERRAL
      - PERSISTENT_DEBT
      - TEST_CATEGORY
      title: TagCategory
    GetAccountPayoffAmountsResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: "\n        The account id associated with the imputed interest calculation.\n        "
        effective_at:
          type: string
          title: Effective At
          description: "\n        The effective timing of the payoff response.\n        "
        account_aggregate:
          $ref: '#/components/schemas/PayoffAmounts'
          description: "\n        Account-level aggregations of payoff amounts.\n        "
        payoff_amounts_by_loan:
          additionalProperties:
            $ref: '#/components/schemas/PayoffAmounts'
          type: object
          title: Payoff Amounts By Loan
          description: "\n        Payoff amounts for each loan.\n        "
      type: object
      required:
      - account_id
      - effective_at
      - account_aggregate
      - payoff_amounts_by_loan
      title: GetAccountPayoffAmountsResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    GetAccountPoliciesResponse:
      properties:
        timezone:
          type: string
          title: Timezone
          description: The timezone of the account
          default: America/Los_Angeles
        effective_at:
          type: string
          title: Effective At
          description: The effective date of the policies
        fee_policies:
          $ref: '#/components/schemas/AccountFeePolicies'
          default:
            immediate_late_fee_accrual: true
            late_fee_cents: 0
        tagging_policies:
          $ref: '#/components/schemas/AccountTaggingPolicies'
          default:
            enable_persistent_debt_evaluation: false
        account_id:
          type: string
          title: Account Id
      type: object
      required:
      - account_id
      title: GetAccountPoliciesResponse
    ErrNotFoundSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - Entity not found.
      type: object
      required:
      - message
      title: ErrNotFoundSchema
    CreateAccountResponse:
      properties:
        account_id:
          type: string
          title: Account Id
          description: The account id.
        effective_at:
          type: string
          title: Effective At
          description: The effective at date of account creation.
        external_fields:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              additionalProperties: true
              type: object
            type: array
          - items: {}
            type: array
          title: External Fields
          description: The external fields associated with the account.
        borrowers:
          items:
            $ref: '#/components/schemas/GetBorrowerDetailsResponse'
          type: array
          title: Borrowers
          description: The borrowers associated with the account.
        originating_organization_name:
          type: string
          title: Originating Organization Name
          description: The name of the organization that originated the account.
          examples:
          - Acme Corporation
        current_owner_organization_name:
          type: string
          title: Current Owner Organization Name
          description: The name of the organization that owns the account.
          examples:
          - Acme Corporation
      type: object
      required:
      - account_id
      - effective_at
      - external_fields
      - borrowers
      title: CreateAccountResponse
    ErrServerErrorSchema:
      properties:
        message:
          type: string
          title: Message
          description: The error message
          examples:
          - A server error has occurred.
      type: object
      required:
      - message
      title: ErrServerErrorSchema
    AssignBorrower:
      properties:
        borrower_id:
          type: string
          title: Borrower Id
          description: The borrower id to assign to this account
          examples:
          - 123e4567-e89b-12d3-a456-426614174000
          hidden: false
        borrower_account_id:
          type: string
          title: Borrower Account Id
          description: The borrower account id to assign to this account. If not provided, a new borrower account id will be generated.
          examples:
          - can_1
        borrower_account_role:
          $ref: '#/components/schemas/BorrowerAccountRole'
          description: The role of the borrower in this account. If not provided, the borrower will be assigned as a secondary borrower.
          examples:
          - PRIMARY
          - SECONDARY
      type: object
      required:
      - borrower_id
      title: AssignBorrower
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer