API Endpoints and Functions


Public

View Platform Statistics

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.

Response
{
  "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
}

View Users (without login)

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.

Response
{
  "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
}


View Organizations (without login)

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.

Response
{
  "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
}


View an Organization (without login)

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 id of the Organization


Response
{
  "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
}

Key Concepts: Unauthenticated Users

View Featured Offerings (without login)

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.

Response
{
  "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
}


View Offerings (without login)

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.

Response
{
  "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
}


View an Offering (without login)

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 id of the Offering


Response
{
  "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
}


Verify Email

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 id of the User whose email is being verified by calling this function.

secret Body String

The secret string sent by the Crowd Valley Back Office to the User by email, after calling POST /users or POST /self/resendVerificationEmail.


Sample Request Body
{
    "user_id" : "1234",
    "secret" : "Jkt8RBs4AsFnl5FmzR2tZ16B0"
}

Response
{
  "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: email

10018 400 (BAD REQUEST)

Failed to re-send verification email

Parameter missing: url

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 email_verified set to true


Forgot Password

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.

email Body String

The email of the User who has forgotten their password.


Sample Request Body
{
    "url" : "https://www.yoursite.com/password-reset-page",
    "email" : "john.doe@test.com"
}

Response
{
  "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: email

10010 400 (BAD REQUEST)

Failed to send forgot password link

Parameter missing: url

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

Key Concepts: User Password Management

Reset User Password

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 id of the User whose email is being reset by calling this function.

secret Body String

The secret string sent by the Crowd Valley Back Office to the User by email, after calling POST /public/forgotPassword.

password Body String

The User's new password.

password_confirm Body String

Confirmation of the User's new password.


Sample Request Body
{
    "user_id" : "1000",
    "secret" : "5vnhfv2Afrz13ZctbJ0PrJrhs",
    "password" : "NewPassword123!",
    "password_confirm" : "NewPassword123!"
}

Response
{
  "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 secret parameter. Please check that you are correctly parsing the secret string from the link sent in the User\'s email.

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: user_id

10006 400 (BAD REQUEST)

Failed to reset password

Parameter missing: secret

10007 400 (BAD REQUEST)

Failed to reset password

Parameter missing: password

10008 400 (BAD REQUEST)

Failed to reset password

Parameter missing: password_confirm

Key Concepts: User Password Management

Newsletter Sign Up

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.

email Body String

The email address of the User or website visitor who wants to sign up to a newsletter.


Sample Request Body
{
    "email" : "john.doe@test.com"
}

Response
{
  "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

Key Concepts: Unauthenticated Users

View Global Constants

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.

Response
{
  "outcome": "success",
  "data": {
    "key": "value"
  },
  "status": 200
}

View Approved Applications Beta

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.

Response
{
  "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
}

Authenticate

Log in

GET https://api.sandbox.crowdvalley.com/v1/{network}/authenticate

Log in as a named User in your network.

Response
{
  "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
}

Key Concepts: Starter Functions

Social

Get a Facebook Login Link

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


Response
{
  "outcome": "success",
  "data": {
    "url": "URL for logging in using a Facebook account"
  },
  "status": 200
}

Key Concepts: Single Sign On

Get a Twitter Login Link

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


Response
{
  "outcome": "success",
  "data": {
    "url": "URL for logging in using a Twitter account"
  },
  "status": 200
}

Key Concepts: Single Sign On

Get a LinkedIn Login Link

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


Response
{
  "outcome": "success",
  "data": {
    "url": "URL for logging in using a LinkedIn account"
  },
  "status": 200
}

Key Concepts: Single Sign On

Log in using Facebook

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


Sample Request Body
{
    "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"
}

Response
{
  "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
}

Key Concepts: Single Sign On

Log in using Twitter

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


Sample Request Body
{
    "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"
}

Response
{
  "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
}

Key Concepts: Single Sign On

Log in using LinkedIn

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


Sample Request Body
{
    "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"
}

Response
{
  "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
}

Key Concepts: Single Sign On

Self

Logged-in user's account information

GET https://api.sandbox.crowdvalley.com/v1/{network}/self

Populate information on an user's private account page.

Response
{
  "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)",
				"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)",
					"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 = Crowd Valley 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
}

Key Concepts: Starter Functions

Example Front-End Screenshots


Logged-in User's Investment Statistics

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:

  1. Find all Settled Investments made by the logged-in User
  2. For all Payouts for each Investment where Payout > payout_type == 0 (Dividend), find all Transactions for each Payout where Transaction > payment_status == 1 (Paid)
  3. Sum the total of all of those Transactions' transaction_amount values and return it

The 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:

  1. Find all Settled Investments made by the logged-in User
  2. For all Payouts for each Investment where Payout > payout_type == 0 (Dividend)
  3. Sum the total of all of those Transactions' 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

Response
{
    "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
}

Key Concepts: Share Registries

Logged-in User's Portfolio Beta

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

Response
{
    "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
}

Key Concepts: Share Registries

Update the logged-in user's information

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 id of the address in the API call. If you do not include the Address id parameter then this will create an additional Address for the User

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 id of the Bank Account in the API call. If you do not include the Bank Account id parameter then this will create an additional Bank Account for the User

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 id of a Document record that holds the User's profile image

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


Sample Request Body
{
    "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"   
}

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Key Concepts: Starter Functions

Example Front-End Screenshots


Accept End User Terms and Conditions

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.

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Key Concepts: User Onboarding

Reset Accept End User Terms and Conditions

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.

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Key Concepts: User Onboarding

Resend Verification Email

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


Sample Request Body
{
    "url" : "https://www.yoursite.com/verify-email"
}

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User who re-sent the verification email"
  },
  "status": 200
}

Key Concepts: Starter Functions

Change Password

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


Sample Request Body
{
    "current_password" : "Password123!",
    "new_password" : "NewPassword123!",
    "new_password_confirm" : "NewPassword123!"
}

Response
{
  "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
}


Change Email

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


Sample Request Body
{
    "verify_email_url" : "https://www.your-site.com/verify-email",
    "new_email" : "newemail@test.com",
    "new_email_confirm" : "newemail@test.com"
}

Response
{
  "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
}

Approve User

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:

  1. term_service_accepted
  2. registration_complete
  3. 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.

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Key Concepts: User Onboarding

Mark Registration Complete

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.

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Key Concepts: User Onboarding

Block User

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


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "user_access_denied_log_id": "A Unique Identifier for the audit record showing that the User has been blocked"
  },
  "status": 200
}

