nCino Borrowers API

openapi: 3.2.0
info:
  title: nCino Mortgage Borrowers API
  description: API framework built from the ground up to be more a robust, forward thinking solution with tools to support our developer community
  version: '1.0'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.ncinomortgage.com
  description: Production server
security:
- OAuth2: []
tags:
- name: Borrowers
  description: Endpoints pertaining to <<glossary:borrower account>>s in the nCino Mortgage platform
paths:
  /users/borrowers:
    post:
      tags:
      - Borrowers
      operationId: borrowers-create
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '201':
          description: Created borrower account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '409':
          description: Borrower account already exists for the given email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'This endpoint will create a <<glossary:borrower account>> in the platform.


        The borrower will use this information to register or log in to their account on the specified <<glossary:loan officer>>''s shared application.

        > 🙇 Heads up!

        **This record is not to be confused with a <<glossary:loan borrower>> record,** which is directly associated with and created through a loan or loan application.'
      summary: Create a borrower account
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBorrowerPostBody'
    get:
      tags:
      - Borrowers
      operationId: borrowers-index
      parameters:
      - name: email
        description: Email by which to filter borrower accounts.
        required: false
        in: query
        schema:
          type: string
      - name: has_custom_consent
        description: Consent status by which to filter borrower accounts.
        required: false
        in: query
        schema:
          type: boolean
      - name: is_active
        description: Status by which to filter borrower accounts.
        required: false
        in: query
        schema:
          type: boolean
      - name: loan_officer_id
        description: Loan officer's ID by which to filter borrower accounts.
        required: false
        in: query
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/CreatedAfter'
      - $ref: '#/components/parameters/CreatedBefore'
      - $ref: '#/components/parameters/UpdatedAfter'
      - $ref: '#/components/parameters/UpdatedBefore'
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBorrowerPagination'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'This endpoint will retrieve all <<glossary:borrower account>>s for the company.


        To filter the scope of records returned, leverage one or more of the query params found below. `Email` is a common parameter by which to filter.


        By default, all borrower accounts are returned regardless of `is_active` status.'
      summary: Retrieve all borrower accounts
  /users/borrowers/{user_borrower_id}:
    get:
      tags:
      - Borrowers
      operationId: borrowers-show
      parameters:
      - name: user_borrower_id
        description: Borrower account ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBorrower'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: This endpoint will retrieve a single <<glossary:borrower account>>.
      summary: Retrieve a borrower account
    patch:
      tags:
      - Borrowers
      operationId: borrowers-update
      parameters:
      - name: user_borrower_id
        description: Borrower account ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '204':
          description: Successfully updated borrower account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoContent'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '409':
          description: Borrower account already exists for the given email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'This endpoint will update any data provided via body params on the <<glossary:borrower account>>. Only the body params listed maybe be used.


        Passing an empty body will result in a successful request but no changes in data.

        > 🙇 Heads up!

        **Email addresses may NOT be reused across borrower accounts.** Every borrower account must have a unique email address.'
      summary: Update a borrower account
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBorrowerPatchBody'
    delete:
      tags:
      - Borrowers
      operationId: borrowers-destroy
      parameters:
      - name: user_borrower_id
        description: Borrower account ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '204':
          description: Successfully deleted borrower account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoContent'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'This endpoint will delete a <<glossary:borrower account>>.


        > 🙇 Heads up!

        **This action will delete all loan applications attached to the borrower account and thus should be considered an irreversible action.**'
      summary: Delete a borrower account
  /users/borrowers/{user_borrower_id}/actions:
    post:
      tags:
      - Borrowers
      operationId: borrowers-actions
      parameters:
      - name: user_borrower_id
        description: Borrower account ID.
        required: true
        in: path
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ApiVersionHeader'
      responses:
        '204':
          description: No content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoContent'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '412':
          description: Resource is in an invalid state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '409':
          description: An association already exists for the borrower account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSet'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '201':
          description: Created borrower account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCreated'
          headers:
            X-Api-Version:
              $ref: '#/components/headers/ApiVersionResponseHeader'
            X-Api-Supported-Versions:
              $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      description: 'This endpoint allows a variety of actions to be taken on a <<glossary:borrower account>>.


        > 📌 Available actions

        **SEND_WELCOME_EMAIL** - Resend welcome email

        **REASSIGN_LO** - Reassign borrower account to a different loan officer. Applications for the indicated borrower account may be reassigned to the new <<glossary:loan officer>>.

        If existing applications are not reassigned or loan records are associated with the borrower account then a new borrower account will be created.

        <<glossary:Partner>> information will be removed during the reassignment and will need to be reestablished through a borrower account update.

        To update the association of a loan officer and borrower account on a loan record, update the loan officer on the loan record.

        **ASSIGN_PARTNER** - Assign partner to borrower account

        **REMOVE_PARTNER** - Unassign partner from borrower account


        The `action` property must be one of the available actions above, provided in the JSON as screaming snake case.'
      summary: Perform action on a borrower account
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/SendWelcomeEmailUserBorrower'
              - $ref: '#/components/schemas/ReassignLoUserBorrower'
              - $ref: '#/components/schemas/AssignPartnerUserBorrower'
              - $ref: '#/components/schemas/RemovePartnerUserBorrower'
              discriminator:
                propertyName: action
                mapping:
                  SEND_WELCOME_EMAIL: '#/components/schemas/SendWelcomeEmailUserBorrower'
                  REASSIGN_LO: '#/components/schemas/ReassignLoUserBorrower'
                  ASSIGN_PARTNER: '#/components/schemas/AssignPartnerUserBorrower'
                  REMOVE_PARTNER: '#/components/schemas/RemovePartnerUserBorrower'
