Object Data Models


User

The User represents both your end users, such as the investors, fundraisers, brokers or affiliates who use your front-end digital finance marketplace, and your admin users.

Users can be categorized by using the additional_type field in order to distinguish between, for example, borrowers and lenders, or fundraisers and investors. There is no limit to the number of different such categories that you can use.

The User object contains some information that is only accessible to the admin team and to that User when logged in, i.e., personal information such as passport_number or addresses, and other information that is accessible to all Users, such as location or job_title.


Attribute Data Type Description
additional_name String

An additional name for the User, such as a middle name.

additional_type String

An additional type or category for the User. Use this to define categories or groups of Users.

address Address

The User's current address. If the User has multiple addresses then the address field will return the first in the list.

addresses Array of Address

A list of the User's addresses.

affiliate_code String

A code that can be given out by the User to track that User's affiliate activity.

Key Concepts: Affiliates
bank_accounts Array of BankAccount

The User's bank accounts.

biography String

The User's biography.

birth_country String

The User's country of birth.

birth_date Date (Y-m-d)

The User's date of birth.

birth_place String

The User's place of birth.

created_at Date (Y-m-d)

Date on which the User joined your platform.

custom Array of Custom Fields

This attribute holds an array of custom User fields, which can be used to hold any data relating to a User that do not fit the default User object model. You may use up to 100 such fields per User.

Key Concepts: Custom Fields
driving_license_number String

The User's full driving license number.

Key Concepts: KYC/AML
email String

The User's registered email address. The email address can only be changed using POST /self/changeEmail.

email_verified Boolean

Flag to show whether the User has verified their email account. This is calculated based on whether the User has successfully clicked a link in an activation email sent by the Crowd Valley back-end, which must also be verified on your platform's front-end by implementing POST /public/verifyEmail.

Key Concepts: Email Verification
external_reference_id String

An external reference identifier. Use this field if your Users have an existing identifying reference in an existing database.

family_name String

Family name. In the U.S., the last name of a User. This is typically used alongside given_name.

full_name String

The User's full name. This is calculated by taking the User's given_name and family_name attributes.

gbg_pass_id String

The User's last GBGroup AML/KYC Check identifier. This attribute is set by the Crowd Valley back-end if you successfully call the GBGroup ID verification service and the User returns a PASS.

Key Concepts: GBGroup
gcen_client_id String

The User's GCEN Client ID. This is generated by successfully calling the GCEN User Registration function.

Key Concepts:
gender String

The gender of the User. Use 'M' or 'F' to denote gender if the User's gender is required for AML/KYC purposes.

Key Concepts: KYC/AML
given_name String

The User's given name. In the U.S., the first name of a User. This is typically used alongside family_name.

has_been_approved Boolean

Flag to show whether the User has been marked as Approved on your platform. You can approve Users by implementing POST /self/approveUser on your front-end or by using the 'Approve User' action button on the Crowd Valley Back Office application.

Key Concepts: User Onboarding
has_been_blocked Boolean

Flag to show whether the User has been blocked from your platform. You can block Users by implementing POST /self/blockUser on your front-end or by using the 'Block User' action button on the Crowd Valley Back Office application. Users will not be able to log on to your platform whilst they are blocked.

Key Concepts: Blocking Users
honorific_prefix String

An honorific prefix preceding the User's name such as Dr/Mrs/Mr.

honorific_suffix String

An honorific suffix following the User's name such as M.D./PhD/MSCSW.

id Integer

A Unique Identifier for the User. This is generated automatically when the User is first registering using POST /users. The id attribute can never be changed so it can be used as a unique reference for the User on your platform.

image Document

The User's profile image.

income_range String

The User's income range.

info Depreciated Array of Custom Fields

This attribute is depreciated. Please use custom.

is_admin Boolean

Flag to show whether the User has admin rights for your platform.

Key Concepts: Admin Users
is_vip Boolean

Flag to show whether the User has been given 'VIP' status.

Key Concepts: VIP Users
job_title String

The job title of the User (for example, CEO).

last_login_at Date (Y-m-d)

Date on which the User last logged in to your platform. This is calculated as the last date on which the User called the GET /authenticate function to log in.

loanbook_id Integer

If the Offering is part of a Loanbook then this returns the Unique Identifier for that Loanbook.

Key Concepts: Loanbooks
location String

The User's location, e.g. San Francisco.

mangopay_card_id String

A unique identifier for the User's most recently-created Mangopay Card. This field is set when the User successfully calls the Mangopay Card Registration function. If the User registers a second Mangopay Card then the mangopay_card_id will be updated to show the second Card's identifier in place of the first.

Key Concepts: Mangopay
mangopay_user_id String

A unique identifier for the User's Mangopay account. This field is set when the User successfully calls the Mangopay User Registration function.

Key Concepts: Mangopay
nationality Country Code (ISO 3166-1 alpha-2)