Key Concepts: Blocking Users

User's Organizations

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.

Response
{
  "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
}

Key Concepts: Filtering and Sorting

User's Offerings

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.

Response
{
  "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
}


User's Investments

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.

Response
{
  "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
}

Key Concepts: Starter Functions

Example Front-End Screenshots


User's Payouts

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.

Response
{
  "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
}

User's Internal Wallets

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.

Response
{
  "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
}

User's Capitalizations Beta

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.

Response
{
  "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
}

Key Concepts: Share Registries

Create a new internal Wallet for the logged-in User

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


Sample Request Body
{
	"currency" : "USD"
}

Response
{
  "outcome": "success",
  "data": {
    "wallet_id": "A Unique Identifier for the Wallet"
  },
  "status": 200
}

Retrieve a given internal Wallet

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.

Response
{
  "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
}

User's Documents

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.

Response
{
  "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
}

Key Concepts: Starter Functions

Add a new User Document

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


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "document_id": "Unique Identifier for the Document"
  },
  "status": 200
}

Key Concepts: Starter Functions

User's Invitations

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.

Response
{
  "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
}

Create a new Invitation

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

email 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


Sample Request Body
{
    "email" : "john.doe@test.com",
    "given_name" : "John",
    "family_name" : "Doe",
    "organization_name" : "JD, Inc"
}

Response
{
  "outcome": "success",
  "data": {
    "invitation_id": "Unique Identifier for the Invitation"
  },
  "status": 200
}

Retrieve an Invitation

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.

Response
{
  "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 My Account

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.

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}

Create a new Application for the logged-in User Beta

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


Sample Request Body
{
	"life_cycle_stage" : "0",
	"investment_amount" : "10000"
}

Response
{
  "outcome": "success",
  "data": {
    "application_id": "A Unique Identifier for the Application"
  },
  "status": 200
}

Users

Register a new User

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

email 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 id of the address in the API call. If you do not include the Address id parameter then this will create an additional Address for the User

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 id of the Bank Account in the API call. If you do not include the Bank Account id parameter then this will create an additional Bank Account for the User

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 id of a Document record that holds the User's profile image

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


Sample Request Body
{
    "email" : "newuser@test.com",
    "password" : "Password123!",
    "url" : "https://www.yoursite.com/verify-email"
}

Response
{
  "outcome": "success",
  "data": {
    "user_id": "A Unique Identifier for the User"
  },
  "status": 200
}


Example Front-End Screenshots


View Users (logged in)

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.

Response
{
  "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
}

Key Concepts: Filtering and Sorting

View a User (logged in)

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 id of the User


Response
{
  "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
}

View a User's Offerings

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 id of the User


Response
{
  "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
}

Key Concepts: Filtering and Sorting

View a User's Investments

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 id of the User


Response
{
  "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
}

Key Concepts: Filtering and Sorting

Organizations

Create a new Organization

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

facebook 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

linkedin Body String

The Organization's LinkedIn account page

location Body String

The Organization's location

logo Body Integer

The id of a Document record that holds the Organization's logo image

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

twitter 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


Sample Request Body
{
    "display_name": "My Organization",
    "address" : { "building" : "One Market Plaza", "street_address" : "Spear Tower", "city" : "San Francisco" },
    "visibility" : "1"   
}

Response
{
  "outcome": "success",
  "data": {
    "organization_id": "A Unique Identifier for the new Organization"
  },
  "status": 200
}


View Organizations (logged in)

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.

Response
{
  "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
}

Key Concepts: Filtering and Sorting

View an Organization (logged in)

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 id of the Organization


Response
{
  "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
}

Update an Organization

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 id of the Organization

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

facebook 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

linkedin 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 id of a Document record that holds the Organization's logo image

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

twitter 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


Sample Request Body
{
    "brief_desc" : "New Brief Description"
}

Response
{
  "outcome": "success",
  "data": {
    "organization_id": "A Unique Identifier for the Organization"
  },
  "status": 200
}

Key Concepts:

Add a User to an Organization

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 id of the Organization

user_id Path Integer

The id of the User


Response
{
  "outcome": "success",
  "data": [],
  "status": 200
}

Key Concepts: Organization Members

Remove a User from an Organization

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 id of the Organization

user_id Path Integer

The id of the User


Response
{
  "outcome": "success",
  "data": {
    "org_member_id deleted": "A Unique Identifier for the User who has been removed from the Organization"
  },
  "status": 200
}

Key Concepts: Organization Members

View an Organization's Capitalizations Beta

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 id of the Organization


Response
{
  "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
}

Key Concepts: Share Registries

Create a new Capitalization Beta

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 id of the Organization

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 id of the User who currently owns this Capitalization

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


Sample Request Body
{
    "number_of_shares": "100",
    "price_per_share": "1",
    "owner_id" : "1098",
    "life_cycle_stage" : "1",
    "capitalization_type" : "0"
}

Response
{
  "outcome": "success",
  "data": {
    "capitalization_id": "Unique identifier for this Capitalization"
  },
  "status": 200
}

Key Concepts: Share Registries

View an Organization's Offerings

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 id of the Organization


Response
{
  "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
}


Create a new Offering

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 id of the Organization

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

Theid of a secondary offering's original Offering

term Body Integer

The loan term of the Offering

valuation Body Decimal

The current valuation of the Offering


Sample Request Body
{
	"funding_goal" : "50000",
	"is_secondary_offering" : "1",
	"primary_offering_id" : "1000",
	"num_of_shares" : "50000",
	"price_per_share" : "1"
}

Response
{
  "outcome": "success",
  "data": {
    "offering_id": "A Unique Identifier for the new Offering"
  },
  "status": 200
}


Example Front-End Screenshots


View an Organization's Documents

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 id of the Organization


Response
{
  "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
}

Add a Document to an Organization

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 id of the Organization

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


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "document_id": "A Unique Identifier for the new Document"
  },
  "status": 200
}

Capitalizations

View a Capitalization Beta

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 id of the Capitalization


Response
{
  "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
}

Key Concepts: Share Registries

