Investing in loans – orders API

The orders API allows you to submit bid requests on Prosper listings. Once an order has been submitted, a unique order id is created, which you can use to retrieve information about the order.

The following table shows the types of tasks you can complete using the orders API. Select a task to jump directly to the API documentation for that task.

Supported methods

GET, POST

Example URIs

Submit a new investment order

POST <prosper_base_address>/orders/
   Authorization: bearer <access_token>
   Accept: application/json
   Content-Type: application/json

Retrieve details of a single investment order

GET <prosper_base_address>/orders/{order_id}
   Authorization: bearer <access_token>
   Accept: application/json

Retrieve details of all placed orders

GET <prosper_base_address>/orders/
   Authorization: bearer <access_token>
   Accept: application/json

Retrieve listings associated with an investment order

GET <prosper_base_address>/orders/{order_id}/listings
   Authorization: bearer <access_token>
   Accept: application/json

Submit a new investment order – POST /orders/

Use the POST /orders/ method call to submit a new investment order with loan bid requests. When creating an investment order, you will pass in an array of bid requests. Each bid request must contain the listing number you want to bid on, and the amount you want to invest in each listing. You can make up to 100 bid requests in a single order. You cannot bid on the same listing more than once in a single order.

The POST /orders/ call is an asynchronous call. Prosper will process the bid requests within the order, and update the status of each bid as it is executed. To retrieve the status of the individual bid requests within the order, you can make a call later to GET orders/{order_id}. To retrieve the status for all your orders, you can make a call later to GET/orders/.

Once you place the order, the Prosper user’s account balance will be debited the total amount of the order immediately. If any bid within the order is not successfully placed, the Prosper user’s account balance will be credited the amount of the unsuccessful bid.

For a partial loan listing that is less than 24 hours old, you cannot bid more than 10% of the loan total (you will get LENDER_NOT_ELIGIBLE_TO_BID in your bid_result). After 24 hours, you can bid any amount of the loan listing total remaining.

If a bid request is larger than the amount remaining on the loan listing, Prosper will invest the remaining amount, credit the account with the note, and credit the account with the excess funds remaining after the note purchase. For example, if a loan listing only has $15 left to become fully invested, and a bid request has an amount of $25 when the note purchase transaction occurs, you will receive a note on that listing for $15, and your Prosper account’s cash balance will be credited $10.

About order validation and processing

When Prosper receives an order, an initial validation is performed to determine if any of the listing bid requests within the order are invalid. If initial order validation fails, the entire order will fail (even if some other parts of the order might still succeed). Initial order validation is an “all or nothing” validation.

If there are no errors, the order will proceed. Keep in mind that after the initial order validation, any of the bid requests within the order can expire during the processing of the order. Prosper will process the order, expiring any bid requests that are determined invalid during processing.

Example URI:

POST <prosper_base_address>/orders/
   Authorization: bearer <access_token>
   Accept: application/json
   Content-Type: application/json

HTTP Headers

order request object elements

When creating an investment order, you must pass the following elements in the request JSON body of the request:

order response object elements

bid_request elements

Example

The following example creates an order with four bids.

Request

POST <prosper_base_address>/orders/
   Authorization: bearer <access_token>
   Accept: application/json
   Content-Type: application/json

Request body

{
   "bid_requests": [
      {"listing_id":215032, "bid_amount":32},
      {"listing_id":215045, "bid_amount":45.53},
      {"listing_id":215050, "bid_amount":50.10},
      {"listing_id":215998, "bid_amount":98.09}
   ]
}

Response

{
  "order_id": “067e6162-3b6f-4ae2-a171-2470b63dff00”,
  "bid_requests": [
    { 
       "listing_id": 215032, 
       "bid_status": "PENDING", 
       "bid_amount": 32 
    },
    { 
       "listing_id": 215045, 
       "bid_status": "PENDING", 
       "bid_amount": 45.53 
    },
    {  
       "listing_id": 215050, 
       "bid_status": "PENDING", 
       "bid_amount": 50.10 
    },
    { 
       "listing_id": 215998, 
       "bid_status": "PENDING", 
       "bid_amount": 98.09 
    }
  ],
  "source": "API",
  "order_status": "IN_PROGRESS",
  "order_date": "2018-08-14 19:54:58 +0000"
}

Retrieve details for a specific order or a group of orders – GET /orders/{order_id} and GET /orders/

Use the GET /orders/{order_id}  method to retrieve the details of a given order.

Use the GET /orders/ method to retrieve the details for all of your orders.

Use these methods after placing orders to poll the details of the placed orders. This call will return the bid_status and bid_result of all bid requests within your order(s), along with the order_status of your order.

For a detailed explanation of order_status, bid_result, and bid_status changes during the life of an order, see “About order_status, bid_result, and bid_status changes” at the bottom of this page.