The User's nationality, for example, 'US' for the United States of America or 'GB' for the United Kingdom of Great Britain and Northern Ireland.

organizations Array of Organization Membership

A list of Organizations of which the User is a member.

Key Concepts: Organization Members
passport_country Country Code (ISO 3166-1 alpha-2)

The country that issued the User's passport. This field may be used by certain AML/KYC or Identity Verification service providers.

Key Concepts: KYC/AML
passport_expiry Date (Y-m-d)

The expiry date of the User's passport in 'Y-m-d' format, e.g. 2020-12-21. This may be used by certain KYC/AML and Identity Verifiation services.

Key Concepts: KYC/AML
passport_number String

The User's full passport number. This may be used by certain KYC/AML and Identity Verifiation services.

Key Concepts: KYC/AML
password_expired Boolean

Flag to show whether the User's password has expired.

Key Concepts: User Password Management
phone_1 String

The User's primary phone number. If two numbers are required for KYC purposes then use phone_1 to represent the User's mobile number. The phone_1 attribute is also used to determine which number to use when verifying a number using a Multi-Factor Authentication service, in which case you should also include the country code (e.g. +1 or +44) in phone_1.

Key Concepts: KYC/AML
phone_2 String

The User's secondary phone number. If two numbers are required for KYC purposes then use phone_2 to represent the User's landline number.

Key Concepts: KYC/AML
phone_verified Boolean

Flag to show whether the User has verified their phone number using a Multi-Factor Authentication process. This attribute is calculated based on having successfully completed an authentication process that involves sending a verification code by SMS message to their phone and validating the code.

referral_code String

The code that was entered by the User to connect them to another User acting as an affiliate.

Key Concepts: Affiliates
registration_complete Boolean

Flag to show whether the User has completed their registration requirements for this network. This attribute can be edited by implementing POST /self/markRegistrationComplete on your front-end platform or by pressing the 'Mark Registration Complete' action button on the Crowd Valley Back Office application.

Key Concepts: User Onboarding
reyker_id String

A Unique Identifier for the User's Reyker account. This field is set automatically when the User successfully calls the Reyker Registration function.

Key Concepts: Reyker
sector String

The User's industry or sector.

tagline String

A short tagline about the User.

tax_id String

The Tax or Fiscal identifier of the User, e.g. the TIN in the US, the National Insurance Number in the UK, or the CIF/NIF in Spain. This may be used by certain KYC/AML or Identity Verification service providers.

Key Concepts: KYC/AML
term_service_accepted Boolean

Flag to show whether the User has accepted Terms and Conditions for your platform. This can be edited by implementing POST /self/acceptTerms on your platform's front-end.

Key Concepts: User Onboarding
time_zone String

The User's timezone. Format: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

visibility User Visibility Enum

The User's visibility: 0 = Open, 1 = Hidden, 2 = Anonymous. The visibility attribute determines how much information about this User other Users can retrieve through the GET /users function. If a User if Anonymous then their given_name, family_name and full_name will not be returned. If a User is Hidden then no information will be returned.

web_site String

The URL of a reference website that is linked to the User, for example, the User's Wikipedia page or official website.

Organization

The Organization represents the capital raising entity, whether it be a company, a property, a fund, or a project.

An Organization must have at least one User, which by default is the User who created the Organization. An Organization can, however, have multiple Users, in order to represent a team or group.


Attribute Data Type Description
additional_type String

An additional type or category for the Organization. Use this to define categories or groups of Organizations.

address Address

The Organization's address.

alternate_name String

An alternate name for the Organization.

brief_desc String

A brief description of the Organization. This is typically used to show a few lines about an Organization on an Offering or Organization search page.

company_number String

The company registration number for the Organization. This attribute is used in some risk services when retrieving credit scoring data about a company.

Key Concepts:
contact_point Integer

A contact point for the Organization. The contact_point is an identifier that equates to the id of the User who is the Organization's contact point. The contact point is by default the User who created the Organization.

created_at Date (Y-m-d)

Date on which the Organization was created.

credit_score String

The Organization's current credit score. This can be set manually by the Organization's member Users or by the platform's Admin Users, or automatically by the platform front-end according to your business logic.

The credit_score attribute is not set automatically by calling third-party risk services, although it is common to use the data from those services to calculate your own credit score according to your own risk algorithms.

Key Concepts:
custom Array of Custom Fields

This attribute holds an array of custom Organization fields, which can be used to hold any data relating to a Organization that do not fit the default Organization object model. You may use up to 100 such fields per Organization.

Key Concepts: Custom Fields
detail_desc String

A long-form, detailed description of the Organization.

display_name String

The display name of the Organization. The display_name attribute should be used as the public-facing name of the Organization. Use legal_name to store the official, registered name of the Organization.

facebook String

The Organization's Facebook account page.

founding_date Date (Y-m-d)

The date on which the Organization was founded.

founding_location String