Update a Capitalization Beta

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 id of the Capitalization

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 id of the User who currently owns this Capitalization

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


Sample Request Body
{
    "price_per_share": "1.10"
}

Response
{
  "outcome": "success",
  "data": {
    "capitalization_id": "Unique identifier for this Capitalization"
  },
  "status": 200
}

Key Concepts: Share Registries

View a Capitalization's Change Log Beta

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 id of the Capitalization


Response
{
  "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
}

Key Concepts: Share Registries

Split a Capitalization Beta

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 id of the Capitalization

capitalizations Body Array

The parameters of the child Capitalizations


Sample Request Body
[
	{
    	"number_of_shares": "40", 
    	"price_per_share" : "1.50"
   	},
   	{
	"number_of_shares": "60", 
	"price_per_share" : "2.50"    		
    }
]

Response
{
  "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
}

Key Concepts: Share Registries

Merge Capitalizations Beta

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:

  • Capitalization A with number_of_shares = 100 and price_per_share = 1.00
  • Capitalization B with number_of_shares = 100 and price_per_share = 2.00

will generate:

  • Capitalization C with number_of_shares = 200 and price_per_share = 1.50

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 id of the Capitalization to be merged

capitalization_ids Body Array of Integers

The id of each Capitalization to be merged with the Capitalization in the request URL


Sample Request Body
{
    "capitalization_ids": "[100, 101]"
}

Response
{
  "outcome": "success",
  "data": {
    "capitalization_id": "Unique identifier for the child Capitalization"
  },
  "status": 200
}

Key Concepts: Share Registries

Offerings

View Offerings (logged in)

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.

Response
{
  "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
}


Example Front-End Screenshots


View an Offering (logged in)

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:

  • Admin Users will be able to retrieve data on any Offering in their network by specifying its id and calling this function.
  • VIP Users will be able to retrieve data on any Offering whose life_cycle_stage is Restricted, Published, Live, Closing or Settled
  • Other non-Admin and non-VIP Users will be able to retrieve data on any Offering whose life_cycle_stage is Published, Live, Closing or Settled but not Offerings that are Restricted

Note 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 id of the Offering


Response
{
  "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
}


Example Front-End Screenshots


Update an Offering

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 id of the Offering

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

Theid of a secondary offering's original Offering

term Body Integer

The loan term of the Offering

valuation Body Decimal

The current valuation of the Offering


Sample Request Body
{
    "credit_score": "A+"
}

Response
{
  "outcome": "success",
  "data": {
    "offering_id": "A Unique Identifier for the Offering"
  },
  "status": 200
}

Cancel an Offering

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 id of the Offering


Response
{
  "outcome": "success",
  "data": {
    "offering_id": "A Unique Identifier for the Offering"
  },
  "status": 200
}

Key Concepts: The Offering Lifecycle

View all Investments for an Offering

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 id of the Offering

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


Response
{
  "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
}

Key Concepts: The Investment Lifecycle

Make a new Investment for an Offering

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 id of the Offering


Sample Request Body
{
    "investment_amount": "10000"
}

Response
{
  "outcome": "success",
  "data": {
    "investment_id": "A Unique Identifier for the new Investment"
  },
  "status": 200
}


Example Front-End Screenshots


View all Deal Rooms for an Offering

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.

Response
{
  "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
}

Key Concepts: Deal Rooms

Create a new Deal Room for an Offering

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.

Response
{
  "outcome": "success",
  "data": {
    "deal_room_id": "A Unique Identifier for the Deal Room"
  },
  "status": 200
}

Key Concepts: Deal Rooms

Create a new Bulletin for an Offering

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 id of the Offering

title Body String

The title of the Bulletin

body Body String

The body content of the Bulletin


Sample Request Body
{
    "title" : "News story",
    "body" : "Great news about this Offering"
}

Response
{
  "outcome": "success",
  "data": {
    "bulletin_id": "A Unique Identifier for the new Bulletin"
  },
  "status": 200
}

Key Concepts:

View an Offering's Bulletins

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 id of the Offering


Response
{
  "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
}

View an Offering's Documents

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 id of the Offering


Response
{
  "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
}

Add a Document to an Offering

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 id of the Offering

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


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "document_id": "A Unique Identifier for the new Document"
  },
  "status": 200
}

Key Concepts:

View all Payout Schedules for an Offering

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 id of the Offering


Response
{
  "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
}

Create a Payout Schedule for an Offering

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 id of the Offering

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 GET self/stats function: Dividend = 0; Capital Gain = 1; Loan Repayment = 2.

minimum_payment Body Decimal

The minimum amount required to settle this Payout

additional_type Body String

An additional type or category for the Payout


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "payout_id": "A Unique Identifier for the new Payout"
  },
  "status": 200
}

Create multiple Payout Schedule items for an Offering Beta

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 id of the Offering

payouts Body Array of Payouts

A list of Payouts to be created


Sample Request Body
{
   "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"
	}
   ]
}

Response
{
  "outcome": "success",
  "data": {
    "payout_id": "A Unique Identifier for the new Payout"
  },
  "status": 200
}

Deal Rooms

View all forum Topics for a Deal Room

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.

Response
{
  "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
}

Key Concepts: Deal Rooms

Create a new forum Topic in a Deal Room

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 id of the Deal Room

title Body String

The title of the Topic

body Body String

The content of the Topic


Sample Request Body
{
    "title" : "The title of the Topic",
    "body" : "The content of the Topic"
}

Response
{
  "outcome": "success",
  "data": {
    "topic_id": "A Unique Identifier for the Topic"
  },
  "status": 200
}

Key Concepts: Deal Rooms

Topics

View all forum Posts for a Topic

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 id of the Topic


Response
{
  "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
}

Key Concepts: Deal Rooms

Create a new forum Post for a Topic

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 id of the Topic

body Body String

The content of the Post


Sample Request Body
{
    "body" : "The content of the Post"
}

Response
{
  "outcome": "success",
  "data": {
    "topic_id": "A Unique Identifier for the Topic"
  },
  "status": 200
}

Key Concepts: Deal Rooms

Posts

View a Post

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 id of the Post


Response
{
  "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
}

Key Concepts: Deal Rooms

View all Comments for a Post

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 id of the Post


Response
{
  "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
}

Key Concepts: Deal Rooms