Example URIs:

GET <prosper_base_address>/orders/{order_id}
   Authorization: bearer <access_token>
   Accept: application/json

GET <prosper_base_address>/orders/
   Authorization: bearer <access_token>
   Accept: application/json

HTTP Headers

Query parameters

General parameters

Other query parameters

order response object elements

bid_request response object elements

Examples

Example one

The following example returns the status for an order with id 90cf709d-81d6-416a-89f2-ba6ab8146ef2.

Request

GET <prosper_base_address>/orders/90cf709d-81d6-416a-89f2-ba6ab8146ef2
   Authorization: bearer <user_access_token>
   Accept: application/json

Response

{
   "order_id": "90cf709d-81d6-416a-89f2-ba6ab8146ef2",
   "bid_requests":    [
            {
         "listing_id": 2211270,
         "bid_amount": 100,
         "bid_status": "INVESTED",
         "bid_result": "BID_SUCCEEDED",
         "bid_amount_placed": 100
      },
            {
         "listing_id": 2166428,
         "bid_amount": 400,
         "bid_status": "EXPIRED",
         "bid_result": "PARTIAL_BID_SUCCEEDED",
         "bid_amount_placed": 120
      }
   ],
   "order_amount": 500,
   "order_amount_placed": 220,
   "order_amount_invested": 100,
   "source", "API",
   "order_date": "2018-08-14 19:54:58 +0000",
   "order_status": "COMPLETED"
}

Example two

The following example returns the status for all orders, limiting the response to two orders.

Request

GET <prosper_base_address>/orders/?limit=2
   Authorization: bearer <user_access_token>
   Accept: application/json

Response

{
   "result":    [
            {
         "order_id": "50e8ae5a-b4dd-47d9-b80a-83b3ded5ec7a",
         "bid_requests": [         {
            "listing_id": 2983301,
            "bid_amount": 40,
            "bid_status": "INVESTED",
            "bid_result": "BID_SUCCEEDED",
            "bid_amount_placed": 40
         }],
         "order_amount": 40,
         "order_amount_placed": 40,
         "order_amount_invested": 40,
         "order_status": "COMPLETED",
         "source": "API",
         "order_date": "2018-08-14 21:05:19 -0500"
      },
            {
         "order_id": "4c14efad-436a-4d94-a71d-d48d36535753",
         "bid_requests": [         {
            "listing_id": 2983301,
            "bid_amount": 40,
            "bid_status": "INVESTED",
            "bid_result": "BID_SUCCEEDED",
            "bid_amount_placed": 40
         }],
         "order_amount": 40,
         "order_amount_placed": 40,
         "order_amount_invested": 40,
         "order_status": "COMPLETED",
         "source": "API",
         "order_date": "2018-08-14 21:05:18 -0500"
      }
   ],
   "result_count": 2,
   "total_count": 4307
}

Retrieve listings belonging to a specific order – GET /orders/{order_id}/listings

Use the GET /orders/{order_id}/listings method to retrieve the set of listings within an investment order. You can paginate the response for an order with a large amount of bid requests.

Example URI:

GET <prosper_base_address>/orders/{order_id}/listings
   Authorization: bearer <access_token>
   Accept: application/json

HTTP Headers

Query parameters

General parameters

Filterable fields

orders/{order_id}/listings response object elements

Example

The following example retrieves a single Prosper listing from the order with id 2412507.

Request

GET <prosper_base_address>/orders/2412507/listings/?offset=0&limit=1
   Authorization: bearer <user_access_token>
   Accept: application/json

Response

{
   "result":[
      {
         "listing_title": "Motorcycle",
         "invested_amount": 25,
         "listing_amount": 4000,
         "loan_term_months": 36,
         "current_yield": 0.1501,
         "amount_funded": 3600,
         "prosper_rating": "AA",
         "verification_stage": 3,
         "percent_funded": 0.9,
         "historical_return": 0.04828,
         "historical_return_10th_pctl": 0.0363,
         "historical_return_90th_pctl": 0.06536,
         "listing_duration": 14,
         "listing_number": "123456",
         "status": "INVESTED",
         "listing_status_reason": "Loan Originated",
         "note_number": "90000000"
      }
   ],
   "result_count": 1,
   "total_count": 10
}

About order_status, bid_result, and bid_status changes

Let’s examine some orders to see how order_status, bid_result, and bid_status values change through the life of an investment order.

Simplest investment order case: An order containing only one bid request

You submit an investment order with a single bid on a listing for $25.00 You know your bid is successful when the bid_result value equals BID_SUCCEEDED. Having a bid_result value of BID_SUCCEEDED does not mean that you have successfully invested in the listing, only that the initial bid on the listing succeeded. Your order_status will now be IN_PROGRESS and will remain so until the bid_status changes from PENDING to either INVESTED or EXPIRED.

