openapi: 3.0.2
info:
  title: DriveWealth Accounts Settlements API
  version: '1.0'
servers:
- url: https://bo-api.drivewealth.io/back-office
  description: Sandbox server (Uses test data)
- url: https://bo-api.drivewealth.net/back-office
  description: Production Server (Uses LIVE data)
tags:
- name: Settlements
  x-displayName: Settlements
paths:
  /funding/reconciliations:
    get:
      tags:
      - Settlements
      summary: List Cashless Reconciliations
      description: Fetches a list of daily reconciliations for a firm using cashless settlement.
      parameters:
      - in: query
        name: to
        schema:
          type: string
        required: true
        example: '2022-12-25T18:36:40.609Z'
        description: The date and time in which to end at.
      - in: query
        name: from
        schema:
          type: string
        required: true
        example: '2022-12-08T18:36:40.609Z'
        description: The date and time in which to start from.
      - in: query
        name: type
        schema:
          type: string
        required: false
        example: CRYPTO
        description: Filters the reconciliations reports by the type of reconciliation.
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/reconciliationStatus'
        required: false
        description: Filters the reconciliations reports by the status of reconciliation.
      responses:
        '200':
          description: Fetching a list of daily reconciliations for a firm was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfDailyReconciliations'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /funding/reconciliations/{reconciliationID}:
    get:
      tags:
      - Settlements
      summary: Retrieve Cashless Reconciliation
      description: Fetches reconciliations details for a firm using cashless settlement.
      parameters:
      - in: path
        name: reconciliationID
        schema:
          $ref: '#/components/schemas/reconciliationID'
        required: true
        description: The unique identifier of the reconciliation report.
      responses:
        '200':
          description: Fetching a firm's reconciliation details was successful.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ReconciliationDetails'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
    patch:
      tags:
      - Settlements
      summary: Update Cashless Reconciliation
      description: Updates a Cashless Reconciliation by reconciliationID.
      parameters:
      - in: path
        name: reconciliationID
        schema:
          $ref: '#/components/schemas/reconciliationID'
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconciliationUpdate'
      responses:
        '200':
          description: Updating the Cashless Reconciliations was Successful.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ReconciliationDetails'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /accounts/{accountID}/reports/daily-trade-summary:
    post:
      tags:
      - Settlements
      summary: Create DVP RVP Report
      description: Creates a job to generate a DVP RVP Report.
      parameters:
      - in: path
        name: accountID
        schema:
          $ref: '#/components/schemas/accountID'
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDVPRVP'
      responses:
        '200':
          description: Creating the job to generate a DVP/RVP Report was successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDVPRVPRes'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
    get:
      tags:
      - Settlements
      summary: List DVP RVP Reports
      description: Lists DVP RVP reports.
      parameters:
      - in: path
        name: accountID
        schema:
          $ref: '#/components/schemas/accountID'
        required: true
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/DVPRVPStatus'
        description: A filter, to filter on the status of the DVP/RVP.
      - in: query
        name: from
        schema:
          $ref: '#/components/schemas/from'
        required: true
      - in: query
        name: to
        schema:
          $ref: '#/components/schemas/to'
        required: true
      responses:
        '200':
          description: Fetching DVP/RVP List was Successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDVPRVP'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /accounts/{accountID}/reports/daily-trade-summary/{reportID}:
    get:
      summary: Retrieve DVP RVP
      description: Retrieves a DVP RVP by reportID.
      tags:
      - Settlements
      parameters:
      - in: path
        name: accountID
        schema:
          $ref: '#/components/schemas/accountID'
        required: true
      - in: path
        name: reportID
        schema:
          type: string
          example: bsr_040fb9cc-84e8-4f20-bf09-d398dacd458d.1622745430469_20210604
          description: The DVP/RVP report identifier.
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DVPRVPDetails'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /settlements:
    get:
      tags:
      - Settlements
      summary: Retrieve Settlements
      description: Retrieves a list of Settlements.
      parameters:
      - in: query
        name: from
        schema:
          type: string
        required: true
        example: '2022-12-08'
        description: The date to start from.
      - in: query
        name: to
        schema:
          type: string
        required: true
        example: '2022-12-25'
        description: The date to end at.
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/singleSettlementStatus'
        required: false
        description: Filters, the settlements by the status.
      - in: query
        name: settlementProfileID
        schema:
          $ref: '#/components/schemas/settlementProfileID'
        required: false
        description: Filters, the settlements by the settlement profile.
      - in: query
        name: limit
        schema:
          type: integer
          default: 50
          maximum: 200
        required: false
        description: The number of items to return.
      - in: query
        name: offset
        schema:
          type: string
          default: null
        required: false
        description: Used for pagination. Set this to the first/last id value of your payload to get the prev/next page of results respectively.
      - in: query
        name: direction
        schema:
          type: string
          enum:
          - prev
          - next
        required: false
        description: The direction of the pagination.
      responses:
        '200':
          description: Retrieving a list of Settlements was Successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSettlementReports'
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
  /settlements/{settlementID}:
    get:
      tags:
      - Settlements
      summary: Retrieve Settlement
      description: Retrieves Settlement by settlementID.
      parameters:
      - in: path
        name: settlementID
        schema:
          $ref: '#/components/schemas/singleSettlementID'
        required: true
      responses:
        '200':
          description: Retrieving Settlement by settlementID was Successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSettlementByID'
        '404':
          description: The settlement for given settlementID doesn't exist.
      security:
      - bearerAuth: []
        dwAppKey: []
      - sessionToken: []
        dwAppKey: []