Create a new Comment for a Post

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 id of the Post


Sample Request Body
{
    "body" : "Comment about this post"
}

Response
{
  "outcome": "success",
  "data": {
    "comment_id": "Unique Identifier for the Comment"
  },
  "status": 200
}

Key Concepts: Deal Rooms

Investments

View an Investment

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 id of the Investment


Response
{
  "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
}


View an Investment's Documents

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 id of the Investment


Response
{
  "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
}

Add a Document to an Investment

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:

  • The User who made the Investment
  • A member of the Organization for whose Offering this Investment was made
  • An Admin User
Parameter Required Type Format Description
network Path String

The name of your network

investment_id Path Integer

The id of the Investment

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


Response
{
  "outcome": "success",
  "data": {
    "document_id": "A Unique Identifier for the new Document"
  },
  "status": 200
}


View all Payout Schedules for an Investment

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 id of the Investment


Response
{
  "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
}

Create a Payout Schedule for an Investment

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 id of the Investment

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 GET self/stats function: Dividend = 0; Capital Gain = 1; Loan Repayment = 2.

minimum_payment Body Decimal

The minimum amount required to settle this Payout

additional_type Body String

An additional type or category for the Payout


Sample Request Body
{
    "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"
}

Response
{
  "outcome": "success",
  "data": {
    "payout_id": "A Unique Identifier for the new Payout"
  },
  "status": 200
}

Create multiple Payout Schedule records for an Investment Beta

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 id of the Investment

payouts Body Array of Payouts

A list of Payouts to be created


Sample Request Body
{
   "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"
	}
   ]
}

Response
{
  "outcome": "success",
  "data": {
    "payout_id": "A Unique Identifier for the new Payout"
  },
  "status": 200
}

Schedules

View a Payout Schedule record

GET https://api.sandbox.crowdvalley.com/v1/{network}/payouts/{payout_id}

Information about this Payout Schedule record.

Response
{
  "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
}

Update a Payout Schedule record

PATCH https://api.sandbox.crowdvalley.com/v1/{network}/payouts/{payout_id}

Update this Payout Schedule record.

Response
{
  "outcome": "success",
  "data": {
    "payout_id": "Unique identifier for this Payout"
  },
  "status": 200
}

View a Payout Schedule record's Transactions

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.

Response
{
  "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
}

Transactions

View Payment Transaction

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 id of the Transaction


Response
{
  "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
}

Update Payment Transaction

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 id of the Transaction

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


Sample Request Body
{
    "payment_status" : "2"
}

Response
{
  "outcome": "success",
  "data": {
    "transaction_id": "A Unique Identifier for the Transaction"
  },
  "status": 200
}

Wallets

Create a new Wallet Transaction

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 id of the Wallet

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


Sample Request Body
{
    "transaction_amount" : "1000",
    "transaction_description" : "Credit bonus",
    "transaction_currency" : "USD",
    "payment_status" : "1",
    "payment_service" : "1"
}

Response
{
  "outcome": "success",
  "data": {
    "transaction_id": "A Unique Identifier for the new Transaction"
  },
  "status": 200
}

Documents

View a Document

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 id of the Document