Location at which the Organization was founded.

id Integer

Unique Identifier for the Organization. This is generated automatically when the Organization is first created using POST /organizations. The id attribute can never be changed so it can be used as a unique reference for the Organization on your platform.

info Depreciated Array of Custom Fields

This attribute is depreciated. Please use custom.

legal_name String

The full legal name of the Organization. The legal_name attribute is used by some Risk services.

Key Concepts:
life_cycle_stage Organization Lifecycle Enum

The current Lifecycle Stage of the Organization. 0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Archived, 7 = Cancelled.

The life_cycle_stage of an Organization can be updated using PATCH /organizations/{organization_id/. In order to ensure a complete and logical audit trail of your platform operations, the Organization's lifecycle can only go forwards, not backwards.

Key Concepts:
linkedin String

The Organization's LinkedIn account page.

location String

The Organization's location, e.g. San Francisco.

logo Document

The Organization's logo image.

members Array of Organization Membership

The Users who are members of this Organization. The members can be updated by implementing POST /organizations/{organization_id}/members/{user_id} or DELETE /organizations/{organization_id}/members/{user_id} or through the Crowd Valley Back Office application.

Key Concepts: Organization Members
org_email String

An email address for the Organization, for example, info@organization.com.

sector String

The Organization's industry or sector.

tax_id String

The Tax / Fiscal ID of the Organization, e.g. the TIN in the US or the CIF/NIF in Spain.

telephone String

A phone number for the Organization.

twitter String

The Organization's Twitter account page.

updated_at Date (Y-m-d)

Date on which the Organization was last updated.

user_id Integer

Unique identifier for the User who created this Organization. The Organization's contact_point also defaults to this User's id. However, the user_id can never be changed. It always represents the id of the User who was logged in when the call to POST /organizations was made to create the Organization.

visibility Organization Visibility Enum

The Organization's visibility: 0 = Open, 1 = Hidden, 2 = Anonymous. The visibility attribute determines how much information about this Organization other Users can retrieve through the GET /organizations function. If a Organization if Anonymous then their display_name will not be returned. If a Organization is Hidden then no information will be returned.

website String

A URL of a reference webpage that represents the Organization.

youtube String

The Organization's YouTube account page.

Capitalization

The Capitalization object represents an ownership of equity or debt in an Organization.

A Capitalization must have one and only own Organization. An Organization can have many Capitalizations.

If the Capitalization has only 1 number_of_shares then it can represent a single share. Otherwise, a Capitalization represents a block of shares owned by the same User and with the same value.


Attribute Data Type Description
author_id Integer

The id of the User who created this Capitalization.

author_name String

The full_name of the User who created this Capitalization.

capitalization_type Integer

The type of Capitalization: 0 = Equity, 1 = Preferred Equity or 2 = Debt.

created_at Date (Y-m-d)

Date on which this Capitalization was created.

id Integer

Unique identifier for this Capitalization.

life_cycle_stage Integer

The Capitalization's lifecycle stage: 0 = Authorized, 1 = Issued, 2 = Offered, 3 = Treasury, 4 = Split, 5 = Merged.

number_of_shares Integer

The number of shares held by the User.

number_of_shares_at_acquisition Integer

The number of shares held by the User at the time of acquisition.

organization_id Integer

The Organization in which the User owns this Capitalization.

owner_id Integer

The id of the User who currently owns this Capitalization.

owner_name String

The full_name of the User who currently owns this Capitalization.

price_per_share Decimal

The current price per share of this Capitalization.

price_per_share_at_acquisition Decimal

The price per share of this Capitalization when it was acquired.

service_charge Decimal

The service charge for this Capitalization.

This can be used to hold information about a service charge or fee relating to this Capitalization.

updated_at Date (Y-m-d)

Date on which the Capitalization was last updated.

valuation_gain Decimal

The gain in valuation for this Capitalization.

This is calculated as:

price_per_share x number_of_shares - price_per_share_at_acquisition x number_of_shares_at_acquisition

Offering

The Offering represents the activity of raising capital. An Offering must have one and only one Organization. An Organization can have many Offerings, in the case that a company undertakes several capital raises, for example.

Offerings can be created using the Crowd Valley Back Office application or, by implementing the relevant API functionality, by one of your end users on your front-end platform.

Offerings use the life_cycle_stage attribute to represent how far along the capital raising process this particular Offering has reached.

  • Draft: The Offering has been created and it is in your platform's pipeline of capital raising activities
  • Submitted: The Offering has been submitted by a User for review
  • Rejected: The Offering has been rejected as inappropriate for publication on your platform
  • Approved: The Offering has been approved as appropriate for publication on your platform but it is not yet visible
  • Restricted: The Offering is now visible to all Users who have is_vip = true on your platform but it is not yet open for Investments
  • Published: The Offering is now visible to all Users on your platform and it is open for Investments
  • Closing: The Offering is now in a closing and settlement process and no further Investments will be accepted. Investments can be adjusted through the Back Office during the Closing stage.
  • Settled: The Offering is now settled and all Users who have settled Investments in this Offering are considered investors
  • Canceled: The Offering has been canceled and no further Investments are permitted. An Offering can only be Canceled if it has no Investments that are Open, Approved or Settled

Attribute Data Type Description
additional_type String

An additional type or category for the Offering. Use this to define categories or groups of Offerings.

amount_raised Decimal

The amount that the Offering has raised. This is calculated from the Offering's Investments and the Offering's external_commitments value. The Offering's amount_raised is the sum of all investment_amount values for Investments in this Offering whose life_cycle_stage is Approved or Settled plus the Offering's external_commitments. Investments whose life_cycle_stage is Open, Rejected or Withdrawn are not counted.

capital_outstanding Decimal

The current capital outstanding for all Investments in this Offering.

This is calculated as the sum of all payout_amount values of all Payouts for all Investments in this Offering, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.

In other words, for each Investment in this Offering, we calculate the expected amount that is still to be paid back to investors.

category String

A category of the Offering.

close_date Date (Y-m-d)

The closing date after which Investments are no longer allowed for this Offering. If the Offering's close_date is set then Users will not be able to make new Investments after this date.

created_at Date (Y-m-d)

The date on which the Offering was created.

credit_score String

The current credit score for this Offering. The Organization object also has a credit_score attribute, which can be used in cases where the Organization has several different Offerings each with the same credit score. If each Offering has a different credit score then use the Offering's credit_score attribute.

currency Currency Code

The Offering's currency.

custom Array of Custom Fields

This attribute holds an array of custom Offering fields, which can be used to hold any data relating to a Offering that do not fit the default Offering object model. You may use up to 100 such fields per Offering.

Key Concepts: Custom Fields
equity_offered Decimal

The amount of equity offered as a percentage. This is typically used in equity-based offerings.

external_commitments Decimal

Funding received outside the platform that should be counted towards this Offering's total.

funding_goal Decimal

The funding goal for this Offering.

gcen_client_id String

The Offering's GCEN Client ID. This must be entered manually through the admin Back Office application.

Key Concepts:
id Integer

Unique Identifier for the Offering. This is generated automatically when the Organization is first created using POST /organizations/{organization_id}/offerings. The id attribute can never be changed so it can be used as a unique reference for the Offering on your platform.

info Depreciated Array of Custom Fields

This attribute is depreciated. Please use custom.

interest_rate Decimal

The interest rate offered. This is typically used in debt-based Offerings.

investment_count Integer

The number of Investments that have been made for this Offering, which have life_cycle_stage equal to Approved or Settled.

investor_count Integer

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 Boolean

Flag to show whether the Offering is featured and therefore available through the Public API endpoint GET /public/featuredOfferings.

Key Concepts: Featured Offerings
is_secondary_offering Boolean

Flag to show whether the Offering is a secondary market Offering.

Key Concepts: Secondary Markets
life_cycle_stage Offering Lifecycle Enum

The current Lifecycle Stage of the Offering. 0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Restricted, 5 = Published, 6 = Live (depreciated - please use 'Published'), 7 = Closing, 8 = Settled, 9 = Canceled.

The life_cycle_stage of an Offering can be updated using PATCH /offerings/{offering_id}. In order to ensure a complete and logical audit trail of your platform operations, the Offering's lifecycle can only go forwards, not backwards.

Key Concepts: The Offering Lifecycle
max_commitment Decimal

The maximum total amount that a User can invest in this Offering. If the max_commitment is set then a User will be prevented from making new Investments if the investment_amount, plus the sum of the same User's existing Approved or Settled Investments' investment_amount values for this Offering, is greater than the Offering's max_commitment.

max_overfunding_amount Decimal

The maximum amount raised by a Offering up to which Users can submit new Investments. If the max_overfunding_amount is set then Users will be prevented from making new Investments if the investment_amount, plus the sum of all existing Investments' investment_amount values for this Offering, is greater than the Offering's max_overfunding_amount. Implement this investment rule if you want to prevent an Offering from raising more investment than their funding_goal by setting its max_overfunding_amount to be equal to its funding_goal.

min_commitment Decimal

The minimum amount that a User can invest in this Offering. If the min_commitment is set then Users will be prevented from making new Investments if the investment_amount is less than the Offering's min_commitment.

name String

The name of the Offering, for example, 'SPV 1'.

num_of_shares Integer

The number of shares available in this Offering. The num_of_shares attribute is particularly important in secondary markets.

Key Concepts: Secondary Markets
offering_description String

A long-form description of the Offering to complement the name attribute.

open_date Date (Y-m-d)

The starting date after which new Investments are permitted for this Offering. If the Offering's open_date is set then Users will not be able to make new Investments before this date.

organization_id Integer

Unique identifier for the Organization that owns this Offering. It always represents the id of the Organization that was specified when the call to POST /organizations/{organization_id}/offerings was made to create the Offering.

Once created, an Offering cannot change its Organization.

price_per_share Decimal

The price per share for this Offering. The price_per_share attribute is particularly important in secondary markets.

Key Concepts: Secondary Markets
published_at Date (Y-m-d)

The date on which the Offering was Published.

raised_percent Decimal

The amount that the Offering has raised as a percentage of its funding_goal. This is calculated from the Offering's Investments and the Offering's external_commitments value. The Offering's raised_percent is its amount_raised divided by its funding_goal and multiplied by 100 to give a percentage. Use the amount_raised attribute to show a funding progress bar on an Offering overview page.

repayments_remaining Integer

The total number of repayments outstanding for all Investments in this Offering.

This is calculated as the total number of all Payouts for all Investments in this Offering, which do not have associated Transactions with a transaction_amount that is greater than or equal to the Payout's payout_amount.

In other words, we calculate the expected number of repayments that are still to be paid back to all Users who made Investments into this Offering.

service_charge Decimal

The service charge for this Offering.

This can be used to hold information about a service charge or fee relating to this Offering.

settled_at Date (Y-m-d)

The date on which the Offering was Settled.

submitted_at Date (Y-m-d)

The date on which the Offering was Submitted.

sum_outstanding_payouts Array of Custom Fields

The sum of all payout_amount values of all unpaid Payouts (which do not have sufficient Transactions whose transaction_amount is greater than the Payout's payout_amount) broken into categories according to their payout_type. This array is shown as: "sum_outstanding_payouts": { "dividends": 0, "capitalgains": 0, "loanrepayments": 0 }

term Integer

The loan term of the Offering. The term attribute is typically used in debt-based Offerings. The term can be used to represent days, months or years according to your platform's requirements.

updated_at Date (Y-m-d)

The date on which the Offering was last updated.

user_id Integer

Unique identifier for the User who created this Offering. It always represents the id of the User who was logged in when the call to POST /organizations/{organization_id}/offerings was made to create the Offering. It is particularly important in secondary markets to identify the seller of the secondary Offering.

Key Concepts: Secondary Markets
valuation Decimal

The current valuation of the Offering. The valuation attribute is typically used in equity-based Offerings.

Investment

The Investment represents the request by a User to make an investment in an Offering. An Investment must have one and only one Offering. An Offering can have many Investments, in the case that a company attracts multiple investors for its capital raise, for example.

Investments use the life_cycle_stage attribute to represent how far along the investment process this particular Investment has reached:

  • Open: The Investment has been submitted and it is being reviewed by the team managing this Offering
  • Rejected: The Investment has been rejected by the team managing this Offering
  • Approved: The Investment has been approved by the team managing this Offering
  • Withdrawn: The Investment has been withdrawn by the User who made the Investment
  • Settled: The Investment has been settled and is now considered complete

Attribute Data Type Description
capital_outstanding Decimal

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.

In other words, we calculate the expected amount that is still to be paid back to the User who made this Investment.

created_at Date (Y-m-d)

The date on which the Investment was created.

currency Currency Code

The Investment's currency.

custom Array of Custom Fields

This attribute holds an array of custom Investment fields, which can be used to hold any data relating to a Investment that do not fit the default Investment object model. You may use up to 100 such fields per Investment.

Key Concepts: Custom Fields
divested_amount Decimal

The amount that has 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.

The Investment's divested_amount may in some circumstances exceed the Investment's investment_amount if, for example, the price_per_share of the Offering increased over time.

Key Concepts: Secondary Markets
divested_shares Integer

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.

Key Concepts: Secondary Markets
id Integer

A Unique Identifier for the Investment. This is generated automatically when the Investment is first created using POST /offerings/{offering_id}/investments. The id attribute can never be changed so it can be used as a unique reference for the Investment on your platform.

info Depreciated Array of Custom Fields

This attribute is depreciated. Please use custom.

interest_rate Decimal

The interest rate requested. This is typically used in Investments for debt-based Offerings.

investment_amount Decimal

The investment amount submitted by the User for this Offering. Use the investment_amount attribute when implementing POST /offerings/{offering_id}/investments to make a new Investment.

is_loanbook Boolean

Flag to show whether this Investment was made for a Loanbook instead of an Offering.

Key Concepts: Loanbooks
life_cycle_stage Investment Lifecycle Enum

The current Lifecycle Stage of the Investment. 0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Settled.

The life_cycle_stage of an Investment can be updated using PATCH /investments/{investment_id}. In order to ensure a complete and logical audit trail of your platform operations, the Investment's lifecycle can only go forwards, not backwards.

Key Concepts: The Investment Lifecycle
number_of_shares Integer

The number of shares rate offered. This is typically used in Investments for debt-based Offerings.

offering_id Integer

Unique identifier for the Offering for which the User made this Investment.

repayments_remaining Integer

The number of repayments outstanding for this Investment.

This is calculated as the number 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.

In other words, we calculate the expected number of repayments that are still to be paid back to the User who made this Investment.

service_charge Decimal

The service charge for this Investment.

This can be used to hold information about a service charge or fee relating to this Investment.

term Integer

The term requested. This is typically used in Investments for debt-based Offerings, where term represents the number of months of a loan.

updated_at Date (Y-m-d)

The date on which the Investment was last updated.

user_id Integer

Unique identifier for the User who made this Investment.

visibility Investment Visibility Enum

The Investment's visibility. 0 = Open, 1 = Hidden, 2 = Anonymous. The visibility attribute determines how much information can be accessed by other Users through the GET /offerings/{offering_id}/investments function. Open Investments can be seen if they have a life_cycle_stage of Approved or Settled. If the Investment's visibility is Hidden then the Investment will not be returned in the list. If the Investment's visibility is Anonymous then its user_id will not be returned.

Document

The Document represents any file that is attached to any other object in the API. Documents can be associated to a User, an Organization, an Offering, an Investment or a Payout. Any of these objects can have any number of Documents. A Document must have one and only one of these objects.

The Document object is also used to store the User's profile image and the Organization's logo image.


Attribute Data Type Description
created_at Date (Y-m-d)

The date on which the Document was created.

file_alias String

The publicly visible alias of the document, e.g., 'Current Year Financials'.

file_description String

The publicly visible description of the document, e.g. 'Our company's most recent financial statement'.

file_name String

The document's file name, e.g., current-year-financials.pdf

file_type String

The document's mime-type, e.g., application/pdf

id Integer

Unique Identifier for the Document.

life_cycle_stage Document Lifecycle Enum

The current Lifecycle Stage of the Document. 0 = Draft, 1 = Submitted, 2 = Rejected, 3 = Approved, 4 = Archived.

The life_cycle_stage of a Document can be updated using PATCH /documents/{document_id} if the Document is owned by the logged-in User or by an object that is owned by the logged-in User.

source_type Integer

0 = Crowd Valley CDN, 1 = External CDN. If source_type = 0 then the Document's url will be pre-signed with Crowd Valley's CDN credentials

tag String

A tag or category for the Document. Use tags to categorize Documents to display on your platform's front-end, e.g. 'Financials'.

The tag is often used to specify which Document should be sent to a third-party KYC/AML service.

Key Concepts: KYC/AML
updated_at Date (Y-m-d)

The date on which the Document was last updated.

url String

The Document's full URL.

If the Document has source_type = 1 then the Document's url will be returned without any CDN access credentials. Otherwise the Document will be assumed to be stored with Crowd Valley and Crowd Valley's pre-signed credentials will be added to the url in the response.

user_id Integer

Unique Identifier for the User who added this Document.

Address

The Address object is primarily used for Users and Organizations. It is often required for third-party payments or KYC/AML services.

Users can have any number of Addresses. Organizations can have up to one Address.


Attribute Data Type Description
address_locality String

The address locality. For example, Mountain View.

building String

The building name or number, for example, '1600'. This can be used as Address Line 1.

city String

The city or town. For example, San Francisco.

country String

The country. For example, US.

When adding data to this field as part of a third-party AML/KYC service, use the two-letter ISO 3166-1 Alpha 2 country code.

id Integer

Unique Identifier for the Address.

postal_code String

The postal or ZIP code. For example, '94043'.

region String

The region, county or state. For example, CA.

street_address String

The street address. For example, Amphitheatre Pkwy. This can be used as Address Line 2.

sub_building String

The Sub-Building of an Address. If the Address has a Flat Number or Building Number as well as a Building Name then use this sub_building field.

For example, an address: Flat 100, Mansion House, High Road, London should use the following structure:

  • sub_building = Flat 100
  • building = Mansion House
  • street_address = High Road
  • city = London

If you are using a third-party KYC/AML service then it is important to separate the Flat Number from the House Name/Number in the data model because the following would not be parsed correctly: building = Flat 100, Mansion House. Therefore, always use sub_building if the Address has two parts to the Building Name/Number.

Bank Account

The Bank Account object is primarily used for Users and Organizations. Users can have any number of Bank Accounts. Organizations can have up to one Bank Account.


Attribute Data Type Description
bank_account_number String

Bank Account Number.

bank_address String

The bank's address.

bank_country String

The bank's country. For example, USA. You can also provide the two-letter ISO 3166-1 Alpha 2 country code.

bank_currency Currency Code

The bank account's ISO 4217 currency code.

bank_name String

The bank's name.

bank_routing_number String

Bank Account Routing number or Sort Code.

bank_swift_code String

Bank Account SWIFT code

id Integer

Unique Identifier for the Bank Account.

Bulletin

The Bulletin object is used to represent an update or news item related to an Offering, for instance an update on progress during the capital raising process, or an update to Users who invested in the Offering after it has closed.

A Bulletin must have one and only one Offering. Offerings can have multiple Bulletins.


Attribute Data Type Description
body String

The body or content of the Bulletin.

created_at Date (Y-m-d)

The date on which the Bulletin was created.

id Integer

Unique Identifier for the Bulletin.

life_cycle_stage Integer

The Bulletin's lifecycle stage,

offering_id Integer

Unique Identifier for this Bulletin's Offering.

title String

The title or heading of the Bulletin.

updated_at Date (Y-m-d)

The date on which the Bulletin was last updated.

Payout

The Payout object is used to represent a scheduled payment or transaction for a User, which results from the User's activities on your platform. In equity-based platforms a Payout can be used to create a schedule of Dividend payments from the Organization back to Users who made an Investment in that Organization's Offering. In debt-based platforms a Payout can be used to create a schedule of loan repayments from the borrower User back to the lender Users.

A Payout must have one and only one Investment. Investments can have multiple Payouts.


Attribute Data Type Description
additional_type String

An additional type or category for the Payout. Use this to define categories or groups of Payouts.

charge_offs Decimal

A chargeoff for the Payout.

A chargeoff is the amount of a Payout that has been declared by a creditor as unlikely to be collected. Chargeoffs are typically used in P2P lending platforms where the borrower User is unable to make a repayment back to the lenders.

created_at Date (Y-m-d)

The date on which the Payout was created.

currency Currency Code

The Payout's ISO 4217 currency code.

custom Array of Custom Fields

This attribute holds an array of custom Payout fields, which can be used to hold any data relating to a Payout based on your requirements.

Key Concepts: Custom Fields
due_date Date (Y-m-d)

The date on which a Transaction is due for this Payout.

id Integer

Unique Identifier for the Payout.

investment_id Integer

Unique Identifier for this Payout's Investment.

late_fee Decimal

A late fee for the Payout.

A late fee is the amount charged by your platform for late payment, typically used in P2P lending platforms.

minimum_payment Decimal

The minimum amount required to settle this Payout.

net_annualized_return Decimal

The Net Annualized Return of this Payout.

The Net Annualized Return (NAR) is a measure of return on investment. It is typically used in P2P lending platforms.

NAR is calculated based on the Payout's payout_amount due, net of its service_charge, chargeoffs, and net_recoveries.

net_recoveries Decimal

A net recovery amount for the Payout.

A net recovery is the amount of a Payout that has been recovered from the total amount due less any applicable taxes. Net recoveries are typically used in P2P lending platforms where the borrower User has been unable to make a repayment back to the lenders.

offering_id Integer

The id of the Offering to which this Payout is linked.

If the Payout represents a scheduled repayment of an Investment, e.g. a dividend to an investor, then the offering_id will not be returned.

If the Payout represents a scheduled repayment of an Offering, e.g. a loan repayment by a borrower, then the offering_id field will return the id of that Offering.

offering_name String

The name of the Offering to which this Payout is linked.

If the Payout represents a scheduled repayment of an Investment, e.g. a dividend to an investor, then the Offering Name will be the name of the Offering into which the Investment was made.

If the Payout represents a scheduled repayment of an Offering, e.g. a loan repayment by a borrower, then the Offering Name will the be name of that Offering.

paid_at Date (Y-m-d)

The time and date on which this Payout was fully paid.

This is calculated as the earliest time at which the sum of all the transaction_amount values of all of this Payout's Transactions that have payment_status equal to 1 (i.e., Paid) is greater than or equal to this Payout's payout_amount.

In other words, this can be used to show when the Payout was considered to be paid.

If the Payout has not yet been paid, i.e., it does not have Paid Transactions whose total transaction_amount exceeds the Payout's expected payout_amount, then the paid_at field will return an empty string.

payout_amount Decimal

The amount expected for this Payout's Transaction.

payout_type 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.

service_charge Decimal

The service charge for this Payout.

This can be used to hold information about a service charge or fee relating to this Payout.

transactions_paid Integer

The number of Paid Transactions that have been associated to this Payout.

This is calculated as the number of Transactions that have a payout_id equal to this Payout's id and that have a payment_status equal to 1 (i.e., Paid).

updated_at Date (Y-m-d)

The date on which the Payout was last updated.

user_id Integer

The id of the User that owns this Payout.

user_name String

The full name of the User that owns this Payout.

Transaction

The Transaction object is used to record an actual payment or transaction for a User, which may be compared to that User's expected payments, in the form of Payouts, on your platform. By comparing a User's Transactions to their Payouts, you can calculate your defaulted payments or number of late days on your loan portfolio.

Transactions are also used to add or subtract funds from a User's internal Wallet. Creating Transactions is the only way to update the a User's Wallet balance.

A Transaction can have one and only one Payout. Payouts can have multiple Transactions. A Transaction can have one and only one Wallet. Wallets can have multiple Transactions. A Transaction must have either a Payout or a Wallet.


Attribute Data Type Description
confirmation_number String

A number or code that confirms the given transaction has been successfully processed.

created_at Date (Y-m-d)

The date on which the Transaction was created.

id Integer

Unique Identifier for the Transaction.

original_transaction_amount Decimal

The original amount paid if in a different currency from the user's wallet.

original_transaction_currency Currency Code

The currency of the original amount paid.

payment_service Integer

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 String

A unique identifier for the transaction log of the payment service.

payment_status Integer

0 = Pending, 1 = Paid, 2 = Cancelled or 3 = Failed. Defaults to 1 (Paid)

payout_id Integer

Unique Identifier for this Transaction's Payout.

If the Transaction was created from POST /payouts/{payout_id}/transactions then this field is set automatically. Otherwise the payout_id can be set manually to associate an existing Transaction with a Payout.

transaction_amount Decimal

The amount paid in this Transaction. Enter transaction_amount > 0 for debits and transaction_amount < 0 for credits.

transaction_currency Currency Code

The Transaction's ISO 4217 currency code.

transaction_description String

A log description for the Transaction.

updated_at Date (Y-m-d)

The date on which the Transaction was last updated.

user_id Integer

Unique Identifier for the User who made this Transaction.

wallet_id Integer

Unique Identifier for this Transaction's Wallet.

If the Transaction was created from POST /wallets/{wallet_id}/transactions then this field is set automatically. Otherwise the wallet_id can be set manually to associate an existing Transaction with a Wallet.

Wallet

The Wallet object is used to represent the amount of funds a User has available to invest through your platform. This Wallet object can be used alongside or in place of external wallets provided by third-party payments service providers. Wallets can be used to represent real capital or a system of credits.

A Wallet must have one and only one User. Users can have multiple Wallets.


Attribute Data Type Description
balance Decimal

The total Wallet balance. This is calculated from the Wallet's Transactions.

committed_balance Decimal

The amount that has been committed to pending Transactions from this Wallet. This is calculated from the Wallet's Transactions.

created_at Date (Y-m-d)

The date on which the Wallet was created.

currency Currency Code

The Wallet's ISO 4217 currency code.

free_balance Decimal

The amount that has not been committed to pending Transactions from this Wallet. This is calculated from the Wallet's Transactions.

id Integer

Unique Identifier for the Wallet.

updated_at Date (Y-m-d)

The date on which the Wallet was last updated.

user_id Integer

Unique Identifier for the User who owns this Wallet.

Invitation

The Invitation object is used to represent an email invitation sent by a User to someone who is not yet a member of your platform. Invitations can be used to track the number of times a User has invited someone to join your platform and the number of registered Users who have joined by clicking a link in the email notification that is sent when the Invitation is created.

An Invitation must have one and only one User. Users can have multiple Invitations.


Attribute Data Type Description
author_id Integer

Unique Identifier for the User who sent this Invitation.

created_at Date (Y-m-d)

The date on which the Invitation was created.

email Integer

The email address of the invitee.

expires_at Date (Y-m-d)

The date on which this Invitation should no longer be considered valid.

family_name String

The family name of the invitee.

given_name String

The given name of the invitee.

id Integer

Unique Identifier for the Invitation.

organization_name String

The organization name of the invitee.

responded_at Date (Y-m-d)

The date on which the invitee clicked the link of the Invitation.

updated_at Date (Y-m-d)

The date on which the Invitation was last updated.

Application

The Application object is used to represent a submission by a User to be considered and approved by the admin team, perhaps as part of a User Onboarding or Funding Application process.

The Application object has a light data model with the intention that you can create your own custom form structure based on your requirements.

An Application must have one User and Users can have any number of Applications.


Attribute Data Type Description
author_id Integer

The Unique Identifier for the User who created the Application. If the logged-in User created their own Application then its user_id will be equal to its author_id. Otherwise if the User created an Application on behalf of a different User then the user_id will be different to the author_id.

created_at Date (Y-m-d)

The date on which the Application was created.

custom Array of Custom Fields

This attribute holds an array of custom Application fields, which can be used to hold any data relating to a Application based on your application form requirements.

Key Concepts: Custom Fields
id Integer

Unique Identifier for the Application.

info Depreciated Array of Custom Fields

This attribute is depreciated. Please use custom.

life_cycle_stage Application Lifecycle Enum

The current Lifecycle Stage of the Application. 0 = Open, 1 = Rejected, 2 = Approved, 3 = Withdrawn, 4 = Completed.

updated_at Date (Y-m-d)

The date on which the Application was last updated.

user_id Integer

The Unique Identifier for the User who is making this Application. If the logged-in User created their own Application then its user_id will be equal to its author_id.

user_name String

The full_name of the User who is making this Application based on its user_id.