GET https://api.sandbox.crowdvalley.com/v1/{network}/public/stats
Returns a set of global statistics about your platform's activities.
Implement this to show on your homepage, for example, the total amount raised on your platform.
{ "outcome": "success", "data": { "sum_settled_investments": "The sum of all investment_amount values from all Investments on your platform that are Settled", "count_settled_investments": "The number of all Investments on your platform that are Settled", "count_settled_offerings": "The number of Offerings on your platform that are Settled", "count_investors_with_settled_investments": "The number of Users on your platform that have made at least one Settled Investment" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/users
Returns a list of public Users. Public Users are all Users with visibility
set to its default value of Open.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Users requested", "count": "The total number of Users available", "list": [ { "additional_type": "An additional type or category for the User", "affiliate_code": "A code that can be given out by the User to track that User's affiliate activity", "biography": "The User's biography", "created_at": "Date on which the User joined your platform", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ], "email": "The User's registered email address", "external_reference_id": "External reference identifier", "family_name": "The User's family name", "full_name": "The User's full name", "gender": "The gender of the User ('M' or 'F')", "given_name": "The User's given name", "has_been_approved": "Flag to show whether the User has been marked as Approved on your platform", "has_been_blocked": "Flag to show whether the User has been blocked from your platform", "honorific_prefix": "An honorific prefix preceding the User's name such as Dr/Mrs/Mr", "honorific_suffix": "An honorific suffix preceding the User's name such as MD/PhD/MSCSW", "id": "A Unique Identifier for the User", "image": "The User's profile image", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "is_admin": "Flag to show whether the User has admin rights for your platform", "is_vip": "Flag to show whether the User has been given 'VIP' status", "job_title": "The job title of the User (for example, CEO)", "location": "The User's location", "organizations": [ { "organization_id": "Unique Identifier for the Organization", "organization_name": "Display name of the Organization", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "status": "Boolean flag to show whether the User’s membership of the Organization is active", "contact_point": "Unique Identifier for the User who is this Organization’s `contact_point`" } ], "phone_1": "The User's primary phone number", "phone_2": "The User's secondary phone number", "referral_code": "The code that was entered by the User to connect them to another User acting as an affiliate", "registration_complete": "Flag to show whether the User has completed their registration requirements", "sector": "The User's industry or sector", "tagline": "A short tagline to summarise the User", "time_zone": "The User's timezone", "visibility": "The User's visibility (0 = Open, 1 = Hidden, 2 = Anonymous)", "web_site": "The User's website" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/organizations
Returns a list of public Organizations. Public Organizations are all Organizations with life_cycle_stage
as Approved, Restricted or Published.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Organizations requested", "count": "The total number of Organizations available", "list": [ { "additional_type": "An additional type or category for the Organization", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "alternate_name": "An alternate name for the Organization", "approved_at": "Date on which the Organization was marked as Approved", "brief_desc": "A brief description of the Organization", "canceled_at": "Date on which the Organization was marked as Canceled", "company_number": "The company registration number for the Organization", "contact_point": "A Unique Identifier for the User who represents the Organization's contact point", "created_at": "Date on which the Organization was created", "credit_score": "The Organization's current credit score", "custom": { "The name of the custom field": "The value of the custom field" }, "detail_desc": "A long-form, detailed description of the Organization", "display_name": "The display name of the Organization", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "facebook": "The Organization's Facebook account page", "founding_date": "Date on which the Organization was founded", "founding_location": "Location at which the Organization was founded", "fundamerica_entity_id": "Unique identifier for the Fund America entity that represents this Organization", "gcen_client_id": "Unique identifier for the GCEN client that represents this Organization", "id": "A Unique Identifier for the Organization", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "legal_name": "Full legal name of the Organization", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Canceled", "linkedin": "The Organization's LinkedIn account page", "location": "The Organization's location", "logo": "The Organization's logo image", "mangopay_card_id": "The Organization’s Mangopay-registered payment card identifier", "mangopay_user_id": "The Organization’s Mangopay account identifier when used to represent a Legal User", "mangopay_wallet_id": "The Organization's Mangopay wallet identifier", "members": [ { "user_id": "A Unique Identifier for the User", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "user_full_name": "The `full_name` of the User", "contact_point": "The `contact_point` of the Organization" } ], "org_email": "An email address for the Organization", "reyker_isin": "The Organization's ISIN code", "sector": "The Organization's industry or sector", "submitted_at": "Date on which the Organization was marked as Submitted", "tax_id": "The Tax / Fiscal ID of the Organization", "telephone": "A phone number for the Organization", "twitter": "The Organization's Twitter account page", "updated_at": "Date on which the Organization was last updated", "user_name": "The `full_name` of the User who created this Organization", "user_id": "A Unique Identifier for the User who created this Organization", "visibility": "0 = Open, 1 = Hidden, 2 = Anonymous", "website": "A URL of a reference webpage that represents the Organization", "youtube": "The Organization's YouTube account page" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/organizations/{organization_id}
Returns a an Organization without requiring the User to be logged in. Public Organizations are all Organizations with life_cycle_stage
as Approved, Restricted or Published.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "organization": { "additional_type": "An additional type or category for the Organization", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "alternate_name": "An alternate name for the Organization", "approved_at": "Date on which the Organization was marked as Approved", "brief_desc": "A brief description of the Organization", "canceled_at": "Date on which the Organization was marked as Canceled", "company_number": "The company registration number for the Organization", "contact_point": "A Unique Identifier for the User who represents the Organization's contact point", "created_at": "Date on which the Organization was created", "credit_score": "The Organization's current credit score", "custom": { "The name of the custom field": "The value of the custom field" }, "detail_desc": "A long-form, detailed description of the Organization", "display_name": "The display name of the Organization", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "facebook": "The Organization's Facebook account page", "founding_date": "Date on which the Organization was founded", "founding_location": "Location at which the Organization was founded", "fundamerica_entity_id": "Unique identifier for the Fund America entity that represents this Organization", "gcen_client_id": "Unique identifier for the GCEN client that represents this Organization", "id": "A Unique Identifier for the Organization", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "legal_name": "Full legal name of the Organization", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Canceled", "linkedin": "The Organization's LinkedIn account page", "location": "The Organization's location", "logo": "The Organization's logo image", "mangopay_card_id": "The Organization’s Mangopay-registered payment card identifier", "mangopay_user_id": "The Organization’s Mangopay account identifier when used to represent a Legal User", "mangopay_wallet_id": "The Organization's Mangopay wallet identifier", "members": [ { "user_id": "A Unique Identifier for the User", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "user_full_name": "The `full_name` of the User", "contact_point": "The `contact_point` of the Organization" } ], "org_email": "An email address for the Organization", "reyker_isin": "The Organization's ISIN code", "sector": "The Organization's industry or sector", "submitted_at": "Date on which the Organization was marked as Submitted", "tax_id": "The Tax / Fiscal ID of the Organization", "telephone": "A phone number for the Organization", "twitter": "The Organization's Twitter account page", "updated_at": "Date on which the Organization was last updated", "user_name": "The `full_name` of the User who created this Organization", "user_id": "A Unique Identifier for the User who created this Organization", "visibility": "0 = Open, 1 = Hidden, 2 = Anonymous", "website": "A URL of a reference webpage that represents the Organization", "youtube": "The Organization's YouTube account page" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/featuredOfferings
Returns a list of featured Offerings. Featured Offerings are those marked by the is_featured
flag being set to true
. Offerings can be marked as 'featured' in the Crowd Valley admin portal.
Use Featured Offerings to display a list of Offerings to users who are not logged in to your platform, for instance on a front-end homepage.
Featured Offerings only retrieves Offerings with life_cycle_stage
as Approved, Restricted or Published.
Note that in some regulatory environments there are restrictions related to the marketing of private securities. In those cases you can use GET /offerings, which requires the user to be authenticated in order to retrieve any information about the platform's Offerings.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/offerings
Returns a list of Offerings.
This function is similar to the GET /offerings
function, although this 'public' endpoint version is available to website visitors of your front-end before they are authenticated.
If you want to allow your website visitors to see information about all Offerings before logging in then implement this feature on your Offerings list page.
This function retrieves Offerings whose life_cycle_stage
is Published or Settled.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/offerings/{offering_id}
Returns information about a given Offering specified by the offering_id
path parameter.
This function is similar to the GET /offerings/{offering_id}
function, although this 'public' endpoint version is available to website visitors of your front-end before they are authenticated.
If you want to allow your website visitors to see information about an Offering before logging in then implement this feature on your Offering overview page.
This function will only return the Offering if its life_cycle_stage
is Published or Settled.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offering": { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/public/verifyEmail
Validates a User's email address.
This function requires the parameters user_id
and secret
, which must be generated by calling POST /users
or POST /self/resendVerificationEmail
in advance of reaching the page from which POST /public/verifyEmail
is called.
Successfully calling this function sets the User's email_verified
flag to true
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network. |
|
user_id | Body | Integer | The |
|
secret | Body | String | The secret string sent by the Crowd Valley Back Office to the User by email, after calling |
{ "user_id" : "1234", "secret" : "Jkt8RBs4AsFnl5FmzR2tZ16B0" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
Exception | HTTP Response | User Message | Developer Message |
---|---|---|---|
10017 | 400 (BAD REQUEST) | Failed to re-send verification email |
Parameter missing: |
10018 | 400 (BAD REQUEST) | Failed to re-send verification email |
Parameter missing: |
10019 | 404 (NOT FOUND) | Email address not recognized - please check that you have entered the correct email address without any typos |
No User with this email address was found |
10020 | 400 (BAD REQUEST) | Invalid email address - please check that you have entered the correct email address without any typos |
The User entered an invalid email address |
10021 | 409 (CONFLICT) | You have already verified your email address |
The User already has |
POST https://api.sandbox.crowdvalley.com/v1/{network}/public/forgotPassword
Sends an email to a User who has forgotten their password and therefore cannot log in. The email contains a link that the User should click in order to go to your front-end site and create a new password.
This function takes as a parameter a url
, which should be a page on your front-end site, and generates a link that includes the parameters user_id
and secret
. The parameter user_id
is the id
of the User in your database with email address equal to the required email
parameter of this function.
For example, if you send as parameters: url
= https://www.yoursite.com/password-reset-page and email
= john.doe@test.com then Crowd Valley's back-end will send an email to john.doe@test.com with a link such as http://www.mysite.com/reset-password?user_id=1234&secret=73kVx83z9w8wdF41fsJkxjRm1, if your network has a User with email
= john.doe@test.com and id
= 1234.
Your front-end page http://www.mysite.com/reset-password should then parse the full link to retrieve the parameters: user_id
and email
and use them to implement POST /{network}/public/resetPassword
, which actually resets the User's password to a new value.
The link in the User's email is only valid for 24 hours. If 24 hours have passed after having received the email, the User must generate a new link by calling this function again.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network. |
|
url | Body | String | The full URL of a page on your front-end site to which the User will be sent by clicking the activation link in an email sent by the Crowd Valley back-end. |
|
Body | String | The email of the User who has forgotten their password. |
{ "url" : "https://www.yoursite.com/password-reset-page", "email" : "john.doe@test.com" }
{ "outcome": "success", "data": { "user_id": "The ID of the User who has forgotten their password." }, "status": 200 }
Exception | HTTP Response | User Message | Developer Message |
---|---|---|---|
10009 | 400 (BAD REQUEST) | Failed to send forgot password link |
Parameter missing: |
10010 | 400 (BAD REQUEST) | Failed to send forgot password link |
Parameter missing: |
10011 | 404 (NOT FOUND) | Email address not recognized - please check that you have entered the correct email address without any typos |
No User with this email address was found |
10012 | 400 (BAD REQUEST) | Invalid email address - please check that you have entered the correct email address without any typos |
The User entered an invalid email address |
POST https://api.sandbox.crowdvalley.com/v1/{network}/public/resetPassword
Resets the User's password to a new value defined by the password
parameter.
This function requires the parameters user_id
and secret
, which must be generated by calling POST /{network}/public/forgotPassword
in advance of reaching the page from which POST /{network}/public/resetPassword
is called.
The function also requires a password_confirm
parameter, which must be equal to the password
parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network. |
|
user_id | Body | Integer | The |
|
secret | Body | String | The secret string sent by the Crowd Valley Back Office to the User by email, after calling |
|
password | Body | String | The User's new password. |
|
password_confirm | Body | String | Confirmation of the User's new password. |
{ "user_id" : "1000", "secret" : "5vnhfv2Afrz13ZctbJ0PrJrhs", "password" : "NewPassword123!", "password_confirm" : "NewPassword123!" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
Exception | HTTP Response | User Message | Developer Message |
---|---|---|---|
10001 | 409 (CONFLICT) | Passwords do not match |
The password and password_confirm fields are not equal |
10002 | 404 (NOT FOUND) | Email address not recognized. Please check that you have entered the correct email address without any typos |
No User with this email address was found |
10003 | 400 (BAD REQUEST) | Failed to reset password |
Invalid |
10004 | 409 (CONFLICT) | Your password reset link has expired - please request a new verification email and click the link within 24 hours |
The User's password reset link has expired after 24 hours. Please allow the User to request a new link in order to reset their password. |
10005 | 400 (BAD REQUEST) | Failed to reset password |
Parameter missing: |
10006 | 400 (BAD REQUEST) | Failed to reset password |
Parameter missing: |
10007 | 400 (BAD REQUEST) | Failed to reset password |
Parameter missing: password |
10008 | 400 (BAD REQUEST) | Failed to reset password |
Parameter missing: password_confirm |
POST https://api.sandbox.crowdvalley.com/v1/{network}/public/newsletterSignUp
Creates an alert for the admin team that a website visitor or User wishes to subscribe to a newsletter list.
Note that this does not add the email address to any live newsletter list; it should be used simply as an alert for the admin team to add the email address to your preferred marketing newsletter system.
It requires an email
parameter, which should be the website visitor's or User's email address.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network. |
|
Body | String | The email address of the User or website visitor who wants to sign up to a newsletter. |
{ "email" : "john.doe@test.com" }
{ "outcome": "success", "data": { "message": "Message confirming the email address that requested to sign up to a newsletter list" }, "status": 200 }
Exception | HTTP Response | User Message | Developer Message |
---|---|---|---|
10022 | 400 (BAD REQUEST) | Invalid email address - please check that you have entered the correct email address without any typos |
The User entered an invalid email address |
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/globals
Returns the global constants for your platform.
Global constants can be set by admin users in the Back Office.
{ "outcome": "success", "data": { "key": "value" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/public/applications
Returns a list of Applications for your network that have life_cycle_stage
of 2 (Approved).
Implement this feature for bid/auction models in P2P lending where a request to lend or borrow is represented by an Application object.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Applications requested", "count": "The total number of Applications available", "list": [ { "additional_type": "An additional type or category for the Application", "author_id": "A Unique Identifier for the User who created this Application", "code": "A configurable internal code for the Application", "created_at": "Date on which the Application was created", "custom": { "The name of the custom field": "The value of the custom field" }, "description": "A description of the Application", "funding_goal": "The funding goal for the Application", "id": "A Unique Identifier of the Application", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate of the Application", "investment_amount": "The investment amount of the Application", "life_cycle_stage": "The current Lifecycle Stage of the Application. 0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Completed.", "number_of_shares": "The number of shares of the Application", "offering": "The Unique Identifier for the Offering of the Application", "organization": "The Unique Identifier for the Organization of the Application", "price_per_share": "The price per share of the Application", "term": "The term of the Application", "updated_at": "Date on which the Application was last updated", "user_id": "A Unique Identifier for the User who is responsible for this Application", "user_name": "The full_name of the User who is responsible for this Application" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/authenticate
Log in as a named User in your network.
{ "outcome": "success", "data": { "token": "Authentication token that can be used in the 'cv-auth' header to act as this User", "network": "Platform's network name" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/social/facebook/link
Retrieve a link to which the User should be directed in order to log in to your platform with a Facebook account.
In order to implement this feature you will need to add your platform's Facebook App credentials to your Crowd Valley account.
The redirect_uri
query parameter is required for the Facebook authentication process to work correctly. It should be set as the URL for a page to which the User should be directed after completing the authentication process with Facebook. This URL must also be associated to your Facebook application, and this can be set through the Facebook developer portal.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
redirect_uri | Query | String | The page to which your User should be redirected after authenticating with Facebook |
{ "outcome": "success", "data": { "url": "URL for logging in using a Facebook account" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/social/twitter/link
Retrieve a link to which the User should be directed in order to log in to your platform with a Twitter account.
In order to implement this feature you will need to add your platform's Twitter App credentials to your Crowd Valley account.
The url
returned by this function contains an oauth_token_secret
query parameter. It should be stored in session on your front-end to be used in next step, POST /social/twitter/authenticate
.
In the second step after the User is authorised by Twitter and is being redirected to the front-end resource_uri, there are 2 GET parameters: oauth_token & oauth_verifier, and all three parameters need to be sent to POST /social/twitter/authenticate
:
[ 'oauth_token' => ‘…’ 'oauth_token_secret' => ‘…’ 'oauth_verifier' => ‘…’ ]
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "url": "URL for logging in using a Twitter account" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/social/linkedin/link
Retrieve a link to which the User should be directed in order to log in to your platform with a LinkedIn account.
In order to implement this feature you will need to add your platform's LinkedIn App credentials to your Crowd Valley account.
The redirect_uri
query parameter is required for the LinkedIn authentication process to work correctly. It should be set as the URL for a page to which the User should be directed after completing the authentication process with LinkedIn. This URL must also be associated to your LinkedIn application, and this can be set through the LinkedIn developer portal.
If the redirect_uri
is either not provided or is not recognised by LinkedIn as being associated with your application then the url
generated by this function will show a page with an error: Invalid redirect URI.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
redirect_uri | Query | String | The page to which your User should be redirected after authenticating with LinkedIn |
{ "outcome": "success", "data": { "url": "URL for logging in using a LinkedIn account" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/social/facebook/authenticate
Logs the User in to your platform using an authenticated Facebook account.
The feature requires a code
parameter that is returned by Facebook after the User has granted access to their Facebook account. It also requires two URLs: redirect_uri
, which should be the full URL of the page from which you implement this function, and which must be associated to your Facebook App in the Facebook Developer Dashboard; and url
, which should be the full URL of the page to which Facebook should return the User after they log in, and which should then use a jwt-auth
header to allow the User to continue.
In order to implement this feature you will need to add your platform's Facebook App credentials to your Crowd Valley account.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
code | Query | String | Authentication code returned by Facebook after the User has granted access to their account |
|
redirect_uri | Query | String | The Redirect URL associated to your Facebook App, from which you should implement this API call |
|
url | Query | String | The URL to which Facebook should return the User after granting access to their account |
{ "code" : "Authentication code returned by Facebook after the User has granted access to their account", "redirect_uri" : "The Redirect URL associated to your Facebook App, from which you should implement this API call", "url" : "The URL to which Facebook should return the User after granting access to their account" }
{ "outcome": "success", "data": { "token": "A token that can be used in a `jwt-auth` header to allow the User to authenticate with Crowd Valley's API using SSO", "user_id": "The `id` of the logged-in User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/social/twitter/authenticate
Logs the User in to your platform using an authenticated Twitter account.
The feature requires a code
parameter that is returned by Twitter after the User has granted access to their Twitter account. It also requires two URLs: redirect_uri
, which should be the full URL of the page from which you implement this function, and which must be associated to your Twitter App in the Twitter Developer Dashboard; and url
, which should be the full URL of the page to which Twitter should return the User after they log in, and which should then use a jwt-auth
header to allow the User to continue.
In order to implement this feature you will need to add your platform's Twitter App credentials to your Crowd Valley account.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
code | Query | String | Authentication code returned by Twitter after the User has granted access to their account |
|
redirect_uri | Query | String | The Redirect URL associated to your Twitter App, from which you should implement this API call |
|
url | Query | String | The URL to which Twitter should return the User after granting access to their account |
{ "code" : "Authentication code returned by Twitter after the User has granted access to their account", "redirect_uri" : "The Redirect URL associated to your Twitter App, from which you should implement this API call", "url" : "The URL to which Twitter should return the User after granting access to their account" }
{ "outcome": "success", "data": { "token": "A token that can be used in a `jwt-auth` header to allow the User to authenticate with Crowd Valley's API using SSO", "user_id": "The `id` of the logged-in User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/social/linkedin/authenticate
Logs the User in to your platform using an authenticated LinkedIn account.
The feature requires a code
parameter that is returned by LinkedIn after the User has granted access to their LinkedIn account. It also requires two URLs: redirect_uri
, which should be the full URL of the page from which you implement this function, and which must be associated to your LinkedIn App in the LinkedIn Developer Dashboard; and url
, which should be the full URL of the page to which LinkedIn should return the User after they log in, and which should then use a jwt-auth
header to allow the User to continue.
In order to implement this feature you will need to add your platform's LinkedIn App credentials to your Crowd Valley account.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
code | Query | String | Authentication code returned by LinkedIn after the User has granted access to their account |
|
redirect_uri | Query | String | The Redirect URL associated to your LinkedIn App, from which you should implement this API call |
|
url | Query | String | The URL to which LinkedIn should return the User after granting access to their account |
{ "code" : "Authentication code returned by LinkedIn after the User has granted access to their account", "redirect_uri" : "The Redirect URL associated to your LinkedIn App, from which you should implement this API call", "url" : "The URL to which LinkedIn should return the User after granting access to their account" }
{ "outcome": "success", "data": { "token": "A token that can be used in a `jwt-auth` header to allow the User to authenticate with Crowd Valley's API using SSO", "user_id": "The `id` of the logged-in User" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self
Populate information on an user's private account page.
{ "outcome": "success", "data": { "user": { "additional_name": "An additional name for the User", "additional_type": "An additional type or category for the User", "address": { "building": "The building name or number (Address Line 1)", "sub_building": "The flat name or number", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "addresses": [ { "id": "Unique Identifier for the Address", "building": "The building name or number (Address Line 1)", "sub_building": "The flat name or number", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" } ], "affiliate_code": "A code that can be given out by the User to track that User's affiliate activity", "bank_accounts": [ { "id": "Unique identifier for the Bank Account", "bank_name": "The bank's name", "bank_account_number": "Bank Account Number", "bank_swift_code": "Bank Account SWIFT code", "bank_routing_number": "Bank Account Routing number", "bank_address": "The bank's address", "bank_currency": "The bank's currency code", "bank_country": "The bank's country in ISO 3166-1 Alpha 2 format" } ], "biography": "The User's biography", "birth_country": "The User's country of birth", "birth_date": "The User's date of birth", "birth_place": "The User's place of birth", "created_at": "Date on which the User joined your platform", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Difitek CDN, 1 = External CDN" } ], "driving_license_number": "The User's full driving license number", "email": "The User's registered email address", "email_verified": "Flag to show whether the User has verified their email account", "external_reference_id": "External reference identifier", "family_name": "The User's family name", "full_name": "The User's full name", "fundamerica_entity_id": "The User's unique identifier as an entity registered with Fund America", "gbg_pass_id": "The User's last GBGroup AML/KYC Check identifier", "gcen_client_id": "The User's GCEN Client ID", "gender": "The gender of the User ('M' or 'F')", "given_name": "The User's given name", "has_been_approved": "Flag to show whether the User has been marked as Approved on your platform", "has_been_blocked": "Flag to show whether the User has been blocked from your platform", "honorific_prefix": "An honorific prefix preceding the User's name such as Dr/Mrs/Mr", "honorific_suffix": "An honorific suffix preceding the User's name such as MD/PhD/MSCSW", "id": "A Unique Identifier for the User", "image": "The User's profile image", "income_range": "The User's income range", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "is_admin": "Flag to show whether the User has admin rights for your platform", "is_vip": "Flag to show whether the User has been given 'VIP' status", "job_title": "The job title of the User (for example, CEO)", "last_login_at": "Date on which the User last logged in to your platform", "location": "The User's location", "mangopay_card_id": "The User’s Mangopay-registered payment card identifier", "mangopay_user_id": "The User’s Mangopay account identifier", "nationality": "The User's nationality", "organizations": [ { "organization_id": "Unique Identifier for the Organization", "organization_name": "Display name of the Organization", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "status": "Boolean flag to show whether the User’s membership of the Organization is active", "contact_point": "Unique Identifier for the User who is this Organization’s `contact_point`" } ], "passport_country": "The country that issued the User's passport", "passport_expiry": "The expiry date of the User's passport in 'MMYY' format", "passport_number": "The User's full passport number", "password_expired": "Flag to show whether the User's password has expired", "phone_1": "The User's primary phone number", "phone_2": "The User's secondary phone number", "phone_verified": "Flag to show whether the User has verified their phone number", "referral_code": "The code that was entered by the User to connect them to another User acting as an affiliate", "registration_complete": "Flag to show whether the User has completed their registration requirements", "reyker_id": "The User's Reyker Unique Identifier", "sector": "The User's industry or sector", "tagline": "A short tagline to summarise the User", "tax_id": "The Tax / Fiscal ID of the User", "term_service_accepted": "Flag to show whether the User has accepted Terms and Conditions for your platform", "time_zone": "The User's timezone", "updated_at": "Date on which the User’s information was last updated", "visibility": "The User's visibility (0 = Open, 1 = Hidden, 2 = Anonymous)", "web_site": "The User's website" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/stats
View some investment statistics about the logged-in User's investment activity.
This function is typically implemented to show some high-level dashboard statistics for the User to see about their own investments.
The statistics are calculated based on the User's Investments, Payouts and Transactions.
The calculation for total_dividends_received
is as follows:
payout_type
== 0 (Dividend), find all Transactions for each Payout where Transaction > payment_status
== 1 (Paid)transaction_amount
values and return itThe calculation for total_capitalgains_received
is same as above but for Payout > payout_type
== 1 (Capital Gain). Similarly, the calculation of total_loanrepayments_received
uses Payout > payout_type
== 2 (Loan Repayment).
The calculation for outstanding_dividends
and the other similar values is as follows:
payout_type
== 0 (Dividend)transaction_amount
values and subtract the amount calculated in total_dividends_received
Therefore this figure represents the amount of dividends that a User expects to receive but has not yet been paid.
The investment statistics can be filtered by start_date
and end_date
by using the following syntax:
GET /self/stats?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
{ "outcome": "success", "data": { "outstanding_capitalgains": "Scheduled but unpaid Capital Gains", "outstanding_dividends": "Scheduled but unpaid Dividends", "outstanding_loanrepayments": "Scheduled but unpaid Loan Repayments", "total_capitalgains_received": "Total Capital Gains Received", "total_dividends_received": "Total Dividends Received", "total_loanrepayments_received" : "Total Loan Repayments Received" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/portfolio
View the User's portfolio based on their investment activity.
The array given in the portfolio
is typically used to populate a tax statement or portfolio page for a User. The data are provided as follows, for each of the User's Capitalizations:
{
"name": Capitalization > Organization > display_name
"acquisition_date": Capitalization > created_at
"number_of_shares": Capitalization > number_of_shares
"dividends_received": Sum of all ‘payout_amount’ in Capitalization > Payouts where payout_type == 0 (Dividend)
"sales_proceeds": Sum of (price_per_share_at_acquisition x number_of_shares_at_acquisition) of all Capitalization > child Capitalizations, i.e., the total value of the shares that this User sold on a secondary market
"investment_cost": Capitalization > price_per_share_at_acquisition x number_of_shares_at_acquisition)
"transaction_cost": Capitalization > transaction_cost
"capital_gains_realised": Sum of all ‘investment_cost - transaction_cost’ in the sold child Capitalizations
"sales": for all child Capitalizations that have been sold:
[
{
"sale_date": Child Capitalization > created_at
"number_of_shares": Child Capitalization > number_of_shares
"price_per_share": Child Capitalization > price_per_share
"sales_proceeds": Child Capitalization > (price_per_share_at_acquisition x number_of_shares_at_acquisition)
"investment_cost": Parent Capitalization > original price_per_share_at_acquisition x child Capitalization > number_of_shares
"transaction_cost": Child Capitalization > transaction_cost
"capital_gains": Child Capitalization > investment_cost - transaction_cost
}
],
"offered": for all child Capitalizations that are currently offered on the secondary market by the User:
[
{
...
}
],
"held": for all child Capitalizations that are still held by the User:
[
{
...
}
]
}
The portfolio can be filtered by start_date
and end_date
by using the following syntax:
GET /self/portfolio?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
{ "outcome": "success", "data": { "portfolio": [ { "name": "Organization in which the User owns a Capitalization", "acquisition_date": "Acquisition date of the Capitalization", "number_of_shares": "Number of shares owned through the Capitalization", "dividends_received": "Dividends received for this Capitalization", "sales_proceeds": "Sales proceeds made from this Capitalization", "investment_cost": "Original cost of this Capitalization", "capital_gains_realised": "Capital Gains received for this Capitalization", "sales": [ { "sale_date": "Date of sale on the secondary market", "number_of_shares": "Number of shares sold", "price_per_share": "Sale price per share", "sales_proceeds": "Amount raised through the sale", "investment_cost": "Original cost of the shares sold", "capital_gains": "Capital Gains made from the original shares" } ], "sales": [ { "sale_date": "Date on which the shares were split", "number_of_shares": "Number of shares on offer", "price_per_share": "Sale price per share", "sales_proceeds": "0, "investment_cost": "Original cost of the shares", "capital_gains": "0" } ], "held": [ { "sale_date": "Date on which the Offering was split", "number_of_shares": "Number of shares in this batch of shares", "price_per_share": "Current price per share", "sales_proceeds": "0", "investment_cost": "Original cost of the shares", "capital_gains": "0" } ] } ] }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/self
Update the logged-in user's profile information.
Any parameter that is "Editable" in the User data model can be updated by implementing this method.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
additional_type | Body | String | An additional type or category for the User. Use this to define categories or groups of Users |
|
address | Body | { 'id' : Integer, 'building' : String, 'street_address' : String, 'city' : String, 'address_locality' : String, 'region' : String, 'postal_code' : String, 'country' : ISO_3166-1 alpha2 Country Code } | The User's address. All fields within the Address are optional. To update an existing address, include the |
|
affiliate_code | Body | String | A code that can be given out by the User to track that User's affiliate activity |
|
bank_accounts | Body | [ { 'id' : Integer, 'bank_account_number' : String, 'bank_address' : Address, 'bank_country' : String, 'bank_currency' : String, 'region' : ISO 4217 Currency Code, 'bank_name' : String, 'bank_routing_number' : String, 'bank_swift_code' : String } ] | The User's Bank Account. All fields within the Bank Account are optional. To update an existing Bank Account, include the |
|
biography | Body | String | The User's biography |
|
birth_date | Body | ISO 8601 Date | The User's date of birth |
|
birth_place | Body | String | The User's place of birth |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom User fields. Use an existing custom attribute name to replace the existing value. Use a new custom attribute name to add a new custom field |
|
driving_license_number | Body | String | The User's full driving license number |
|
external_reference_id | Body | String | External reference identifier |
|
family_name | Body | String | Family name |
|
gender | Body | String ('M' or 'F') | The gender of the User |
|
given_name | Body | String | The User's given name |
|
honorific_prefix | Body | String | An honorific prefix preceding the User's name |
|
honorific_suffix | Body | String | An honorific suffix following the User's name |
|
image | Body | Integer | The |
|
income_range | Body | String | The User's income range |
|
is_vip | Body | Boolean (1 or 0) | Flag to show whether the User has been given 'VIP' status |
|
job_title | Body | String | The job title of the User |
|
location | Body | String | The User's location |
|
nationality | Body | ISO 3166-1 alpha-2 Country Code | The User's nationality |
|
passport_country | Body | ISO 3166-1 alpha-2 Country Code | The country that issued the User's passport |
|
passport_expiry | Body | 'Y-m-d' Date | The expiry date of the User's passport in 'Y-m-d' format e.g. 2020-12-21 |
|
passport_number | Body | String | The User's full passport number |
|
phone_1 | Body | String | The User's primary phone number |
|
phone_2 | Body | String | The User's secondary phone number |
|
sector | Body | String | The User's industry or sector |
{ "tagline": "My tagline", "address" : { "building" : "One Market Plaza", "street_address" : "Spear Tower", "city" : "San Francisco" }, "bank_accounts": [ { "id": "Unique identifier of the Bank Details record", "bank_name": "Bank Name", "bank_account_number": "ABC123456", "bank_swift_code": "XYZ12345", "bank_routing_number": "ABC123", "bank_address": "1000 Main Street", "bank_currency": "USD", "bank_country": "US" } ], "visibility" : "1" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/acceptTerms
Accept End User Terms and Conditions. Accepting Terms can be implemented as part of creating a user or as a separate step.
Calling this function sets the logged-in User's term_service_accepted
attribute to true
.
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/resetAcceptTerms
Reset the User's acxceptance of the End User Terms and Conditions.
Calling this function sets the logged-in User's term_service_accepted
attribute to false.
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/resendVerificationEmail
Re-sends an email to the logged-in User, which contains the private link that is required for the User to verify their email address.
Implement this function on a holding page on your front-end that a User sees before they have validated their email address. Users should be able to re-send the verification email in case they entered the incorrect email when creating their account or they were unable to find their email.
When enabled in the Back Office application, the first verification email is sent as soon as POST /users
is called, which creates the User on your platform. By default the User's email_verified
attribute is set to false
. It can be set to true
by implementing POST /public/verifyEmail
on the page that you specify in the url
attribute of POST /users
.
The secret
provided to the User in the verification email has a time limit of 24 hours, so if your User has not been able to verify their email within 24 hours of creating their account, they will need to resend the verification email using this function.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network. |
|
url | Body | String | The full URL of a page on your front-end site to which the User will be sent by clicking the activation link in an email sent by the Crowd Valley back-end |
{ "url" : "https://www.yoursite.com/verify-email" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User who re-sent the verification email" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/changePassword
Change the User's password.
This function is typically implemented on a My Account or My Profile page on your platform front-end. Users must be able to provide their correct existing password in order to change it to a new password.
The function returns a token
for the logged-in User that can be used on the front-end to keep the User logged in after changing their password.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
password | Body | String | The logged-in User's existing password |
|
new_password | Body | String | The logged-in User's new password |
|
new_password_confirm | Body | String | Confirm the logged-in User's new password |
{ "current_password" : "Password123!", "new_password" : "NewPassword123!", "new_password_confirm" : "NewPassword123!" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User who changed their password", "token": "Authentication token that can be used in the 'cv-auth' header to act as this User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/changeEmail
Change the User's email.
This function is typically implemented on a My Account or My Profile page on your platform front-end. Calling this function will reset the User's email_verified
flag to false and send a new system email from the Crowd Valley back-end with a new verification link.
The function returns a token
for the logged-in User that can be used on the front-end to keep the User logged in after changing their email address.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
verify_email_url | Body | String | The full URL of a page on your front-end site to which the User will be sent by clicking the activation link in an email sent by the Crowd Valley back-end |
|
new_email | Body | String | The logged-in User's new email address |
|
new_email_confirm | Body | String | Confirm the logged-in User's new email address |
{ "verify_email_url" : "https://www.your-site.com/verify-email", "new_email" : "newemail@test.com", "new_email_confirm" : "newemail@test.com" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User who changed their email address", "token": "Authentication token that can be used in the 'cv-auth' header to act as this User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/approveUser
Mark the logged-in User as Approved as part of the platform's user onboarding process.
Calling this function sets the User's has_been_approved
attribute to true
.
In any user onboarding process, platforms have various options to determine when a User should be considered ready to engage fully with their Offerings. Typically, in order of importance, the basic levels are:
term_service_accepted
registration_complete
has_been_approved
In other words, a User should first accept a platform's terms and conditions, and then complete your registration process, and then be approved either automatically or manually by admin users in the Back Office application.
Then by calling GET /self
when the User logs in, you can find out whether the User has passed each step or not. Based on that status, you can either allow them or prevent them from accessing certain pages or features in your front-end application.
If you require further steps or levels then you can use custom User fields to represent as many additional flags or settings as you require. For instance, if you require a custom is_accredited_investor
field then you can simply create this as a custom User field, using PATCH /self
, with a value of 1 or 0 as appropriate.
Each step is optional and depends solely on your business and compliance requirements.
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/markRegistrationComplete
Mark the logged-in User as having completed your registration requirements as part of the platform's user onboarding process.
Calling this function sets the User's registration_complete
attribute to true
.
For more about onboarding processes, see the discussion under POST /self/approveUser
above.
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/blockUser
Block the logged-in User from the platform.
Users can be blocked from your platform either manually by an admin user in the Back Office application or automatically by calling this function.
This automated 'block user' feature is typically implemented during your user onboarding process. For instance, if you require users to pass an accreditation or eligibility test, and the logged-in User fails the test, then they can be blocked from the platform by calling this function.
As well as calling this function, you should log out the User to ensure that they cannot go back and adjust their responses knowing that they have been blocked.
If you call this function without any parameters then the User will be blocked without any expiration date. Once blocked without an expiration date, Users will not be able to log in until they have been unblocked manually by an Admin User in the Back Office application.
You may also provide parameters: user_message
, description
and expiration_date
to block a User until a certain date in the future. User the format: YYYY-MM-DD to specify a date on which the User will be able to log in again.
The user_message
attribute is used to show a custom message to the User if they try to log in whilst they are blocked, for instance: "We have been unable to verify your KYC/AML details. Please contact the admin team for more information."
Use description
to record an internal log of the reason for which the User was blocked. For instance, you may have your own list of KYC exceptions and definitions that fit your business and compliance requirements, such as "101 - User was under 18 years of age". This log will be recorded against the User in the Back Office admin application.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
user_message | Body | String | A custom message to be shown to the User if they try to log in whilst being blocked. This message is provided by the Exception that is raised when a blocked User tries to log in or call any API function |
|
description | Body | String | A code or designation to describe the reason for blocking this User |
|
expiration_date | Body | Date YYYY-MM-DD | The date on which the User's access to the platform should be automatically reinstated |
{ "user_message" : "We have been unable to verify your KYC/AML details. Please contact the admin team for more information.", "description" : "101 - User was under 18 years of age", "expiration_date" : "2017-01-01" }
{ "outcome": "success", "data": { "user_access_denied_log_id": "A Unique Identifier for the audit record showing that the User has been blocked" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/organizations
A list of the logged-in User's Organizations. This could be used to show for which Organization(s) the User works or for which Organization(s) the User has created Offerings.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Organizations requested", "count": "The total number of Organizations available", "list": [ { "additional_type": "An additional type or category for the Organization", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "alternate_name": "An alternate name for the Organization", "approved_at": "Date on which the Organization was marked as Approved", "brief_desc": "A brief description of the Organization", "canceled_at": "Date on which the Organization was marked as Canceled", "company_number": "The company registration number for the Organization", "contact_point": "A Unique Identifier for the User who represents the Organization's contact point", "created_at": "Date on which the Organization was created", "credit_score": "The Organization's current credit score", "custom": { "The name of the custom field": "The value of the custom field" }, "detail_desc": "A long-form, detailed description of the Organization", "display_name": "The display name of the Organization", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "facebook": "The Organization's Facebook account page", "founding_date": "Date on which the Organization was founded", "founding_location": "Location at which the Organization was founded", "fundamerica_entity_id": "Unique identifier for the Fund America entity that represents this Organization", "gcen_client_id": "Unique identifier for the GCEN client that represents this Organization", "id": "A Unique Identifier for the Organization", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "legal_name": "Full legal name of the Organization", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Canceled", "linkedin": "The Organization's LinkedIn account page", "location": "The Organization's location", "logo": "The Organization's logo image", "mangopay_card_id": "The Organization’s Mangopay-registered payment card identifier", "mangopay_user_id": "The Organization’s Mangopay account identifier when used to represent a Legal User", "mangopay_wallet_id": "The Organization's Mangopay wallet identifier", "members": [ { "user_id": "A Unique Identifier for the User", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "user_full_name": "The `full_name` of the User", "contact_point": "The `contact_point` of the Organization" } ], "org_email": "An email address for the Organization", "reyker_isin": "The Organization's ISIN code", "sector": "The Organization's industry or sector", "submitted_at": "Date on which the Organization was marked as Submitted", "tax_id": "The Tax / Fiscal ID of the Organization", "telephone": "A phone number for the Organization", "twitter": "The Organization's Twitter account page", "updated_at": "Date on which the Organization was last updated", "user_name": "The `full_name` of the User who created this Organization", "user_id": "A Unique Identifier for the User who created this Organization", "visibility": "0 = Open, 1 = Hidden, 2 = Anonymous", "website": "A URL of a reference webpage that represents the Organization", "youtube": "The Organization's YouTube account page" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/offerings
Retrieve all the logged-in User's own Offerings.
In secondary market implementations, this function can be used to show all Offerings that an investor has listed on the secondary market, since the User will be the author
of each secondary Offering on the market even if the User is not part of the Offering's Organization.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/investments
Retrieve a list of the User's Investments.
This function retrieves all investments of any life_cycle_stage
made by the logged-in User.
Implement this function to populate a User's investment portfolio or current holdings page.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Investments requested", "count": "The total number of Investments available", "list": [ { "capital_outstanding": "The current capital outstanding for this Investment. This is calculated as the sum of all payout_amount values of all Payouts for this Investment, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.", "created_at": "Date on which the Investment was created", "currency": "The Investment's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "divested_amount": "The amount from this Investment that has been divested by the User through secondary market trades", "divested_shares": "The number of shares that have been divested from this original Investment. This figure is calculated based on the amount of Settled Investments that have been made by other Users for Secondary Market Offerings created by the User who made this original Investment.", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "fundamerica_investment_id": "Fund America's unique identifier for the Investment", "funding_goal": "The funding goal for the Offering for which the User made this Investment", "id": "A Unique Identifier for the Investment", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_outstanding": "The amount of interest outstanding for this Investment as calculated using a Net Annualized Return formula", "interest_rate": "The interest rate offered by the User for the Offering", "investment_amount": "The investment amount submitted by the User for the Offering", "is_loanbook": "Flag to show whether the Investment is into a Loanbook rather than an Offering", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Settled", "number_of_shares": "The number of shares requested for this Investment", "offering_id": "A Unique identifier for the Offering for which the User made this Investment", "org_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "org_name": "The `display_name` of the Organization that owns this Investment's Offering", "raised_percent": "The amount that this Investment's Offering has raised as a percentage of its funding_goal.", "repayments_remaining": "The remaining number of Payouts for this Investment that are not yet paid", "settled_at": "Date on which the Investment was marked as Settled", "term": "The term offered by the User for the Offering", "updated_at": "Date on which the Investment was last updated", "user_email": "The email of the User who made this Investment", "user_id": "A Unique Identifier for the User who made this Investment", "user_name": "The `full_name` of the User who made this Investment", "visibility": "The Investment's visibility. 0 = Open, 1 = Hidden, 2 = Anonymous" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/payouts
Retrieve a list of the User's Payouts.
A Payout is an expected or scheduled payment. It can be used to track loan repayment schedules or dividend payment schedules.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Payouts requested", "count": "The total number of Payouts available", "list": [ { "additional_type": "An additional type or category for the Payout" "charge_offs": "The amount of charge-offs associated with this Payout", "created_at": "Date on which this Payout was created", "currency": "The Payout's currency code", "custom": { "The name of the custom field": "The value of the custom field" }, "due_date": "The date on which a Transaction is due for this Payout", "id": "Unique Identifier for the Payout", "investment_id": "Unique Identifier for this Payout's Investment", "late_fee": "The amount of late fees associated with this Payout", "minimum_payment": "The minimum amount required to settle this Payout", "net_annualized_return": "The Net Annualized Return for this Payout", "net_recoveries": "The amount of net recoveries associated with this Payout", "offering_name": "The name of the Offering with which this Payout is associated", "paid_at": "Date on which this Payout was paid", "payout_amount": "The amount expected for this Payout's Transaction", "payout_type": "The type of Payout: 0 = Dividend; 1 = Loan Repayment; 2 = Capital Gain", "service_charge": "The amount of service charge associated with this Payout", "transactions_paid": "The number of Transactions that have been paid for this Payout", "updated_at": "Date on which this Payout was last updated", "user_id": "Unique identifier for the User who owns this Payout", "user_name": "Name of the User who owns this Payout" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/wallets
Retrieve a list of the User's internal Wallets. This list does not include wallets provided by third-party payments services.
In order to see a list of User internal Wallets in the Back Office application, this feature must be enabled by your Crowd Valley support contact.
Internal Wallets can be used to represent real cash, in platforms that use 'front-end' implementations of a payment gateway such as SagePay or Stripe. In this case, you would implement an e-commerce style payments process on your front-end and then when the payments service returns successfully you can update the User's Wallet's balance by creating a Transaction for the Wallet.
Internal Wallets can also be used to record taxes or fees payable, if they should be handled separately from the main investment process. In some jurisdictions, taxes are withheld by the platform operators and therefore it can be useful to keep an audit record of each line item that incurs a future tax repayment.
Alternatively, internal Wallets can be used to keep track of 'credits' or 'bonuses', which may then be used in some way on your platform.
By default, a User does not have any internal Wallets. In order to see an internal Wallet when implementing this function, you should first implement POST self/wallets
in order to create an internal Wallet.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Wallets requested", "count": "The total number of Wallets available", "list": [ { "balance": "The total Wallet balance", "committed_balance": "The amount that has been committed to pending Transactions from this Wallet", "currency": "The Wallet's currency code", "free_balance": "The amount that has not been committed to pending Transactions from this Wallet", "id": "A Unique Identifier for the Wallet", "user_id": "A Unique Identifier for the User who owns this Wallet", "user_name": "The `full_name` of the Wallet's owner" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/capitalizations
Retrieve a list of the User's Capitalizations.
If a User owns a Capitalization then this indicates a record of a shareholding or loan part held by the User in an Organization.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Capitalizations requested", "count": "The total number of Capitalizations available", "list": [ { "author_id": "The `id` of the User who created this Capitalization", "author_name": "The `full_name` of the User who created this Capitalization", "capitalization_type": "The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt", "created_at": "Date on which this Capitalization was created", "id": "Unique identifier for this Capitalization", "life_cycle_stage": "The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed", "number_of_shares": "The number of shares held by the User", "number_of_shares_at_acquisition": "The number of shares owned by this User when the Capitalization was first acquired", "organization_id": "The Organization in which the User owns this Capitalization", "owner_id": "The `id` of the User who currently owns this Capitalization", "owner_name": "The `full_name` of the User who currently owns this Capitalization", "price_per_share": "The current price per share of this Capitalization", "price_per_share_at_acquisition": "The price per share when the Capitalization was first acquired", "updated_at": "Date on which the Capitalization was last updated" "valuation_gain": "The difference in value of this Capitalization compared to its value at acquisition" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/wallets
Create a new internal Wallet for the logged-in User.
If you are using internal Wallets on your platform, you should implement this function at some point before the User is able to add funds to it. Typically POST self/wallets
is called
By default, a User does not have any internal Wallets. In order to see an internal Wallet when implementing this function, you should first implement POST self/wallets
in order to create an internal Wallet.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
currency | Body | Currency | The currency of this wallet |
{ "currency" : "USD" }
{ "outcome": "success", "data": { "wallet_id": "A Unique Identifier for the Wallet" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/wallets/{wallet_id}
Retrieve a User's internal Wallet.
Users can have any number of internal Wallets so if you have a platform where Users hold several different Wallets you can specify a wallet_id
to return the information for a particular Wallet.
To get a list of all of the logged-in User's internal Wallets, implement GET self/wallets
.
{ "outcome": "success", "data": { "wallet": { "balance": "The total Wallet balance", "committed_balance": "The amount that has been committed to pending Transactions from this Wallet", "currency": "The Wallet's currency code", "free_balance": "The amount that has not been committed to pending Transactions from this Wallet", "id": "A Unique Identifier for the Wallet", "user_id": "A Unique Identifier for the User who owns this Wallet", "user_name": "The `full_name` of the Wallet's owner" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/documents
Retrieve a list of all the Documents that have been attached to the User's account.
Documents can be attached to Users, Organizations, Offerings or Investments. If a Document is attached to an Investment and the Investment was created by the logged-in User then it will not appear in this list. Documents returned by implementing GET self/documents
are only those that were created by calling POST self/documents
.
If you are implementing a User Profile or Account page that should show all Documents relating to the logged-in User then you should first call GET self/documents
to get the User's 'User Documents' and then call GET /investments/{investment_id}/documents
for each Investment from the list returned by GET self/investments
.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Documents requested", "count": "The total number of Documents available", "list": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" }, ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/documents
Add a Document to the User's account.
This is typically implemented to allow a User to upload a KYC Document such as a Utility Bill that may constitute part of your user onboarding process.
Documents added by using POST self/documents
are considered to be attached to the User specifically as a User, rather than documents such as Loan Agreements or Share Certificates that can be added to the User's account by attaching it to a particular Investment made by the User, by implementing POST investments/{investment_id}/documents
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
file_name | Body | String | The Document's file name |
|
url | Body | String | The Document's full URL |
|
file_type | Body | String | The Document's mime-type |
|
file_alias | Body | String | The publicly visible alias of the Document |
|
file_description | Body | String | The publicly visible description of the Document |
|
group_id | Body | Integer | Unique identifier for the Document Group of this Document |
|
source_type | Body | Boolean (1 or 0) | 0 = Crowd Valley CDN, 1 = External CDN |
|
tag | Body | String | A tag for the Document |
{ "file_name": "utility_bill.jpg", "url": "https://yourcdn.yourstoragefacility.com/utility_bill.jpg", "file_alias": "Utility Bill", "file_description": "Utility Bill from Jan 1st to March 31st", "file_type": "image/jpg", "tag": "KYC" }
{ "outcome": "success", "data": { "document_id": "Unique Identifier for the Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/invitations
Retrieve a list of Invitations made by the logged-in User.
Invitations allow Users to invite their external contacts to join the platform.
{ "outcome": "success", "data": { "count": "The total number of Invitations available", "list": [ { "author_id": "Unique Identifier for the User who sent this Invitation", "created_at": "Date on which the Invitation was created", "email": "The recipient's email address", "expires_at": "Date on which the Invitation expires", "id": "Unique Identifier for the Invitation" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/invitations
Create a new Invitation to an external contact from the logged-in User.
Invitations allow Users to invite their external contacts to join the platform.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
Body | String | The recipient's email |
||
given_name | Body | String | The recipient's given name |
|
family_name | Body | String | The recipient's family name |
|
organization_name | Body | String | The recipient's organization |
{ "email" : "john.doe@test.com", "given_name" : "John", "family_name" : "Doe", "organization_name" : "JD, Inc" }
{ "outcome": "success", "data": { "invitation_id": "Unique Identifier for the Invitation" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/invitations/{invitation_id}
Retrieve information about a given Invitation made by the logged-in User.
Invitations allow Users to invite their external contacts to join the platform.
{ "outcome": "success", "data": { "invitation": { "author_id": "Unique Identifier for the User who sent this Invitation", "created_at": "Date on which the Invitation was created", "email": "The recipient's email address", "expires_at": "Date on which the Invitation expires", "id": "Unique Identifier for the Invitation" } }, "status": 200 }
DELETE https://api.sandbox.crowdvalley.com/v1/{network}/self
Delete a User's account.
This blocks the User and, if enabled, sends a notification to the Admin User team to inform them that the logged-in User wishes to delete their account from the platform.
No User data are physically deleted from the platform in order to ensure that a full audit trail of the User's activity history remains available, including records of their previous Offerings or Investments.
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/applications
Create a new Application for the logged-in User.
Applications can be used as preliminary or draft versions of other objects such as Organizations, Offerings or Investments.
Applications are typically used in auction-based processes where the Application can represent a preliminary 'ask' or 'bid'. Such Applications can then be matched using your own proprietary algorithms and then converted to full Offerings and Investments in order to complete the investment process.
Applications are designed to be a generic object that does not have any required fields except life_cycle_stage
. If your processes involve promoting an Application to another object, such as an Offering or an Investment, then use the Application object's fields that are also associated to that object such as investment_amount
(Investment) or funding_goal
(Offering).
Otherwise, it is also a typical use case to implement a process with Applications that only use the custom
attribute, for instance, when using Applications to represent an application to raise capital on a private placement platform.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
life_cycle_stage | Body | Integer | 0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Canceled |
|
additional_type | Body | String | An additional type or category for the Application |
|
code | Body | String | A code that you can use to define a type of application |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom Application fields |
|
description | Body | String | A description for the Application |
|
funding_goal | Body | Decimal | The funding_goal of this Application. Use this attribute when an Application will be promoted to an Offering |
|
interest_rate | Body | Decimal | The interest_rate of this Application. Use this attribute when an Application will be promoted to an Investment |
|
investment_amount | Body | Decimal | The investment_amount of this Application. Use this attribute when an Application will be promoted to an Investment |
|
number_of_shares | Body | Integer | The number_of_shares of this Application. Use this attribute when an Application will be promoted to an Investment or an Offering |
|
offering | Body | Integer | The ID of the offering of this Application. Use this attribute when an Application will be promoted to an Investment |
|
organization | Body | Integer | The ID of the organization of this Application. Use this attribute when an Application will be promoted to an Offering |
|
price_per_share | Body | Decimal | The price_per_share of this Application. Use this attribute when an Application will be promoted to an Offering or an Investment |
|
term | Body | Integer | The term of this Application. Use this attribute when an Application will be promoted to an Offering or an Investment |
{ "life_cycle_stage" : "0", "investment_amount" : "10000" }
{ "outcome": "success", "data": { "application_id": "A Unique Identifier for the Application" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/users
Registers a new User.
Implement this as the first step of your registration process. The required parameters for this function are email
, password
, and url
. All other editable attributes of a User can also be provided as optional parameters, for instance, given_name
or family_name
.
If your registration process has several steps then you can ask new Users for their email and password and then update their User record by implementing PATCH /self
at a later point.
The email
and password
parameters should be provided by the User. The url
parameter is used to generate the verification email that is sent to Users automatically by the Back Office application when the User is successfully created.
Specify a url
as a page on your front-end that implements the POST /public/verifyEmail
method using the parameters user_id
and secret
that are generated for the new User by implementing POST /users
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
Body | String | The new User's email address |
||
password | Body | String | The new User's password |
|
url | Body | String | The full URL of a page on your front-end site to which the User will be sent by clicking the activation link in an email sent by the Crowd Valley back-end |
|
additional_type | Body | String | An additional type or category for the User. Use this to define categories or groups of Users |
|
address | Body | { 'id' : Integer, 'building' : String, 'street_address' : String, 'city' : String, 'address_locality' : String, 'region' : String, 'postal_code' : String, 'country' : ISO_3166-1 alpha2 Country Code } | The User's address. All fields within the Address are optional. To update an existing address, include the |
|
affiliate_code | Body | String | A code that can be given out by the User to track that User's affiliate activity |
|
bank_accounts | Body | { 'id' : Integer, 'bank_account_number' : String, 'bank_address' : Address, 'bank_country' : String, 'bank_currency' : String, 'region' : ISO 4217 Currency Code, 'bank_name' : String, 'bank_routing_number' : String, 'bank_swift_code' : String } | The User's Bank Account. All fields within the Bank Account are optional. To update an existing Bank Account, include the |
|
biography | Body | String | The User's biography |
|
birth_date | Body | ISO 8601 Date | The User's date of birth |
|
birth_place | Body | String | The User's place of birth |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom User fields. Use an existing custom attribute name to replace the existing value. Use a new custom attribute name to add a new custom field |
|
driving_license_number | Body | String | The User's full driving license number |
|
external_reference_id | Body | String | External reference identifier |
|
family_name | Body | String | Family name |
|
gender | Body | String ('M' or 'F') | The gender of the User |
|
given_name | Body | String | The User's given name |
|
honorific_prefix | Body | String | An honorific prefix preceding the User's name |
|
honorific_suffix | Body | String | An honorific suffix following the User's name |
|
image | Body | Integer | The |
|
is_vip | Body | Boolean (1 or 0) | Flag to show whether the User has been given 'VIP' status |
|
job_title | Body | String | The job title of the User |
|
location | Body | String | The User's location |
|
nationality | Body | ISO 3166-1 alpha-2 Country Code | The User's nationality |
|
passport_country | Body | ISO 3166-1 alpha-2 Country Code | The country that issued the User's passport |
|
passport_expiry | Body | 'MMYY' Date | The expiry date of the User's passport in 'MMYY' format |
|
passport_number | Body | String | The User's full passport number |
|
phone_1 | Body | String | The User's primary phone number |
|
phone_2 | Body | String | The User's secondary phone number |
|
sector | Body | String | The User's industry or sector |
|
tagline | Body | String | A short tagline to summarise the User |
|
tax_id | Body | String | The Tax / Fiscal ID of the User, e.g. the TIN in the US or the CIF/NIF in Spain |
|
timezone | Body | String | The User's timezone |
|
visibility | Body | Integer | 0 = Open, 1 = Hidden, 2 = Anonymous |
|
web_site | Body | String | The URL of a reference website that is linked to the User |
{ "email" : "newuser@test.com", "password" : "Password123!", "url" : "https://www.yoursite.com/verify-email" }
{ "outcome": "success", "data": { "user_id": "A Unique Identifier for the User" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/users
Retrieves a list of Users in your network.
Implement this function to populate a public listing page of your visible Users. Users are returned in this list if they have their visibility
attribute set to Open.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Users requested", "count": "The total number of Users available", "list": [ { "additional_type": "An additional type or category for the User", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" } "affiliate_code": "A code that can be given out by the User to track that User's affiliate activity", "biography": "The User's biography", "created_at": "Date on which the User joined your platform", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ], "email": "The User's registered email address", "external_reference_id": "External reference identifier", "family_name": "The User's family name", "full_name": "The User's full name", "gender": "The gender of the User ('M' or 'F')", "given_name": "The User's given name", "has_been_approved": "Flag to show whether the User has been marked as Approved on your platform", "has_been_blocked": "Flag to show whether the User has been blocked from your platform", "honorific_prefix": "An honorific prefix preceding the User's name such as Dr/Mrs/Mr", "honorific_suffix": "An honorific suffix preceding the User's name such as MD/PhD/MSCSW", "id": "A Unique Identifier for the User", "image": "The User's profile image", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "is_admin": "Flag to show whether the User has admin rights for your platform", "is_vip": "Flag to show whether the User has been given 'VIP' status", "job_title": "The job title of the User (for example, CEO)", "location": "The User's location", "organizations": [ { "organization_id": "Unique Identifier for the Organization", "organization_name": "Display name of the Organization", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "status": "Boolean flag to show whether the User’s membership of the Organization is active", "contact_point": "Unique Identifier for the User who is this Organization’s `contact_point`" } ], "phone_1": "The User's primary phone number", "phone_2": "The User's secondary phone number", "referral_code": "The code that was entered by the User to connect them to another User acting as an affiliate", "registration_complete": "Flag to show whether the User has completed their registration requirements", "sector": "The User's industry or sector", "tagline": "A short tagline to summarise the User", "time_zone": "The User's timezone", "visibility": "The User's visibility (0 = Open, 1 = Hidden, 2 = Anonymous)", "web_site": "The User's website" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/users/{user_id}
Retrieve information about a given User.
Implement this function to populate another User's public profile page. This is the equivalent for viewing another User's profile of calling GET /self
for the logged-in User.
This allows the logged-in User to see information about other Users on your platform. It does not return as much information about other Users as you would see about yourself: it will only show public profile information such as given_name
and family_name
. It will not show private account information such as birth_date
or passport_number
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
user_id | Path | Integer | The |
{ "outcome": "success", "data": { "user": { "additional_type": "An additional type or category for the User", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" } "affiliate_code": "A code that can be given out by the User to track that User's affiliate activity", "biography": "The User's biography", "created_at": "Date on which the User joined your platform", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ], "email": "The User's registered email address", "external_reference_id": "External reference identifier", "family_name": "The User's family name", "full_name": "The User's full name", "gender": "The gender of the User ('M' or 'F')", "given_name": "The User's given name", "has_been_approved": "Flag to show whether the User has been marked as Approved on your platform", "has_been_blocked": "Flag to show whether the User has been blocked from your platform", "honorific_prefix": "An honorific prefix preceding the User's name such as Dr/Mrs/Mr", "honorific_suffix": "An honorific suffix preceding the User's name such as MD/PhD/MSCSW", "id": "A Unique Identifier for the User", "image": "The User's profile image", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "is_admin": "Flag to show whether the User has admin rights for your platform", "is_vip": "Flag to show whether the User has been given 'VIP' status", "job_title": "The job title of the User (for example, CEO)", "location": "The User's location", "organizations": [ { "organization_id": "Unique Identifier for the Organization", "organization_name": "Display name of the Organization", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "status": "Boolean flag to show whether the User’s membership of the Organization is active", "contact_point": "Unique Identifier for the User who is this Organization’s `contact_point`" } ], "phone_1": "The User's primary phone number", "phone_2": "The User's secondary phone number", "referral_code": "The code that was entered by the User to connect them to another User acting as an affiliate", "registration_complete": "Flag to show whether the User has completed their registration requirements", "sector": "The User's industry or sector", "tagline": "A short tagline to summarise the User", "time_zone": "The User's timezone", "visibility": "The User's visibility (0 = Open, 1 = Hidden, 2 = Anonymous)", "web_site": "The User's website" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/users/{user_id}/offerings
View a given User's public Offerings.
Implement this function to see another User's Offerings. This is the equivalent for viewing another User's profile of calling GET /self/offerings
for the logged-in User.
This allows the logged-in User to see information about other Users on your platform. It does not return as much information about other Users as you would see about yourself: it will only show Offerings whose life_cycle_stage
is Published, Closing or Settled. The equivalent function for the logged-in User returns all Offerings.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
user_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/users/{user_id}/investments
View a given User's public Investments.
Implement this function to see another User's history of Investments. This is the equivalent for viewing another User's profile of calling GET /self/investments
for the logged-in User.
This allows the logged-in User to see information about other Users on your platform. It does not return as much information about other Users as you would see about yourself: it will only show Investments whose life_cycle_stage
is Settled. The equivalent function for the logged-in User returns all Investments.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
user_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Investments requested", "count": "The total number of Investments available", "list": [ { "capital_outstanding": "The current capital outstanding for this Investment. This is calculated as the sum of all payout_amount values of all Payouts for this Investment, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.", "created_at": "Date on which the Investment was created", "currency": "The Investment's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "divested_amount": "The amount from this Investment that has been divested by the User through secondary market trades", "divested_shares": "The number of shares that have been divested from this original Investment. This figure is calculated based on the amount of Settled Investments that have been made by other Users for Secondary Market Offerings created by the User who made this original Investment.", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "fundamerica_investment_id": "Fund America's unique identifier for the Investment", "funding_goal": "The funding goal for the Offering for which the User made this Investment", "id": "A Unique Identifier for the Investment", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_outstanding": "The amount of interest outstanding for this Investment as calculated using a Net Annualized Return formula", "interest_rate": "The interest rate offered by the User for the Offering", "investment_amount": "The investment amount submitted by the User for the Offering", "is_loanbook": "Flag to show whether the Investment is into a Loanbook rather than an Offering", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Settled", "number_of_shares": "The number of shares requested for this Investment", "offering_id": "A Unique identifier for the Offering for which the User made this Investment", "org_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "org_name": "The `display_name` of the Organization that owns this Investment's Offering", "raised_percent": "The amount that this Investment's Offering has raised as a percentage of its funding_goal.", "repayments_remaining": "The remaining number of Payouts for this Investment that are not yet paid", "settled_at": "Date on which the Investment was marked as Settled", "term": "The term offered by the User for the Offering", "updated_at": "Date on which the Investment was last updated", "user_email": "The email of the User who made this Investment", "user_id": "A Unique Identifier for the User who made this Investment", "user_name": "The `full_name` of the User who made this Investment", "visibility": "The Investment's visibility. 0 = Open, 1 = Hidden, 2 = Anonymous" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations
Create a new Organization. This can be done through the Back Office application or directly through the API from your front-end platform.
Every Organization requires a User to be its contact_point
and by default the User who is logged in when calling POST /organizations
is set as the new Organization's contact_point
.
The contact_point
can then be adjusted by adding or removing other Users using the /organizations/{organizationID}/members/{userID}
endpoint.
There is one required parameter for this function - the Organization's display_name
. You may optionally provide any other editable Organization field as a parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
display_name | Body | String | The display name of the Organization |
|
additional_type | Body | String | An additional type or category for the Organization |
|
alternate_name | Body | String | An alternate name for the Organization |
|
brief_desc | Body | String | A brief description of the Organization |
|
credit_score | Body | String | The Organization's current credit score |
|
company_number | Body | String | The company registration number for the Organization |
|
detail_desc | Body | String | A long-form, detailed description of the Organization |
|
Body | String | The Organization's Facebook account page |
||
founding_date | Body | ISO-8601 Date | Date on which the Organization was founded |
|
founding_location | Body | String | Location at which the Organization was founded |
|
legal_name | Body | String | Full legal name of the Organization |
|
Body | String | The Organization's LinkedIn account page |
||
location | Body | String | The Organization's location |
|
logo | Body | Integer | The |
|
org_email | Body | String | An email address for the Organization |
|
sector | Body | String | The Organization's industry or sector |
|
tax_id | Body | String | The Tax / Fiscal ID of the Organization |
|
telephone | Body | String | A phone number for the Organization |
|
Body | String | The Organization's Twitter account page |
||
visibility | Body | Integer | 0 = Open, 1 = Hidden, 2 = Anonymous |
|
website | Body | String | A URL of a reference webpage that represents the Organization |
|
youtube | Body | String | The Organization's YouTube account page |
{ "display_name": "My Organization", "address" : { "building" : "One Market Plaza", "street_address" : "Spear Tower", "city" : "San Francisco" }, "visibility" : "1" }
{ "outcome": "success", "data": { "organization_id": "A Unique Identifier for the new Organization" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations
Retrieve a list of all Organizations in the network.
Implement this to show a list of Organizations that are supporting various deals, or that are umbrella entities for various Users. This will only show Organizations that have visibility
set to the default value of Open and life_cycle_stage
as Approved or Published.
Since Organizations can represent investors/lenders or fundraisers/borrowers or simply groups of Users, this function can be implemented on many different types of pages.
In some platforms, an Organization represents the entity that is raising capital on your platform, and so the list of all Organizations will show all such entities (which may be companies, properties, funds, projects, etc.) whether they are currently raising capital (i.e., they have a live Offering), they are not yet raising capital (i.e., they do not have an Offering), or they have completed the capital raising process (i.e., they have an Offering that is Settled).
In others, an Organization may also represent an Institutional Investor, which may have several individual Users as its representatives. In this case, the GET /organizations
function will show a list of all Institutions that are approved to invest on your platform.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Organizations requested", "count": "The total number of Organizations available", "list": [ { "additional_type": "An additional type or category for the Organization", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "alternate_name": "An alternate name for the Organization", "approved_at": "Date on which the Organization was marked as Approved", "brief_desc": "A brief description of the Organization", "canceled_at": "Date on which the Organization was marked as Canceled", "company_number": "The company registration number for the Organization", "contact_point": "A Unique Identifier for the User who represents the Organization's contact point", "created_at": "Date on which the Organization was created", "credit_score": "The Organization's current credit score", "custom": { "The name of the custom field": "The value of the custom field" }, "detail_desc": "A long-form, detailed description of the Organization", "display_name": "The display name of the Organization", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "facebook": "The Organization's Facebook account page", "founding_date": "Date on which the Organization was founded", "founding_location": "Location at which the Organization was founded", "fundamerica_entity_id": "Unique identifier for the Fund America entity that represents this Organization", "gcen_client_id": "Unique identifier for the GCEN client that represents this Organization", "id": "A Unique Identifier for the Organization", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "legal_name": "Full legal name of the Organization", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Canceled", "linkedin": "The Organization's LinkedIn account page", "location": "The Organization's location", "logo": "The Organization's logo image", "mangopay_card_id": "The Organization’s Mangopay-registered payment card identifier", "mangopay_user_id": "The Organization’s Mangopay account identifier when used to represent a Legal User", "mangopay_wallet_id": "The Organization's Mangopay wallet identifier", "members": [ { "user_id": "A Unique Identifier for the User", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "user_full_name": "The `full_name` of the User", "contact_point": "The `contact_point` of the Organization" } ], "org_email": "An email address for the Organization", "reyker_isin": "The Organization's ISIN code", "sector": "The Organization's industry or sector", "submitted_at": "Date on which the Organization was marked as Submitted", "tax_id": "The Tax / Fiscal ID of the Organization", "telephone": "A phone number for the Organization", "twitter": "The Organization's Twitter account page", "updated_at": "Date on which the Organization was last updated", "user_name": "The `full_name` of the User who created this Organization", "user_id": "A Unique Identifier for the User who created this Organization", "visibility": "0 = Open, 1 = Hidden, 2 = Anonymous", "website": "A URL of a reference webpage that represents the Organization", "youtube": "The Organization's YouTube account page" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}
Retrieve information about an Organization.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "organization": { "additional_type": "An additional type or category for the Organization", "address": { "building": "The building name or number (Address Line 1)", "street_address" : "The street address (Address Line 2)", "city": "The city or town", "address_locality" : "The locality", "region" : "The region, county or state", "postal_code" : "The postal or ZIP code", "country": "The country in ISO 3166-1 Alpha 2 format" }, "alternate_name": "An alternate name for the Organization", "approved_at": "Date on which the Organization was marked as Approved", "brief_desc": "A brief description of the Organization", "canceled_at": "Date on which the Organization was marked as Canceled", "company_number": "The company registration number for the Organization", "contact_point": "A Unique Identifier for the User who represents the Organization's contact point", "created_at": "Date on which the Organization was created", "credit_score": "The Organization's current credit score", "custom": { "The name of the custom field": "The value of the custom field" }, "detail_desc": "A long-form, detailed description of the Organization", "display_name": "The display name of the Organization", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "facebook": "The Organization's Facebook account page", "founding_date": "Date on which the Organization was founded", "founding_location": "Location at which the Organization was founded", "fundamerica_entity_id": "Unique identifier for the Fund America entity that represents this Organization", "gcen_client_id": "Unique identifier for the GCEN client that represents this Organization", "id": "A Unique Identifier for the Organization", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "legal_name": "Full legal name of the Organization", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Canceled", "linkedin": "The Organization's LinkedIn account page", "location": "The Organization's location", "logo": "The Organization's logo image", "mangopay_card_id": "The Organization’s Mangopay-registered payment card identifier", "mangopay_user_id": "The Organization’s Mangopay account identifier when used to represent a Legal User", "mangopay_wallet_id": "The Organization's Mangopay wallet identifier", "members": [ { "user_id": "A Unique Identifier for the User", "member_type": "The User’s relationship to the Organization (‘author’ or ‘member’)", "user_full_name": "The `full_name` of the User", "contact_point": "The `contact_point` of the Organization" } ], "org_email": "An email address for the Organization", "reyker_isin": "The Organization's ISIN code", "sector": "The Organization's industry or sector", "submitted_at": "Date on which the Organization was marked as Submitted", "tax_id": "The Tax / Fiscal ID of the Organization", "telephone": "A phone number for the Organization", "twitter": "The Organization's Twitter account page", "updated_at": "Date on which the Organization was last updated", "user_name": "The `full_name` of the User who created this Organization", "user_id": "A Unique Identifier for the User who created this Organization", "visibility": "0 = Open, 1 = Hidden, 2 = Anonymous", "website": "A URL of a reference webpage that represents the Organization", "youtube": "The Organization's YouTube account page" } }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}
Update an Organization.
Any parameter that is "Editable" in the Organization data model can be updated by implementing this method.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
additional_type | Body | String | An additional type or category for the Organization |
|
address | Body | { 'id' : Integer, 'building' : String, 'street_address' : String, 'city' : String, 'address_locality' : String, 'region' : String, 'postal_code' : String, 'country' : ISO_3166-1 alpha2 Country Code } | The Organization's address. All fields within the Address are optional |
|
alternate_name | Body | String | An alternate name for the Organization |
|
brief_desc | Body | String | A brief description of the Organization |
|
credit_score | Body | String | The Organization's current credit score |
|
company_number | Body | String | The company registration number for the Organization |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom Organization fields. Use an existing custom attribute name to replace the existing value. Use a new custom attribute name to add a new custom field |
|
detail_desc | Body | String | A long-form, detailed description of the Organization |
|
display_name | Body | String | The display name of the Organization |
|
Body | String | The Organization's Facebook account page |
||
founding_date | Body | ISO-8601 Date | Date on which the Organization was founded |
|
founding_location | Body | String | Location at which the Organization was founded |
|
legal_name | Body | String | Full legal name of the Organization |
|
Body | String | The Organization's LinkedIn account page |
||
life_cycle_stage | Body | Integer | The Organization's Lifecycle Stage |
|
location | Body | String | The Organization's location |
|
logo | Body | Integer | The |
|
org_email | Body | String | An email address for the Organization |
|
sector | Body | String | The Organization's industry or sector |
|
tax_id | Body | String | The Tax / Fiscal ID of the Organization |
|
telephone | Body | String | A phone number for the Organization |
|
Body | String | The Organization's Twitter account page |
||
visibility | Body | Integer | 0 = Open, 1 = Hidden, 2 = Anonymous |
|
website | Body | String | A URL of a reference webpage that represents the Organization |
|
youtube | Body | String | The Organization's YouTube account page |
{ "brief_desc" : "New Brief Description" }
{ "outcome": "success", "data": { "organization_id": "A Unique Identifier for the Organization" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/members/{user_id}
Add a User to the team of an Organization.
Implement this to add a given User, specified by the path parameter user_id
, to the team of the Organization with id
equal to the parameter organization_id
.
This function is typically used when setting up an Offering in advance of it going live on your platform. As part of the Offering's overview page, you may wish to show some information about the team behind the Organization that is raising capital through this Offering. This can be implemented by creating custom Organization or custom Offering fields in the case that the team members are not part of your platform. Otherwise you can associate any User with the Organization by calling POST organizations/{organization_id}/members/{user_id}
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
user_id | Path | Integer | The |
{ "outcome": "success", "data": [], "status": 200 }
DELETE https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/members/{user_id}
Remove a User from the team of an Organization.
Implement this to remove a given User, specified by the path parameter user_id
, from the team of the Organization with id
equal to the parameter organization_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
user_id | Path | Integer | The |
{ "outcome": "success", "data": { "org_member_id deleted": "A Unique Identifier for the User who has been removed from the Organization" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/capitalizations
Retrieve a list of Capitalizations for the given Organization, as specified by the path parameter organization_id
.
This function is typically implemented to show an Organization's cap table or shareholder registry.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Capitalizations requested", "count": "The total number of Capitalizations available", "list": [ { "author_id": "The `id` of the User who created this Capitalization", "author_name": "The `full_name` of the User who created this Capitalization", "capitalization_type": "The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt", "created_at": "Date on which this Capitalization was created", "id": "Unique identifier for this Capitalization", "life_cycle_stage": "The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed", "number_of_shares": "The number of shares held by the User", "number_of_shares_at_acquisition": "The number of shares owned by this User when the Capitalization was first acquired", "organization_id": "The Organization in which the User owns this Capitalization", "owner_id": "The `id` of the User who currently owns this Capitalization", "owner_name": "The `full_name` of the User who currently owns this Capitalization", "price_per_share": "The current price per share of this Capitalization", "price_per_share_at_acquisition": "The price per share when the Capitalization was first acquired", "updated_at": "Date on which the Capitalization was last updated" "valuation_gain": "The difference in value of this Capitalization compared to its value at acquisition" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/capitalizations
Create a new Capitalization for the Organization specified by the path parameter organization_id
. This can be done through the Back Office application or directly through the API from your front-end platform.
Create Capitalizations in order to use the share registry features in the Back Office, which allow you to transfer shares from the Organization or individual Users to the investors in an Offering.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
number_of_shares | Body | Integer | The number of shares held |
|
price_per_share | Body | Decimal | The current price per share of this Capitalization |
|
owner_id | Body | Integer | The |
|
life_cycle_stage | Body | Integer | The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed |
|
capitalization_type | Body | Integer | The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt |
{ "number_of_shares": "100", "price_per_share": "1", "owner_id" : "1098", "life_cycle_stage" : "1", "capitalization_type" : "0" }
{ "outcome": "success", "data": { "capitalization_id": "Unique identifier for this Capitalization" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/offerings
Retrieve a list of Offerings for the given Organization, as specified by the path parameter organization_id
.
When logged in as a normal end User, this function will only return Offerings whose life_cycle_stage
is Published, Live, Closing, or Settled.
If the logged-in User is a VIP User, i.e. the is_vip
attribute is set to true
, then calling this function will also return Offerings whose life_cycle_stage
is Restricted.
If the logged-in User is an Admin User, i.e. the is_admin
attribute is set to true
, then this function returns all Offerings of any life_cycle_stage
.
This function is typically implemented in secondary market features, which list secondary Offerings grouped by the original asset (Organization) that raised the capital, for example a fund or a property.
It may also be implemented on a page that shows an Organization's information, such as a borrower or equity fundraiser, to provide information about upcoming Offerings, currently live Offerings or historical Offerings.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/offerings
Create a new Offering for the Organization specified by the path parameter organization_id
. This can be done through the Back Office application or directly through the API from your front-end platform.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
funding_goal | Body | Decimal | The funding goal for this Offering |
|
additional_type | Body | String | An additional type or category for the Offering |
|
capitalization_id | Body | Integer | Unique identifier for the Capitalization that is being offered through this Offering |
|
close_date | Body | ISO-8601 Date | The closing date after which Investments are no longer allowed for this Offering |
|
credit_score | Body | String | The current credit score for this Offering |
|
currency | Body | Currency Code | The Offering's currency |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom Offering fields. Use an existing custom attribute name to replace the existing value. Use a new custom attribute name to add a new custom field |
|
equity_offered | Body | Decimal | The amount of equity offered as a percentage |
|
external_commitments | Body | Decimal | Funding received outside the platform that should be counted towards this Offering's total |
|
interest_rate | Body | Decimal | The interest rate offered |
|
is_featured | Body | Boolean (1 or 0) | Flag to show whether the Offering is featured |
|
is_secondary_offering | Body | Boolean (1 or 0) | Flag to show whether the Offering is a secondary market Offering |
|
max_commitment | Body | Decimal | The maximum total amount that a User can invest in this Offering |
|
max_overfunding_amount | Body | Decimal | The maximum amount raised by a Offering up to which Users can submit new Investments |
|
min_commitment | Body | Decimal | The minimum amount that a User can invest in this Offering |
|
name | Body | String | The name of the Offering |
|
num_of_shares | Body | Integer | The number of shares available in this Offering |
|
offering_description | Body | String | A long-form description of the Offering |
|
open_date | Body | ISO-8601 Date | The starting date after which new Investments are permitted for this Offering |
|
price_per_share | Body | Decimal | The price per share for this Offering |
|
primary_offering_id | Body | Integer | The |
|
term | Body | Integer | The loan term of the Offering |
|
valuation | Body | Decimal | The current valuation of the Offering |
{ "funding_goal" : "50000", "is_secondary_offering" : "1", "primary_offering_id" : "1000", "num_of_shares" : "50000", "price_per_share" : "1" }
{ "outcome": "success", "data": { "offering_id": "A Unique Identifier for the new Offering" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/documents
Retrieve a list of Documents for the given Organization, as specified by the path parameter organization_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Documents requested", "count": "The total number of Documents available", "list": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/documents
Add a Document to the given Organization, as specified by the path parameter organization_id
.
When displaying Documents on an Offering overview page, you may choose to attach the Document to the Offering itself or to the Offering's Organization.
Typically you would attach a Document to an Organization by calling this function if the Document applies equally to all of the Organization's Offerings. You might attach a Document to an Offering if it only applies to that particular Offering and not any others that may be created later, for instance, as part of a secondary market.
As an example, it makes sense to attach a Certificate of Incorporation document to the Organization because each Organization only has one such certificate and it is the same document no matter how many Offerings the Organization creates. Conversely, a Loan Agreement document might specify the terms and conditions for a particular loan, as represented by an Offering, and the terms will not necessarily be the same for the next Offering created for this Organization. In that case, it would make sense to attach the document to the Offering.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
file_name | Body | String | The Document's file name |
|
url | Body | String | The Document's full URL |
|
file_type | Body | String | The Document's mime-type |
|
file_alias | Body | String | The publicly visible alias of the Document |
|
file_description | Body | String | The publicly visible description of the Document |
|
group_id | Body | Integer | Unique identifier for the Document Group of this Document |
|
source_type | Body | Boolean (1 or 0) | 0 = Crowd Valley CDN, 1 = External CDN |
|
tag | Body | String | A tag for the Document |
{ "file_name": "floorplan.png", "url": "https://yourcdn.yourstoragefacility.com/floorplan.png", "file_alias": "Floor Plan", "file_description": "Floor Plan from architect's designs", "file_type": "image/png", "tag": "FLOOR_PLAN" }
{ "outcome": "success", "data": { "document_id": "A Unique Identifier for the new Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/capitalizations/{capitalization_id}
Retrieve information about a given Capitalization by specifying the Capitalization's id
in the capitalization_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
capitalization_id | Path | Integer | The |
{ "outcome": "success", "data": { "capitalization": { "author_id": "The `id` of the User who created this Capitalization", "author_name": "The `full_name` of the User who created this Capitalization", "capitalization_type": "The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt", "created_at": "Date on which this Capitalization was created", "id": "Unique identifier for this Capitalization", "life_cycle_stage": "The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed", "number_of_shares": "The number of shares held by the User", "number_of_shares_at_acquisition": "The number of shares owned by this User when the Capitalization was first acquired", "organization_id": "The Organization in which the User owns this Capitalization", "owner_id": "The `id` of the User who currently owns this Capitalization", "owner_name": "The `full_name` of the User who currently owns this Capitalization", "price_per_share": "The current price per share of this Capitalization", "price_per_share_at_acquisition": "The price per share when the Capitalization was first acquired", "updated_at": "Date on which the Capitalization was last updated" "valuation_gain": "The difference in value of this Capitalization compared to its value at acquisition" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/capitalizations/{capitalization_id}/changelog
Retrieve a full audit log of every change made to a given Capitalization by specifying the Capitalization's id
in the capitalization_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
capitalization_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Capitalization changes requested", "count": "The total number of Capitalization changes available", "list": [ { "author_id": "The `id` of the User who created this Capitalization", "author_name": "The `full_name` of the User who created this Capitalization", "capitalization_type": "The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt", "created_at": "Date on which this Capitalization was created", "id": "Unique identifier for this Capitalization", "life_cycle_stage": "The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed", "number_of_shares": "The number of shares held by the User", "number_of_shares_at_acquisition": "The number of shares held by the User at acquisition", "organization_id": "The Organization in which the User owns this Capitalization", "owner_id": "The `id` of the User who currently owns this Capitalization", "owner_name": "The `full_name` of the User who currently owns this Capitalization", "price_per_share": "The current price per share of this Capitalization", "price_per_share_at_acquisition": "The price per share of this Capitalization at acquisition", "updated_at": "Date on which the Capitalization was last updated" "valuation_gain": "The difference in value of this Capitalization compared to its value at acquisition" }, ] }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/capitalizations/{capitalization_id}
Update a Capitalization.
All changes to any Capitalization are logged and visible through the Back Office application.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
capitalization_id | Path | Integer | The |
|
number_of_shares | Body | Integer | The number of shares held |
|
price_per_share | Body | Decimal | The current price per share of this Capitalization |
|
owner_id | Body | Integer | The |
|
life_cycle_stage | Body | Integer | The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Distributed |
|
capitalization_type | Body | Integer | The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt |
{ "price_per_share": "1.10" }
{ "outcome": "success", "data": { "capitalization_id": "Unique identifier for this Capitalization" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/capitalizations/{capitalization_id}/split
Split a Capitalization.
This function divides a Capitalization into two or more 'child' Capitalizations. Implement this in seconary market applications to allow Capitalization owners (e.g. investors) to divide their share capital into several parts, one of which to offer on the secondary market and another to keep.
The parameters of the child Capitalizations are specified by an array of tuples each holding number_of_shares
and price_per_share
. The other attributes of the child Capitalizations are taken from the parent Capitalization.
The total number_of_shares
calculated by summing each number_of_shares
value in each child Capitalization must be equal to the parent Capitalization's number_of_shares
. In other words, this feature cannot be used to create new shares or to discard shares as part of the split.
The Capitalization must be Issued (i.e. have a life_cycle_stage
of 1) in order to be split into multiple parts.
All changes to any Capitalization are logged and visible through the Back Office application.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
capitalization_id | Path | Integer | The |
|
capitalizations | Body | Array | The parameters of the child Capitalizations |
[ { "number_of_shares": "40", "price_per_share" : "1.50" }, { "number_of_shares": "60", "price_per_share" : "2.50" } ]
{ "outcome": "success", "data": { "offset": 1, "limit": 1000, "count": 2, "list": [ { "author_id": 4815, "author_name": "Issuer User", "capitalization_type": 0, "created_at": "2017-01-18T14:53:20+0000", "id": 255, "life_cycle_stage": 1, "number_of_shares": "40", "organization_id": 2257, "owner_id": 4815, "owner_name": "Issuer User", "parent_id": 254, "price_per_share": "1.50", "updated_at": "2017-01-18T14:53:20+0000", "valuation_gain": 60 }, { "author_id": 4815, "author_name": "Issuer User", "capitalization_type": 0, "created_at": "2017-01-18T14:53:20+0000", "id": 256, "life_cycle_stage": 1, "number_of_shares": "60", "organization_id": 2257, "owner_id": 4815, "owner_name": "Issuer User", "parent_id": 254, "price_per_share": "2.50", "updated_at": "2017-01-18T14:53:20+0000", "valuation_gain": 150 } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/capitalizations/{capitalization_id}/merge
Merge two or more Capitalizations.
This function merges multiple Capitalization into a single 'child' Capitalization. Implement this in seconary market applications to allow Capitalization owners (e.g. investors) to merge multiple Capitalizations into a single part, for example to offer as a single Offering on the secondary market.
The child Capitalization will be generated with a number_of_shares
equal to the sum of its parents' number_of_shares
and with a price_per_share
equal to the average of its parents' price_per_share
weighted by their number_of_shares
.
For example, merging:
number_of_shares
= 100 and price_per_share
= 1.00number_of_shares
= 100 and price_per_share
= 2.00will generate:
number_of_shares
= 200 and price_per_share
= 1.50All changes to any Capitalization are logged and visible through the Back Office application.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
capitalization_id | Path | Integer | The |
|
capitalization_ids | Body | Array of Integers | The |
{ "capitalization_ids": "[100, 101]" }
{ "outcome": "success", "data": { "capitalization_id": "Unique identifier for the child Capitalization" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings
Retrieve a list of all Offerings.
Implement this function to populate a live Offerings page and/or a historical/closed deals page.
The number of Offerings that are returned by this function will depend on the type of User who is logged in.
Admin Users, i.e. Users with is_admin
set to true
, will see all Offerings including those that are not visible to your end users, because they are not yet Published.
Non-admin Users, i.e. all users created on your front-end by implementing POST /users
, will only see Offerings whose life_cycle_stage
is Published, Live, Closing or Settled.
VIP Users, i.e. Users who have is_vip
set to true
, will also see Offerings whose life_cycle_stage
is Restricted. So in total they will be able to see all Offerings whose life_cycle_stage
is Restricted, Published, Live, Closing or Settled.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Offerings requested", "count": "The total number of Offerings available", "list": [ { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}
Retrieve information about a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to retrieve data to be shown on an Offering's overview page. This is often one of the most important pages of a typical fintech application because it usually shows all the detail that an investor or lender would want to see before making a decision to invest.
Access to the data about this Offering follows the same rules as GET /offerings
:
id
and calling this function.life_cycle_stage
is Restricted, Published, Live, Closing or Settledlife_cycle_stage
is Published, Live, Closing or Settled but not Offerings that are RestrictedNote that the Offering's amount_raised
and raised_percent
calculations are based on Investments in the Offering with life_cycle_stage
of Approved or Settled. Investments with life_cycle_stage
of Open will not count towards the Offering's total until they are approved. Investments with life_cycle_stage
of Rejected or Withdrawn will never count towards the Offering's total amount_raised
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offering": { "additional_type": "An additional type or category for the Offering", "amount_raised": "The amount that the Offering has raised", "capital_outstanding": "The total amount of all repayments still to be repaid for all Investments in this Offering", "category": "A category for the Offering", "close_date": "The closing date after which Investments are no longer allowed for this Offering", "created_at": "Date on which the Offering was created", "credit_score": "The current credit score for this Offering", "currency": "The Offering's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ] "equity_offered": "The amount of equity offered as a percentage", "external_commitments": "Funding received outside the platform that should be counted towards this Offering's total", "fundamerica_offering_id": "A Fund America unique identifier for this Offering", "funding_goal": "The funding goal for this Offering", "gcen_client_id": "The Offering's GCEN Client ID", "id": "A Unique Identifier for the Offering", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_rate": "The interest rate offered", "investment_count": "The current count of Approved or Settled Investments for this Offering", "investor_count": "The number of distinct Users who have made at least one Investment in this Offering, which has life_cycle_stage equal to Approved or Settled", "is_featured": "Flag to show whether the Offering is featured", "is_secondary_offering": "Flag to show whether the Offering is a secondary market Offering", "life_cycle_stage": "0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled", "loan_to_value": "The Offering's LTV as calculated by its funding_goal divided by its valuation", "loanbook_id": "If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook", "mangopay_wallet_id": "Unique Identifier for the Offering's Mangopay Wallet", "max_commitment": "The maximum total amount that a User can invest in this Offering", "max_overfunding_amount": "The maximum amount raised by a Offering up to which Users can submit new Investments", "min_commitment": "The minimum amount that a User can invest in this Offering", "name": "The name of the Offering", "num_of_shares": "The number of shares available in this Offering", "offering_description": "A long-form description of the Offering", "open_date": "The starting date after which new Investments are permitted for this Offering", "organization_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "price_per_share": "The price per share for this Offering", "primary_offering_id": "If the Offering is a secondary market offering then this returns the Unique Identifier for its original Offering", "published_at": "The date on which this Offering was Published", "raised_percent": "The amount that the Offering has raised as a percentage of its funding_goal", "repayments_remaining": "The number of repayments still to be repaid for all Investments in this Offering", "settled_at": "The date on which this Offering was marked as Settled", "sum_outstanding_payouts": { "dividends": "The sum of all outstanding Dividend Payouts", "capitalgains": "The sum of all outstanding Capital Gain Payouts", "loanrepayments": "The sum of all outstanding Loan Repayment Payouts" }, "term": "The loan term of the Offering", "updated_at": "Date on which the Offering was last updated", "user_id": "A Unique Identifier for the User who created this Offering", "valuation": "The current valuation of the Offering" } }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}
Update an Offering.
Any parameter that is "Editable" in the Offering data model can be updated by implementing this method.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
funding_goal | Body | Decimal | The funding goal for this Offering |
|
additional_type | Body | String | An additional type or category for the Offering |
|
capitalization_id | Body | Integer | Unique identifier for the Capitalization that is being offered through this Offering |
|
close_date | Body | ISO-8601 Date | The closing date after which Investments are no longer allowed for this Offering |
|
credit_score | Body | String | The current credit score for this Offering |
|
currency | Body | Currency Code | The Offering's currency |
|
custom | Body | { Attribute Name : Attribute Value } | An array of custom Offering fields. Use an existing custom attribute name to replace the existing value. Use a new custom attribute name to add a new custom field |
|
equity_offered | Body | Decimal | The amount of equity offered as a percentage |
|
external_commitments | Body | Decimal | Funding received outside the platform that should be counted towards this Offering's total |
|
interest_rate | Body | Decimal | The interest rate offered |
|
is_featured | Body | Boolean (1 or 0) | Flag to show whether the Offering is featured |
|
is_secondary_offering | Body | Boolean (1 or 0) | Flag to show whether the Offering is a secondary market Offering |
|
life_cycle_stage | Body | Integer | 0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live, 7 = Closing, 8 = Settled, 9 = Canceled |
|
max_commitment | Body | Decimal | The maximum total amount that a User can invest in this Offering |
|
max_overfunding_amount | Body | Decimal | The maximum amount raised by a Offering up to which Users can submit new Investments |
|
min_commitment | Body | Decimal | The minimum amount that a User can invest in this Offering |
|
name | Body | String | The name of the Offering |
|
num_of_shares | Body | Integer | The number of shares available in this Offering |
|
offering_description | Body | String | A long-form description of the Offering |
|
open_date | Body | ISO-8601 Date | The starting date after which new Investments are permitted for this Offering |
|
price_per_share | Body | Decimal | The price per share for this Offering |
|
primary_offering_id | Body | Integer | The |
|
term | Body | Integer | The loan term of the Offering |
|
valuation | Body | Decimal | The current valuation of the Offering |
{ "credit_score": "A+" }
{ "outcome": "success", "data": { "offering_id": "A Unique Identifier for the Offering" }, "status": 200 }
DELETE https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}
Cancel an Offering.
This updates the Offering's life_cycle_stage
to Canceled
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offering_id": "A Unique Identifier for the Offering" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/investments
Retrieve a list of public Investments for a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to show a list of Investments that have been made for this Offering. This is typically implemented on an Offering's overview page to show which other lenders or investors have committed to the Offering.
Unless logged in as an Admin User, this function will only show Investments whose life_cycle_stage
is Approved or Settled. It will not show Investments whose life_cycle_stage
is Open, Rejected or Withdrawn.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
investment_amount | Path | Decimal | The investment amount submitted by the User for the Offering |
|
interest_rate | Path | Decimal | The interest rate offered by the User for the Offering |
|
life_cycle_stage | Path | Integer | Specify '2' (Approved) for this parameter to approve this Investment automatically |
|
number_of_shares | Path | Integer | The number of shares requested for this Investment |
|
term | Path | Integer | The term offered by the User for the Offering |
|
visibility | Path | Integer | 0 = Open, 1 = Hidden, 2 = Anonymous |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Investments requested", "count": "The total number of Investments available", "list": [ { "capital_outstanding": "The current capital outstanding for this Investment. This is calculated as the sum of all payout_amount values of all Payouts for this Investment, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.", "created_at": "Date on which the Investment was created", "currency": "The Investment's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "divested_amount": "The amount from this Investment that has been divested by the User through secondary market trades", "divested_shares": "The number of shares that have been divested from this original Investment. This figure is calculated based on the amount of Settled Investments that have been made by other Users for Secondary Market Offerings created by the User who made this original Investment.", "documents": [ { "id": "Unique Identifier for the Document", "file_name": "The document's file name", "url": "The Document's full URL", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "tag": "A tag for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "updated_at": "Date on which the Document was last updated", "created_at": "Date on which the Document was created", "user_id": "Unique identifier for the User who added this Document", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" } ], "fundamerica_investment_id": "Fund America's unique identifier for the Investment", "funding_goal": "The funding goal for the Offering for which the User made this Investment", "id": "A Unique Identifier for the Investment", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_outstanding": "The amount of interest outstanding for this Investment as calculated using a Net Annualized Return formula", "interest_rate": "The interest rate offered by the User for the Offering", "investment_amount": "The investment amount submitted by the User for the Offering", "is_loanbook": "Flag to show whether the Investment is into a Loanbook rather than an Offering", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Settled", "number_of_shares": "The number of shares requested for this Investment", "offering_id": "A Unique identifier for the Offering for which the User made this Investment", "org_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "org_name": "The `display_name` of the Organization that owns this Investment's Offering", "raised_percent": "The amount that this Investment's Offering has raised as a percentage of its funding_goal.", "repayments_remaining": "The remaining number of Payouts for this Investment that are not yet paid", "settled_at": "Date on which the Investment was marked as Settled", "term": "The term offered by the User for the Offering", "updated_at": "Date on which the Investment was last updated", "user_email": "The email of the User who made this Investment", "user_id": "A Unique Identifier for the User who made this Investment", "user_name": "The `full_name` of the User who made this Investment", "visibility": "The Investment's visibility. 0 = Open, 1 = Hidden, 2 = Anonymous" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/investments
Make a new Investment for a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to allow Users to make an Investment in an Offering.
Investments do not have any required parameters. Creating an Investment without an investment_amount
will set the new Investment's investment_amount
attribute to its default value of 0. In some cases an investment_amount
of 0 can be used to represent an 'expression of interest' in an Offering, which can then be updated at a later time by using PATCH /investments/{investment_id}
.
Specify the optional parameter life_cycle_stage
= 2 (Approved) in the request body for this function to approve the Investment automatically based on your required business logic. If you do not include the life_cycle_stage
parameter then the new Investment's life_cycle_stage
will start at its default value of 0 (Open).
Successfully creating a new Investment is also subject to the Offering's investment rules, which are defined in the Offering itself. Each of these investment rules is optional: only implement them if they make sense to your platform's operations. Each investment rule is defined by the API Exception that is returned by this function.
If you do intend to implement investment rules such as these then ensure that you handle the relevant API Exception(s) so that you can expain to the User the reason that they were unable to make an Investment.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "investment_amount": "10000" }
{ "outcome": "success", "data": { "investment_id": "A Unique Identifier for the new Investment" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/dealrooms
Retrieve a list of Deal Rooms for the given Offering, as specified by the path parameter offering_id
.
An Offering can have multiple Deal Rooms and the Deal Room acts as the access-controlled area of an Offering that includes discussion forums, due diligence tasks, and access-restricted documents.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Deal Rooms requested", "count": "The total number of Deal Rooms available", "list": { "access_groups": "A list of Access Groups for this Deal Room", "created_at": "Date on which the Deal Room was created", "custom": { "The name of the custom field": "The value of the custom field" }, "document_groups": "A list of Document Groups for this Deal Room", "documents": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ], "id": "A Unique Identifier for the Deal Room", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "offering_id": "A Unique Identifier for the Offering that owns this Deal Room", "updated_at": "Date on which the Deal Room was last updated" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/dealrooms
Create a new Deal Room for a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to create a new Deal Room, which acts as the access-controlled area of an Offering that includes discussion forums, due diligence tasks, and access-restricted documents.
This function does not require any body parameters.
{ "outcome": "success", "data": { "deal_room_id": "A Unique Identifier for the Deal Room" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/bulletins
Create a new Bulletin for a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to create a new news item, blog posts or similar updates that are represented by the Bulletin object, which is always attached to an Offering.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
title | Body | String | The title of the Bulletin |
|
body | Body | String | The body content of the Bulletin |
{ "title" : "News story", "body" : "Great news about this Offering" }
{ "outcome": "success", "data": { "bulletin_id": "A Unique Identifier for the new Bulletin" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/bulletins
Retrieve a list of Bulletins for a given Offering by specifying the Offering's id
in the offering_id
path parameter.
Implement this function to show a list of news items, blog posts or similar updates that are represented by the Bulletin object, which is always attached to an Offering. Typically this is used to show a timeline of activities that are related to an Offering during a live fundraising campaign or to show news and updates relating to a historical Offering, in which the logged-in User might have invested.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Bulletins requested", "count": "The total number of Bulletins available", "list": [ { "body": "The body content of the Bulletin", "created_at": "Date on which the Bulletin was created", "id": "Unique Identifier for the Bulletin", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "offering_id": "Unique Identifier for this Bulletin's Offering", "title": "The title of the Bulletin", "updated_at": "Date on which the Bulletin was last updated" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/documents
Retrieve a list of Documents for the given Offering, as specified by the path parameter offering_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Documents requested", "count": "The total number of Documents available", "list": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" }, ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/documents
Add a Document to the given Offering, as specified by the path parameter offering_id
.
When displaying Documents on an Offering overview page, you may choose to attach the Document to the Offering itself or to the Offering's Organization.
Typically you would attach a Document to an Organization by calling this function if the Document applies equally to all of the Organization's Offerings. You might attach a Document to an Offering if it only applies to that particular Offering and not any others that may be created later, for instance, as part of a secondary market.
As an example, it makes sense to attach a Certificate of Incorporation document to the Organization because each Organization only has one such certificate and it is the same document no matter how many Offerings the Organization creates. Conversely, a Loan Agreement document might specify the terms and conditions for a particular loan, as represented by an Offering, and the terms will not necessarily be the same for the next Offering created for this Organization. In that case, it would make sense to attach the document to the Offering.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
file_name | Body | String | The Document's file name |
|
url | Body | String | The Document's full URL |
|
file_type | Body | String | The Document's mime-type |
|
file_alias | Body | String | The publicly visible alias of the Document |
|
file_description | Body | String | The publicly visible description of the Document |
|
group_id | Body | Integer | Unique identifier for the Document Group of this Document |
|
source_type | Body | Boolean (1 or 0) | 0 = Crowd Valley CDN, 1 = External CDN |
|
tag | Body | String | A tag for the Document |
{ "file_name": "financials.jpg", "url": "https://yourcdn.yourstoragefacility.com/financials.pdf", "file_alias": "Financials 15/16", "file_description": "Financial Statements 2015-16", "file_type": "application/pdf", "tag": "Financials" }
{ "outcome": "success", "data": { "document_id": "A Unique Identifier for the new Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/payouts
View a list of Payout Schedules for a given Offering, as specified by the path parameter offering_id
. These schedules are attached directly to the Offering, so they are typically used to show a borrower's repayment schedule, as opposed to the Payouts that are attached to Investments, which typically record a lender's or investor's repayment schedule.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Payouts requested", "count": "The total number of Payouts available", "list": [ { "additional_type": "An additional type or category for the Payout" "charge_offs": "The amount of charge-offs associated with this Payout", "created_at": "Date on which this Payout was created", "currency": "The Payout's currency code", "custom": { "The name of the custom field": "The value of the custom field" }, "due_date": "The date on which a Transaction is due for this Payout", "id": "Unique Identifier for the Payout", "investment_id": "Unique Identifier for this Payout's Investment", "late_fee": "The amount of late fees associated with this Payout", "minimum_payment": "The minimum amount required to settle this Payout", "net_annualized_return": "The Net Annualized Return for this Payout", "net_recoveries": "The amount of net recoveries associated with this Payout", "offering_name": "The name of the Offering with which this Payout is associated", "paid_at": "Date on which this Payout was paid", "payout_amount": "The amount expected for this Payout's Transaction", "payout_type": "The type of Payout: 0 = Dividend; 1 = Loan Repayment; 2 = Capital Gain", "service_charge": "The amount of service charge associated with this Payout", "transactions_paid": "The number of Transactions that have been paid for this Payout", "updated_at": "Date on which this Payout was last updated", "user_id": "Unique identifier for the User who owns this Payout", "user_name": "Name of the User who owns this Payout" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/payouts
Add a Payout Schedule record to the given Offering, as specified by the path parameter offering_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
currency | Body | Currency | The Payout's currency code |
|
due_date | Body | ISO-8601 Date | The date on which a Transaction is due for this Payout |
|
payout_amount | Body | Decimal | The amount expected for this Payout's Transaction |
|
payout_type | Body | Integer | The type of Payout. Use the following enumeration in order to see the correct calculations through the |
|
minimum_payment | Body | Decimal | The minimum amount required to settle this Payout |
|
additional_type | Body | String | An additional type or category for the Payout |
{ "payout_amount" : "1000", "payout_type" : "1", "minimum_payment" : "1000", "due_date" : "2016-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "dividend", "investment_id" : "102" }
{ "outcome": "success", "data": { "payout_id": "A Unique Identifier for the new Payout" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/generatePaymentSchedule
Add multiple Payout Schedule records to the given Offering, as specified by the path parameter offering_id
.
Implement this function if you want to create a whole repayment schedule for this User, typically on a P2P lending platform.
The parameters should be sent in an array, each one specifying the parameters for a given Payout.
The payout_id
returned is the last Payout to be created. If you create Payouts 100-110 then this function will return payout_id
: "100" in its response.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
offering_id | Path | Integer | The |
|
payouts | Body | Array of Payouts | A list of Payouts to be created |
{ "payouts" : [ { "payout_amount" : "1000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" }, { "payout_amount" : "2000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" }, { "payout_amount" : "3000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" } ] }
{ "outcome": "success", "data": { "payout_id": "A Unique Identifier for the new Payout" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/dealrooms/{dealroom_id}/topics
Retrieve a list of forum Topics for the given Deal Room, as specified by the path parameter dealroom_id
.
A Deal Room can have multiple Topics and the Topic acts as a category or group of users' Posts in a forum. Topics are always attached to a particular Deal Room, which in turn is associated with a single Offering.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Topics requested", "count": "The total number of Topics available", "list": [ { "body": "The content of the Topic", "created_at": "Date on which the Topic was created", "deal_room_id": "A Unique Identifier for the Deal Room that owns this Topic", "family_name": "The `family_name` of the User who created this Topic", "given_name": "The `given_name` of the User who created this Topic", "id": "A Unique Identifier for the Topic", "title": "The title of the Topic", "updated_at": "Date on which the Topic was last updated", "user_id": "A Unique Identifier for the User who created this Topic", "visibility": "The Topic's visibility (0 = Open, 1 = Hidden, 2 = Anonymous)" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/dealrooms/{dealroom_id}/topics
Create a new Topic for a given Deal Room by specifying the Deal Room's id
in the dealroom_id
path parameter.
Implement this function to create a new category or group of users' Posts in a forum. Topics are always attached to a particular Deal Room, which in turn is associated with a single Offering.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
dealroom_id | Path | Integer | The |
|
title | Body | String | The title of the Topic |
|
body | Body | String | The content of the Topic |
{ "title" : "The title of the Topic", "body" : "The content of the Topic" }
{ "outcome": "success", "data": { "topic_id": "A Unique Identifier for the Topic" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/dealrooms/{dealroom_id}/documents
Retrieve a list of Documents for the given Deal Room, as specified by the path parameter dealroom_id
.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Topics requested", "count": "The total number of Topics available", "list": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Difitek CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/dealrooms/{dealroom_id}/documents
Add a Document to the given Deal Room, as specified by the path parameter dealroom_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
|
file_name | Body | String | The Document's file name |
|
url | Body | String | The Document's full URL |
|
file_type | Body | String | The Document's mime-type |
|
file_alias | Body | String | The publicly visible alias of the Document |
|
file_description | Body | String | The publicly visible description of the Document |
|
group_id | Body | Integer | Unique identifier for the Document Group of this Document |
|
source_type | Body | Boolean (1 or 0) | 0 = Crowd Valley CDN, 1 = External CDN |
|
tag | Body | String | A tag for the Document |
{ "outcome": "success", "data": { "document_id": "A Unique Identifier for the new Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/topics/{topic_id}/posts
View all Posts for a given Topic in a Deal Room by specifying the Topic's id
in the topic_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
topic_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Posts requested", "count": "The total number of Posts available", "list": [ { "body": "The body of the Post", "created_at": "Date on which the Post was created", "id": "Unique Identifier for the Post", "topic_id": "Unique Identifier for the Topic", "updated_at": "Date on which the Post was last updated", "user_id": "Unique Identifier for the User who created this Post", "user_name": "The `full_name` of the User who created this Post", "visibility": "The visibility of the Post - 0 = Open, 1 = Hidden, 2 = Anonymous" }, ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/topics/{topic_id}/posts
Create a new Post for a given Topic in a Deal Room by specifying the Topic's id
in the topic_id
path parameter.
Implement this function to create a new Post in a forum. Topics are always attached to a particular Deal Room, which in turn is associated with a single Offering. All Posts belong to a Topic and a Topic can have multiple Posts.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
topic_id | Path | Integer | The |
|
body | Body | String | The content of the Post |
{ "body" : "The content of the Post" }
{ "outcome": "success", "data": { "topic_id": "A Unique Identifier for the Topic" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/posts/{post_id}
View a given Post in a Deal Room by specifying the Post's id
in the post_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
post_id | Path | Integer | The |
{ "outcome": "success", "data": { "post": { "body": "The body of the Post", "created_at": "Date on which the Post was created", "id": "Unique Identifier for the Post", "topic_id": "Unique Identifier for the Topic", "updated_at": "Date on which the Post was last updated", "user_id": "Unique Identifier for the User who created this Post", "user_name": "The `full_name` of the User who created this Post", "visibility": "The visibility of the Post - 0 = Open, 1 = Hidden, 2 = Anonymous" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/posts/{post_id}/comments
View all Comments for a given Post in a Deal Room by specifying the Post's id
in the post_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
post_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Comments requested", "count": "The total number of Comments available", "list": [ { "body": "The body of the Comment", "created_at": "Date on which the Comment was created", "id": "Unique Identifier for the Comment", "post_id": "Unique Identifier for the Post", "updated_at": "Date on which the Comment was last updated" "user_id": "Unique Identifier for the User who created this Comment", "user_name": "The `full_name` of the User who created this Comment", "visibility": "The visibility of the Comment: 0 = Open, 1 = Hidden, 2 = Anonymous" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/posts/{post_id}/comments
Create a new Comment for a given Post in a Deal Room.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
post_id | Path | Integer | The |
{ "body" : "Comment about this post" }
{ "outcome": "success", "data": { "comment_id": "Unique Identifier for the Comment" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}
Retrieve information about an Investment.
Access to this information is determined by the logged-in User's rights to know about the Investment.
The User who created the Investment can retrieve the Investment's data regardless of its life_cycle_stage
.
Admin Users, i.e. Users who have is_admin
set to true
, can also see all Investments of any life_cycle_stage
.
Users who are members of the Organization for whose Offering this Investment was made can see all Investments of any life_cycle_stage
.
Other Users are only able to retrieve Investments whose life_cycle_stage
is Approved or Settled.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
{ "outcome": "success", "data": { "investment": { "capital_outstanding": "The current capital outstanding for this Investment. This is calculated as the sum of all payout_amount values of all Payouts for this Investment, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.", "created_at": "Date on which the Investment was created", "currency": "The Investment's currency", "custom": { "The name of the custom field": "The value of the custom field" }, "divested_amount": "The amount from this Investment that has been divested by the User through secondary market trades", "divested_shares": "The number of shares that have been divested from this original Investment. This figure is calculated based on the amount of Settled Investments that have been made by other Users for Secondary Market Offerings created by the User who made this original Investment.", "documents": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } ], "fundamerica_investment_id": "Fund America's unique identifier for the Investment", "funding_goal": "The funding goal for the Offering for which the User made this Investment", "id": "A Unique Identifier for the Investment", "info": [ { "type": "The name of the custom field", "value": "The value of the custom field" } ], "interest_outstanding": "The amount of interest outstanding for this Investment as calculated using a Net Annualized Return formula", "interest_rate": "The interest rate offered by the User for the Offering", "investment_amount": "The investment amount submitted by the User for the Offering", "is_loanbook": "Flag to show whether the Investment is into a Loanbook rather than an Offering", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Settled", "number_of_shares": "The number of shares requested for this Investment", "offering_id": "A Unique identifier for the Offering for which the User made this Investment", "org_id": "A Unique Identifier for the Organization that owns this Investment's Offering", "org_name": "The `display_name` of the Organization that owns this Investment's Offering", "raised_percent": "The amount that this Investment's Offering has raised as a percentage of its funding_goal.", "repayments_remaining": "The remaining number of Payouts for this Investment that are not yet paid", "settled_at": "Date on which the Investment was marked as Settled", "term": "The term offered by the User for the Offering", "updated_at": "Date on which the Investment was last updated", "user_email": "The email of the User who made this Investment", "user_id": "A Unique Identifier for the User who made this Investment", "user_name": "The `full_name` of the User who made this Investment", "visibility": "The Investment's visibility. 0 = Open, 1 = Hidden, 2 = Anonymous" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}/documents
Retrieve a list of Documents for the given Investment, as specified by the path parameter investment_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Documents requested", "count": "The total number of Documents available", "list": [ { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" }, ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}/documents
Add a Document to the given Investment, as specified by the path parameter investment_id
.
The logged-in User must be one of the following in order to have access to attach a Document to an Investment:
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
|
file_name | Body | String | The Document's file name |
|
url | Body | String | The Document's full URL |
|
file_type | Body | String | The Document's mime-type |
|
file_alias | Body | String | The publicly visible alias of the Document |
|
file_description | Body | String | The publicly visible description of the Document |
|
group_id | Body | Integer | Unique identifier for the Document Group of this Document |
|
source_type | Body | Boolean (1 or 0) | 0 = Crowd Valley CDN, 1 = External CDN |
|
tag | Body | String | A tag for the Document |
{ "outcome": "success", "data": { "document_id": "A Unique Identifier for the new Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}/payouts
View a list of Payout Schedules for a given Investment, as specified by the path parameter investment_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Payouts requested", "count": "The total number of Payouts available", "list": [ { "additional_type": "An additional type or category for the Payout" "charge_offs": "The amount of charge-offs associated with this Payout", "created_at": "Date on which this Payout was created", "currency": "The Payout's currency code", "custom": { "The name of the custom field": "The value of the custom field" }, "due_date": "The date on which a Transaction is due for this Payout", "id": "Unique Identifier for the Payout", "investment_id": "Unique Identifier for this Payout's Investment", "late_fee": "The amount of late fees associated with this Payout", "minimum_payment": "The minimum amount required to settle this Payout", "net_annualized_return": "The Net Annualized Return for this Payout", "net_recoveries": "The amount of net recoveries associated with this Payout", "offering_name": "The name of the Offering with which this Payout is associated", "paid_at": "Date on which this Payout was paid", "payout_amount": "The amount expected for this Payout's Transaction", "payout_type": "The type of Payout: 0 = Dividend; 1 = Loan Repayment; 2 = Capital Gain", "service_charge": "The amount of service charge associated with this Payout", "transactions_paid": "The number of Transactions that have been paid for this Payout", "updated_at": "Date on which this Payout was last updated", "user_id": "Unique identifier for the User who owns this Payout", "user_name": "Name of the User who owns this Payout" } ] }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}/payouts
Add a Payout Schedule record to the given Investment, as specified by the path parameter investment_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
|
currency | Body | Currency | The Payout's currency code |
|
due_date | Body | ISO-8601 Date | The date on which a Transaction is due for this Payout |
|
payout_amount | Body | Decimal | The amount expected for this Payout's Transaction |
|
payout_type | Body | Integer | The type of Payout. Use the following enumeration in order to see the correct calculations through the |
|
minimum_payment | Body | Decimal | The minimum amount required to settle this Payout |
|
additional_type | Body | String | An additional type or category for the Payout |
{ "payout_amount" : "1000", "payout_type" : "1", "minimum_payment" : "1000", "due_date" : "2016-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "dividend", "investment_id" : "102" }
{ "outcome": "success", "data": { "payout_id": "A Unique Identifier for the new Payout" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}/generatePaymentSchedule
Add multiple Payout Schedule records to the given Investment, as specified by the path parameter investment_id
.
Implement this function if you want to create a whole repayment schedule for this User, typically on a P2P lending platform.
The parameters should be sent in an array, each one specifying the parameters for a given Payout.
The payout_id
returned is the last Payout to be created. If you create Payouts 100-110 then this function will return payout_id
: "100" in its response.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
|
payouts | Body | Array of Payouts | A list of Payouts to be created |
{ "payouts" : [ { "payout_amount" : "1000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" }, { "payout_amount" : "2000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" }, { "payout_amount" : "3000", "payout_type" : "1", "due_date" : "2015-07-20T09:38:55+0000", "currency" : "GBP", "additional_type" : "type" } ] }
{ "outcome": "success", "data": { "payout_id": "A Unique Identifier for the new Payout" }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/investments/{investment_id}
Update an Investment. Any parameter that is "Editable" in the Investment data model can be updated by implementing this method.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
investment_id | Path | Integer | The |
{ "investment_amount": "11000" }
{ "outcome": "success", "data": { "investment_id": "The Unique Identifier for the Investment" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/payouts/{payout_id}
Information about this Payout Schedule record.
{ "outcome": "success", "data": { "payout": { "additional_type": "An additional type or category for the Payout" "charge_offs": "The amount of charge-offs associated with this Payout", "created_at": "Date on which this Payout was created", "currency": "The Payout's currency code", "custom": { "The name of the custom field": "The value of the custom field" }, "due_date": "The date on which a Transaction is due for this Payout", "id": "Unique Identifier for the Payout", "investment_id": "Unique Identifier for this Payout's Investment", "late_fee": "The amount of late fees associated with this Payout", "minimum_payment": "The minimum amount required to settle this Payout", "net_annualized_return": "The Net Annualized Return for this Payout", "net_recoveries": "The amount of net recoveries associated with this Payout", "offering_name": "The name of the Offering with which this Payout is associated", "paid_at": "Date on which this Payout was paid", "payout_amount": "The amount expected for this Payout's Transaction", "payout_type": "The type of Payout: 0 = Dividend; 1 = Loan Repayment; 2 = Capital Gain", "service_charge": "The amount of service charge associated with this Payout", "transactions_paid": "The number of Transactions that have been paid for this Payout", "updated_at": "Date on which this Payout was last updated", "user_id": "Unique identifier for the User who owns this Payout", "user_name": "Name of the User who owns this Payout" } }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/payouts/{payout_id}
Update this Payout Schedule record.
{ "outcome": "success", "data": { "payout_id": "Unique identifier for this Payout" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/payouts/{payout_id}/transactions
View a list of Transactions that have been associated to this Payout Schedule record.
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Transactions requested", "count": "The total number of Transactions available", "list": [ { "confirmation_number": "A number or code that confirms the given transaction has been successfully processed.", "created_at": "The date on which the Transaction was created.", "custom": [], "id": "Unique Identifier for the Transaction", "original_transaction_amount": "The original amount paid if in a different currency from the User's wallet.", "original_transaction_currency": "The currency of the original amount paid.", "payment_service": "An identifier for the payment service used to make this transaction. Use this to create an integer-based enumeration for the payment services that you use on your platform.", "payment_service_log_id": "A unique identifier for the transaction log of the payment service", "payment_status": "0 = Pending, 1 = Paid, 2 = Cancelled or 3 = Failed.", "payout_id": "Unique Identifier for this Transaction's Payout.", "transaction_amount": "The amount paid in this Transaction. Enter transaction_amount > 0 for debits and transaction_amount < 0 for credits.", "transaction_currency": "The Transaction's ISO 4217 currency code", "transaction_description": "A log description for the Transaction", "updated_at": "The date on which the Transaction was last updated", "user_id": "Unique Identifier for the User who made this Transaction", "user_name": "The full_name of the User who made this Transaction", "wallet_id": "Unique Identifier for the User who made this Transaction" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/transactions/{transaction_id}
Information about this Transaction.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
transaction_id | Path | Integer | The |
{ "outcome": "success", "data": { "transaction": { "confirmation_number": "A number or code that confirms the given transaction has been successfully processed", "created_at": "Date on which the Transaction was created", "custom": { "The name of the custom field": "The value of the custom field" }, "id": "Unique Identifier for this Transaction", "original_transaction_amount": "The original amount paid if in a different currency from the user's wallet", "original_transaction_currency": "The currency of the original amount paid", "payment_service": "0 = Offline, 1 = MangoPay, 2 = GCEN, 3 = GoCardless", "payment_service_log_id": "A unique identifier for the transaction log of the payment service", "payment_status": "0 = Pending, 1 = Paid, 2 = Cancelled or 3 = Failed", "payout_id": "Unique Identifier for this Transaction's Payout", "transaction_amount": "The amount paid in this Transaction", "transaction_currency": "The Transaction's currency code", "transaction_description": "A log description for the Transaction", "updated_at": "Date on which the Transaction was last updated", "user_id": "Unique identifier for the User who made this Transaction", "user_name": "The `full_name` of the User who made this Transaction", "wallet_id": "Unique Identifier for the Wallet from which this Transaction was made" } }, "status": 200 }
PATCH https://api.sandbox.crowdvalley.com/v1/{network}/transactions/{transaction_id}
Update this Transaction.
Any parameter that is "Editable" in the Transaction data model can be updated by implementing this method.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
transaction_id | Path | Integer | The |
|
transaction_description | Body | String | A log description for the Transaction |
|
transaction_amount | Body | String | The amount paid in this Transaction |
|
transaction_currency | Body | Currency Code | The Transaction's currency code |
|
payment_status | Body | Integer | 0 = Pending, 1 = Paid, 2 = Cancelled or 3 = Failed |
|
payment_service | Body | Integer | 0 = Offline, 1 = MangoPay, 2 = GCEN, 3 = GoCardless |
|
payout_id | Body | Integer | Unique Identifier for this Transaction's Payout |
|
original_transaction_amount | Body | Decimal | The original amount paid if in a different currency from the user's wallet |
|
original_transaction_currency | Body | Currency Code | The currency of the original amount paid |
|
payment_service_log_id | Body | String | A unique identifier for the transaction log of the payment service |
|
confirmation_number | Body | String | A number or code that confirms the given transaction has been successfully processed |
{ "payment_status" : "2" }
{ "outcome": "success", "data": { "transaction_id": "A Unique Identifier for the Transaction" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/wallets/{wallet_id}/transactions
Create a new Transaction associated to a given internal Wallet as specified by the wallet_id
path parameter.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | Integer | The |
|
transaction_amount | Body | Decimal | The amount paid in this Transaction |
|
transaction_currency | Body | Currency Code | The Transaction's currency code |
|
transaction_description | Body | String | A log description for the Transaction |
|
payment_status | Body | Integer | 0 = Pending, 1 = Paid, 2 = Cancelled or 3 = Failed |
|
payment_service | Body | Integer | 0 = Offline, 1 = MangoPay, 2 = GCEN, 3 = GoCardless |
|
payout_id | Body | Integer | Unique Identifier for this Transaction's Payout |
|
original_transaction_amount | Body | Decimal | The original amount paid if in a different currency from the user's wallet |
|
original_transaction_currency | Body | Currency Code | The currency of the original amount paid |
|
payment_service_log_id | Body | String | A unique identifier for the transaction log of the payment service |
|
confirmation_number | Body | String | A number or code that confirms the given transaction has been successfully processed |
{ "transaction_amount" : "1000", "transaction_description" : "Credit bonus", "transaction_currency" : "USD", "payment_status" : "1", "payment_service" : "1" }
{ "outcome": "success", "data": { "transaction_id": "A Unique Identifier for the new Transaction" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/documents/{document_id}
View a Document
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
document_id | Path | Integer | The |
{ "outcome": "success", "data": { "document": { "created_at": "Date on which the Document was created", "document_group": "The name of the Document Group for this Document", "file_alias": "The publicly visible alias of the document", "file_description": "The publicly visible description of the document", "file_name": "The document's file name", "file_type": "The document's mime-type", "group_id": "Unique identifier for a Deal Room Document Group for this Document", "id": "Unique Identifier for the Document", "life_cycle_stage": "0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn", "owner_id": "The Unique Identifier of the owner of this Document", "owner_object": "The Crowd Valley object that owns this Document: User, Organization, Offering or Investment", "source_type": "0 = Crowd Valley CDN, 1 = External CDN" "tag": "A tag for the Document", "updated_at": "Date on which the Document was last updated", "url": "The Document's full URL", "user_id": "Unique identifier for the User who added this Document" } }, "status": 200 }
DELETE https://api.sandbox.crowdvalley.com/v1/{network}/documents/{document_id}
Delete a Document.
The Document is made inactive and unavailable through the platform. However, documents are kept in the Crowd Valley back-end for audit trail purposes.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
document_id | Path | Integer | The |
{ "outcome": "success", "data": { "document_id": "A Unique Identifier for the Document" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/stripe
Retrieve your network's publishable key for accessing the Stripe API.
{ "outcome": "success", "data": { "publishable_key": "Key to use with accessing the Stripe API" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/stripe/payment
Make a card payment using the Stripe API.
This function requires two parameters: amount
and token
.
The amount
represents the amount to be paid as a decimal, e.g. $123.50 would be sent as 123.50.
The token
should be generated by using Stripe's API directly in advance of calling this function.
To generate a token
implement POST https://api.stripe.com/v1/tokens
with a header Authorization: Bearer {{publishable_key}}
, where publishable_key
can be retrieved from your Crowd Valley account through the GET /stripe
function.
When implementing POST https://api.stripe.com/v1/tokens
the following parameters are required:
The Stripe API will return an id
which you should then use as the token
when implementing this POST /self/stripe/payment
function.
Typically you would use the result of this function to add funds to the User's internal wallet by creating a Transaction for the User's Wallet that records the result of the Stripe function.
{ "outcome": "success", "data": { "success": true, "paymentId": "ch_19Dz0UBtw7sTK5tDMZWzF5f5", "_raw": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": { "id": "ch_19Dz0UBtw7sTK5tDMZWzF5f5", "object": "charge", "amount": 12350, "amount_refunded": 0, "balance_transaction": "txn_19Dz0VBtw7sTK5tD80kPV0FK", "captured": true, "created": 1478709182, "currency": "usd", "description": "Normal User - 666b712c-7969-4e63-aaba-8dd10cde7ff0@demo.com", "fraud_details": [], "livemode": false, "metadata": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": [], "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [] }, "outcome": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": { "network_status": "approved_by_network", "risk_level": "normal", "seller_message": "Payment complete.", "type": "authorized" }, "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [] }, "paid": true, "refunded": false, "refunds": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/charges/ch_19Dz0UBtw7sTK5tDMZWzF5f5/refunds" }, "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [], "_h_e_a_d_e_r_s__t_o__p_e_r_s_i_s_t": { "Stripe-Account": true, "Stripe-Version": true }, "_request_params": [] }, "source": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": { "id": "card_19Dz0PBtw7sTK5tDkMcEa17F", "object": "card", "brand": "Visa", "country": "US", "cvc_check": "pass", "exp_month": 12, "exp_year": 2022, "fingerprint": "6b06ySjTFEvOV43U", "funding": "credit", "last4": "4242", "metadata": { "permanent_attributes": { "_elts": { "_opts": true, "id": true } }, "nested_updatable_attributes": { "_elts": { "0": true, "1": true, "2": true, "3": true, "4": true, "metadata": true, "legal_entity": true, "address": true, "dob": true, "transfer_schedule": true, "verification": true, "tos_acceptance": true, "personal_address": true, "additional_owners": true, "inventory": true } }, "_opts": { "headers": [], "api_key": "sk_test_XO3o1vQ23TU3gyKLPdWMHNl9" }, "_values": [], "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [] } }, "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [], "_h_e_a_d_e_r_s__t_o__p_e_r_s_i_s_t": { "Stripe-Account": true, "Stripe-Version": true } }, "status": "succeeded" }, "_unsaved_values": { "_elts": [] }, "_transient_values": { "_elts": [] }, "_retrieve_options": [], "_last_response": { "headers": { "Server": "nginx", "Date": "Wed, 09 Nov 2016 16:33:03 GMT", "Content-Type": "application/json", "Content-Length": "1749", "Connection": "keep-alive", "Access-Control-Allow-Credentials": "true", "Access-Control-Allow-Methods": "GET, POST, HEAD, OPTIONS, DELETE", "Access-Control-Allow-Origin": "*", "Access-Control-Max-Age": "300", "Cache-Control": "no-cache, no-store", "Request-Id": "req_9X36OxZb6sQ1ER", "Stripe-Version": "2016-03-07", "Strict-Transport-Security": "max-age=31556926; includeSubDomains" }, "body": "{\n \"id\": \"ch_19Dz0UBtw7sTK5tDMZWzF5f5\",\n \"object\": \"charge\",\n \"amount\": 12350,\n \"amount_refunded\": 0,\n \"application\": null,\n \"application_fee\": null,\n \"balance_transaction\": \"txn_19Dz0VBtw7sTK5tD80kPV0FK\",\n \"captured\": true,\n \"created\": 1478709182,\n \"currency\": \"usd\",\n \"customer\": null,\n \"description\": \"Normal User - 666b712c-7969-4e63-aaba-8dd10cde7ff0@demo.com\",\n \"destination\": null,\n \"dispute\": null,\n \"failure_code\": null,\n \"failure_message\": null,\n \"fraud_details\": {},\n \"invoice\": null,\n \"livemode\": false,\n \"metadata\": {},\n \"order\": null,\n \"outcome\": {\n \"network_status\": \"approved_by_network\",\n \"reason\": null,\n \"risk_level\": \"normal\",\n \"seller_message\": \"Payment complete.\",\n \"type\": \"authorized\"\n },\n \"paid\": true,\n \"receipt_email\": null,\n \"receipt_number\": null,\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"total_count\": 0,\n \"url\": \"/v1/charges/ch_19Dz0UBtw7sTK5tDMZWzF5f5/refunds\"\n },\n \"review\": null,\n \"shipping\": null,\n \"source\": {\n \"id\": \"card_19Dz0PBtw7sTK5tDkMcEa17F\",\n \"object\": \"card\",\n \"address_city\": null,\n \"address_country\": null,\n \"address_line1\": null,\n \"address_line1_check\": null,\n \"address_line2\": null,\n \"address_state\": null,\n \"address_zip\": null,\n \"address_zip_check\": null,\n \"brand\": \"Visa\",\n \"country\": \"US\",\n \"customer\": null,\n \"cvc_check\": \"pass\",\n \"dynamic_last4\": null,\n \"exp_month\": 12,\n \"exp_year\": 2022,\n \"fingerprint\": \"6b06ySjTFEvOV43U\",\n \"funding\": \"credit\",\n \"last4\": \"4242\",\n \"metadata\": {},\n \"name\": null,\n \"tokenization_method\": null\n },\n \"source_transfer\": null,\n \"statement_descriptor\": null,\n \"status\": \"succeeded\"\n}\n", "json": { "id": "ch_19Dz0UBtw7sTK5tDMZWzF5f5", "object": "charge", "amount": 12350, "amount_refunded": 0, "balance_transaction": "txn_19Dz0VBtw7sTK5tD80kPV0FK", "captured": true, "created": 1478709182, "currency": "usd", "description": "Normal User - 666b712c-7969-4e63-aaba-8dd10cde7ff0@demo.com", "fraud_details": [], "livemode": false, "metadata": [], "outcome": { "network_status": "approved_by_network", "risk_level": "normal", "seller_message": "Payment complete.", "type": "authorized" }, "paid": true, "refunded": false, "refunds": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/charges/ch_19Dz0UBtw7sTK5tDMZWzF5f5/refunds" }, "source": { "id": "card_19Dz0PBtw7sTK5tDkMcEa17F", "object": "card", "brand": "Visa", "country": "US", "cvc_check": "pass", "exp_month": 12, "exp_year": 2022, "fingerprint": "6b06ySjTFEvOV43U", "funding": "credit", "last4": "4242", "metadata": [] }, "status": "succeeded" }, "code": 200 }, "_h_e_a_d_e_r_s__t_o__p_e_r_s_i_s_t": { "Stripe-Account": true, "Stripe-Version": true } } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/register
Register the logged-in User as a 'Natural User' with Mangopay.
A 'natural user' is a person whereas a 'legal user' represents a business or an organization.
A natural user is able to:
In order to register successfully the User must already have the following attributes:
email
given_name
family_name
birth_date
nationality
address
(including at least building
, street_address
and country
)job_title
Successfully implementing this function saves the Mangopay Unique Identifier for this User into the User's mangopay_user_id
field.
{ "outcome": "success", "data": { "mangopay_id": "The User's Mangopay ID" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/register
Register an Organization as a 'Legal User' with Mangopay with the Organization's contact_point
acting as its legal representative. The contact_point
will often be the same as the User who created the Organization, but this is not always the case.
A legal user represents a business or an organization whereas a natural user is a person. This natural user is able on behalf of the Organization to:
In order to register a 'Legal User' successfully the Organization's contact_point
User must have already registered with Mangopay by calling POST /self/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute. In addition, the Organization must already have the following attributes:
legal_name
(defaults to display_name
if legal_name
is not provided)org_email
address
(including at least building
, street_address
and country
)Successfully implementing this function saves the Mangopay Unique Identifier for this Legal User into the Organization's mangopay_user_id
field.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "mangopay_id": "The Organization's Mangopay ID" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets
Create a new Mangopay Wallet for the logged-in User.
A Mangopay Wallet is an object in which payins and transfers from Users or Organizations are stored in order to collect money. You can pay into a wallet, withdraw funds from a wallet or transfer funds from a wallet to another wallet.
In order to register successfully the User must have already registered with Mangopay by calling POST /self/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
{ "outcome": "success", "data": { "mangopay_wallet_id": "Unique identifier for the logged-in User's new Mangopay Wallet" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets
Create a new Mangopay Wallet for an Organization (Legal User).
A Mangopay Wallet is an object in which payins and transfers from Users or Organizations are stored in order to collect money. You can pay into a wallet, withdraw funds from a wallet or transfer funds from a wallet to another wallet.
The Organization must have already registered with Mangopay by calling POST self/organizations/{organization_id}/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
{ "outcome": "success", "data": { "mangopay_wallet_id": "Unique identifier for the Organization's new Mangopay Wallet" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/mangopay/wallets
Create a new Mangopay Wallet for an Offering.
A Mangopay Wallet is an object in which payins and transfers from Users or Organizations are stored in order to collect money. You can pay into a wallet, withdraw funds from a wallet or transfer funds from a wallet to another wallet.
The Offering's Organization must have already registered with Mangopay by calling POST self/organizations/{organization_id}/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
The Mangopay Wallet's ID is stored in the Offering's mangopay_wallet_id
field when this function is called successfully.
{ "outcome": "success", "data": { "mangopay_wallet_id": "Unique identifier for the Offering's new Mangopay Wallet" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets
View a list of all the logged-in User's Mangopay Wallets.
{ "outcome": "success", "data": { "list": [ { "id": "Manogpay Wallet ID", "tag": "The `id` of the User who owns this Wallet", "creation_date": "Timestamp showing the date on which the Wallet was created", "description": "A description of the Wallet", "balance": "The Wallet's current balance", "currency": "The Wallet's currency" } ], "wallets": "Depreciated. Please use 'list' instead." }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets
View a list of all the Organization's Mangopay Wallets.
The Organization must have already registered with Mangopay by calling POST self/organizations/{organization_id}/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | String | The |
{ "outcome": "success", "data": { "list": [ { "id": "Manogpay Wallet ID", "tag": "The `id` of the Organization who owns this Wallet", "creation_date": "Timestamp showing the date on which the Wallet was created", "description": "A description of the Wallet", "balance": "The Wallet's current balance", "currency": "The Wallet's currency" } ], "wallets": "Depreciated. Please use 'list' instead." }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}
View a Mangopay Wallet specified by its Mangopay unique identifier in the path parameter wallet_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | Integer | The Mangopay identifier of the Wallet |
{ "outcome": "success", "data": { "wallet": { "id": "Manogpay Wallet ID", "tag": "The `id` of the User who owns this Wallet", "creation_date": "Timestamp showing the date on which the Wallet was created", "description": "A description of the Wallet", "balance": "The Wallet's current balance", "currency": "The Wallet's currency" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets/{wallet_id}
View a Mangopay Wallet owned by an Organization (Legal User) specified by its Mangopay unique identifier in the path parameter wallet_id
.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
wallet_id | Path | Integer | The Mangopay identifier of the Wallet |
{ "outcome": "success", "data": { "wallet": { "id": "Manogpay Wallet ID", "tag": "The `id` of the Organization that owns this Wallet", "creation_date": "Timestamp showing the date on which the Wallet was created", "description": "A description of the Wallet", "balance": "The Wallet's current balance", "currency": "The Wallet's currency" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/submitKycDocument
Perform a Mangopay KYC Check on the logged-in User.
KYC means 'Know Your Customer'. These legal obligations are related to Mangopay's license as an electronic money issuer and are neccessary in order to fight fraud, money laundering and financing of terrorism. There are 3 levels of authentication (light/regular/strong) managed through the API.
Users have to send some documents through the API to be validated by the Mangopay compliance team. This validation will allow your to access a higher level of KYC sign-off (light to regular or regular to strong).
Before making this API call, the logged-in User must have a Document in GET /self/documents
with a tag
that is equal to proof_of_identity.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "kyc_id": "Unique Identifier for the Mangopay KYC Check" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/submitKycDocument
Perform a Mangopay KYC Check on the Legal User represented by the Organization specified by the path parameter organization_id
.
KYC means 'Know Your Customer'. These legal obligations are related to Mangopay's license as an electronic money issuer and are neccessary in order to fight fraud, money laundering and financing of terrorism. There are 3 levels of authentication (light/regular/strong) managed through the API.
Users have to send some documents on behalf of the Organization (Legal User) through the API to be validated by the Mangopay compliance team. This validation will allow your Users to access a higher level of KYC sign-off (light to regular or regular to strong).
Before making this API call, the Organization must have Documents in GET /organizations/{organization_id}/documents
with a valid tag
that can be used by the Mangopay Compliance team to identify the type of document that has been submitted. The permitted document tags are:
This function has one required parameter, tag
, which must be the tag
of the Document that should be sent to Mangopay for KYC purposes. If you want to provide multiple Documents then call this function once per Document, each time with a different tag
to point to the relevant Document.
The Organization must have already registered with Mangopay by calling POST self/organizations/{organization_id}/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | String | The |
|
tag | Body | String | The |
{ "tag" : "SHAREHOLDER_DECLARATION" }
{ "outcome": "success", "data": { "kyc_id": "Unique Identifier for the Mangopay KYC Check" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/cards/register
Generate a registration link from Mangopay in order to tokenize a payment card for the logged-in User.
Users must tokenize a card in order to process payments on your platform. Card tokenization enables it to be re-used on your platform without the card details being re-entered every time.
The full card registration process is as follows:
POST /self/mangopayCardRegister
id
, access_key
, preregistration_data
and a card_registration_url
preregistration_data
and access_key
, along with the User's Card Number, Card Expiration Date and CVV number, and a returnURL
, to the URL provided by card_registration_url
. The returnURL
must be a page on your front-end that can receive the Card Registration Server's response, which will include adata
attributePOST /self/mangopayCards
, which has two required parameters: card_registration_id
and data
card_registration_id
field must contain the id
of the Card Registration generated by the initial call to POST /self/mangopayCardRegister
in step 1data
field must contain the data
string returned by the Card Registration Server in step 3Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
In order to generate a card registration link the User must have already registered with Mangopay by calling POST /self/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
currency | Body | Currency Code | The currency of the card |
{ "currency" : "GBP" }
{ "outcome": "success", "data": { "card_registration": { "id": "Unique identifier for the Card Registration link", "access_key": "A private access key used to tokenize a card", "preregistration_data": "Card Pre-registration data used to tokenize a card", "card_registration_url": "The URL required by the Crowd Valley API to POST the card details directly to Mangopay" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/cards/register
Generate a registration link from Mangopay in order to tokenize a payment card for the Organization.
Users must tokenize a card in order to process payments on your platform. Card tokenization enables it to be re-used on your platform without the card details being re-entered every time.
The full card registration process is as follows:
POST /organizations/{org_id}/mangopay/cards/register
id
, access_key
, preregistration_data
and a card_registration_url
preregistration_data
and access_key
, along with the User's Card Number, Card Expiration Date and CVV number, and a returnURL
, to the URL provided by card_registration_url
. The returnURL
must be a page on your front-end that can receive the Card Registration Server's response, which will include adata
attributePOST /organizations/{org_id}/mangopay/cards
, which has two required parameters: card_registration_id
and data
card_registration_id
field must contain the id
of the Card Registration generated by the initial call to POST /organizations/{org_id}/mangopay/cards/register
in step 1data
field must contain the data
string returned by the Card Registration Server in step 3Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
The Organization must have already registered with Mangopay by calling POST self/organizations/{organization_id}/mangopayRegister
, and therefore have a valid mangopay_user_id
attribute.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
currency | Body | Currency Code | The currency of the card |
{ "currency" : "GBP" }
{ "outcome": "success", "data": { "card_registration": { "id": "Unique identifier for the Card Registration link", "access_key": "A private access key used to tokenize a card", "preregistration_data": "Card Pre-registration data used to tokenize a card", "card_registration_url": "The URL required by the Crowd Valley API to POST the card details directly to Mangopay" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/cards
Registers a payment card with Mangopay.
Users must tokenize a card in order to process payments on your platform. Card tokenization enables it to be re-used on your platform without the card details being re-entered every time.
The full card registration process is as follows:
POST /self/mangopayCardRegister
id
, access_key
, preregistration_data
and a card_registration_url
preregistration_data
and access_key
, along with the User's Card Number, Card Expiration Date and CVV number, and a returnURL
, to the URL provided by card_registration_url
. The returnURL
must be a page on your front-end that can receive the Card Registration Server's response, which will include adata
attributePOST /self/mangopayCards
, which has two required parameters: card_registration_id
and data
card_registration_id
field must contain the id
of the Card Registration generated by the initial call to POST /self/mangopayCardRegister
in step 1data
field must contain the data
string returned by the Card Registration Server in step 3When testing in a sandbox environment you can use these Mangopay test cards for transactions under €100:
Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
This function stores the Mangopay Unique Identifier for the card in the User's mangopay_card_id
attribute.
Sample Form to use in step 3
<form action="{{ card_registration_url }}" method="post">
<input type="hidden" name="data" value="{{ preregistration_data }}" />
<input type="hidden" name="accessKeyRef" value="{{ access_key }}" />
<input type="hidden" name="returnURL" value="{{ https://www.yoursite.com/mangopay-card-return }}" />
<label for="cardNumber">Card Number</label>
<input type="text" name="cardNumber" placeholder="Card Number" />
<div class="clear"></div>
<label for="cardExpirationDate">Expiration Date</label>
<input type="text" name="cardExpirationDate" placeholder="Expiration Date MMYY" />
<div class="clear"></div>
<label for="cardCvx">CVV</label>
<input type="text" name="cardCvx" placeholder="CVV" />
<div class="clear"></div>
<input type="submit" value="Register Card" />
</form>
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
card_registration_id | Body | String | The |
|
data | Body | String | The value of the |
{ "data" : "long_string_provided_by_card_registration_server", "card_registration_id" : "12345678" }
{ "outcome": "success", "data": { "card_id": "Unique Identifier for the Mangopay Tokenized Card" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/cards
Registers a payment card with Mangopay for the Organization.
Users must tokenize a card in order to process payments on your platform. Card tokenization enables it to be re-used on your platform without the card details being re-entered every time.
The full card registration process is as follows:
POST /organizations/{org_id}/mangopay/cards/register
id
, access_key
, preregistration_data
and a card_registration_url
preregistration_data
and access_key
, along with the User's Card Number, Card Expiration Date and CVV number, and a returnURL
, to the URL provided by card_registration_url
. The returnURL
must be a page on your front-end that can receive the Card Registration Server's response, which will include adata
attributePOST /organizations/{org_id}/mangopay/cards
, which has two required parameters: card_registration_id
and data
card_registration_id
field must contain the id
of the Card Registration generated by the initial call to POST /organizations/{org_id}/mangopay/cards/register
in step 1data
field must contain the data
string returned by the Card Registration Server in step 3When testing in a sandbox environment you can use these Mangopay test cards for transactions under €100:
Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
This function stores the Mangopay Unique Identifier for the card in the Organization's mangopay_card_id
attribute.
Sample Form to use in step 3
<form action="{{ card_registration_url }}" method="post">
<input type="hidden" name="data" value="{{ preregistration_data }}" />
<input type="hidden" name="accessKeyRef" value="{{ access_key }}" />
<input type="hidden" name="returnURL" value="{{ https://www.yoursite.com/mangopay-card-return }}" />
<label for="cardNumber">Card Number</label>
<input type="text" name="cardNumber" placeholder="Card Number" />
<div class="clear"></div>
<label for="cardExpirationDate">Expiration Date</label>
<input type="text" name="cardExpirationDate" placeholder="Expiration Date MMYY" />
<div class="clear"></div>
<label for="cardCvx">CVV</label>
<input type="text" name="cardCvx" placeholder="CVV" />
<div class="clear"></div>
<input type="submit" value="Register Card" />
</form>
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
card_registration_id | Body | String | The |
|
data | Body | String | The value of the |
{ "data" : "long_string_provided_by_card_registration_server", "card_registration_id" : "12345678" }
{ "outcome": "success", "data": { "card_id": "Unique Identifier for the Mangopay Tokenized Card" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/cards
View a list of Mangopay Card Identifiers for the logged-in User (Natural User). Note that this does not return credit/debit card numbers or any other identifiable information relating to a payment card, but only Mangopay's unique identifier for this card.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Cards requested", "count": "The total number of Cards available", "list": [ { "id": "Unique Identifier for the Mangopay Card in Crowd Valley's database", "organization_id": "Unique Identifier for the Organization", "mangopay_card_id": "Mangopay Unique Identifier for the Card" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/cards
View a list of Mangopay Card Identifiers for an Organization (Legal User). Note that this does not return credit/debit card numbers or any other identifiable information relating to a payment card, but only Mangopay's unique identifier for this card.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
{ "outcome": "success", "data": { "offset": "The list offset requested", "limit": "The maximum number of Cards requested", "count": "The total number of Cards available", "list": [ { "id": "Unique Identifier for the Mangopay Card in Crowd Valley's database", "organization_id": "Unique Identifier for the Organization", "mangopay_card_id": "Mangopay Unique Identifier for the Card" } ] }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/cards/{card_id}
View information about a Mangopay Card owned by the logged-in User (Natural User).
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
card_id | Path | String | The Mangopay Unique Identifier for the Card (not the Crowd Valley database ID) |
{ "outcome": "success", "data": { "mangopay_card": { "id": "Unique Identifier for the Mangopay Card in Crowd Valley's database", "user_id": "Unique Identifier for the User", "mangopay_card_id": "Mangopay Unique Identifier for the Card", "mangopay_data": { "_id": "Mangopay Unique Identifier for the Card", "_creation_date": "Date on which the Card was registered through Mangopay", "_expiration_date": "The expiration date of the Card", "_alias": "An alias for the Card, e.g. 356999XXXXXX0132", "_card_type": "E.g. CB_VISA_MASTERCARD", "_product": "The Card product type. See https://docs.mangopay.com/uploads/medias/Product-codes.pdf", "_bank_code": "", "_active": "Flag to show whether the card is active or not", "_currency": "Currency code in ISO4217 format", "_validity": "Indicator for whether the card is valid or not. Once Users process (or attempt to process) a payment with the card Mangopay is able to indicate if it is "valid" or "invalid". If the User has not yet processed a payment then the "Validity" will be 'unknown'." } } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/cards/{card_id}
View information about a Mangopay Card owned by an Organization (Legal User).
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
card_id | Path | String | The Mangopay Unique Identifier for the Card (not the Crowd Valley database ID) |
{ "outcome": "success", "data": { "mangopay_card": { "id": "Unique Identifier for the Mangopay Card in Crowd Valley's database", "organization_id": "Unique Identifier for the Organization", "mangopay_card_id": "Mangopay Unique Identifier for the Card", "mangopay_data": { "_id": "Mangopay Unique Identifier for the Card", "_creation_date": "Date on which the Card was registered through Mangopay", "_expiration_date": "The expiration date of the Card", "_alias": "An alias for the Card, e.g. 356999XXXXXX0132", "_card_type": "E.g. CB_VISA_MASTERCARD", "_product": "The Card product type. See https://docs.mangopay.com/uploads/medias/Product-codes.pdf", "_bank_code": "", "_active": "Flag to show whether the card is active or not", "_currency": "Currency code in ISO4217 format", "_validity": "Indicator for whether the card is valid or not. Once Users process (or attempt to process) a payment with the card Mangopay is able to indicate if it is "valid" or "invalid". If the User has not yet processed a payment then the "Validity" will be 'unknown'." } } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets/{wallet_id}/payinByCard
Adds funds to a Mangopay Wallet using a tokenized payment card. The payment card must have been registered with Mangopay using POST /organizations/{organization_id}/mangopay/cards
.
This function can be implemented to allow Organizations (Legal Users) to move funds from a tokenized card into their own Mangopay Wallet or directly from a card into an Offering's Mangopay Wallet, in case the Organization is making an investment.
The amount
and fee_amount
fields are Integers based on taking the Decimal amount and multiplying by 100. Therefore a payment of €100.00 should be sent as '10000'.
Read more about Mangopay Fees Rules
Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
wallet_id | Path | String | The Unique Identifier for the Mangopay Wallet |
|
card_id | Body | String | The Unique Identifier for a tokenized payment card |
|
amount | Body | Integer | The amount to pay from the Organization's card |
|
currency | Body | Currency Code | The currency of the card payment |
|
return_url | Body | String | A return URL on your front-end platform that will receive the response from the Mangopay payment server |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "return_url" : "http://www.yoursite.com/card-return", "currency" : "GBP", "fee_amount" : "100" }
{ "outcome": "success", "data": [], "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/payinByCard
Adds funds to a Mangopay Wallet using a tokenized payment card. The payment card must have been registered with Mangopay using POST /self/mangopay/cards
.
This function can be implemented to allow Users to move funds from a tokenized card into their own Mangopay Wallet or directly from a card into an Offering's Mangopay Wallet, in case the User is making an investment.
The amount
and fee_amount
fields are Integers based on taking the Decimal amount and multiplying by 100. Therefore a payment of €100.00 should be sent as '10000'.
Read more about Mangopay Fees Rules
Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | String | The Unique Identifier for the Mangopay Wallet |
|
card_id | Body | String | The Unique Identifier for a tokenized payment card |
|
amount | Body | Integer | The amount to pay from the User's card |
|
currency | Body | Currency Code | The currency of the card payment |
|
return_url | Body | String | A return URL on your front-end platform that will receive the response from the Mangopay payment server |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "return_url" : "http://www.yoursite.com/card-return", "currency" : "GBP", "fee_amount" : "100" }
{ "outcome": "success", "data": [], "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/payinByUnregisteredCard
Adds funds to a Mangopay Wallet using a card that is not registered and tokenized.
In this method, the payment card details are entered directly by the User into a form that is managed by Mangopay. Platforms must not attempt to store or process the User's card details through any other method.
The User's card details are not saved so the User would have to enter their full card details each time in order to make further payments into their Mangopay Wallet.
The amount
and fee_amount
fields are Integers based on taking the Decimal amount and multiplying by 100. Therefore a payment of €100.00 should be sent as '10000'.
Read more about Mangopay Fees Rules
Card details must never pass via your server or Crowd Valley's servers – therefore you must use the card registration process as described above and not implement a different system where the card details may touch your server and using cURL to create the card. This approach or anything similar is strictly not allowed
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | String | The Unique Identifier for the Mangopay Wallet |
|
card_type | Body | String | The type of card that will be used for this transaction: CB_VISA_MASTERCARD, DINERS, MASTERPASS, MAESTRO, P24, IDEAL, BCMC, PAYLIB |
|
amount | Body | Integer | The amount to pay from the User's card |
|
currency | Body | Currency Code | The currency of the card payment |
|
callback_url | Body | String | A callback URL on your front-end platform that will receive the response from the Mangopay payment server |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "currency" : "GBP", "fee_amount" : "100", "card_type" : "CB_VISA_MASTERCARD", "callback_url" : "https://yourdomain.com/callback" }
{ "outcome": "success", "data": { "RedirectURL": "A URL to which you should direct the User in order to complete the card payment", "mangopay_response": "{\"CreditedWalletId\":\"20006796\",\"PaymentType\":\"CARD\",\"PaymentDetails\":{\"CardType\":\"CB_VISA_MASTERCARD\",\"CardId\":null},\"ExecutionType\":\"WEB\",\"ExecutionDetails\":{\"RedirectURL\":\"https:\\/\\/homologation-webpayment.payline.com\\/webpayment\\/step2.do?reqCode=prepareStep2&token=2WNgCRRJVPqLAg13B6071484749449142\",\"ReturnURL\":\"https:\\/\\/yourdomain.com\\/callback?transactionId=20006797\",\"TemplateURL\":\"https:\\/\\/api.sandbox.mangopay.com\\/Content\\/PaylineTemplate?rp=6ee61a6c636642cc&transactionId=20006797\",\"Culture\":\"EN\",\"SecureMode\":\"DEFAULT\"},\"AuthorId\":\"20006793\",\"CreditedUserId\":\"20006793\",\"DebitedFunds\":{\"Currency\":\"GBP\",\"Amount\":10000},\"CreditedFunds\":{\"Currency\":\"GBP\",\"Amount\":9900},\"Fees\":{\"Currency\":\"GBP\",\"Amount\":100},\"Status\":\"CREATED\",\"ResultCode\":null,\"ResultMessage\":null,\"ExecutionDate\":null,\"Type\":\"PAYIN\",\"Nature\":\"REGULAR\",\"Id\":\"20006797\",\"Tag\":\"\",\"CreationDate\":1484749448}" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/payinByBankWire
Retrieve the Bank Account details in order for the User to make a bank wire transfer into their Mangopay Wallet.
Implementing this function returns the bank details that the User should use when making a transfer from their own bank. The bank transfer itself is not handled by this API.
The amount
and fee_amount fields
are Integers based on taking the Decimal amount and multiplying by 100. Therefore a payment of €100.00 should be sent as '10000'.
Currently, UK bank Accounts are not available through the API. This means that Mangopay always returns a BIC/IBAN for cash-in transfers. To allow bank wire transfer payments in the UK, display this UK bank account even if the API returns the BIC:
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
user_id | Path | String | The |
|
wallet_id | Path | String | The Mangopay Unique Identifier of the Wallet into which the User wants to make a Bank Wire transfer |
|
amount | Body | Integer | The amount to pay from the User's card |
|
currency | Body | Currency Code | The currency of the card payment |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "currency" : "GBP", "fee_amount" : "100" }
{ "outcome": "success", "data": { "bank_account": { "type": "IBAN", "owner_name": "Bank Account Name", "IBAN": "Bank Account IBAN", "BIC": "Bank Account BIC", "wire_reference": "Bank Account Wire Reference. The User must use this reference in order to ensure their funds are allocated correctly to their Mangopay Wallet" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets/{wallet_id}/payinByBankWire
Retrieve the Bank Account details in order for an Organization (Legal User) to make a bank wire transfer into their Mangopay Wallet.
Implementing this function returns the bank details that the Organization should use when making a transfer from their own bank. The bank transfer itself is not handled by this API.
The amount
and fee_amount fields
are Integers based on taking the Decimal amount and multiplying by 100. Therefore a payment of €100.00 should be sent as '10000'.
Currently, UK bank Accounts are not available through the API. This means that Mangopay always returns a BIC/IBAN for cash-in transfers. To allow bank wire transfer payments in the UK, display this UK bank account even if the API returns the BIC:
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | String | The |
|
wallet_id | Path | String | The Mangopay Unique Identifier of the Wallet into which the User wants to make a Bank Wire transfer |
|
amount | Body | Integer | The amount to pay from the User's card |
|
currency | Body | Currency Code | The currency of the card payment |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "currency" : "GBP", "fee_amount" : "100" }
{ "outcome": "success", "data": { "bank_account": { "type": "IBAN", "owner_name": "Bank Account Name", "IBAN": "Bank Account IBAN", "BIC": "Bank Account BIC", "wire_reference": "Bank Account Wire Reference. The User must use this reference in order to ensure their funds are allocated correctly to their Mangopay Wallet" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/transfer
Make a transfer of e-money from a User's Mangopay Wallet to an Organization's Mangopay Wallet.
To implement this as part of your investment process, first ensure that each Organization that runs an Offering on your platform is registered with Mangopay as a 'Legal User', and therefore has a valid mangopay_user_id
.
Then, when a User makes an Investment into the Offering, implement this function to move e-money from the User's Mangopay Wallet into the Organization. You should create the Investment by calling POST /offerings/{offering_id}/investments
only when you get a success
response back from this function, in order to ensure that Investments are not created before checking that the User has sufficient funds in their Mangopay Wallet, for example.
The function has three required parameters:
target_wallet_id
, which should be the Mangopay Unique Identifier for the Wallet into which the funds should be transferred;amount
, which is the amount as an Integer, calculated by taking the Decimal amount and multiplying by 100 such that an investment of €100.00 would be sent as 10000currency
, which should be the currency code of the User's WalletParameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | String | The Mangopay Unique Identifier of the Wallet from which the User wants to make a transfer |
|
target_wallet_id | Body | String | The Mangopay Unique Identifier of the Wallet into which the User wants to make a transfer |
|
amount | Body | Integer | The amount to pay from the User's Mangopay Wallet |
|
currency | Body | Currency Code | The currency of the transfer |
|
fee_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "currency" : "GBP", "fee_amount" : "100", "target_wallet_id" : "12876543" }
{ "outcome": "success", "data": { "transfer": { "id": "Mangopay Unique Identifier for the transaction", "creation_date": Timestamp showing the date on which the transaction was created, "author_id": "Mangopay Unique Identifier of the transaction’s author User", "credited_user_id": "Mangopay Unique Identifier for the User who owns the credited wallet", "debited_funds": "Amount of debited funds", "credited_funds": "Amount of credited funds", "status": "CREATED, SUCCEEDED or FAILED", "type": "PAYIN, PAY_OUT or TRANSFER", "execution_date": "Timestamp showing the date on which the transaction was executed", "nature": "REGULAR, REFUND or REPUDIATION" "result_message" : "Success" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/bankaccounts
Register a Bank Account in preparation for making a Payout to a User's own bank account from their Mangopay e-money wallet.
Currently the Crowd Valley API accepts these formats:
Please get in touch with Crowd Valley to request any of the following formats:
When registering a BIC/IBAN account, there are four required parameters for this function:
IBAN
- the Bank Account's IBAN codeBIC
- the Bank Account's BIC codeowner_name
- the full name of the User who owns the Bank Accountowner_address
- the full address of the User who owns the Bank AccountPlease note that that even in a sandbox environment you will need to put a real-life existing valid BIC/IBAN in order to pass Mangopay's validation checks.
When registering a UK account, there are also four required parameters:
account_number
- the Bank Account's Account Numbersort_code
- the Bank Account's Sort Codeowner_name
- the full name of the User who owns the Bank Accountowner_address
- the full address of the User who owns the Bank AccountSimilarly for UK accounts, even in a sandbox environment you will need to put a real-life existing valid Account Number and Sort Code in order to pass Mangopay's validation checks.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
type | Body | String | The type of Bank Account. Must be one of: IBAN, GB, US, CA or OTHER |
|
BIC or account_number | Body | String | The Bank Account's BIC code or Account Number |
|
IBAN or sort_code | Body | String | The Bank Account's IBAN code or Sort Code |
|
owner_address | Body | String | The full address of the User who owns the Bank Account |
|
owner_name | Body | String | The full name of the User who owns the Bank Account |
{ "type" : "IBAN", "BIC" : "ABCDGB12", "IBAN" : "GB32ESSE40486562136016", "owner_address" : "1 Oxford Street, London, WC1A 1AA", "owner_name" : "John Doe" }
{ "outcome": "success", "data": { "bank_account": { "id": "Unique Identifier for the Bank Account", "type": "IBAN, GB, US, CA or OTHER", "owner_name": "The full name of the User who owns this Bank Account", "created_at": "Timestamp showing the date on which the Bank Account was registered", "IBAN": "The Bank Account's IBAN code", "BIC": "The Bank Account's BIC code" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/bankaccounts
Register a Bank Account in preparation for making a Payout to a Organization's own bank account from their Mangopay e-money wallet.
Currently the Crowd Valley API accepts these formats:
Please get in touch with Crowd Valley to request any of the following formats:
When registering a BIC/IBAN account, there are five required parameters for this function:
type
- IBANIBAN
- the Bank Account's IBAN codeBIC
- the Bank Account's BIC codeowner_name
- the full name of the User who owns the Bank Accountowner_address
- the full address of the User who owns the Bank AccountPlease note that that even in a sandbox environment you will need to put a real-life existing valid BIC/IBAN in order to pass Mangopay's validation checks.
When registering a UK account, there are also four required parameters:
type
- GBaccount_number
- the Bank Account's Account Numbersort_code
- the Bank Account's Sort Codeowner_name
- the full name of the User who owns the Bank Accountowner_address
- the full address of the User who owns the Bank AccountSimilarly for UK accounts, even in a sandbox environment you will need to put a real-life existing valid Account Number and Sort Code in order to pass Mangopay's validation checks.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | String | The |
|
type | Body | String | The type of Bank Account. Must be one of: IBAN, GB, US, CA or OTHER |
|
BIC or account_number | Body | String | The Bank Account's BIC code or Account Number |
|
IBAN or sort_code | Body | String | The Bank Account's IBAN code or Sort Code |
|
owner_address | Body | String | The full address of the User who owns the Bank Account |
|
owner_name | Body | String | The full name of the User who owns the Bank Account |
{ "BIC" : "ABCDGB12", "IBAN" : "GB32ESSE40486562136016", "owner_address" : "1 Oxford Street, London, WC1A 1AA", "owner_name" : "John Doe" }
{ "outcome": "success", "data": { "bank_account": { "id": "Unique Identifier for the Bank Account", "type": "IBAN, GB, US, CA or OTHER", "owner_name": "The full name of the User who owns this Bank Account", "created_at": "Timestamp showing the date on which the Bank Account was registered", "IBAN": "The Bank Account's IBAN code", "BIC": "The Bank Account's BIC code" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/bankaccounts
Retrieve a list of Bank Accounts registered with Mangopay.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "list": { "id": "Unique Identifier for the Bank Account in Crowd Valley's database", "user_id": "Unique Identifier for the User who owns this Bank Account", "mangopay_bank_account_id": "Mangopay's Unique Identifier for the Bank Account" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/bankaccounts/{bank_account_id}
Retrieve information about a Bank Account registered with Mangopay.
The bank_account_id
attribute should be Mangopay's Unique Identifier not the identifier given to the Bank Account in Crowd Valley's database.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
bank_account_id | Path | Integer | The Mangopay Unique Identifier of the Bank Account |
{ "outcome": "success", "data": { "bank_account": { "id": "Unique Identifier for the Bank Account", "type": "IBAN, GB, US, CA or OTHER", "owner_name": "The full name of the User who owns this Bank Account", "created_at": "Timestamp showing the date on which the Bank Account was registered", "IBAN": "The Bank Account's IBAN code", "BIC": "The Bank Account's BIC code" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/bankaccounts
Retrieve a list of Bank Accounts registered with Mangopay.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | Unique Identifier for the Organization |
{ "outcome": "success", "data": { "list": { "id": "Unique Identifier for the Bank Account in Crowd Valley's database", "organization_id": "Unique Identifier for the Organization that owns this Bank Account", "mangopay_bank_account_id": "Mangopay's Unique Identifier for the Bank Account" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/bankaccounts/{bank_account_id}
Retrieve information about a Bank Account registered with Mangopay.
The bank_account_id
attribute should be Mangopay's Unique Identifier not the identifier given to the Bank Account in Crowd Valley's database.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
bank_account_id | Path | Integer | The Mangopay Unique Identifier of the Bank Account |
{ "outcome": "success", "data": { "bank_account": { "id": "Unique Identifier for the Bank Account", "type": "IBAN, GB, US, CA or OTHER", "owner_name": "The full name of the User who owns this Bank Account", "created_at": "Timestamp showing the date on which the Bank Account was registered", "IBAN": "The Bank Account's IBAN code", "BIC": "The Bank Account's BIC code" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/payout
A Pay-out by bank wire is a request to withdraw money from a wallet to a bank account.
Users must have registered a Bank Account with Mangopay before implementing this function. Note that if a User is planning to make a PayOut to someone different from the Wallet's owner, you should not register the Bank Account with the same User - you must create a second User for this purpose. Please contact Mangopay's support team if you are unsure about this point, as it is important and will otherwise cause your PayOuts to be rejected by the Mangopay compliance team.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | String | The Mangopay Unique Identifier of the Wallet from which the User wants to make a transfer |
|
amount | Body | Integer | The amount to pay from the User's Mangopay Wallet |
|
bank_account_id | Body | Integer | The Mangopay Unique Identifier for a Bank Account that has been registered with Mangopay using |
|
currency | Body | Currency Code | The currency of the transfer |
|
fees_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "bank_account_id" : "12345678", "currency" : "GBP", "fees_amount" : "100" }
{ "outcome": "success", "data": { "bank_account": { "type": "PAY_OUT", "created_at": "Timestamp showing the date on which the Payout was made", "author_id": "Unique Identifier for the User who made the Payout", "amount": "Amount paid out to the User's Bank Account", "fees": "Amount of fees taken by the platform for processing the Payout", "bank_account_id": "Unique Identifier for the User's Bank Account" } }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets/{wallet_id}/payout
A Pay-out by bank wire is a request to withdraw money from a wallet to a bank account.
Organizations must have registered a Bank Account with Mangopay before implementing this function. Note that if a Organization is planning to make a PayOut to someone different from the Wallet's owner, you should not register the Bank Account with the same Organization - you must create a second User or Organization for this purpose. Please contact Mangopay's support team if you are unsure about this point, as it is important and will otherwise cause your PayOuts to be rejected by the Mangopay compliance team.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | String | The |
|
wallet_id | Path | String | The Mangopay Unique Identifier of the Wallet from which the Organization wants to make a transfer |
|
amount | Body | Integer | The amount to pay from the Organization's Mangopay Wallet |
|
bank_account_id | Body | Integer | The Mangopay Unique Identifier for a Bank Account that has been registered with Mangopay |
|
currency | Body | Currency Code | The currency of the transfer |
|
fees_amount | Body | Integer | The amount of fees taken by your platform from this transaction |
{ "amount" : "10000", "bank_account_id" : "12345678", "currency" : "GBP", "fees_amount" : "100" }
{ "outcome": "success", "data": { "bank_account": { "type": "PAY_OUT", "created_at": "Timestamp showing the date on which the Payout was made", "author_id": "Unique Identifier for the User who made the Payout", "amount": "Amount paid out to the User's Bank Account", "fees": "Amount of fees taken by the platform for processing the Payout", "bank_account_id": "Unique Identifier for the User's Bank Account" } }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets/{wallet_id}/transactions
View a log of transactions for a Mangopay Wallet.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
wallet_id | Path | String | The Unique Identifier for the Mangopay Wallet |
{ "outcome": "success", "data": { "list": [ { "id": "Mangopay Unique Identifier for the transaction", "creation_date": Timestamp showing the date on which the transaction was created, "author_id": "Mangopay Unique Identifier of the transaction’s author User", "credited_user_id": "Mangopay Unique Identifier for the User who owns the credited wallet", "debited_funds": "Amount of debited funds", "credited_funds": "Amount of credited funds", "status": "CREATED, SUCCEEDED or FAILED", "type": "PAYIN, PAY_OUT or TRANSFER", "nature": "REGULAR, REFUND or REPUDIATION" } ], "transactions": "Depreciated. Please use 'list' instead." }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/organizations/{organization_id}/mangopay/wallets/{wallet_id}/transactions
View a log of transactions for an Organization's (Legal User) Mangopay Wallet.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
organization_id | Path | Integer | The |
|
wallet_id | Path | Integer | The Mangopay identifier of the Wallet |
{ "outcome": "success", "data": { "list": [ { "id": "Mangopay Unique Identifier for the transaction", "creation_date": Timestamp showing the date on which the transaction was created, "author_id": "Mangopay Unique Identifier of the transaction’s author User", "credited_user_id": "Mangopay Unique Identifier for the User who owns the credited wallet", "debited_funds": "Amount of debited funds", "credited_funds": "Amount of credited funds", "status": "CREATED, SUCCEEDED or FAILED", "type": "PAYIN, PAY_OUT or TRANSFER", "nature": "REGULAR, REFUND or REPUDIATION" } ], "transactions": "Depreciated. Please use 'list' instead." }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/register
Register the logged-in User as a 'Client' with GCEN.
GCEN Clients are able to add funds to their GCEN wallets, make transfers to other Users' GCEN wallets, make a transfer into an Offering's GCEN wallet, and receive funds that may be paid as a dividend or a loan repayment.
In order to register successfully the User must already have the following attributes:
In addition the following attributes are sent to GCEN if they are available:
Successfully implementing this function saves the GCEN Unique Identifier for this User into the User's gcen_client_id
field.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
performAML | Body | Boolean | Flag to set whether to perform a full AML check on the User |
{ "performAML": true }
{ "outcome": "success", "data": "", "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen
Retrieves the logged-in User's current KYC status as assessed by GCEN.
GCEN maintains two KYC statuses for all Users who are registered as GCEN clients, i.e., Users with a valid gcen_client_id
value.
The eKYC
status represents the automated checks that are run when a user registers with their details using POST /self/gcen/register
. The User's details are run through a third party verification system which generates an eKYC result.
The KYC
status is the manual process of a GCEN account manager verifying the documents uploaded by a registered client and ticking their account off as verified. Documents are uploaded by a User by implementing the POST /self/gcen/submitKycDocument
function.
This function can be implemented as part of your User Onboarding process or as an additional check that you could run before a User tries to make their first Investment, for example.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "StatusId": 0, "Success": true, "ReturnObject": [ { "ClientId": "The User's GCEN Client ID", "eKYCPassed": "true or false", "KYCPassed": "true or false" } ], "Message": "" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/balance
Retrieves the logged-in User's current GCEN balance.
The Currency of the balance is based on the User's Bank Account's currency
field. If the User has not yet set up a Bank Account record then currency
will default to GBP.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "StatusId": 0, "Success": true, "ReturnObject": "The User's GCEN Balance", "Message": "" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/balanceLog
Retrieves the logged-in User's GCEN balance log.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
{ "outcome": "success", "data": { "StatusId": 0, "Success": true, "ReturnObject": [ { "AgentId": "GCEN Unique Identifier for your platform", "ClientId": "GCEN Unique Identifier for this User", "ClientIdFull": "The full GCEN Identifier for this User including AgentId", "Amount": "The amount for this transaction", "Balance": 0, "AllocatedDate": "The date on which this transaction was allocated", "Log": "GCEN Unique Identifier for this transaction", "Currency": "Currency of this transaction", "Uncleared": "Flag to show whether the transaction has cleared", "StatementDate": "The date on which this transaction was added to the statement", "DealCode": "GCEN Unique Identifier for the Offering", "Narrative": "Free text description of this transaction" } ], "Message": "" }, "status": 200 }
GET https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/runningBalance
Retrieves the logged-in User's Running GCEN balance log between two dates provided by the query parameters start_date
and end_date
.
Implement this feature to create a date filter on a User's GCEN transaction balance log page.
The date format of both start_date
and end_date
must be yyyy-MM-dd.
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
start_date | Query | yyyy-MM-dd | The start date of the filter |
|
end_date | Query | yyyy-MM-dd | The end date of the filter |
{ "outcome": "success", "data": { "StatusId": 0, "Success": true, "ReturnObject": { "ClientId": "GCEN Unique Identifier for this User", "Currency": "Currency of this transaction", "StartDate": "Start Date of the request", "EndDate": "End Date of the request", "StartBalance": "Balance at the start_date", "EndBalance": "Balance at the end_date", "BalanceLog": [ { "AgentId": "GCEN Unique Identifier for your platform", "ClientId": "GCEN Unique Identifier for this User", "ClientIdFull": "The full GCEN Identifier for this User including AgentId", "Amount": "The amount for this transaction", "Balance": 0, "AllocatedDate": "The date on which this transaction was allocated", "Log": "GCEN Unique Identifier for this transaction", "Currency": "Currency of this transaction", "Uncleared": "Flag to show whether the transaction has cleared", "StatementDate": "The date on which this transaction was added to the statement" } ] }, "Message": "" }, "status": 200 }
POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/requestWithdrawal
Requests a withdrawal from the logged-in User's GCEN balance.
Implement this feature to allow Users to make payments from their online GCEN balance to their offline bank account.
The amount
and currency
parameters are required to instruct GCEN to make a payment of the given amount to the User's bank account.
The narrative
parameter optionally adds a custom description to the transaction, which is returned by the GCEN Balance Log function in the Narrative
field. This allows you to populate a transaction log page with custom descriptions.
By default the Bank Account details are used from the User's bank_accounts
data but the following optional parameters can be provided to specify the User's bank account without saving the information to the User's account.
full_name
)Note that GCEN will run a check to ensure that the User is associated to the bank account before processing a withdrawal request.
There are four possible error cases when implementing this function:
{ "StatusId": 1200, "Success": false, "ReturnObject": 50, "Message": "Client does not have a balance with GCEN" }
{ "StatusId": 1201, "Success": false, "ReturnObject": null, "Message": "Client has insufficient balance on their account" }
{ "StatusId": 1302, "Success": false, "ReturnObject": null, "Message": "Amount must be a positive number" }
{ "StatusId": 9500, "Success": false, "ReturnObject": [{ "Currency": "GBP", "Total": 12000, "ClientId": 101, "Limit": 7500, "IdChecked": false }], "Message": "One or more of the clients have exceed their annual tunover limit." }
Parameter | Required | Type | Format | Description |
---|---|---|---|---|
network | Path | String | The name of your network |
|
amount | Body | Decimal | The amount requested to be withdrawn |
|
currency | Body | Currency | The Currency code as specified in ISO 4217 |
|
account_number | Body | String | The beneficiary User's Bank IBAN or account number |
|
bank_code | Body | String | The beneficiary User's Bank Swift code / Sort code / Branch code |
|
bene_name | Body | String | The beneficiary User's account name |
|
bene_ref1 | Body | String | Reference that will appear on the beneficiary User's statement |
|
narrative | Body | String | A custom description that will be returned for this transaction from the Balance Log function |
{ "outcome": "success", "data": { "StatusId": 0, "Success&