Response
{
  "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 a Document

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 id of the Document


Response
{
  "outcome": "success",
  "data": {
    "document_id": "A Unique Identifier for the Document"
  },
  "status": 200
}

Stripe

Retrieve Stripe credentials Beta

GET https://api.sandbox.crowdvalley.com/v1/{network}/stripe

Retrieve your network's publishable key for accessing the Stripe API.

Response
{
  "outcome": "success",
  "data": {
    "publishable_key": "Key to use with accessing the Stripe API"
  },
  "status": 200
}

Make a Payment through Stripe Beta

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:

  • card[number] (e.g. 4242424242424242)
  • card[exp_month] (e.g. 12)
  • card[exp_year] (e.g. 2022)
  • card[cvc] (e.g. 000)

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.

Response
{
  "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
}

Mangopay

Register User as a 'Natural User'

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:

  • process payments
  • transfer e-money between wallets
  • withdraw e-money from a wallet
  • create wallets, etc.

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.

Response
{
  "outcome": "success",
  "data": {
    "mangopay_id": "The User's Mangopay ID"
  },
  "status": 200
}

Key Concepts: Mangopay

Register Organization as a 'Legal User'

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:

  • process payments
  • transfer e-money between wallets
  • withdraw e-money from a wallet
  • create wallets, etc.

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 id of the Organization


Response
{
  "outcome": "success",
  "data": {
    "mangopay_id": "The Organization's Mangopay ID"
  },
  "status": 200
}

Key Concepts: Mangopay

Create a Mangopay Wallet for a User

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.

Response
{
  "outcome": "success",
  "data": {
    "mangopay_wallet_id": "Unique identifier for the logged-in User's new Mangopay Wallet"
  },
  "status": 200
}

Key Concepts: Mangopay

Create a Mangopay Wallet for an Organization

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.

Response
{
  "outcome": "success",
  "data": {
    "mangopay_wallet_id": "Unique identifier for the Organization's new Mangopay Wallet"
  },
  "status": 200
}

Key Concepts: Mangopay

Create a Mangopay Wallet for an Offering

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.

Response
{
  "outcome": "success",
  "data": {
    "mangopay_wallet_id": "Unique identifier for the Offering's new Mangopay Wallet"
  },
  "status": 200
}

Key Concepts: Mangopay

Retrieve User's Mangopay Wallets

GET https://api.sandbox.crowdvalley.com/v1/{network}/self/mangopay/wallets

View a list of all the logged-in User's Mangopay Wallets.

Response
{
  "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
}

Key Concepts: Mangopay

Retrieve Organization's Mangopay Wallets

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 id of the Organization (Legal User). Use the Crowd Valley id not the Organization's mangopay_user_id


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve a User's Mangopay Wallet

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


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve an Organization's Mangopay Wallet

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 id of the Organization

wallet_id Path Integer

The Mangopay identifier of the Wallet


Response
{
  "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
}

Key Concepts: Mangopay

Mangopay User KYC Check

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


Response
{
  "outcome": "success",
  "data": {
    "kyc_id": "Unique Identifier for the Mangopay KYC Check"
  },
  "status": 200
}

Key Concepts: Mangopay KYC/AML

Mangopay Organization KYC Check

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:

  • IDENTITY_PROOF: ID of the User making this API call, who is duly empowered to act on behalf of the legal entity
  • REGISTRATION_PROOF: An extract from the relevant register of commerce issued within the last three months
  • ARTICLES_OF_ASSOCIATION: The business statute - a formal memorandum containing the Organization's business name, activity, registered address, and shareholding
  • SHAREHOLDER_DECLARATION: A document showing the Organization's shareholders

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 id of the Organization (Legal User). Use the Crowd Valley id not the Organization's mangopay_user_id

tag Body String

The tag of the Organization's Document that should be sent to Mangopay for KYC purposes. It must be one of: IDENTITY_PROOF, REGISTRATION_PROOF, ARTICLES_OF_ASSOCIATION, or SHAREHOLDER_DECLARATION


Sample Request Body
{
    "tag" : "SHAREHOLDER_DECLARATION"
}

Response
{
  "outcome": "success",
  "data": {
    "kyc_id": "Unique Identifier for the Mangopay KYC Check"
  },
  "status": 200
}

Key Concepts: Mangopay KYC/AML

Generate a User Payment Card Registration link

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:

  1. Generate a 'card registration' link by implementing POST /self/mangopayCardRegister
  2. The API will return fields id, access_key, preregistration_data and a card_registration_url
  3. Send in a form, such as the one provided below, the values of 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 attribute
  4. Complete the card registration process by implementing POST /self/mangopayCards, which has two required parameters: card_registration_id and data
  5. The card_registration_id field must contain the id of the Card Registration generated by the initial call to POST /self/mangopayCardRegister in step 1
  6. The data field must contain the data string returned by the Card Registration Server in step 3

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

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


Sample Request Body
{
    "currency" : "GBP"
}

Response
{
  "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
}

Key Concepts: Mangopay

Generate an Organization Payment Card Registration link

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:

  1. Generate a 'card registration' link by implementing POST /organizations/{org_id}/mangopay/cards/register
  2. The API will return fields id, access_key, preregistration_data and a card_registration_url
  3. Send in a form, such as the one provided below, the values of 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 attribute
  4. Complete the card registration process by implementing POST /organizations/{org_id}/mangopay/cards, which has two required parameters: card_registration_id and data
  5. The 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 1
  6. The data field must contain the data string returned by the Card Registration Server in step 3

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

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


Sample Request Body
{
    "currency" : "GBP"
}

Response
{
  "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
}

Key Concepts: Mangopay

Register a Payment Card for a User

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:

  1. Generate a 'card registration' link by implementing POST /self/mangopayCardRegister
  2. The API will return fields id, access_key, preregistration_data and a card_registration_url
  3. Send in a form, such as the one provided below, the values of 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 attribute
  4. Complete the card registration process by implementing POST /self/mangopayCards, which has two required parameters: card_registration_id and data
  5. The card_registration_id field must contain the id of the Card Registration generated by the initial call to POST /self/mangopayCardRegister in step 1
  6. The data field must contain the data string returned by the Card Registration Server in step 3

When testing in a sandbox environment you can use these Mangopay test cards for transactions under €100:

  • Card Number: 4970100000000154 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334422 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334406 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334414 / Expiry: Any date in the future / CVV: 123

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 id of the Card Registration object generated by POST /self/mangopayCardRegister

data Body String

The value of the data parameter returned by the Mangopay Card Registation server


Sample Request Body
{
    "data" : "long_string_provided_by_card_registration_server",
    "card_registration_id" : "12345678"
}

Response
{
  "outcome": "success",
  "data": {
    "card_id": "Unique Identifier for the Mangopay Tokenized Card"
  },
  "status": 200
}

Key Concepts: Mangopay

Register a Payment Card for an Organization

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:

  1. Generate a 'card registration' link by implementing POST /organizations/{org_id}/mangopay/cards/register
  2. The API will return fields id, access_key, preregistration_data and a card_registration_url
  3. Send in a form, such as the one provided below, the values of 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 attribute
  4. Complete the card registration process by implementing POST /organizations/{org_id}/mangopay/cards, which has two required parameters: card_registration_id and data
  5. The 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 1
  6. The data field must contain the data string returned by the Card Registration Server in step 3

When testing in a sandbox environment you can use these Mangopay test cards for transactions under €100:

  • Card Number: 4970100000000154 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334422 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334406 / Expiry: Any date in the future / CVV: 123
  • Card Number: 4970101122334414 / Expiry: Any date in the future / CVV: 123

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 id of the Card Registration object generated by POST /self/mangopayCardRegister

data Body String

The value of the data parameter returned by the Mangopay Card Registation server


Sample Request Body
{
    "data" : "long_string_provided_by_card_registration_server",
    "card_registration_id" : "12345678"
}

Response
{
  "outcome": "success",
  "data": {
    "card_id": "Unique Identifier for the Mangopay Tokenized Card"
  },
  "status": 200
}

Key Concepts: Mangopay

Retrieve a User's Mangopay Cards

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


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve an Organization's Mangopay Cards

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 id of the Organization


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve information about a User's Mangopay Card

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)


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve information about an Organization's Mangopay Card

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 id of the Organization

card_id Path String

The Mangopay Unique Identifier for the Card (not the Crowd Valley database ID)


Response
{
  "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
}

Key Concepts: Mangopay

Add Funds from a User's Registered Card to a Mangopay Wallet

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


Sample Request Body
{
    "amount" : "10000",
    "return_url" : "http://www.yoursite.com/card-return",
    "currency" : "GBP",
    "fee_amount" : "100"
}

Response
{
  "outcome": "success",
  "data": [],
  "status": 200
}

Key Concepts: Mangopay

Add Funds from an Organization's Card to a Mangopay Wallet

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 id of the Organization

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


Sample Request Body
{
    "amount" : "10000",
    "return_url" : "http://www.yoursite.com/card-return",
    "currency" : "GBP",
    "fee_amount" : "100"
}

Response
{
  "outcome": "success",
  "data": [],
  "status": 200
}

Key Concepts: Mangopay

Add Funds from a User's Unregistered Card to a Mangopay Wallet

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


