Fundrise Investments API

openapi: 3.2.0
info:
  title: Fundrise Connect (External API) Investments API
  version: 1.0.0
  contact:
    name: Fundrise Connect Support Team
    email: connect@fundrise.com
  description: "### Introduction\nFundrise is a Fintech company democratizing access to alternative assets through technology. This API represents a prototype of Fundrise Connect, which is our external API for providing Client onboarding and investment into our alternative assets. To get started, contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a> or view our <a href='#tag/Authentication'>getting access documentation</a>. <br> <br> The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses,  and uses standard HTTP response codes, authentication, and verbs. <br> <br> Throughout this document, the following terminology will be used:\n  - <strong>Client</strong>: This refers to an End-User or customer that a Partner onboards onto Fundrise for investing in Fundrise assets.\n  - <strong>Partner</strong>: This refers to a company working with Fundrise to provide their End-Users or customers access to Fundrise assets.\n\n### Errors\nFundrise uses conventional HTTP response codes to indicate the success or failure of an API request. In general:\n  - Codes in the 2xx range indicate success. \n  - Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). \n  - Codes in the 5xx range indicate an error with Fundrise's servers (these are rare).\n\nSome 4xx errors that could be handled programmatically (e.g., an address is invalid) include an error code that briefly explains the error reported. These errors that can be handled programmatically have error codes in the error response.  Endpoints that have programmatically resolvable errors have those codes defined in their schema definitions.\n### Request IDs \nEach API request has an associated request identifier. You can find this value in the response headers, under `Request-Id`.  This error will also be present in the error response body under the field `referenceId`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.\n### Idempotency \nFor some POST endpoints, we require a Partner idempotency key to ensure operations are not duplicated. For both Client creation and Investment placement, we require a `partnerReferenceId` to ensure that Investments and Clients are not duplicated in our system.\n### Versioning\nAPI endpoints are versioned with path versioning. Each endpoint contains a version path parameter e.g. (`/v1/...`). To release new functionality without impacting existing customers, we will version endpoints and increment version numbers accordingly.  <br> <br> When endpoints are staged to be deprecated, Partners will be given ample time to integrate with new versions according to our service agreement. Partners should expect to receive communications related to deprecation timelines. \n### Rate limiting\nWe enforce rate limiting on our public API to avoid DoS (denial of service) issues. This rate limiting is enforced per Client and per HTTP method. If you are running into  rate limiting issues, please contact the support team via <a href=\"mailto:connect@fundrise.com\" target=\"_blank\">connect@fundrise.com</a>."
  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: Investments
  description: The Investment APIs provide operations for placing and cancelling Investments in various Offerings on behalf of an authenticated Client.
