{"_id":"5591dc215781ae0d00236807","__v":64,"category":{"_id":"5591adfa342e980d006db03b","project":"543de77431ca981a00a700ec","version":"55819c76a5474a0d00d945db","__v":3,"pages":["5591ae27c671980d00543dde","5591dc215781ae0d00236807","5595b49d608ea43900d8883e"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-29T20:43:38.701Z","from_sync":false,"order":1,"slug":"versions","title":"Versions"},"project":"543de77431ca981a00a700ec","version":{"_id":"55819c76a5474a0d00d945db","__v":6,"project":"543de77431ca981a00a700ec","forked_from":"543de77431ca981a00a700ef","createdAt":"2015-06-17T16:12:38.031Z","releaseDate":"2015-06-17T16:12:38.031Z","categories":["55819c76a5474a0d00d945dc","55883498b3bcf52b00513212","5591ad23c671980d00543dd7","5591adfa342e980d006db03b","5591ae005781ae0d00236737","5595b4c4f4437019002888fb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"user":"557b54fb9670ce0d0071b7bd","parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-30T00:00:33.284Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"In the second version of our API we introduced session based authentication for added security, the ability to purchase fractional loans, view pending orders, as well as various key name changes to make identifying fields easier and expose new fields. See the [Accessing our API](http://developers.fundingcircle.us/v2.0/docs/version-2#accessing-the-api) and [V2 Changes](http://developers.fundingcircle.us/v2.0/docs/version-2#changes-from-version-1) below for more information.   \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Accessing the API\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In order to make sure that your credentials stay secure, you will only be shown the password for API Authentication when it is first generated. If you lose or forget the password you will need to reset it on the API Management page and change any credentials you may have already setup, to use the new password.\",\n  \"title\": \"Credential Security\"\n}\n[/block]\nStarting with Version 2, Funding Circle uses session based token authentication for users to connect to our API. To begin using the API you will need to login using the API ID and Password that you have received from the API Management section of the investor portal [(sandbox link)](https://investor-portal.fc-sandbox.us/us/investors/oauth/applications) [(production link)](https://investor-portal.fundingcircle.us/us/investors/oauth/applications). \n\n\nTo test your account POST the follow code snippet (use your own API ID and Password) to: \nhttps://investor-api.fc-sandbox.us/api/v2/login\n\nWhen you are ready for production, you can POST your API ID and Password to:\nhttps://investor-api.fundingcircle.us/api/v2/login\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://investor-api.fundingcircle.us/api/v2/login\\n\\nPOST {\\\"username\\\": \\\"475f8c42-68o8-4191-a79e-492e2696b386\\\", \\\"password\\\":\\\"2212027e5cf7e5936394303eaod459722b\\\"}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou will be returned with a Bearer Token which will allow you access to the API for 2 hours before having to re-authenticate. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using your Bearer token\"\n}\n[/block]\nHere is an example of how to use the Bearer token in cURL. Remember to use the correct environment. \n\nFor Sandbox:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /listings/fbac75ae-ac1b-417e-ad0o-80f1e94b97d0 HTTP/1.1\\nHost: investor-api.fc-sandbox.us/api/v2\\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGcqiJIUzI1NiJ9.eyJpc3MiOiJogHRwczovL2ZjZGV2ZWxvcG1lbnQuYXV0aDAuY22tLyIsInN1YiI6ImF1dGgwfDf1OWM3YWJkNDg5N2IzYWIxMDFmZGVkNCIsImF1ZCI6IkN5S09MOWNOWlM1dE5DVDhSMjdJa0tQeUJDc01GcjBJIiwiZXhwIjoxNDM2NTg4MzMwLCJpYXQiOjE0MzY1NTIzMzB9.C8pNavn3E4LsOPNFE1s1DR4agwE4t25nXHNU8xppI2M\",\n      \"language\": \"curl\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nFor Production:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /listings/fbac75ae-ac1b-417e-ad0o-80f1e94b97d0 HTTP/1.1\\nHost: investor-api.fundingcircle.us/api/v2/\\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGcqiJIUzI1NiJ9.eyJpc3MiOiJogHRwczovL2ZjZGV2ZWxvcG1lbnQuYXV0aDAuY22tLyIsInN1YiI6ImF1dGgwfDf1OWM3YWJkNDg5N2IzYWIxMDFmZGVkNCIsImF1ZCI6IkN5S09MOWNOWlM1dE5DVDhSMjdJa0tQeUJDc01GcjBJIiwiZXhwIjoxNDM2NTg4MzMwLCJpYXQiOjE0MzY1NTIzMzB9.C8pNavn3E4LsOPNFE1s1DR4agwE4t25nXHNU8xppI2M\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Changes from Version 1\"\n}\n[/block]\nWe've made multiple changes in version 2 to enable faster and easier usage of our API.\nMajor changes from version 1 include:\n\n**Session based authentication **\n* Increases the security of your account,\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Token Expiration\",\n  \"body\": \"Bearer tokens will expire after 2 hours.\"\n}\n[/block]\n**Ability to purchase fractional loans**\n* Previously only whole loans could be purchased via the API. This enhancement allows you to purchase loans listed on the fractional market as well\n\n**Ability to view pending orders**\n* Whole loans that require a three day curing period will show up in this endpoint, giving you faster access to loans that you have purchased and are not yet in your holding account\n* Fractional loans may not be moved into your holding account until the entire loan is purchased. In the interim, those loans will show as pending. This endpoint gives you faster insight into which loans you have ordered, but are not yet in your holding account\n\n**Ability to see all loans**\n* [UNDER DEVELOPMENT] You will now be able to access all of the loans that Funding Circle has listed \n\n**Ability to see financial information for any loan**\n* [UNDER DEVELOPMENT] You will now be able to access financial information on all of the loans that Funding Circle has listed\n\n**New keys (see table below)**\n* New keys have been added to provide you with more information about your holdings and listings\n    \n**Key renaming (see table below)**\n* Key names now more clearly indicate the purpose of the value stored within them\n    \n**Key deprecation (see table below)**\n* Removed keys that were no longer necessary for cleaner API access\n    \n**Rate Limiting**\n* Access for API POSTs is limited to 40 times per second. Your POST will be distributed across a one second period allowing fair access to all investors who want to purchase listings.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"An important note of rate limiting\",\n  \"body\": \"Rate limiting is done at 40 calls/second, however, the calls must be spaced out to be more than 25ms apart. You cannot make 40 calls, wait the remainder of the second, and then make another 40 calls.\"\n}\n[/block]\n\n**Better / Standardized error messaging** \n* Our error messaging has been made consistent across the platform, as well as adding new error types and more important information about those errors. For more information on API Errors, please see the 'Errors' section  \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Endpoint Name Changes\"\n}\n[/block]\nThe following endpoints have changed\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Old (v1)\",\n    \"h-1\": \"New (v2)\",\n    \"0-1\": \"/holdings/:id/payments\",\n    \"1-1\": \"/summary\",\n    \"0-0\": \"/holdings/:id/repayments\",\n    \"1-0\": \"/portfolio\",\n    \"2-0\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"New Endpoints\"\n}\n[/block]\nWe've added the following Endpoint\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"0-0\": \"/orders\",\n    \"0-1\": \"Returns all pending orders (orders you have made but are not yet part of your account). These will be archived once the order settles.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API key name changes\"\n}\n[/block]\nThe following keys have been renamed\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"/holdings\",\n    \"h-0\": \"Endpoint\",\n    \"h-1\": \"Old key name\",\n    \"h-2\": \"New key name\",\n    \"0-1\": \"loan_part_id\",\n    \"0-2\": \"id\",\n    \"1-1\": \"what_loan_is_for\",\n    \"1-0\": \"/holdings/:id\",\n    \"3-1\": \"business_total_outstanding_debt_cents\",\n    \"4-1\": \"business_outstanding_debt_monthly_payment_cents\",\n    \"5-1\": \"website\",\n    \"6-1\": \"start_date\",\n    \"6-2\": \"origination_date\",\n    \"5-2\": \"website_url\",\n    \"4-2\": \"outstanding_debt_monthly_payment_cents\",\n    \"3-2\": \"total_outstanding_debt_cents\",\n    \"1-2\": \"use_of_funds\",\n    \"3-0\": \"/holdings/:id\",\n    \"4-0\": \"/holdings/:id\",\n    \"5-0\": \"/holdings/:id\",\n    \"6-0\": \"/holdings/:id\",\n    \"7-0\": \"/holdings/:id/payments\",\n    \"7-1\": \"paid_count\",\n    \"7-2\": \"count_of_payments_made\",\n    \"8-1\": \"settled_date\",\n    \"8-2\": \"settled_at\",\n    \"8-0\": \"/holdings/:id/payments\",\n    \"9-0\": \"/listings\",\n    \"9-1\": \"loan_id\",\n    \"9-2\": \"id\",\n    \"12-1\": \"business_total_outstanding_debt_cents\",\n    \"12-2\": \"total_outstanding_debt_cents\",\n    \"13-1\": \"business_outstanding_debt_monthly_payment_cents\",\n    \"13-2\": \"outstanding_debt_monthly_payment_cents\",\n    \"17-1\": \"website\",\n    \"17-2\": \"website_url\",\n    \"12-0\": \"/listings:id\",\n    \"13-0\": \"/listings:id\",\n    \"17-0\": \"/listings:id\",\n    \"18-0\": \"/listings/:id/financials\",\n    \"18-1\": \"year\",\n    \"18-2\": \"provided_for_year\",\n    \"19-0\": \"/transactions\",\n    \"20-0\": \"/transactions\",\n    \"20-1\": \"description\",\n    \"20-2\": \"comment\",\n    \"19-2\": \"transaction_code\",\n    \"19-1\": \"transaction_type\",\n    \"11-2\": \"use_of_funds\",\n    \"11-1\": \"what_loan_is_for (Note: this is now an array of strings)\",\n    \"11-0\": \"/listings:id\",\n    \"10-1\": \"loan_type\",\n    \"10-2\": \"type\",\n    \"10-0\": \"/listings\",\n    \"14-0\": \"/listings:id\",\n    \"15-0\": \"/listings:id\",\n    \"16-0\": \"/listings:id\",\n    \"14-1\": \"loan_id\",\n    \"14-2\": \"id\",\n    \"15-1\": \"why_should_you_lend_to_us\",\n    \"15-2\": \"reason_for_borrowing\",\n    \"16-1\": \"loan_type\",\n    \"16-2\": \"type\",\n    \"2-0\": \"/holdings/:id\",\n    \"2-1\": \"why_you_should_lend_to_us\",\n    \"2-2\": \"reason_for_borrowing\"\n  },\n  \"cols\": 3,\n  \"rows\": 21\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Key deprication\"\n}\n[/block]\nThe following keys have been depricated\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"/holdings/:id/payments\",\n    \"0-1\": \"active\",\n    \"h-0\": \"Endpoint\",\n    \"h-1\": \"Key\",\n    \"1-0\": \"/listings/:id\",\n    \"1-1\": \"additional_guarantors_provided\",\n    \"2-0\": \"/holdings/:id\",\n    \"2-1\": \"additional_guarantors_provided\",\n    \"3-0\": \"/holdings/:id\",\n    \"3-1\": \"city **(Note: removed from fractional loans only.)**\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"New keys\"\n}\n[/block]\nThe following keys have been added\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"/holdings:id\",\n    \"0-1\": \"total_cost_cents\\naccrued_interest_days\\naccrued_interest_cents\\nbusiness_name\\nowed_interest_cents\\nowed_investor_fee_cents\",\n    \"1-0\": \"/holdings/:id/financials\",\n    \"1-1\": \"holding_id\\ntotal_cost_cents\\naccrued_interest_days\\naccrued_interest_cents\\nbusiness_name\",\n    \"2-0\": \"/listings:id\",\n    \"2-1\": \"status\",\n    \"h-0\": \"Endpoint\",\n    \"h-1\": \"Key\",\n    \"3-0\": \"/summary\",\n    \"3-1\": \"annualized_net_return_ratio\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","excerpt":"","slug":"version-2","type":"basic","title":"Version 2"}
In the second version of our API we introduced session based authentication for added security, the ability to purchase fractional loans, view pending orders, as well as various key name changes to make identifying fields easier and expose new fields. See the [Accessing our API](http://developers.fundingcircle.us/v2.0/docs/version-2#accessing-the-api) and [V2 Changes](http://developers.fundingcircle.us/v2.0/docs/version-2#changes-from-version-1) below for more information. [block:api-header] { "type": "basic", "title": "Accessing the API" } [/block] [block:callout] { "type": "info", "body": "In order to make sure that your credentials stay secure, you will only be shown the password for API Authentication when it is first generated. If you lose or forget the password you will need to reset it on the API Management page and change any credentials you may have already setup, to use the new password.", "title": "Credential Security" } [/block] Starting with Version 2, Funding Circle uses session based token authentication for users to connect to our API. To begin using the API you will need to login using the API ID and Password that you have received from the API Management section of the investor portal [(sandbox link)](https://investor-portal.fc-sandbox.us/us/investors/oauth/applications) [(production link)](https://investor-portal.fundingcircle.us/us/investors/oauth/applications). To test your account POST the follow code snippet (use your own API ID and Password) to: https://investor-api.fc-sandbox.us/api/v2/login When you are ready for production, you can POST your API ID and Password to: https://investor-api.fundingcircle.us/api/v2/login [block:code] { "codes": [ { "code": "POST https://investor-api.fundingcircle.us/api/v2/login\n\nPOST {\"username\": \"475f8c42-68o8-4191-a79e-492e2696b386\", \"password\":\"2212027e5cf7e5936394303eaod459722b\"}", "language": "json" } ] } [/block] You will be returned with a Bearer Token which will allow you access to the API for 2 hours before having to re-authenticate. [block:api-header] { "type": "basic", "title": "Using your Bearer token" } [/block] Here is an example of how to use the Bearer token in cURL. Remember to use the correct environment. For Sandbox: [block:code] { "codes": [ { "code": "GET /listings/fbac75ae-ac1b-417e-ad0o-80f1e94b97d0 HTTP/1.1\nHost: investor-api.fc-sandbox.us/api/v2\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGcqiJIUzI1NiJ9.eyJpc3MiOiJogHRwczovL2ZjZGV2ZWxvcG1lbnQuYXV0aDAuY22tLyIsInN1YiI6ImF1dGgwfDf1OWM3YWJkNDg5N2IzYWIxMDFmZGVkNCIsImF1ZCI6IkN5S09MOWNOWlM1dE5DVDhSMjdJa0tQeUJDc01GcjBJIiwiZXhwIjoxNDM2NTg4MzMwLCJpYXQiOjE0MzY1NTIzMzB9.C8pNavn3E4LsOPNFE1s1DR4agwE4t25nXHNU8xppI2M", "language": "curl", "name": null } ] } [/block] For Production: [block:code] { "codes": [ { "code": "GET /listings/fbac75ae-ac1b-417e-ad0o-80f1e94b97d0 HTTP/1.1\nHost: investor-api.fundingcircle.us/api/v2/\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGcqiJIUzI1NiJ9.eyJpc3MiOiJogHRwczovL2ZjZGV2ZWxvcG1lbnQuYXV0aDAuY22tLyIsInN1YiI6ImF1dGgwfDf1OWM3YWJkNDg5N2IzYWIxMDFmZGVkNCIsImF1ZCI6IkN5S09MOWNOWlM1dE5DVDhSMjdJa0tQeUJDc01GcjBJIiwiZXhwIjoxNDM2NTg4MzMwLCJpYXQiOjE0MzY1NTIzMzB9.C8pNavn3E4LsOPNFE1s1DR4agwE4t25nXHNU8xppI2M", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Changes from Version 1" } [/block] We've made multiple changes in version 2 to enable faster and easier usage of our API. Major changes from version 1 include: **Session based authentication ** * Increases the security of your account, [block:callout] { "type": "warning", "title": "Token Expiration", "body": "Bearer tokens will expire after 2 hours." } [/block] **Ability to purchase fractional loans** * Previously only whole loans could be purchased via the API. This enhancement allows you to purchase loans listed on the fractional market as well **Ability to view pending orders** * Whole loans that require a three day curing period will show up in this endpoint, giving you faster access to loans that you have purchased and are not yet in your holding account * Fractional loans may not be moved into your holding account until the entire loan is purchased. In the interim, those loans will show as pending. This endpoint gives you faster insight into which loans you have ordered, but are not yet in your holding account **Ability to see all loans** * [UNDER DEVELOPMENT] You will now be able to access all of the loans that Funding Circle has listed **Ability to see financial information for any loan** * [UNDER DEVELOPMENT] You will now be able to access financial information on all of the loans that Funding Circle has listed **New keys (see table below)** * New keys have been added to provide you with more information about your holdings and listings **Key renaming (see table below)** * Key names now more clearly indicate the purpose of the value stored within them **Key deprecation (see table below)** * Removed keys that were no longer necessary for cleaner API access **Rate Limiting** * Access for API POSTs is limited to 40 times per second. Your POST will be distributed across a one second period allowing fair access to all investors who want to purchase listings. [block:callout] { "type": "info", "title": "An important note of rate limiting", "body": "Rate limiting is done at 40 calls/second, however, the calls must be spaced out to be more than 25ms apart. You cannot make 40 calls, wait the remainder of the second, and then make another 40 calls." } [/block] **Better / Standardized error messaging** * Our error messaging has been made consistent across the platform, as well as adding new error types and more important information about those errors. For more information on API Errors, please see the 'Errors' section [block:api-header] { "type": "basic", "title": "Endpoint Name Changes" } [/block] The following endpoints have changed [block:parameters] { "data": { "h-0": "Old (v1)", "h-1": "New (v2)", "0-1": "/holdings/:id/payments", "1-1": "/summary", "0-0": "/holdings/:id/repayments", "1-0": "/portfolio", "2-0": "" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "New Endpoints" } [/block] We've added the following Endpoint [block:parameters] { "data": { "h-0": "Name", "0-0": "/orders", "0-1": "Returns all pending orders (orders you have made but are not yet part of your account). These will be archived once the order settles." }, "cols": 2, "rows": 1 } [/block] [block:api-header] { "type": "basic", "title": "API key name changes" } [/block] The following keys have been renamed [block:parameters] { "data": { "0-0": "/holdings", "h-0": "Endpoint", "h-1": "Old key name", "h-2": "New key name", "0-1": "loan_part_id", "0-2": "id", "1-1": "what_loan_is_for", "1-0": "/holdings/:id", "3-1": "business_total_outstanding_debt_cents", "4-1": "business_outstanding_debt_monthly_payment_cents", "5-1": "website", "6-1": "start_date", "6-2": "origination_date", "5-2": "website_url", "4-2": "outstanding_debt_monthly_payment_cents", "3-2": "total_outstanding_debt_cents", "1-2": "use_of_funds", "3-0": "/holdings/:id", "4-0": "/holdings/:id", "5-0": "/holdings/:id", "6-0": "/holdings/:id", "7-0": "/holdings/:id/payments", "7-1": "paid_count", "7-2": "count_of_payments_made", "8-1": "settled_date", "8-2": "settled_at", "8-0": "/holdings/:id/payments", "9-0": "/listings", "9-1": "loan_id", "9-2": "id", "12-1": "business_total_outstanding_debt_cents", "12-2": "total_outstanding_debt_cents", "13-1": "business_outstanding_debt_monthly_payment_cents", "13-2": "outstanding_debt_monthly_payment_cents", "17-1": "website", "17-2": "website_url", "12-0": "/listings:id", "13-0": "/listings:id", "17-0": "/listings:id", "18-0": "/listings/:id/financials", "18-1": "year", "18-2": "provided_for_year", "19-0": "/transactions", "20-0": "/transactions", "20-1": "description", "20-2": "comment", "19-2": "transaction_code", "19-1": "transaction_type", "11-2": "use_of_funds", "11-1": "what_loan_is_for (Note: this is now an array of strings)", "11-0": "/listings:id", "10-1": "loan_type", "10-2": "type", "10-0": "/listings", "14-0": "/listings:id", "15-0": "/listings:id", "16-0": "/listings:id", "14-1": "loan_id", "14-2": "id", "15-1": "why_should_you_lend_to_us", "15-2": "reason_for_borrowing", "16-1": "loan_type", "16-2": "type", "2-0": "/holdings/:id", "2-1": "why_you_should_lend_to_us", "2-2": "reason_for_borrowing" }, "cols": 3, "rows": 21 } [/block] [block:api-header] { "type": "basic", "title": "Key deprication" } [/block] The following keys have been depricated [block:parameters] { "data": { "0-0": "/holdings/:id/payments", "0-1": "active", "h-0": "Endpoint", "h-1": "Key", "1-0": "/listings/:id", "1-1": "additional_guarantors_provided", "2-0": "/holdings/:id", "2-1": "additional_guarantors_provided", "3-0": "/holdings/:id", "3-1": "city **(Note: removed from fractional loans only.)**" }, "cols": 2, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "New keys" } [/block] The following keys have been added [block:parameters] { "data": { "0-0": "/holdings:id", "0-1": "total_cost_cents\naccrued_interest_days\naccrued_interest_cents\nbusiness_name\nowed_interest_cents\nowed_investor_fee_cents", "1-0": "/holdings/:id/financials", "1-1": "holding_id\ntotal_cost_cents\naccrued_interest_days\naccrued_interest_cents\nbusiness_name", "2-0": "/listings:id", "2-1": "status", "h-0": "Endpoint", "h-1": "Key", "3-0": "/summary", "3-1": "annualized_net_return_ratio" }, "cols": 2, "rows": 4 } [/block]