Sample Request Body
{
    "amount" : "10000",
    "currency" : "GBP",
    "fee_amount" : "100",
    "card_type" : "CB_VISA_MASTERCARD",
    "callback_url" : "https://yourdomain.com/callback"
}

Response
{
  "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
}

Key Concepts: Mangopay

Add Funds to a User's Mangopay Wallet by Bank Wire

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:

  • Address: 1 CHURCHILL PLACE Leicesterhire, LE87 2BB, Leicester
  • Sort Code: 20-00-00
  • Account: 63956474
  • IBAN: GB09 BARC 2000 0063 9564 74
  • BIC: BARCGB22
Parameter Required Type Format Description
network Path String

The name of your network

user_id Path String

The id of the User making the transfer. Use the Crowd Valley id not the User's mangopay_user_id

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


Sample Request Body
{
    "amount" : "10000",
    "currency" : "GBP",
    "fee_amount" : "100"
}

Response
{
  "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
}

Key Concepts: Mangopay

Add Funds to an Organization's Mangopay Wallet by Bank Wire

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:

  • Address: 1 CHURCHILL PLACE Leicesterhire, LE87 2BB, Leicester
  • Sort Code: 20-00-00
  • Account: 63956474
  • IBAN: GB09 BARC 2000 0063 9564 74
  • BIC: BARCGB22
Parameter Required Type Format Description
network Path String

The name of your network

organization_id Path String

The id of the Organization making the transfer. Use the Crowd Valley id not the Organization's mangopay_user_id

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


Sample Request Body
{
    "amount" : "10000",
    "currency" : "GBP",
    "fee_amount" : "100"
}

Response
{
  "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
}

Key Concepts: Mangopay

Make a Transfer to an Organization's Wallet

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 10000
  • currency, which should be the currency code of the User's Wallet
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

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


Sample Request Body
{
    "amount" : "10000",
    "currency" : "GBP",
    "fee_amount" : "100",
    "target_wallet_id" : "12876543"
}

Response
{
  "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
}

Key Concepts: Mangopay

Register a User's Bank Account

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:

  • BIC & IBAN
  • Local UK format

Please get in touch with Crowd Valley to request any of the following formats:

  • Local US format
  • Local CA format
  • Other local formats (unspecified but different from the previous)

When registering a BIC/IBAN account, there are four required parameters for this function:

  • IBAN - the Bank Account's IBAN code
  • BIC - the Bank Account's BIC code
  • owner_name - the full name of the User who owns the Bank Account
  • owner_address - the full address of the User who owns the Bank Account

Please 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 Number
  • sort_code - the Bank Account's Sort Code
  • owner_name - the full name of the User who owns the Bank Account
  • owner_address - the full address of the User who owns the Bank Account

Similarly 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


Sample Request Body
{
    "type" : "IBAN",
    "BIC" : "ABCDGB12",
    "IBAN" : "GB32ESSE40486562136016",
    "owner_address" : "1 Oxford Street, London, WC1A 1AA",
    "owner_name" : "John Doe"
}

Response
{
  "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
}

Key Concepts: Mangopay

Register a Organization's Bank Account

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:

  • BIC & IBAN
  • Local UK format

Please get in touch with Crowd Valley to request any of the following formats:

  • Local US format
  • Local CA format
  • Other local formats (unspecified but different from the previous)

When registering a BIC/IBAN account, there are five required parameters for this function:

  • type - IBAN
  • IBAN - the Bank Account's IBAN code
  • BIC - the Bank Account's BIC code
  • owner_name - the full name of the User who owns the Bank Account
  • owner_address - the full address of the User who owns the Bank Account

Please 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 - GB
  • account_number - the Bank Account's Account Number
  • sort_code - the Bank Account's Sort Code
  • owner_name - the full name of the User who owns the Bank Account
  • owner_address - the full address of the User who owns the Bank Account

Similarly 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 id of the Organization. Use the Crowd Valley id not the Organization's mangopay_user_id

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


Sample Request Body
{
    "BIC" : "ABCDGB12",
    "IBAN" : "GB32ESSE40486562136016",
    "owner_address" : "1 Oxford Street, London, WC1A 1AA",
    "owner_name" : "John Doe"
}

Response
{
  "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
}

Key Concepts: Mangopay

Get a User's Bank Accounts

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


Response
{
  "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
}

Key Concepts: Mangopay

Get a User's Bank Account information

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


Response
{
  "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
}

Key Concepts: Mangopay

Get an Organization's Bank Accounts

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


Response
{
  "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
}

Key Concepts: Mangopay

Get an Organization's Bank Account information

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


Response
{
  "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
}

Key Concepts: Mangopay

Make a Payout to a User's Bank Account

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 POST /users/{user_id}/bankaccounts/{type}

currency Body Currency Code

The currency of the transfer

fees_amount Body Integer

The amount of fees taken by your platform from this transaction


Sample Request Body
{
    "amount" : "10000",
    "bank_account_id" : "12345678",
    "currency" : "GBP",
    "fees_amount" : "100"
}

Response
{
  "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
}

Key Concepts: Mangopay

Make a Payout to an Organization's Bank Account

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 id of the Organization making the transfer. Use the Crowd Valley id not the Organization's mangopay_user_id

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


Sample Request Body
{
    "amount" : "10000",
    "bank_account_id" : "12345678",
    "currency" : "GBP",
    "fees_amount" : "100"
}

Response
{
  "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
}

Key Concepts: Mangopay

Retrieve a User Mangopay Wallet's Transaction History

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


Response
{
  "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
}

Key Concepts: Mangopay

Retrieve an Organization Mangopay Wallet's Transaction History

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 id of the Organization

wallet_id Path Integer

The Mangopay identifier of the Wallet


Response
{
  "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
}

Key Concepts: Mangopay

GCEN

Register User as a GCEN Client

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:

  • email
  • honorific_prefix
  • given_name
  • family_name
  • birth_date
  • phone_1
  • address (including at least: building, street_address, city, region, postal_code and country)

In addition the following attributes are sent to GCEN if they are available:

  • birth_place
  • passport_country
  • passport_number
  • passport_expiry
  • tax_id
  • driving_license_number
  • address > sub_building

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


Sample Request Body
{
    "performAML": true
}

Response
{
  "outcome": "success",
  "data": "",
  "status": 200
}

Key Concepts: GCEN

Retrieve GCEN KYC Status

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