components:
  schemas:
    ReassignLoUserBorrower:
      allOf:
      - $ref: '#/components/schemas/UserBorrowerAction'
      - type: object
        properties:
          loan_officer_id:
            type: string
            format: uuid
            description: Loan officer's ID to which the borrower account will be reassigned.
          reassign_apps:
            type: boolean
            description: Whether to reassign all existing loan applications to the provided loan officer (default is false).
        required:
        - loan_officer_id
        additionalProperties: false
      description: Available properties for reassigning an LO to a borrower account.
    SendWelcomeEmailUserBorrower:
      allOf:
      - $ref: '#/components/schemas/UserBorrowerAction'
      description: Available properties for sending a welcome email to a borrower.
    UserBorrowerPagination:
      allOf:
      - $ref: '#/components/schemas/AbstractPagination'
      - type: object
        properties:
          contents:
            type: array
            items:
              $ref: '#/components/schemas/UserBorrower'
        required:
        - contents
    AbstractResourceModel:
      allOf:
      - $ref: '#/components/schemas/AbstractModel'
      - type: object
        properties:
          id:
            type: string
            format: uuid
            description: Unique identifier for the record.
        required:
        - id
        additionalProperties: false
    NoContent:
      type: object
      properties: {}
      additionalProperties: false
    Error:
      type: object
      properties:
        id:
          type: string
          description: A unique ID (useful as a reference when debugging an error with support)
        status:
          type: integer
          description: The HTTP status code
        title:
          type: string
          description: A generic title
        detail:
          type: string
          description: A detailed message
        _links:
          type: object
          description: A list of relevant links
      required:
      - id
      - status
      - title
      example:
        id: 123abc
        status: 400
        title: Generic title for the error
        detail: Detailed message for the error
        _links:
          resource: contextual resource if applicable
    ResourceCreated:
      allOf:
      - $ref: '#/components/schemas/AbstractResourceModel'
      description: Resource created model
    UserBorrower:
      allOf:
      - $ref: '#/components/schemas/AbstractResourceModel'
      - type: object
        properties:
          created_at:
            type: string
            format: date-time
            description: Timestamp of when the borrower record was created.
          updated_at:
            type: string
            format: date-time
            description: Timestamp of when the borrower record was last updated.
          first_name:
            type: string
            description: Borrower's first name.
          last_name:
            type: string
            description: Borrower's last name.
          email:
            type: string
            description: Borrower's email.
          phone:
            type:
            - string
            - 'null'
            description: Borrower's phone.
          is_active:
            type: boolean
            description: Whether the borrower is active in the system.
          custom_consent:
            type: boolean
            description: Whether the borrower has given custom consent.
        required:
        - first_name
        - last_name
        - email
        additionalProperties: false
      description: Borrower model
    AbstractModel:
      type: object
      properties:
        _self:
          type: string
          description: The model's resource link to itself.
        _type:
          type: string
          description: The model's type.
        _links:
          type: object
          description: A list of links for the model's associations.
      required:
      - _self
      - _type
      additionalProperties: false
    RemovePartnerUserBorrower:
      allOf:
      - $ref: '#/components/schemas/UserBorrowerAction'
      description: Available properties for removing a partner from a borrower account.
    ErrorSet:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      required:
      - errors
      example:
        errors:
        - id: 123abc
          status: 400
          title: Generic title for the error
          detail: Detailed message for the error
          _links:
            resource: contextual resource if applicable
    UserBorrowerAction:
      type: object
      properties:
        action:
          type: string
          enum:
          - SEND_WELCOME_EMAIL
          - REASSIGN_LO
          - ASSIGN_PARTNER
          - REMOVE_PARTNER
          description: Action to perform.
      required:
      - action
      description: Available properties for a borrower account action.
      additionalProperties: false
    UserBorrowerPatchBody:
      type: object
      properties:
        first_name:
          type: string
          minLength: 1
          maxLength: 30
          description: Borrower's first name.
        last_name:
          type: string
          minLength: 1
          maxLength: 30
          description: Borrower's last name.
        email:
          type: string
          format: email
          maxLength: 255
          description: Borrower's email.
        phone:
          type: string
          format: phone
          description: Borrower's phone.
        custom_consent:
          type: boolean
          description: Whether the borrower has opted in to custom consent.
      description: Available properties for updating a borrower account.
      additionalProperties: false
      minProperties: 1
    AbstractPagination:
      allOf:
      - $ref: '#/components/schemas/AbstractCollection'
      - type: object
        properties:
          total_pages:
            type: integer
            description: The total number of pages in the collection.
          total:
            type: integer
            description: The total number of items in the collection.
        additionalProperties: false
    UserBorrowerPostBody:
      type: object
      properties:
        first_name:
          type: string
          minLength: 1
          maxLength: 30
          description: Borrower's first name.
        last_name:
          type: string
          minLength: 1
          maxLength: 30
          description: Borrower's last name.
        email:
          type: string
          format: email
          maxLength: 255
          description: Borrower's email.
        phone:
          type: string
          format: phone
          description: Borrower's phone.
        loan_officer_id:
          type: string
          format: uuid
          description: Loan officer's ID to which the borrower account will be assigned. Required unless the "Optional Loan Officer on Borrower Creation" feature setting is enabled, in which case the default LO profile will be used if it is omitted.
        partner_id:
          type: string
          format: uuid
          description: Partner's ID to which the borrower account will be assigned.
      required:
      - first_name
      - last_name
      - email
      description: Available properties for creating a borrower account.
      additionalProperties: false
    AbstractCollection:
      allOf:
      - $ref: '#/components/schemas/AbstractModel'
      - type: object
        properties:
          contents:
            type: array
            items:
              type: object
            description: The contents for the collection.
        required:
        - contents
        additionalProperties: false
    AssignPartnerUserBorrower:
      allOf:
      - $ref: '#/components/schemas/UserBorrowerAction'
      - type: object
        properties:
          partner_id:
            type: string
            format: uuid
            description: Partner's ID to which the borrower account will be assigned.
        required:
        - partner_id
        additionalProperties: false
      description: Available properties for assigning a partner to a borrower account.
  responses:
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    NotFoundError:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSet'
      headers:
        X-Api-Version:
          $ref: '#/components/headers/ApiVersionResponseHeader'
        X-Api-Supported-Versions:
          $ref: '#/components/headers/ApiSupportedVersionsResponseHeader'
  parameters:
    ApiVersionHeader:
      name: X-Api-Version
      description: Specify API version, for example '1.0'. By default, the version configured in the company settings is used.
      required: false
      in: header
      schema:
        type: string
    CreatedBefore:
      name: created_before
      description: The date which a resource must be created before to be returned.
      required: false
      in: query
      schema:
        type: string
        format: date-time
    UpdatedBefore:
      name: updated_before
      description: The date which a resource must be updated before to be returned.
      required: false
      in: query
      schema:
        type: string
        format: date-time
    Page:
      name: page
      description: The page to retrieve.
      required: false
      in: query
      schema:
        type: integer
    UpdatedAfter:
      name: updated_after
      description: The date which a resource must be updated after to be returned.
      required: false
      in: query
      schema:
        type: string
        format: date-time
    PageSize:
      name: page_size
      description: The number of records returned in each page.
      required: false
      in: query
      schema:
        type: integer
    CreatedAfter:
      name: created_after
      description: The date which a resource must be created after to be returned.
      required: false
      in: query
      schema:
        type: string
        format: date-time
  headers:
    ApiSupportedVersionsResponseHeader:
      description: API supported versions for endpoint.
      schema:
        type: string
    ApiVersionResponseHeader:
      description: API version.
      schema:
        type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 Access Token (Default)
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}