Fundrise Liquidations API

openapi: 3.2.0
info:
  title: Fundrise Connect (External API) Liquidations API
  version: 1.0.0
  contact:
    name: Fundrise Connect Support Team
    email: connect@fundrise.com
  description: '### Introduction

    Fundrise is a Fintech company democratizing access to alternative assets through technology.'
  x-logo:
    url: https://d10cq78zmnjvsx.cloudfront.net/interface/logo-hz-color.svg
    backgroundColor: '#FFFFFF'
    altText: Fundrise
    href: .
servers:
- description: Sandbox
  url: https://sandbox.fundrise.com
tags:
- name: Liquidations
  description: The Liquidations APIs provide operations for a Client to place a Liquidation request. A Liquidation request results in selling shares in exchange for dollars.
paths:
  /v1/account/{accountId}/liquidation:
    post:
      security:
      - ClientBearerAuthentication: []
      description: 'Creates a request to liquidate shares.


        In order to place a Liquidation request, the holdings in question must be liquidable. The liquidability of Holdings in any given Offering is determined by the `shares` field on the response from the Get Offering Holdings endpoint. A non zero quantity of `shares` indicates that the Client holds non reduced shares in the given Offering (indicated by the `offeringId`) that can be liquidated.

        Liquidations are reviewed on a quarterly basis. As such, Liquidations submitted in Q1, Q2, Q3, and Q4 will typically be processed in early April, early July, early October, and early January, respectively.'
      operationId: CreateShareLiquidationRequest
      summary: Create Liquidation
      tags:
      - Liquidations
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareLiquidationRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionResponse'
              example:
              - transactionId: '1'
                transactionType: LIQUIDATION
                transactionDate: '2023-02-20T00:00:00.000-05:00'
                description: Share liquidation request
                offerings:
                - offeringId: '24'
                  offeringName: Flagship Fund
                  shares: '25.000001'
                status: FAILED
                isCancellable: false
                debitCreditMemo: DEBIT
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
                type: object
              examples:
                MalformedFields:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    validationErrors:
                      allAcknowledgmentsAccepted:
                      - must not be blank
                      - must not be null
                      - must be true
                      offerings:
                      - must not be blank
                      - must not be null
                      offerings[0].offeringId:
                      - must not be blank
                      - must not be null
                      offerings[0].shares:
                      - must not be blank
                      - must not be null
                      - must be less than or equal to 6 decimal places
                      - must be greater than 0
                PendingTransfers:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100519'
                    message: Account has pending transfers
                LiquidationsDisabledForOffering:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100520'
                    message: Liquidations are blocked for the provided offering
                TooManySharesRequested:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100521'
                    message: Account does not hold the quantity of shares requested for liquidation
                InProcessLiquidationForOffering:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100523'
                    message: Liquidation cannot be placed because there is an in process Liquidation for the provided fund
        '401':
          description: Invalid or expired token
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                InvalidOfferingId:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '200101'
                    message: Invalid offeringId provided
        '500':
          $ref: '#/components/responses/500'
  /v1/account/{accountId}/liquidation/{shareLiquidationRequestId}/cancel:
    put:
      security:
      - ClientBearerAuthentication: []
      description: 'Cancels a request to liquidate shares.


        In order to cancel a Liquidation Transaction, `isCancellable` (boolean field), must have a value of `true`. Liquidations will typically remain cancellable up until the start of the processing period for the respective quarter in which it was placed.'
      operationId: CancelShareLiquidationRequest
      summary: Cancel Liquidation
      tags:
      - Liquidations
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      - $ref: '#/components/parameters/ShareLiquidationRequestIdPath'
      responses:
        '200':
          description: Liquidation cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              examples:
                share-liquidation-response:
                  value:
                    transactionId: '1'
                    transactionType: LIQUIDATION
                    transactionDate: '2023-02-20T00:00:00.000-05:00'
                    description: Share liquidation request
                    offerings:
                    - offeringId: '24'
                      offeringName: Flagship Fund
                      shares: '25.000001'
                    status: FAILED
                    isCancellable: false
                    debitCreditMemo: DEBIT
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
                type: object
              examples:
                InProcessLiquidationForOffering:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100514'
                    message: Liquidation is in an invalid status for cancellation
                CancellationWindowClosed:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100516'
                    message: Liquidation is outside of cancellation window
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                LiquidationNotFound:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100513'
                    message: Liquidation not found
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    DebitCreditTypeEnum:
      title: Debit/Credit type
      description: '`DEBIT` indicates an outbound movement of money. <br> `CREDIT` indicates an inbound movement of money.'
      type: string
      enum:
      - DEBIT
      - CREDIT
    FundriseConnectError:
      title: Error object
      description: Error from Fundrise Connect.
      type: object
      properties:
        referenceId:
          description: A unique reference ID generated for every request that is for error tracing.
          maxLength: 1000
          type: string
        code:
          description: A numeric code mapping to a specific validation error.
          maxLength: 6
          type: string
        message:
          description: A human readable description of the error.
          maxLength: 1000
          type: string
        validationErrors:
          description: A map of field names to an array of form validation error messages
          $ref: '#/components/schemas/FieldErrorMap'
      required:
      - referenceId
    ShareLiquidationOfferingRequest:
      type: object
      description: The fund information for the sale
      properties:
        offeringId:
          $ref: '#/components/schemas/Identifier'
          description: The Fundrise Offering ID
        shares:
          allOf:
          - $ref: '#/components/schemas/SharePrecision'
          description: The fractional quantity of shares to liquidate. The precision of the this number can be up to 6 decimal places. The total quantity of liquididable shares for a given Offering can be obtained from the <a href="#tag/Holdings/operation/GetHoldings">Get Offering Holdings</a> endpoint.
          x-field-extra-annotation: '@Positive @Digits(integer = 999999, fraction = 6, message = "must be less than or equal to 6 decimal places")'
      required:
      - offeringId
      - shares
    TransactionTypeEnum:
      title: Transaction Type
      description: Enum representing the type of financial Transaction.
      enum:
      - INVESTMENT
      - LIQUIDATION
      - DIVIDEND
    SharePrecision:
      title: SharePrecision
      description: Value can be fractional, with a precision up to 6 decimal places. Intended to be used as the standard format for shares.
      type: string
      format: double
      example: '10.000001'
    TransactionResponse:
      title: TransactionResponse
      description: An abstract response representing the core Transaction properties.
      type: object
      properties:
        transactionId:
          $ref: '#/components/schemas/Identifier'
          description: The ID of the Transaction
        amount:
          description: Total amount in USD.
          type: string
          format: double
        transactionType:
          $ref: '#/components/schemas/TransactionTypeEnum'
        transactionDate:
          description: The Transaction date.
          type: string
          format: date-time
        description:
          description: The Transaction description
          maxLength: 2000
          type: string
        status:
          $ref: '#/components/schemas/TransactionStatusEnum'
        debitCreditMemo:
          $ref: '#/components/schemas/DebitCreditTypeEnum'
        fees:
          description: The fees associated with the Transaction
          type: string
          format: double
        offerings:
          type: array
          items:
            $ref: '#/components/schemas/TransactionOfferingResponse'
        isCancellable:
          description: Boolean indicating whether or not the Transaction is cancellable.
          type: boolean
      required:
      - transactionId
      - transactionType
      - transactionDate
      - description
      - status
      - debitCreditMemo
    StringArray:
      type: array
      items:
        type: string
    TransactionStatusEnum:
      title: Transaction Status
      description: '`PENDING` indicates the Transaction is pending. `COMPLETE` indicates that the Transaction has completed. This is a terminal state. <br> `FAILED` indicates that the Transaction was not successful. This is a terminal state. <br>'
      type: string
      enum:
      - PENDING
      - COMPLETE
      - FAILED
    ShareLiquidationRequest:
      type: object
      description: A request for a Fundrise share liquidation
      properties:
        allAcknowledgmentsAccepted:
          description: An indication that acknowledgments have been accepted
          type: boolean
          x-field-extra-annotation: '@AssertTrue'
          example: true
        offerings:
          description: A collection of shares being submitted for liquidation.
          type: array
          items:
            $ref: '#/components/schemas/ShareLiquidationOfferingRequest'
          x-field-extra-annotation: '@NotEmpty'
          example:
          - offeringId: '1'
            shares: '10.000001'
          - offeringId: '2'
            shares: '25.000001'
      required:
      - allAcknowledgmentsAccepted
      - offerings
    TransactionOfferingResponse:
      title: Transaction Offering Response
      description: An Offering included in a Transaction
      type: object
      properties:
        offeringId:
          $ref: '#/components/schemas/Identifier'
          description: The Offering ID
        offeringName:
          description: The Offering name.
          maxLength: 2000
          type: string
        shares:
          $ref: '#/components/schemas/SharePrecision'
          description: The number of shares in the Transaction
        sharePrice:
          description: The value in USD per share at the time of processing.
          type: string
          format: double
        amount:
          description: 'The total amount in USD to be returned to the Client, net of fees.  For example, the `amount` to be returned is described by the following formula:


            `amount = (shares * sharePrice) - fees`.'
          type: string
          format: double
      required:
      - offeringId
      - offeringName
    Identifier:
      title: Identifier
      description: Value for a unique identifier.
      type: string
      format: int64
    FieldErrorMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/StringArray'
  parameters:
    ShareLiquidationRequestIdPath:
      name: shareLiquidationRequestId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
        description: The share liquidation request ID (returned by the <a href="#tag/Liquidation/operation/CreateShareLiquidationRequest">Create Liquidation operation</a>) associated with the request.
    AccountIdPath:
      name: accountId
      in: path
      required: true
      schema:
        type: integer
        format: int64
      description: The account ID (returned by the <a href="#tag/Clients/operation/CreateClient">Create Client operation</a> or the <a href="#tag/Clients/operation/GetClient">Get Client operation</a>) associated with the request.
  responses:
    '401':
      description: Unauthorized request to server, Invalid access token or Partner credentials
    '403':
      description: Customer is not permitted to access the resource
    '500':
      description: Internal Service Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FundriseConnectError'
          examples:
            clientExists:
              value:
                referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c35
                message: Internal service error
  securitySchemes:
    PartnerBasicAuthentication:
      description: PartnerBasicAuthentication is enforced by HTTP Basic Authentication. A Partner username and password will be provided by Fundrise support.  The Partner password should be stored securely. At a minimum, it should be encrypted at-rest and access restricted to services making requests to the Fundrise API. The Partner password should not be exposed to a Client or any of their devices. If the password is compromised please contact Fundrise support.
      type: http
      scheme: basic
    ClientBearerAuthentication:
      description: 'ClientBearerAuthentication is enforced by HTTP Bearer Authentication and requires an OAuth access token.  Since access tokens are scoped to specific Clients, they identify and authenticate the Client in a request.


        Access tokens can be obtained in <a href="#tag/Authentication/operation/GetAccessToken">Get Access Token</a> requests by using the refresh token flow. OAuth refresh token are issued on <a href="#tag/Clients/operation/CreateClient">Client Creation</a> and scoped specifically to that Client. The refresh tokens will not expire and should be stored securely after Client creation. At a minimum, refresh tokens should be encrypted at-rest and access restricted to services making requests to the Fundrise API. Refresh tokens should not be exposed to a Client or any of their devices.'
      type: http
      scheme: bearer