Response
{
  "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
}

Key Concepts: GCEN User Onboarding

Retrieve GCEN Balance

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


Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": "The User's GCEN Balance",
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Retrieve GCEN Balance Log

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


Response
{
  "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
}

Key Concepts: GCEN

Retrieve GCEN Running Balance Log

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


Response
{
  "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
}

Key Concepts: GCEN

Request a Withdrawal from the User's GCEN Balance

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.

  • account_number
  • bank_code
  • country_code
  • bene_name (defaults to the User's full_name)
  • bene_ref1 (defaults to 'GCEN Withdrawal')

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


Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": "GCEN Unique Identifier for this transaction",
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Retrieve GCEN Balance for an Offering

GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/gcen/balance

Retrieves the Offering's current GCEN balance.

The Currency of the balance is based on the account that is set up by GCEN before you can add the gcen_client_id to the Offering in the Back Office.

The Offering requires a valid gcen_client_id in order to use this function.

Parameter Required Type Format Description
network Path String

The name of your network

offering_id Path Integer

The Unique Identifier for the Offering


Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": "The User's GCEN Balance",
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Retrieve GCEN Balance Log for an Offering

GET https://api.sandbox.crowdvalley.com/v1/{network}/offerings/{offering_id}/gcen/balanceLog

Retrieves the Offering's GCEN balance log.

The Offering requires a valid gcen_client_id in order to use this function.

Parameter Required Type Format Description
network Path String

The name of your network

offering_id Path Integer

Unique Identifier for the Offering


Response
{
  "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
}

Key Concepts: GCEN

Make a Payment from User's Card to their GCEN Wallet

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/cardPayment

Makes a payment from the User's Credit/Debit Card to their GCEN Wallet.

The User must already have a valid gcen_client_id in order to use this function. This function returns a PaymentUrl parameter which is the URL of a site provided by GCEN where the User can securely enter their card details. This page is typically displayed in an iframe within your site. Users should never need to enter their credit card details on your own site if you are using GCEN's services.

This function has three required parameters: amount, payment_type and url.

The amount is the full amount in the card's currency, for instance 100.00 to represent £100.

The payment_type determines the type of card that the User wishes to use:

  • 1 - Visa (credit)
  • 3 - MasterCard (credit)
  • 114 - Visa (debit)
  • 117 - Maestro (debit)
  • 119 - MasterCard (debit)
  • 122 - Visa Electron(debit)

Note that credit card payments, or payments made in a non-GBP currency incur a 2.6% charge.

Finally the url parameter should contain the page to which the User should be redirected once the payment is complete. This page should implement the POST /self/gcen/confirmCardPayment function.

The function will also register the currency of the card transaction with GCEN. By default the currency will be taken from the currency value of the User's Bank Details. If no Bank Details have been saved for the logged-in User then it will default to GBP.

After implementing this function, you should also implement the POST /self/gcen/confirmCardPayment function using the REF and RETURNMAC values that are returned by POST /self/gcen/cardPayment in order to obtain the final status of the payment, and to show confirmation to the User.

Parameter Required Type Format Description
network Path String

The name of your network

amount Body Decimal

The amount that the User wishes to pay from their card

payment_type Body Integer

The type of payment card that the User wishes to use

url Body String

The page on your site to which the User should be redirected after completing payment

narrative Body String

A custom description that will be returned for this transaction from the Balance Log function


Sample Request Body
{
    "amount": "100.00",
    "payment_type" : "1",
    "url" : "https://www.yoursite.com/handle-gcen-response"
}

Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": {
      "Amount": "The amount that the User wishes to pay from their card",
      "PaymentUrl": "The URL of a site provided by GCEN where the User can securely enter their card details",
      "REF": "A Unique code that allows you to confirm the card payment",
      "RETURNMAC": "A Unique code that allows you to confirm the card payment"
    },
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Confirm a User's Card Payment

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/confirmCardPayment

Check whether a card payment was authorized and payment was successfully taken through the POST /self/gcen/cardPayment function.

This function has two required parameters: REF, RETURNMAC. Both values are returned by the POST /self/gcen/cardPayment function.

Using the return value StatusId you can determine whether the card payment was processed successfully. A StatusId of 0 indicates success.

A StatusId of 10 indicates that the client is over their annual turnover limit and extended client due diligence should be done by implementing POST /self/gcen/submitKycDocument.

The other error cases are as follows:

  • "StatusId": 2001 - Error retrieving order status. Please confirm the REF / RETURNMAC
  • "StatusId": 2002 - Your payment could not be authorised. The usual cause is due to using incorrect card details. If, after verifying your details, the problem persists, please consider using a different card to try again.
  • "StatusId": 2020 - PENDING AT MERCHANT: The Hosted Merchant Link transaction is waiting for the consumer to be redirected by the merchant to WebCollect.
  • "StatusId": 2025 - PENDING AT GLOBALCOLLECT: The Hosted Merchant Link transaction is waiting for the consumer to enter missing data on the payment pages of GlobalCollect.
  • "StatusId": 2030 - PENDING AT GLOBALCOLLECT: The Hosted Merchant Link transaction is waiting for the consumer to be redirected by WebCollect to the payment pages of the bank (optionally after the completion of missing data).
  • "StatusId": 2050 - PENDING AT BANK: The payment request and consumer have been forwarded to the payment pages of the bank.
  • "StatusId": 2055 - PENDING AT CONSUMER: The consumer received all payment details to initiate the transaction. The consumer must go to the (bank) office to initiate the payment.
  • "StatusId": 2060 - NOT ENROLLED: The consumer is not enrolled for 3D Secure authentications.
  • "StatusId": 2065 - PENDING PAYMENT (CONSUMER AT BANK): The consumer is at an office to initiate a transaction. The status is used when the supplier polls the WebCollect database to verify if a payment on an order is (still) possible.
Parameter Required Type Format Description
network Path String

The name of your network

REF Body String

A Unique code that allows you to confirm the card payment

RETURNMAC Body String

A Unique code that allows you to confirm the card payment


Sample Request Body
{
    "REF": "000000772100000340380000100001",
    "RETURNMAC" : "1VziAD/LsxuSoUY2R4CrRctYyE5WqPFD1moRXqzvQFo="
}

Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": "A Unique Identifier for the card transaction",
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Make a Payment from User's Bank Account to their GCEN Wallet

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/bankTransfer