components:
  schemas:
    SingleSettlementDetails:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/singleSettlementID'
        settlementDate:
          $ref: '#/components/schemas/date'
          description: The date for which the settlement was generated.
        partnerID:
          $ref: '#/components/schemas/parentIBID'
        status:
          $ref: '#/components/schemas/singleSettlementStatus'
        totalAmount:
          type: number
          example: -14250
          description: The total aggregated sum of all underlying accounts and transactions.
        createdAt:
          $ref: '#/components/schemas/created'
          description: The date and time the settlement was created.
        updatedAt:
          $ref: '#/components/schemas/updated'
          description: The date and time the settlement was last updated.
        settlementProfileID:
          $ref: '#/components/schemas/settlementProfileID'
    reconciliationID:
      type: string
      example: 80f9b672-120d-4b73-9cc9-42fb3262c4b9_20240417
      description: The unique identifier of the reconciliation report.
    CreateDVPRVPRes:
      type: object
      properties:
        id:
          type: string
          example: bsr_040fb9cc-84e8-4f20-bf09-d398dacd458d.1622745430469_20210604
          description: The DVP/RVP report identifier.
        accountID:
          $ref: '#/components/schemas/accountID'
        accountNo:
          $ref: '#/components/schemas/accountNo'
        tradeDate:
          type: string
          format: date
          example: '2021-06-04'
          pattern: yyyy-MM-dd
          description: The date for which the DVP/RVP was run for.
        note:
          $ref: '#/components/schemas/note'
        partnerID:
          $ref: '#/components/schemas/partnerID'
    CreateDVPRVP:
      type: object
      required:
      - tradeDate
      properties:
        tradeDate:
          type: string
          format: date
          example: '2021-06-04'
          pattern: yyyy-MM-dd
          description: The date to generate the DVP/RVP report for.
        note:
          $ref: '#/components/schemas/note'
    note:
      type: string
      example: Hey! Welcome to DriveWealth Developer Docs!
      description: A way to store a message/comment on the this object.
    reconciliationStatus:
      type: string
      example: APPROVED
      description: The current status of the reconciliation report.
      enum:
      - PENDING
      - APPROVED
      - PROCESSING
      - SUCCESSFUL
      - FAILED
    settlementProfileID:
      type: string
      example: settlement-profile-bank-account-1
      description: A settlement profile identifier that links to a specific bank account for fund settlement.
    updated:
      type: string
      example: '2022-12-11T22:28:21.810Z'
      description: ''
    SingleSettlementReports:
      type: object
      properties:
        pageSize:
          type: integer
          example: 1
          description: The amount of results on the page.
        limit:
          type: integer
          example: 50
          description: The maximum number of results per page.
        settlements:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/SingleSettlementDetails'
    SingleSettlementByID:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/singleSettlementID'
        settlementDate:
          $ref: '#/components/schemas/date'
          description: The date the settlement was generated for.
        status:
          $ref: '#/components/schemas/singleSettlementStatus'
        statusComment:
          type: string
          example: Finished processing breakdown
          description: A custom comment about the current status of the settlement.
        amount:
          type: object
          properties:
            total:
              type: number
              example: 5000.45
              description: The aggregated sum of all the transactions settling on the settlement date.
            credits:
              type: number
              example: 6000.45
              description: The aggregated sum of all the credit transactions settling on the settlement date.
            debits:
              type: number
              example: -1000
              description: The aggregated sum of all the debit transactions settling on the settlement date.
        breakdownReport:
          type: string
          format: url
          example: https://du2c4wzqz90h1.cloudfront.net/singleSettlementReport....
          description: A breakdown of all the deposits or withdrawals across sub accounts over the course of the settlement date.
        partnerID:
          $ref: '#/components/schemas/partnerID'
        settlementProfileID:
          $ref: '#/components/schemas/settlementProfileID'
        updatedBy:
          $ref: '#/components/schemas/updatedBy'
        createdAt:
          $ref: '#/components/schemas/created'
          description: The date and time of when the settlement was created.
        updatedAt:
          $ref: '#/components/schemas/updated'
          description: The date and time of when the settlement was last updated.
    created:
      type: string
      example: '2022-12-11T22:28:21.810Z'
      description: ''
    singleSettlementID:
      type: string
      example: sett_63ccb073-a7b6-4b33-af77-5baec5cc4494_settle-profile-usa_20221224
      description: A unique identifier that identifies the settlement.
    from:
      type: string
      format: date
      pattern: yyyy-MM-dd
      example: '2022-12-25'
      description: A filter, the start date.
    singleSettlementStatus:
      type: string
      example: PENDING
      description: The current status of the settlement.
      enum:
      - PENDING
      - APPROVED
      - SUCCESSFUL
      - REJECTED
    accountID:
      type: string
      example: cc07f91b-7ee1-4868-b8fc-823c70a1b932.1407775317759
      description: The user's unique account identifier.
    DailyReconciliation:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/reconciliationID'
        date:
          type: string
          example: '2024-04-17'
          description: The date of when the reconciliation report was generated for.
        status:
          $ref: '#/components/schemas/reconciliationStatus'
        statusComment:
          type: string
          example: Finished processing breakdown
          description: A custom comment about the status.
        totalAmount:
          type: number
          example: 12001.01
          description: The total amount due or owed to the firm.
        created:
          type: string
          example: '2024-04-15T22:28:21.810Z'
          description: The date and time the reconciliation report was created.
        updated:
          type: string
          example: '2024-04-17T22:28:21.810Z'
          description: The date and time the reconciliation report was last updated.
        updatedBy:
          $ref: '#/components/schemas/updatedBy'
    to:
      type: string
      format: date
      pattern: yyyy-MM-dd
      example: '2022-12-26'
      description: A filter, the end date.
    ReconciliationUpdate:
      type: object
      properties:
        status:
          type: string
          example: SUCCESSFUL
          description: The status to update the reconciliation report to.
          enum:
          - SUCCESSFUL
        statusComment:
          type: string
          example: Manually approving reconciliation for testing purposes.
          description: A custom comment about the status.
    parentIBID:
      type: string
      example: 80f9b672-120d-4b73-9cc9-42fb3262c4b9
      description: The unique identifier of the firm.
    ReconciliationDetails:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/reconciliationID'
        date:
          type: string
          example: '2024-04-17'
          description: The date of when the reconciliation report was generated for.
        status:
          $ref: '#/components/schemas/reconciliationStatus'
        statusComment:
          type: string
          example: Finished processing breakdown
          description: A custom comment about the status.
        amounts:
          type: object
          properties:
            total:
              type: number
              example: -1263.56
              description: The total amount due or owed to the firm.
            purchases:
              type: number
              example: -1680.07
              description: The total amount in purchases of equity instruments, that are due to DriveWealth.
            sales:
              type: number
              example: 416.51
              description: The total amount in sales of equity instruments, that are owed to the firm.
            dividends:
              type: number
              example: 0
              description: The total amount of dividends, that are owed to the firm.
            fees:
              type: number
              example: 0
              description: The total amount of fees, that are due to DriveWealth.
            other:
              type: number
              example: 0
              description: The total amount of other payments, that are owed to the firm.
        transferAmounts:
          type: object
          properties:
            currency:
              type: string
              example: USD
              description: The currency in abbreviation form.
            payablesToDW:
              type: number
              example: 1263.56
              description: The total amount due to DriveWealth.
            receivablesFromDW:
              type: number
              example: 0
              description: The total amount owed to the partner firm.
        reconciliationBreakdown:
          type: string
          properties:
            JSON:
              type: string
              example: https://d3k101jzh5wilt.cloudfront.net/reconciliation_2e901d48-dd17-42fe-8225-32d2ca6b633e_20190322.json?Policy=eyJTdGF0ddiOiBbeyJSZXNvdXJjZSI6Imh0dHBzOi8vZDNrMTAxanpoNXdpbHQuY2xvdWRmcm9udC5uZXQvcmVjb25jaWxpYXRpb25fMmU5ffdasdamA17ggVl6C40gHkKsr2HLfmjTd9BevcYRPh-QDKA1J~76INZ3nfada4ROS6OUR66A%22
              description: A URL that contains the breakdown of all the transactions that are settling in the reconciliation report.
        partnerID:
          $ref: '#/components/schemas/parentIBID'
        created:
          type: string
          example: '2024-04-15T22:28:21.810Z'
          description: The date and time when the reconciliation report was created.
        updated:
          type: string
          example: '2024-04-17T22:28:21.810Z'
          description: The date and time when the reconciliation report was last updated.
        updatedBy:
          $ref: '#/components/schemas/updatedBy'
    accountNo:
      type: string
      example: DWBG000052
      description: The user's unique account number, that is human readable.
    DVPRVP:
      type: object
      properties:
        id:
          type: string
          example: bsr_040fb9cc-84e8-4f20-bf09-d398dacd458d.1622745430469_20210604
          description: The DVP/RVP report identifier.
        tradeDate:
          type: string
          format: date
          example: '2021-06-04'
          pattern: yyyy-MM-dd
          description: The date for which the DVP/RVP was run for.
        status:
          type: string
          example: SUCCESSFUL
          description: The status of the generated report.
          enum:
          - PROCESSING
          - SUCCESSFUL
        note:
          $ref: '#/components/schemas/note'
        partnerID:
          $ref: '#/components/schemas/partnerID'
        created:
          $ref: '#/components/schemas/created'
        updated:
          $ref: '#/components/schemas/updated'
        updatedBy:
          $ref: '#/components/schemas/updatedBy'
        source:
          type: string
          example: MANUAL
          enum:
          - MANUAL
          - SYSTEM
          description: The method type in which the report was generated.
    date:
      type: string
      example: '2022-12-25'
      description: ''
    partnerID:
      type: string
      example: 80f9b672-120d-4b73-9ccv9-42fb3262c4b9
      description: The partner's unique identifier.
    ListOfDailyReconciliations:
      type: array
      description: A list of daily reconciliations for a firm.
      items:
        oneOf:
        - $ref: '#/components/schemas/DailyReconciliation'
    ListDVPRVP:
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/DVPRVP'
    updatedBy:
      type: string
      example: SYSTEM
      enum:
      - SYSTEM REPORT SERVICE
      - INSTANT FUNDING BREAKDOWN JOB
    DVPRVPStatus:
      type: string
      example: Processing
      enum:
      - Processing
      - Successful
    DVPRVPDetails:
      type: object
      allOf:
      - $ref: '#/components/schemas/DVPRVP'
      - type: object
        properties:
          amount:
            type: object
            properties:
              totalBuy:
                type: object
                properties:
                  quantity:
                    type: number
                    example: 10.71358941
                    description: The amount of shares that were purchased.
                  notional:
                    type: number
                    example: 144.26
                    description: The total amount in USD value of the instruments.
                  orders:
                    type: number
                    example: 30
                    description: The total amount of orders assiocated to the amount of shares purchased.
              totalSell:
                type: object
                properties:
                  quantity:
                    type: number
                    example: 0
                    description: The amount of shares that were sold.
                  notional:
                    type: number
                    example: 0
                    description: The total amount in USD value of the instruments.
                  orders:
                    type: number
                    example: 0
                    description: The total amount of orders assiocated to the amount of shares sold.
          breakdownJson:
            type: string
            format: url
            description: A json file of the trade breakdown of all the purchases and sale transactions.
            example: https://du2c4wzqz90h1.cloudfront.net/buySellTradesReport....
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    dwAppKey:
      type: apiKey
      in: header
      name: dw-client-app-key
    sessionToken:
      type: apiKey
      in: header
      name: dw-auth-token