At this point, you must still wait for the loan listing to originate. Origination can take up to 14 days from the date the listing was posted, as Prosper borrower verification and funding occur.

What can happen to a listing during this waiting period?

• Listing is withdrawn – If the listing is withdrawn for any reason, such as the borrower deciding not to take the loan, the listing expiring before being fully funded, or Prosper cancels the listing due to borrower verification or other issues, the bid_status will become EXPIRED and the order_status will be COMPLETED.Note: Even if the listing expires, the bid_result can still be BID_SUCCEEDED, as the bid_result status only tells you that the initial bid was successful.
• Listing originates – Listing origination will only occur when the borrower has successfully passed the three stages of Prosper verification, and the listing has become at least 70% funded. During this time, the bid_status will remain in the PENDING state. When the listing originates, the bid_status will change to INVESTED and the order will be COMPLETED.

  After loan origination, the bid_status value will change from PENDING to INVESTED, and your order will change from IN_PROGRESS to COMPLETED.

In short, bid_result has nothing to do with listing status changes, but bid_status does.

If you don’t successfully invest in the listing, the bid_result will tell you why, and the bid_status will become EXPIRED when the result is known.

Note: Unless it’s your intention, once you submit a bid, do not submit another bid on the same listing until you get an Order ID and can confirm your bid’s bid_result. A bid with a bid_result status of NONE is still waiting to be processed.

More complex investment order case: An order containing more than one bid request

Now we’ll look at a more complex example where multiple bids have been placed, each bid for a single listing.

Initial investment order

For this example, we’ll provide a diagram. In the diagram below, the original POST /orders/ API calls contains four bids on listings, totaling $125. Three bids are for $25, and one bid is for $50. The account starting balance is $500.00

Note that the diagram refers to email notifications being sent when the following occurs:

• Order validation results in an error
• Order is processed
• Order is complete

A Prosper investor must register to receive these email notifications on the Prosper settings page.

Basic order validation occurs on the order.

At this point, Prosper performs some basic order validation on the order.

If validation passes, you’ll receive a 200 response, and the order is queued for processing.

If validation fails, you will receive a 400 error, with error code and description. You can then fix the error and resubmit the order using another POST /orders/ method call.

Note: As soon as an error is located, the error will be returned.

Now the initial order_status for order “xyz” is IN_PROGRESS, the initial bid_status for all bids is PENDING, and the account balance is $375.00

A call to GET /orders/xyx will return the status on the order before order processing.

The investment order is processed
Now that the order has been processed, a call to GET/orders/xyz returns new bid_result and bid_status values for the four listings bids.

• Listing 11101 for $25: bid_result is LISTING_NOT_BIDDABLE, because the listing is no longer active.
• Listing 11102 for $25: bid_result is BID_SUCCEEDED and the bid_status is PENDING as the listing is in the borrower verification and funding stage waiting for origination.
• Listing 11103 for $25: bid_result is BID_SUCCEEDED. However, the bid_status is EXPIRED. It’s possible that the listing was cencelled because the borrower did not pass the verification process or for some other reason.
• Listing 11104 for $50: bid_result is PARTIAL_BID_SUCCEEDED and the bid_status is PENDING as the listing is in the borrower verification and funding stage waiting for origination. In this example, the listing only had $25 remaining to be fully funded. You’ll notice that the bid_amount_placed has been changed to $25 from the original bid request of $50.

A GET call to your Prosper account will return an account balance of $450.00, as only $50 from the original bid is still committed to PENDING investments.

The order_status is still IN_PROGESS awaiting loan origination on listings.

The investment order completes

When borrower verification on listings 11102 and 11104 completes, and the loans originate, another call to GET /orders/xyz returns new bid_result and bid_status values for the four listings bids.

• Listing 11101 for $25: bid_result is LISTING_NOT_BIDDABLE, because the listing is no longer active.
• Listing 11102 for $25: bid_result is BID_SUCCEEDED and the bid_status is INVESTED as the listing has originated. You invested $25 in listing 11102.
• Listing 11103 for $25: bid_result is BID_SUCCEEDED. However, the bid_status is EXPIRED. It’s possible that the listing was cancelled because the borrower did not pass the verification process or for some other reason.
• Listing 11104 for $50: bid_result is PARTIAL_BID_SUCCEEDED and the bid_status is INVESTED as the listing has originated. You invested $25 in listing 11104.

A GET call to your Prosper account will return an account balance of $450.00, as only $50 from the original bid request was INVESTED in listings.

The order_status is now COMPLETED as all listing bids have either EXPIRED or INVESTED.

Errors

The orders API returns the following errors.