Instructs GCEN of an impending bank transfer deposit from the User and provides the bank details and reference number necessary for the User to make the payment.

Note that this function does not facilitate any actual transfer of funds: it simply alerts GCEN that an incoming payment is due from the User, and provides the User with all the details they need in order to make a payment from their Bank Account. The User will make the payment themselves, and this transaction will not take place on your platform.

The User must already have a valid gcen_client_id in order to use this function. The function returns a BankDetails object which contains GCEN's bank account information. The User must provide the correct Reference Number when making the transaction in order to ensure that it is correctly allocated to their account.

This function has one required parameter: amount, which is the full amount in the card's currency, for instance 100.00 to represent £100.

The function will also register the currency of the card transaction with GCEN. By default the currency will be taken from the currency value of the User's Bank Details. If no Bank Details have been saved for the logged-in User then it will default to GBP.

Parameter Required Type Format Description
network Path String

The name of your network

amount Body Decimal

The amount that the User wishes to transfer from their bank account

narrative Body String

A custom description that will be returned for this transaction from the Balance Log function


Sample Request Body
{
    "amount": "100.00"
}

Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "ReturnObject": {
      "BankReference": "The Reference Number that the User should use when making the bank transfer",
      "PaymentAmount": "The amount that the User wishes to transfer to their GCEN wallet",
      "PaymentCurrency": "The currency of the transaction",
      "BankDetails": {
        "AccountHolder": "Global Currency Exchange Network",
        "BankName": "Santander",
        "SwiftCode": "ABBYGB2LXXX",
        "IBAN": "GB47ABBY09022210448391",
        "BankCountry": "United Kingdom",
        "BankAccountNumber": "10448391",
        "SpecialId": "Sort code: 090222"
      }
    },
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Submit a Document for KYC screening by GCEN

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/submitKycDocument

Submit a Document to GCEN in order for the logged-in User to pass GCEN's KYC checks.

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.

The current statuses can be found by implementing the GET /self/gcen function.

The POST /self/gcen/submitKycDocument function has one required parameter: document_id, which must be the id of a Document that is already saved to the User's account. In other words, the Document should be visible to the User through the GET /self/documents function.

Users may submit any number of Documents to GCEN in order to support their KYC application.

GCEN can verify the identity of individuals based on the following documents. One document, from list A, must be a government-issued photo ID. The second document must be no older than 90 days. We are able to accept either scanning or photographs of the documents.

Acceptable Photo IDs

  • Unexpired passport
  • Unexpired UK photo card driving licence
  • National Identity card – in countries where these are issued
  • Firearms certificate or shotgun licence issued by a Police authority
  • Military ID card

Acceptable Proof of address documents

  • Council tax bill / demand letter
  • Notification of entitlement to state / local authority benefit
  • Notification of entitlement to tax credit
  • Notification of entitlement to pension from the DWP
  • Notification of entitlement to educational loan / grant
  • Notification of entitlement to other government / local authority grant
  • HMRC (Inland Revenue) coding / assessment / statement / tax credit
  • Gas, Electricity, water bill (no mobile telephone bills)
  • Bank statement, credit card statement, insurance documents which clearly state the address.

The file format of the uploaded files must be one of the .pdf .jpg, .png, .bmp or .gif file extensions.

Parameter Required Type Format Description
network Path String

The name of your network

document_id Body Integer

The Unique Identifier of the Document that the User wishes to submit for KYC purposes


Sample Request Body
{
    "document_id" : "10000"
}

Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Transfer Funds to an Offering

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/balanceTransferToOffering/{offering_id}

Transfers funds from the logged-in User's GCEN wallet to an Offering's GCEN wallet.

Both the logged-in User and the Offering must have valid gcen_client_id values in order to use this function. Users get a gcen_client_id by implementing POST /self/gcen/register whereas Offerings' gcen_client_id values must be added manually by an Admin User through the Back Office application.

The only required parameter is amount, which is the amount that the User wishes to transfer from their GCEN wallet. There is also an optional narrative attribute, which is saved in GCEN's database and retrieved through GET /self/gcen/balanceLog as a custom description of the transfer, for example, "Investment in Offering X".

In the API response, a StatusId of '10' indicates that the from client is over their annual turnover limit and extended client due diligence should be done by implementing POST /self/gcen/submitKycDocument.

The other possible error cases are as follows: { "StatusId": 1201, "Success": false, "ReturnObject": null, "Message": "The client only has GBP 25 on their GCS balance" }

{ "StatusId": 1200, "Success": false, "ReturnObject": null, "Message": "Client does not have a GCS balance" }

{ "StatusId": 9500, "Success": false, "ReturnObject": [{ "Currency": "GBP", "Total": 12000, "ClientId": 101, "Limit": 7500, "IdChecked": false }], "Message": "The client has exceeded their annual tunover limit." }

Parameter Required Type Format Description
network Path String

The name of your network

offering_id Path Integer

The Offering to which the User wishes to make a payment transfer

narrative Body String

A custom description of the transaction that will be shown on the User's GCEN Balance Log


Sample Request Body
{
    "amount" : "100.00",
    "narrative" : "Investment into Series A of Project Tomorrow"
}

Response
{
  "outcome": "success",
  "data": {
    "StatusId": 0,
    "Success": true,
    "Message": ""
  },
  "status": 200
}

Key Concepts: GCEN

Transfer Funds to another User

POST https://api.sandbox.crowdvalley.com/v1/{network}/self/gcen/balanceTransferToUser/{user_id}

Transfers funds from the logged-in User's GCEN wallet to another User's GCEN wallet, as specified by the user_id parameter, which must be the id of a User on your platform.

Both the logged-in User and the recipient User must have valid gcen_client_id values in order to use this function. Users get a gcen_client_id by implementing POST /self/gcen/register.

The only required parameter is amount, which is the amount that the User wishes to transfer from their GCEN wallet. There is also an optional narrative attribute, which is saved in GCEN's database and retrieved through GET /self/gcen/balanceLog as a custom description of the transfer, for example, "Investment in Offering X".

In the API response, a StatusId of '10' indicates that the from client is over their annual turnover limit and extended client due diligence should be done by implementing POST /self/gcen/submitKycDocument.

The other possible e