paths:
  /v1/account/{accountId}/investment:
    post:
      security:
      - ClientBearerAuthentication: []
      summary: Place Investment
      description: "Place an Investment in an Offering on behalf of a Client. \n\nNAV (net asset value, reflected as `sharePrice` in this response) is typically updated daily for the interval funds (Flagship Real Estate Fund and the Income Real Estate Fund).  As such, the `sharePrice` for Investments in interval funds will not be returned upon Investment placement in such funds via this endpoint. \n\nWith this specification, we are assuming that accounts on the Partner platform, at the time of onboarding, have linked & funded a central payment source with the ability to fund Investments placed."
      operationId: PlaceInvestment
      tags:
      - Investments
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvestmentPlacementRequest'
            examples:
              InvestmentPlacedSuccessfully:
                value:
                  partnerReferenceId: '2314'
                  offeringId: '1'
                  acknowledgedDocumentIds:
                  - '1'
                  - '2'
                  amount: '24187.50'
      responses:
        '200':
          description: Investment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              examples:
                client:
                  value:
                    transactionId: '11'
                    transactionType: INVESTMENT
                    description: Investment into Fundrise Offering
                    amount: '10000.00'
                    transactionDate: '2023-02-15T00:00:00.000-05:00'
                    offerings:
                    - offeringId: '24'
                      offeringName: Flagship Fund
                      sharePrice: '10.04'
                      shares: '996.015936'
                    status: PENDING
                    isCancellable: true
                    debitCreditMemo: CREDIT
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                MalformedFields:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    validationErrors:
                      partnerReferenceId:
                      - must not be blank
                      - must not be null
                      offeringId:
                      - must not be blank
                      - must not be null
                      amount:
                      - must not be blank
                      - must not be null
                      - must be greater than or equal to 10.00
                      - must be less than or equal to 100000.00
                      acknowledgedDocumentIds:
                      - must not be blank
                      - must not be null
                InvalidDocumentIds:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100502'
                    message: acknowledgedDocumentIds do not match those required
        '401':
          description: Invalid or expired token
          $ref: '#/components/responses/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                AccountFrozen:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c40
                    code: '100500'
                    message: Account is frozen
                FullLiquidationInProgress:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c41
                    code: '100501'
                    message: Account has a full Liquidation request in progress and is ineligible for Investment placement
        '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}/investment/{transactionId}/cancel:
    put:
      security:
      - ClientBearerAuthentication: []
      summary: Cancel Investment
      description: "Cancel an Investment in an Offering on behalf of the currently authenticated Client. \n\nAn Investment may be cancelled up until 5:00pm on the day that the Investment was placed. If the Investment was placed after 5:00pm EST or on a non-business day, it may be cancelled prior to 5:00pm of the next business day."
      operationId: CancelInvestment
      tags:
      - Investments
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      - $ref: '#/components/parameters/TransactionIdPath'
      responses:
        '200':
          description: Investment cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponse'
              examples:
                client:
                  value:
                    transactionId: '11'
                    transactionType: INVESTMENT
                    description: Investment into Fundrise Offering
                    amount: '10000.00'
                    transactionDate: '2023-02-15T00:00:00.000-05:00'
                    offerings:
                    - offeringId: '24'
                      offeringName: Flagship Fund
                      sharePrice: '10.04'
                      shares: '996.015936'
                    status: FAILED
                    isCancellable: false
                    debitCreditMemo: CREDIT
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                InvestmentNotInCancellableState:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100510'
                    message: Investment must have a PENDING status to cancel
                InvestmentOutsideOfCancellationWindow:
                  value:
                    referenceId: ed8583b9-6cd9-43ed-ad46-c7c52fff0c34
                    code: '100511'
                    message: Cancellation window is closed for this Investment
        '401':
          description: Invalid or expired token
          $ref: '#/components/responses/401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundriseConnectError'
              examples:
                InvestmentNotFound:
                  value:
                    referenceId: ed8583b9-6cd9-43ef-ad46-c7c52fff0c34
                    code: '100512'
                    message: Invalid investmentId provided
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    Identifier:
      title: Identifier
      description: Value for a unique identifier.
      type: string
      format: int64
    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'
    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
    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
    FieldErrorMap:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/StringArray'
    InvestmentPlacementRequest:
      title: Investment Placement
      type: object
      description: An Investment placement request.
      required:
      - partnerReferenceId
      - amount
      - offeringId
      - acknowledgedDocumentIds
      properties:
        partnerReferenceId:
          description: An idempotency key to ensure duplicate Investments are not created in the system for a Partner. This is a unique ID from the Partner used to reference the Investment in their system.
          type: string
          x-field-extra-annotation: '@NotBlank'
        offeringId:
          description: The Offering ID
          $ref: '#/components/schemas/Identifier'
        amount:
          description: The amount in USD to be purchased. The maximum decimal places is 2.
          type: string
          format: double
          x-field-extra-annotation: '@Min(10) @Max(100000) @Digits(integer = 999999, fraction = 2, message = "decimal places must be less than or equal to 2")'
        acknowledgedDocumentIds:
          type: array
          description: A list of `InvestmentAcknowledgment` IDs representing signatures of said acknowledgments. Submission of these IDs indicates that the user has both signed and consents to the acknowledgment agreements.
          items:
            $ref: '#/components/schemas/Identifier'
    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
    TransactionTypeEnum:
      title: Transaction Type
      description: Enum representing the type of financial Transaction.
      enum:
      - INVESTMENT
      - LIQUIDATION
      - DIVIDEND
    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
    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
  parameters:
    TransactionIdPath:
      in: path
      name: transactionId
      required: true
      schema:
        type: integer
        format: int64
      description: The ID of the underlying Transaction object.  Transactions are differentiated by their `transactionType` field. The `transactionId` for a given `transactionType` may be obtained from the response bodies of either the generic Transactions endpoints, or the respective Investment placement or Liquidations request endpoint called when creating the Transaction.
    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:
    '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
    '401':
      description: Unauthorized request to server, Invalid access token or Partner credentials
  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