API Documentation

Introduction

January 7, 2017 — the FundAmerica platform is a RESTful API that uses JSON as its response type for everything. It also makes heavy use of different HTTP verbs (GET, POST, PATCH, DELETE) and HTTP error messages where applicable.

For an example of creating an offering, accepting it for investment, making investments and closing the offering, see Investment Quick Start Example.

Support

Please report any issues immediately by contacting developer support directly at tech-support@fundamerica.com and we will deal with them promptly. Additionally, any questions, comments, suggestions or feature requests are welcome.

There is a developer newsletter directly related to the API which will include new feature announcements, updates, tips and tricks, and upcoming maintenance schedules. It is strongly recommended that all developers sign up to receive this newsletter by clicking here.

Invest Now Users

If you're using our Invest Now product and wish to further customize or better integrate with it, please see our Invest Now Developer's Guide for more information.

Changelog

For a list of recent changes and news, check out our changelog.

Time Zone

New accounts will default to the 'Eastern Time' time zone. You can update this value under "Account Settings" when logged in.

API Keys

In order to authenticate with our API, you'll need to get an API key. This can be done by logging in to your account at apps.fundamerica.com and navigating to "Account Settings" -> "API Keys".

Test vs Production

There are two seperate environments for testing and production:

The API examples throughout this document will reference the production calls except where they are testing specific. Remember to point to sandbox.fundamerica.com for all calls when testing.

If you have multiple test environments (e.g. staging, QA, etc.) simply create another account for each. This is the easiest way to keep data segregated and test multiple endpoints.

Keep in mind that there is no billing or approval necessary in the sandbox environment. No objects created on the sandbox are ever reviewed by customer service.

Since objects created on the sandbox are not reviewed by customer service, certain objects that undergo manual state changes (e.g. accepting an offering's escrow account or marking an investment as "received") require special test calls to change the state. (See Test Mode Endpoint Reference.)

Authentication

HTTP authentication is used for all requests. Your API key should be used as your username with the password left blank. Only make requests over HTTPS.

API Versions

The API does not have a strict version, but rather a rolling version. New features are added regularly and occasionally features are deprecated and removed. At the time a new account is created, an API version date is set to the sign up date.

The API version date will dictate certain behavior in the API. For instance, API response values that have been deprecated prior to the API version date will not appear in API responses. Additionally, certain changes may be manditory for the current version of the API that may still be optional for older versions.

The version date can be set in one of two ways:

  1. Using Account Settings to set a default.

  2. Passing a _version parameter with your API requests either as a querystring or form value.

curl https://apps.fundamerica.com/api/example_objects?_version=2015-02-27 \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Note: If you are implmenting a white label or other system that allows multiple FundAmerica accounts and API keys to be used, it's important to make sure that everyone is using the same version. Using the querystring method is the simplest way to accomodate this without having your account users set a default to match whatever you have developed against.

Deprecated Features

Due to changes in statute, policy, technology, or just plain correction of early oversights, certain features of the API will be deprecated and ultimately removed from time to time.

In general, deprecation notices will be announced in the changelog via the newsletter. Additionally, deprecation warnings will be included in API responses if certain fields have been deprecated. A deprecated_keys field will be included in any response containing keys that are set to be removed.

Example Object JSON with Deprecated Keys

{
  "object":"example_object",
  "id":"XXXXXXXXXXXXXXXXXXXXXX",
  "url":"https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX",
  "name":"OBJECT NEW NAME",
  "old_key":"No one uses this anymore.",
  "deprecated_keys":["old_key"]
}

If you notice these in your responses, please adjust your code not to rely on these keys as they will be removed at some point in the future.

Crowdfunding has a lot of moving parts and many of our services are subject to changes in law, policy, judicial review, etc. We do not always have control over these changes and when they must be implemented. While we strive not to break existing implementations, there may be times where this simply isn't an option. As a result, it is prudent for developers to check out the changelog from time to time or, more conveniently, sign up for the newsletter to receive updates on API changes.

Deprecated keys will be removed from the documentation examples to avoid confusing new developers.

Errors

An HTTP status of 200 means everything processed as expected. The 4xx and 5xx error codes means something went wrong. The most common errors you'll see are as follows:

  • 401: Authentication error. Your API key is incorrect.
  • 403: Not authorized. You don't have permission to take action on a particular resource. It may not be owned by your account or it may be in a state where you action cannot be taken (such as attempting to cancel an invested investment).
  • 404: Resource was not found.
  • 422: This usually means you are missing or have supplied invalid parameters for a request.
  • 500: Internal server error. Something went wrong. This is a bug. Please report it to support immediately.

Example 422 Error

  {
    "offering": {
      "name":["is already in use"]
    },
    "entity":{}
  }

The details of an error are listed with the object type as the key and a value of another object keyed by the attribute name followed by an array of errors on the field. In instances where multiple objects may be modified in a request (almost universally an entity) multiple object keys will be listed.

Note: Sometimes there is an error not related to any particular attribute of an object. Those errors will be keyed under base. For instance, if there was an error processing ACH on an investment, it would be listed as an error under base.

Programming Language Support

All examples in this document are in the form of language-agnostic cURL commands. We currently do not support or provide API examples in any specific languages.

cURL is a popular tool used for executing HTTP requests and returning the subsequent responses which makes it suitable for interacting with a RESTful API. More information can be found at the cURL homepage and the Wikipedia page.

Resources and Action Overview

Resources are represented as JSON objects and have predictable endpoints for each action. Let's take an example object called "Example Object."

Creating an example object:

curl https://apps.fundamerica.com/api/example_objects \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d name="OBJECT NAME"

Viewing an example object:

curl https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Updating an example object:

curl https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d name="OBJECT NEW NAME"

Destroying an example object:

curl https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X DELETE

Example Object JSON

{
  "object":"example_object",
  "id":"XXXXXXXXXXXXXXXXXXXXXX",
  "url":"https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX",
  "name":"OBJECT NEW NAME"
}

Response Attributes

These attributes are the same for every object and will not be repeated below.

  • object: The type of object.
  • id: The object's unique ID.
  • url: The URL of this particular object.

Listing all examples objects:

curl https://apps.fundamerica.com/api/example_objects \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Example Object List JSON

{
  "object":"resource_list",
  "total_resources":1,
  "more":false,
  "page":1,
  "per":25,
  "resources":[
    {
      "object":"example_object",
      "id":"XXXXXXXXXXXXXXXXXXXXXX",
      "url":"https://apps.fundamerica.com/api/example_objects/XXXXXXXXXXXXXXXXXXXXXX",
      "name":"https://apps.fundamerica.com/api/offerings/OBJECT NAME"
    }
  ]
}

Response Attributes

  • total_resources: The total number of resources.
  • more: Whether or not there are additional pages.
  • page: The current page.
  • per: The number of resources per page.
  • resources: The list of resources.

The query strings page and per can be sent to a list action to change which page is being viewed and how many resources are included in a page.

A complete list of API endpoints can be found at API Endpoint Reference.

Special Request Options

Sorting

On index methods that return more than one object, you may wish to sort them by a particular attribute. Most non-url attributes are sortable. This can be done by passing a _sort[<attribute_name>]=1 or _sort[<attribute_name>]=-1 with the request as either a query string or a post parameter. A value of 1 will sort the objects by the attribute in ascending order and a value of -1 will sort the objects by the attribute in descending order.

Expansion

Many objects contain references to other objects. For instance an offering many contain an issuer entity. Instead of making a second GET request if you wanted to also get the information for the issuer, you could expand the issuer. Any object that returns <attribute_name>_url with a URL pointing to another API URL can be expanded by passing _expand[<attribute_name>]=1 with the request as either a query string or a post parameter.

So, if _expand[entity]=1 was passed to an offering request, the response would include an entity parameter with the same data as GET entity_url would provide.

Hiding

Sometimes you only want to bring back a subset of data, especially on certain API requests that return a lot of data. You can hide attributes you do not wish to see by passing a _hide[<attribute_name>]=1 with the request as either a query string or a post parameter.

Webhooks

There is a lot of manual approval required in securities, particularly with escrow. Additionally, some actions execute asynchronously like processing background checks. You have two options, you can regularly poll a particular object for changes or use webhooks.

When configuring up an API key, you can provide an optional webhook URL and when certain actions take place, you will receive a notification message from our system. The notification will POST to the URL you provided (you should use HTTPS in production) with a parameter of data containing a JSON message about what changed.

Example

{
  "object":"investment",
  "id":"LckF85F4R8Soe3Why-NZzw",
  "url":"https://apps.fundamerica.com/api/investments/LckF85F4R8Soe3Why-NZzw",
  "webhook_id":"R38DyKhFS_Ke6OhtzjMvcQ",
  "signature":"b8a2f282649eebbfac85be3a959942b9",
  "action":"update",
  "changes":["status"]
}

Response Attributes

  • webhook_id: Each webhook has a unique ID. If you want to prevent replay attacks, it is good practice to only execute a particular ID once.
  • signature: An MD5 hex digest of the webhook_id combined with your API key.
  • action: May be set to create or update. If create it means the object was newly created.
  • changes: The attributes that changed.

The actual changes are not sent so once you receive a webhook, you need to request the current state of the object.

Webhook Signature

The signature is an MD5 hex digest of the webhook_id combined with the verification key found in your Webhook Configuration settings. Here is an example in Ruby of how to generate a signature for validation:

  webhook = JSON.parse(params[:data])
  webhook_id = webhook['webhook_id']
  expected_signature = Digest::MD5.hexdigest(webhook_id + webhook_verification_key)
  if expected_signature == webhook['signature']
    # Process webhook...
  end

Webhook Errors

In addition to configuring a webhook_url for your API key, you can also specify an Error Report Email. If there are issues sending webhook requests, you will be notified via this email address if it is provided.

Our platform will make ten attempts, one every minute, to send a webhook. If the HTTP response has a status of anything but a 200 or cannot send the request for any other reason (e.g. DNS problems, unable to reach host, etc.) it will send an email message informing you about the error and containing the webhook information.

Webhook Logs

It's possible to test and debug webhooks by checking your webhook logs. This will give you a list of all webhooks that would have been sent. Even if you haven't configured a webhook_url, webhooks still appear in the log and as such can be used for testing purposes or even playback in the future if there was an error.

https://apps.fundamerica.com/api/webhook_logs (GET)

The data field is exactly the JSON that would have been sent to your webhook_url.

Issuer and Investor Entities

Entities represent either a person or a company. They are used in a number of places. They can be an investor, an issuer or anyone related to an offering that is eligible for a background check.

Entities can also have a investor_suitability_status set for them. For more details on investor_suitability_status and the related investor suitability questionnaires, please see Broker Dealer Services.

API Endpoints

GET    https://apps.fundamerica.com/api/entities
POST   https://apps.fundamerica.com/api/entities
GET    https://apps.fundamerica.com/api/entities/:id
PATCH  https://apps.fundamerica.com/api/entities/:id

Example Object (Company)

{
  "object": "company",
  "id": "uSoJ-sEcRDWkLT978ydfJA",
  "created_at": "2015-04-29T01:34:42.987Z",
  "city": "New York",
  "country": "US",
  "email": "john.johnson@johnson.com",
  "executive_name": "John Johnson",
  "investor_suitability_status": null,
  "kyc_status": null,
  "name": "Johnson, Johnson, Johnson & Johnson",
  "phone": "12025551212",
  "postal_code": "10005",
  "region": "NY",
  "region_formed_in": "NY",
  "street_address_1": "60 Wall St.",
  "street_address_2": null,
  "tax_id_number": "999999999",
  "type": "company",
  "updated_at": "2015-04-29T01:34:42.987Z"
}

Note: custodial entities are identical to company with the exception of what type returns.

Example Create (Company)

curl https://apps.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d city="New+York" \
-d country="US" \
-d email="john.johnson%40johnson.com" \
-d name="Johnson%2C+Johnson%2C+Johnson+%26+Johnson" \
-d phone="12025551212" \
-d postal_code="10005" \
-d region="NY" \
-d street_address_1="60+Wall+St." \
-d tax_id_number="999999999" \
-d type="company" \
-d executive_name="John+Johnson" \
-d region_formed_in="NY"

Example Object (Person)

{
  "object": "person",
  "id": "pGMOuC50Q6q2Eie3KLaVZg",
  "created_at": "2015-04-29T01:34:42.942Z",
  "city": "New York",
  "country": "US",
  "date_of_birth": "1934-06-06",
  "email": "john.johnson@johnson.com",
  "investor_suitability_status": null,
  "kyc_status": null,
  "name": "John Johnson",
  "phone": "12025551212",
  "postal_code": "10022",
  "region": "NY",
  "region_formed_in": null,
  "street_address_1": "520 Park Ave",
  "street_address_2": "Ste 31",
  "tax_id_number": "000000000",
  "type": "person",
  "updated_at": "2015-04-29T01:34:42.942Z"
}

Example Create (Person)

curl https://apps.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d city="Las+Vegas" \
-d country="US" \
-d email="john.investor%40example.com" \
-d name="John+Q+Investor" \
-d phone="17025551212" \
-d postal_code="89123" \
-d region="NV" \
-d street_address_1="555+Some+St" \
-d tax_id_number="000000000" \
-d type="person" \
-d date_of_birth="1980-01-01"

Request Attributes

  • city: City of entity's address. Required.
  • country: Country of entity's address.
  • date_of_birth: Entity's date of birth. Required if type is person.
  • email: Entity's contact email. Required.
  • contact_name: Required if type is company.
  • name: Entity's legal name. Required.
  • phone: Entity's contact phone number. Required.
  • postal_code: Postal or ZIP Code code of entity's address. Required.
  • region: State or region of entity's address. Required.
  • region_formed_in: The state where the company was formed. Required if type is company and country is US.
  • street_address_1: Street address line 1. Required.
  • street_address_2: Street address line 2. Optional.
  • tax_id_number: SSN or FEIN in US, or other tax ID number if non-US for entity. Required.
  • type: Must be person, company or custodial. Required.

Response Attributes

  • investor_suitability_status: It can be one of four values:
    • null: No investor suitability questionnaire has been filled out.
    • pending: Investor suitability questionnaire is being reviewed.
    • accepted: FundAmerica has accepted the investor suitability questionnaire and on offerings using Broker Dealer Services, FundAmerica may act as the broker-dealer of record for the investor.
    • denied: FundAmerica has denied the investor suitability questionnaire and on offerings using Broker Dealer Services, FundAmerica will not act as the broker-dealer of record for the investor.

Customer Service Overview and Webhooks

For entities being used as actual issuers, associated persons and investors, it is possible that they may be contacted by customer service (e.g. there is a problem on an AML review or an investment) for more information or a correction in their information. If entity information is updated by FundAmerica customer service, a webhook will be created letting your system know that information has been updated on the entity.

Nesting Entities

Other API calls that accept entities can accept them in one of two ways:

  1. You explicitly create the entity first and then pass the entity's ID as an attribute to the API call.
  2. You create/update an associated entity with the API call. (See the Offering creation example.)

Entity Relationships

When dealing with company entities, it generally makes sense to have a parent/child relationship with either another company or a person or a mix of each. For instance, an actual issuer LLC may have multiple owners or executives subject to AML. In order to prevent the need for manual intervention, it is a good idea to create relationships between entities.

The parent in the relationship is an entity with some kind of authority over the child. For instance an owner, a stockholder, an executive, a manager, etc. would all be the parent. Both a person and a company can act as a parent in the relationship, however only companies can be the child. For the purposes of complete AML it's important that any chain of parents ends with a person.

Additionally, an ACH Authorization can only be used by the entity it was created in association with. However, many funding platforms allow a person to invest as a company. Child entities can use their parents' ACH authorizations to invest.

API Endpoints

GET    https://apps.fundamerica.com/api/entities/:id/child_entities
GET    https://apps.fundamerica.com/api/entities/:id/parent_entities
GET    https://apps.fundamerica.com/api/entities/:id/relationships_as_child
GET    https://apps.fundamerica.com/api/entities/:id/relationships_as_parent
GET    https://apps.fundamerica.com/api/entity_relationships
POST   https://apps.fundamerica.com/api/entity_relationships
GET    https://apps.fundamerica.com/api/entity_relationships/:id
PATCH  https://apps.fundamerica.com/api/entity_relationships/:id
DELETE https://apps.fundamerica.com/api/entity_relationships/:id

Example Object

{
  "object": "entity_relationship",
  "id": "AHDqVz8AQY-1Eo-wDdlBSw",
  "url": "https://apps.fundamerica.com/api/entity_relationships/AHDqVz8AQY-1Eo-wDdlBSw",
  "child_entity_url": "https://apps.fundamerica.com/api/entities/q4vfKkgKR52yu-JY0QzTWg",
  "created_at": "2015-11-12T18:43:18.243Z",
  "description": "Also a major stockholder.",
  "parent_entity_url": "https://apps.fundamerica.com/api/entities/3z0soACPTRSX4nw7lbMgqw",
  "parent_title": "Authorized Person",
  "updated_at": "2015-11-12T18:43:18.243Z"
}

Example Create

curl https://apps.fundamerica.com/api/entity_relationships \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d child_entity_id="KTFLqoh0RsmOewq6G9OKpQ" \
-d description="Also+a+major+stockholder." \
-d parent_entity_id="CBlrEvV5SUqqVeksZB97uQ" \
-d parent_title="Authorized+Person"

Request Attributes

  • child_entity_id: The ID of the entity that is the child in the relationship.
  • description: An optional description about the relationship. This can be useful for adding special instrutions or notes that customer service might use when resolving AML.
  • parent_entity_id: The ID of the entity that is the parent in the relationship. The parent should have some kind of responsibility over the child entity like a manager, a director, an executive or a shareholder.
  • parent_title: An optional title for the parent entity in relation to the child entity. In general, it's good practice to include this.

Note: In the future, it will be required for issuers to have at least one parent before escrow can be opened.

Entity Documents

There are a number of instances where providing documentation on a particular entity to FundAmerica is important. The most common instances are when there is an AML exception and documentation is necessary to verify the investor's identity. Arbitrary documents can be attached to an entity. This can be done preemptively (e.g. your portal always collects trust documents from trust entities) or as needed during the AML process.

Since this API allows for the transmission of binary data (the file itself), the POST method must be sent as multipart/form-data just as you would if uploading a file from an HTML form.

Files cannot be deleted once uploaded, nor can they be modified via the API.

API Endpoints

GET    https://apps.fundamerica.com/api/entities/:id/entity_documents
POST   https://apps.fundamerica.com/api/entity_documents
GET    https://apps.fundamerica.com/api/entity_documents/:id

Example Object

{
  "object": "entity_document",
  "id": "Vqw63IK8SGmulNDJr2oVLg",
  "url": "https://apps.fundamerica.com/api/entity_documents/Vqw63IK8SGmulNDJr2oVLg",
  "content_type": "application/pdf",
  "description": "Optional description.",
  "entity_url": "https://apps.fundamerica.com/api/entities/3WJURy1eRUSE4tHIRiWHGw",
  "file_url": "... temporary file URL ...",
  "purpose": "accreditation",
  "size": 10455,
  "title": "2015 Bank Statement"
}

Example Create

curl https://apps.fundamerica.com/api/entity_documents \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-F "content_type=application%2Fpdf&description=Optional+description.&entity_id=3WJURy1eRUSE4tHIRiWHGw&purpose=accreditation&title=2015+Bank+Statement" \
-F "file=@/path/to/example.pdf"

Request Attributes

  • content_type: If you want to force a particular content type, you can override it with this parameter. This will be preferred over the content type set in the body of the HTTP request.
  • description: An optional description about the file.
  • entity_id: The entity to be associated with the document.
  • file: The file.
  • purpose: This must be set to kyc.
  • title: The document's title.

Response Attributes

  • file_url: A temporary URL for downloading the file. The link is good for 15 minutes.
  • size: The file's size in bytes.

Cash Blotter

A cash blotter tracks the transactions of an investor's ledger.

Example Object

{
  "object":"ledger_entry",
  "id":"ZzHv4JuDEeSY79ehFBfhbg",
  "balance":"12500.0",
  "created_at":"2015-01-14T00:22:20.227Z",
  "credit":"500.0",
  "debit":null,
  "description":"Received funds",
  "investment_payments":[{"status":"received","url":"https://apps.fundamerica.com/api/investment_payments/truzQuU6TcS8pAS1ZzwF6w"}]
}

Example Get

curl https://apps.fundamerica.com/api/entities/:id/cash_blotter \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Response Attributes

  • balance: The total balance after this transaction cleared.
  • credit: Amount credited to the escrow ledger.
  • debit: Amount debited from the escrow ledger.
  • description: A description of the ledger entry.
  • investment_payments: Related investment payments.

Offerings

Virtually every activity in the FundAmerica platform revolves around offerings. Escrow payments, background checks and documents all require an offering to be attached to.

API Endpoints

GET    https://apps.fundamerica.com/api/offerings
POST   https://apps.fundamerica.com/api/offerings
GET    https://apps.fundamerica.com/api/offerings/:id
PATCH  https://apps.fundamerica.com/api/offerings/:id
PATCH  https://apps.fundamerica.com/api/test_mode/offerings/:id

Example Object

{
  "object": "offering",
  "id": "CXamBIvwRneFrQnh1CjFuw",
  "url": "https://apps.fundamerica.com/api/offerings/CXamBIvwRneFrQnh1CjFuw",
  "accept_investments": true,
  "accredited_investors": true,
  "ach_deposit_amount": "0.0",
  "ach_deposit_max_percent": "6.0",
  "ach_deposit_release_at": null,
  "ach_limit": "1000000.0",
  "amount": "5000000.0",
  "can_disburse": false,
  "check_mailing_address": "FundAmerica Securities\n3455 Peachtree Road, NE\n5th Floor\nAtlanta, GA 30326",
  "check_mailing_instructions": "Please make checks payable to \"FundAmerica Securities\" and include a note with your name, phone number and email address in case we have any questions.",
  "closed_at": null,
  "created_at": "2015-12-08T20:52:22.125Z",
  "description": null,
  "entity_url": "https://apps.fundamerica.com/api/entities/ys2WWghBSDqDT70Ng1DPUg",
  "escrow_closes_at": null,
  "escrow_status": "opened",
  "escrow_term_days": 365,
  "funds_disbursable": "0.0",
  "funds_in_escrow": "0.0",
  "funds_invested": "0.0",
  "funds_received": "0.0",
  "funds_refunded": "0.0",
  "funds_transfer_methods": [
    "ach",
    "check",
    "wire"
  ],
  "funds_unavailable": "0.0",
  "investment_increment_amount": null,
  "max_amount": "5500000.0",
  "max_investment_amount": null,
  "min_amount": "4500000.0",
  "min_investment_amount": null,
  "minimum_met": false,
  "name": "Big Deal",
  "non_accredited_investors": false,
  "non_us_investors": false,
  "opened_at": "2015-12-08T20:52:22.118Z",
  "payment_reference": "<INVESTOR NAME> - Big Deal",
  "regulatory_exemption": "506c",
  "regulatory_exemption_details": null,
  "security_url": null,
  "type": "equity",
  "updated_at": "2015-12-08T20:52:22.125Z",
  "us_investors": true,
  "us_states_only": null,
  "use_broker_dealer_service": false,
  "wire_details": {
    "account_number": "200000147849",
    "bank_address": "1 Bank Road\nLas Vegas, NV 89102",
    "bank_name": "Common Bank",
    "bank_phone": "(702) 555-1234",
    "beneficiary_address": "3455 Peachtree Road, NE\n5th Floor\nAtlanta, GA 30326",
    "beneficiary_name": "FundAmerica Securities, LLC",
    "routing_number": "123456789",
    "swift_code": null
  }
}

Aside from an offering's name, most of the details for an offering don't matter for all services except escrow payments. Offerings act merely as "buckets" for associating data, however in the case of escrow payments, it gets more complex. (See Escrow Payments.)

Offerings can be created with an entity as the issuer. This can be added for the sake of running background checks or, in the case of our escrow service, it is required.

Note: The issuer entity must be the actual issuer on the offering. A common mistake amongst portal operators is using their entity as the issuer. If you attempt to open escrow with the wrong issuer (meaning an entity that does not match what is listed in the PPM) your application will be denied.

If you're using a serial issuer you must provide the entity information for the project company and not the parent. It is, however, good practice to use Entity Relationships to properly associate the issuer with its parent.

Example Create

curl https://apps.fundamerica.com/api/offerings \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d accredited_investors="true" \
-d amount="5000000" \
-d description="A+really+big+deal." \
-d entity_id="nLQ8k41mTW6uX_vRxjeXdA" \
-d escrow_closes_at="2016-06-08" \
-d investment_increment_amount="1000" \
-d max_amount="5500000" \
-d max_investment_amount="25000" \
-d min_amount="4500000" \
-d min_investment_amount="1000" \
-d name="Big+Deal" \
-d non_accredited_investors="false" \
-d non_us_investors="false" \
-d regulatory_exemption="506c" \
-d type="equity" \
-d us_investors="true" \
-d us_states_only="%5B%22CA%22%2C+%22NV%22%2C+%22AZ%22%5D"

Example Update

curl https://apps.fundamerica.com/api/offerings/eij_yCDjTwmiLpE0jeDwFw \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d description="Now+bigger+than+ever%21" \
-d name="Bigger+Deal"

Request Attributes

  • accredited_investors: Whether accredited investors should be allowed to invest in this offering. (Enforced in Invest Now.)
  • amount: The target amount to raise in USD of the offering.
  • description: An optional description of the offering.
  • entity_id: The issuer.
  • escrow_closes_at: The time that the escrow is expected to close and the offering will no longer accept investments.
  • investment_increment_amount: The lowest possible increment for an investment. If set to 1000, then all investments must divide evenly by 1000. This differs from min_investment_amount in that some offerings have a high minimum (e.g. 50000) but once past the minimum, the increments are smaller (so in the case of 10000, the next investment amount would be 60000). (Leave blank if there is no increment.)
  • max_amount: If an offering allows for oversubscription, this is the maximum amount in USD.
  • max_investment_amount: The maximum investment amount allowed by an investor. (Leave blank if there is no max.)
  • min_amount: If an offering can be partially closed, this is the minimum amount in USD.
  • min_investment_amount: The minimum investment amount allowed by an investor. (Leave blank if there is no min.)
  • name: The name of the offering. The offering name can appear in certain documents (like escrow agreements) and will also appear in certain error messages. Because it will be used for virtually all interactions with customer service, it is important that is human readable and not something like a UUID. If your own system doesn't keep offering names unique, keep in mind that you'll need to add some kind of prefix or suffix to keep the name unique with FundAmerica.
  • non_accredited_investors: Whether non-accredited investors should be allowed to invest in this offering. (Enforced in Invest Now.)
  • non_us_investors: Set to true to allow non-US investors. (Default is false.)
  • regulatory_exemption: This is the regulatory exemption the offering is filed under. In most respects, this value is only important for Invest Now offerings because many portal providers manage this data at their own. The only value that affects functionality is selecting 506c as it is the only kind of offering where the confirm_accreditation parameter for investments is allowed.
    • 506c: 506(c) (default)
    • 506b: 506(b)
    • reg_a_t1: Reg A, Tier 1
    • reg_a_t2: Reg A, Tier 2
    • reg_s: Reg S
    • 4a6: 4(a)(6)
    • us_state: US State Exemptions
    • other: Other
  • type: The value can be debt or equity depending on the type of offering. The default is equity.
  • us_investors: Set to true to allow US investors. (Default is true.)
  • us_states_only: An array of states to restrict US investors to. (Leave blank for all states.)

Response Attributes

  • accept_investments: Whether or not an offering can accept investments. This is false by default and true once an (escrow service application)[#escrow-service-applications] has been accepted.
  • closed_at: The time the offering was closed or cancelled.
  • escrow_status:
    • no_escrow: Escrow is not being used for this offering.
    • pending: Escrow is pending review.
    • opened: Escrow is open and investments will be accepted.
    • closed: Escrow has been closed and investments will no longer be accepted.
    • cancelled: Escrow has been cancelled and investments will no longer be accepted.
  • funds_in_escrow: The total amount of funds in escrow for the offering.
  • funds_invested: The total amount of funds invested in offering.
  • funds_received: The total amount of funds received for the offering.
  • funds_refunded: The total amount of funds refunded by the offering..
  • opened_at: The time that an offering was opened for taking investments. This only matters for offerings using the escrow service.
  • use_broker_dealer_service: Whether or not Broker Dealer Services are being used for this offering.

Offering's Investments

It is possible to get a list of investments for a specific offering by adding "investments" to the end of the API call.

Example Get

curl https://apps.fundamerica.com/api/offerings/tjXUYmqYQRyAPUmTX0HNYQ/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Additionally, see Investments for information on check_mailing_address, check_mailing_instructions, payment_reference and wire_details.

Escrow Payments

Handling escrow payments is easily the most complex process in the entire system. It requires a number of different objects to be created with a lot of manual processing in the background. FundAmerica representatives will be reviewing almost every aspect of the process behind-the-scenes.

A brief overview of each step and an explanation of the process will be outlined below. Technical details on API calls will follow.

While there are a lot of steps to the process, as you make test calls to the API, if you forget a step in the process, the error messages will generally lead you back in the right direction.

Overview

Handling escrow payments happens in three steps:

  1. An escrow account must be set up and accepted for the offering.
  2. Investments must be made.
  3. The offering must be either closed or cancelled to disperse funds.

Opening an Escrow Account

Opening an escrow account requires the following steps:

  1. Create an offering with an issuer entity.
  2. Generate an escrow agreement for the issuert.
  3. Have the issuer sign the escrow agreement.
  4. Generate a tech services agreement for the issuer or platform operator.
  5. Generate a registered transfer agent agreement for the issuer if you are using FundAmerica Stock Transfer as your RTA.
  6. Have the issuer or platform operator sign the escrow agreement.
  7. Create an escrow service application.

This process sets forth the details of the offering and the issuer. Once the escrow service application has been created, the credit on file will be charged the appropriate amount for services (see your account fee schedule for the details on an escrow application fee, the first escrow monthly administration fee and a background check fee on the issuer) and FundAmerica representatives will verify the offering and issuer information, run a background and AML check on the issuer and review the PPM provided in the application.

If there is a problem or something does not check out, the issuer will be contacted directly to resolve any potential problems.

If everything checks out, the application will be accepted and an escrow account will be opened for the offering. You will now be able to submit investments.

Making Investments

Making investments is the simplest part of the process. It is done by creating investments.

Closing or Cancelling Offerings

An offering may be closed when the issuer wishes to have funds dispersed to the issuer or an issuer may wish to cancel an offering and refund all investors. This is done by creating a close offering request or a cancel offering request.

Either request will result in a customer service follow-up with the issuer to confirm the process. So, if a cancel request comes in, FundAmerica will contact the issuer to confirm that this is what is desired before processing it and refunding the investments.

Escrow Payment API Reference

Cancel Offering Requests

This simply requests that an offering be cancelled and all investors receive refunds. When confirmed, funds in escrow will be refunded and the offering will no longer be able to accept investments.

The only special case is that only one request to cancel can exist at a time. Attempts to create more will result in errors. If a request to close the offering is being reviewed, a request to cancel cannot be made. Finally, if an offering has been partially closed, it cannot be cancelled.

A comment is optional. It's there if you want to give customer service any special instructions.

Example Object

{
  "object":"cancel_offering_request",
  "id":"6dM6MdWlTVa1WNSaCzCikw",
  "url":"https://apps.fundamerica.com/api/cancel_offering_requests/6dM6MdWlTVa1WNSaCzCikw",
  "offering_url":"https://apps.fundamerica.com/api/offerings/3E2NEf0nS4OtRrRWM4JngA",
  "comment":"Please cancel this. Thanks.",
  "created_at":"2014-11-02T04:01:44.715Z",
  "status":"pending",
  "updated_at":"2014-11-02T04:01:44.715Z"
}

Request Attributes

  • comment: An optional comment giving special instructions to customer service.
  • offering_id: The offering you wish to cancel.

Response Attributes

  • status: It can be one of three values:
    • pending: Being reviewed.
    • confirmed: The offering was cancelled as result.
    • rescinded: When the issuer was contacted, they didn't confirm the cancellation.

Example Create

curl https://apps.fundamerica.com/api/cancel_offering_requests \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d offering_id="XOxZSJvcQFSsaLDKUsxxpg" \
-d comment="Please cancel this. Thanks."

Close Offering Requests

This requests that an offering be closed or partially closed. When accepted, funds in escrow will be transferred to the issuer minus any fees.

Close requests are reviewed by FundAmerica and either accepted or denied.

Example Object

{
  "object":"close_offering_request",
  "id":"VbyEaymPQMK07y2tbkVYlA",
  "url":"https://apps.fundamerica.com/api/close_offering_requests/VbyEaymPQMK07y2tbkVYlA",
  "offering_url":"https://apps.fundamerica.com/api/offerings/3E2NEf0nS4OtRrRWM4JngA",
  "comment":"Please close this partially. Thanks.",
  "created_at":"2014-11-02T04:03:08.758Z",
  "partial":true,
  "status":"pending",
  "updated_at":"2014-11-02T04:03:08.758Z"
}

Request Attributes

  • comment: An optional comment giving special instructions to customer service.
  • offering_id: The offering you wish to close.

Response Attributes

  • status: It can be one of three values:
    • pending: Being reviewed.
    • accepted: Funds will be dispersed to the issuer and, in the case of a non-partial close, the offering will be closed and no further investments allowed.
    • denied: There was a problem with the request or it didn't meet the prerequisites for a close.

Example Create

curl https://apps.fundamerica.com/api/close_offering_requests \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d offering_id="XOxZSJvcQFSsaLDKUsxxpg"

Escrow Agreements

An escrow agreement is a document that must be electronically signed by the issuer and sets forth the terms of the escrow account, the fees to be charged and a lot of other legally relevant information.

Creating an escrow agreement will provide you with a link to send to the issuer so that they can sign the document digitally. Additionally, if you wish to embed this document in your own interface, use body_html and the Electronic Signatures API.

API Endpoints

GET    https://apps.fundamerica.com/api/escrow_agreements
POST   https://apps.fundamerica.com/api/escrow_agreements
GET    https://apps.fundamerica.com/api/escrow_agreements/:id

Example Object

{
  "object": "escrow_agreement",
  "id": "3N2YTNg1TwK5fg4xxvZhvA",
  "url": "https://apps.fundamerica.com/api/escrow_agreements/3N2YTNg1TwK5fg4xxvZhvA",
  "offering_url": "https://apps.fundamerica.com/api/offerings/yDx_9HKFR0y7nr4gvDyANA",
  "archived_pdf_url": null,
  "body_html": " ... escrow agreement HTML ... ",
  "created_at": "2016-09-19T18:31:31.134Z",
  "electronic_signatures": [
    {
      "object": "electronic_signature",
      "id": "kBsM3hS7Tdil5Qufu5I23Q",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/kBsM3hS7Tdil5Qufu5I23Q",
      "anchor_id": "issuer_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/escrow_agreements/3N2YTNg1TwK5fg4xxvZhvA",
      "email": "john.johnson@johnson.com",
      "literal": null,
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    },
    {
      "object": "electronic_signature",
      "id": "BD1mcoMSRmKmjuRlFIA47Q",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/BD1mcoMSRmKmjuRlFIA47Q",
      "anchor_id": "trustee_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/escrow_agreements/3N2YTNg1TwK5fg4xxvZhvA",
      "email": null,
      "literal": null,
      "name": null,
      "signable": false,
      "signed": false,
      "signed_at": null,
      "title": null
    }
  ],
  "signed": false,
  "signing_links": {
    "issuer_signature": {
      "expires": "2016-09-22T18:31:31.199Z",
      "url": "https://apps.fundamerica.com/sign/rdM1K6wB3kMjrdU1jJJzW_ewkyxHZvwC"
    }
  },
  "updated_at": "2016-09-19T18:31:31.134Z"
}

Request Attributes

  • offering_id: The offering related to the escrow agreement.

Response Attributes

  • archived_pdf_url: Once the document has been signed, an archived PDF copy can be found at this location.
  • body_html: The body HTML of the document. If you wish to embed the document in your own interface for signature collection, use this. Even if you have provided a full HTML document, this is ONLY the content inside the <body>. The only exception is that if <style> directives exist in the <head>, they will be included in the body for formatting purposes.
  • electronic_signatures: See Electronic Signatures for more details.
  • signed: Whether or not the document has been signed.
  • signing_links: A list of available signatures, their signing links and when those links expire (defaults to one day from the time of creation). In the case of an escrow agreement, there will only be an "issuer_signature."

Note: A return_url query string can be added to the signing URL and the signer will be redirected to the return_url when the document is signed.

Example Create

curl https://apps.fundamerica.com/api/tech_services_agreements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d offering_id="VTJqahTwR1m6b-MgfHcZ5A"

Tech Services Agreements

Tech services agreements must also be signed before escrow can be opened for an account. Unlike the Escrow Agreement it may be signed by either the issuer or the platform operator, depending on who is taking financial responsibility for the fees being charged through FundAmerica's system. If you are operating a platform where you are billing your issuers directly, rather than having them pay FundAmerica's fees, you should sign this document. Other than the endpoints, it operates identically to Escrow Agreements.

Creating a tech services agreement will provide you with a link to send to the responsible party so that they can sign the document digitally. Additionally, if you wish to embed this document in your own interface, use body_html and the Electronic Signatures API.

API Endpoints

GET    https://apps.fundamerica.com/api/tech_services_agreements
POST   https://apps.fundamerica.com/api/tech_services_agreements
GET    https://apps.fundamerica.com/api/tech_services_agreements/:id

Example Object

{
  "object": "tech_services_agreement",
  "id": "UaXii0EgQC6sQsZtwTgMyQ",
  "url": "https://apps.fundamerica.com/api/tech_services_agreements/UaXii0EgQC6sQsZtwTgMyQ",
  "offering_url": "https://apps.fundamerica.com/api/offerings/H9OE4fTUTbKeBgMZWIVRMw",
  "archived_pdf_url": null,
  "body_html": " ... tech services agreement HTML ... ",
  "created_at": "2016-09-19T18:32:05.904Z",
  "electronic_signatures": [
    {
      "object": "electronic_signature",
      "id": "MhBXmyNUTp-dukkbhxyjMw",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/MhBXmyNUTp-dukkbhxyjMw",
      "anchor_id": "issuer_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/tech_services_agreements/UaXii0EgQC6sQsZtwTgMyQ",
      "email": "john.johnson@johnson.com",
      "literal": null,
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    },
    {
      "object": "electronic_signature",
      "id": "NFZxrBFtTnSdtMotyU97Tw",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/NFZxrBFtTnSdtMotyU97Tw",
      "anchor_id": "technologies_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/tech_services_agreements/UaXii0EgQC6sQsZtwTgMyQ",
      "email": null,
      "literal": null,
      "name": null,
      "signable": false,
      "signed": false,
      "signed_at": null,
      "title": null
    }
  ],
  "signed": false,
  "signing_links": {
    "issuer_signature": {
      "expires": "2016-09-22T18:32:05.964Z",
      "url": "https://apps.fundamerica.com/sign/HAyL7hVlnKKnScLECFKBV6bUcJ2LPeSc"
    }
  },
  "updated_at": "2016-09-19T18:32:05.904Z"
}

Request Attributes

  • offering_id: The offering related to the tech services agreement.

Response Attributes

  • archived_pdf_url: Once the document has been signed, an archived PDF copy can be found at this location.
  • body_html: The body HTML of the document. If you wish to embed the document in your own interface for signature collection, use this. Even if you have provided a full HTML document, this is ONLY the content inside the <body>. The only exception is that if <style> directives exist in the <head>, they will be included in the body for formatting purposes.
  • electronic_signatures: See Electronic Signatures for more details.
  • signed: Whether or not the document has been signed.
  • signing_links: A list of available signatures, their signing links and when those links expire (defaults to one day from the time of creation). In the case of an escrow agreement, there will only be an "issuer_signature."

Note: A return_url query string can be added to the signing URL and the signer will be redirected to the return_url when the document is signed.

Example Create

curl https://apps.fundamerica.com/api/tech_services_agreements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d offering_id="VTJqahTwR1m6b-MgfHcZ5A"

Registered Transfer Agent Agreements

Registered Transfer Agent agreements must be signed if you plan on using FundAmerica Stock Transfer as your registered transfer agent. Other than the endpoints, it operates identically to Escrow Agreements.

Creating an RTA agreement will provide you with a link to send to the responsible party so that they can sign the document digitally. Additionally, if you wish to embed this document in your own interface, use body_html and the Electronic Signatures API.

API Endpoints

GET    https://apps.fundamerica.com/api/rta_agreements
POST   https://apps.fundamerica.com/api/rta_agreements
GET    https://apps.fundamerica.com/api/rta_agreements/:id

Example Object

{
  "object": "rta_agreement",
  "id": "0m0eLD2kQhKx3wjottPC6g",
  "url": "https://apps.fundamerica.com/api/rta_agreements/0m0eLD2kQhKx3wjottPC6g",
  "offering_url": "https://apps.fundamerica.com/api/offerings/rWj6bBQ0Rd2xc8V2G6SUcw",
  "archived_pdf_url": null,
  "body_html": " ... RTA agreement HTML ... ",
  "created_at": "2016-11-17T16:54:37.083Z",
  "electronic_signatures": [
    {
      "object": "electronic_signature",
      "id": "ZcZPZ8L5SBuIIdjHRE_vTA",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/ZcZPZ8L5SBuIIdjHRE_vTA",
      "anchor_id": "issuer_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/rta_agreements/0m0eLD2kQhKx3wjottPC6g",
      "email": "john.johnson@johnson.com",
      "literal": null,
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    },
    {
      "object": "electronic_signature",
      "id": "bkiojVkDQs2ZVlMPd16M7Q",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/bkiojVkDQs2ZVlMPd16M7Q",
      "anchor_id": "transfer_agent_signature",
      "company": null,
      "data": {
      },
      "document_url": "https://apps.fundamerica.com/api/rta_agreements/0m0eLD2kQhKx3wjottPC6g",
      "email": null,
      "literal": null,
      "name": null,
      "signable": false,
      "signed": false,
      "signed_at": null,
      "title": null
    }
  ],
  "signed": false,
  "signing_links": {
    "issuer_signature": {
      "expires": "2016-11-24T16:54:37.122Z",
      "url": "https://apps.fundamerica.com/sign/C5Ktt4jnTRqQxUrnbFmhiD8LcW1kVtYV"
    }
  },
  "updated_at": "2016-11-17T16:54:37.083Z"
}

Request Attributes

  • offering_id: The offering related to the RTA agreement.

Response Attributes

  • archived_pdf_url: Once the document has been signed, an archived PDF copy can be found at this location.
  • body_html: The body HTML of the document. If you wish to embed the document in your own interface for signature collection, use this. Even if you have provided a full HTML document, this is ONLY the content inside the <body>. The only exception is that if <style> directives exist in the <head>, they will be included in the body for formatting purposes.
  • electronic_signatures: See Electronic Signatures for more details.
  • signed: Whether or not the document has been signed.
  • signing_links: A list of available signatures, their signing links and when those links expire (defaults to one day from the time of creation). In the case of an escrow agreement, there will only be an "issuer_signature."

Note: A return_url query string can be added to the signing URL and the signer will be redirected to the return_url when the document is signed.

Example Create

curl https://apps.fundamerica.com/api/rta_agreements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d offering_id="VIPsVOOAS5aXvR4SqKwCzg"

Escrow Service Applications

An escrow service application is a request to open an escrow account. It provides customer service with all the data that is necessary to open an account. In addition to the request attributes it accepts, it will return errors if the offering is lacking required information.

Also note that the credit card on file will be charged when an application is submitted.

API Endpoints

GET    https://apps.fundamerica.com/api/escrow_service_applications
POST   https://apps.fundamerica.com/api/escrow_service_applications
GET    https://apps.fundamerica.com/api/escrow_service_applications/:id

Example Object

{
  "object": "escrow_service_application",
  "id": "oXjV-_NBSse9kMi_UaLkqA",
  "url": "https://apps.fundamerica.com/api/escrow_service_applications/oXjV-_NBSse9kMi_UaLkqA",
  "offering_url": "https://apps.fundamerica.com/api/offerings/HBRCNBcpQA-dk8gVuo6DEA",
  "created_at": "2016-09-19T18:51:52.276Z",
  "denial_message": null,
  "ppm_password": null,
  "ppm_url": "http://www.example.com/ppm.html",
  "ppm_username": null,
  "status": "pending",
  "updated_at": "2016-09-19T18:51:52.276Z"
}

Request Attributes

  • offering_id: The related offering.
  • escrow_agreement_id: A signed escrow agreement.
  • ppm_password: An optional login password for viewing the PPM.
  • ppm_url: A link to information about the offering. It can be the offering URL on your portal or a PDF containing the PPM. It just needs to be information that customer service can review regarding the offering.
  • ppm_username: An optional login username for viewing the PPM.

Note: The PPM URL will often require a login on your platform in order to view an offering's contents. This can be handled in a number of ways:

  1. You can create an account for FundAmerica on your platform that gives our customer service representatives access to view the offering. Create an account and provide the username and password as ppm_username and ppm_password.
  2. Include some kind of token in the URL.
  3. If your platform utilizes HTTP authentication, you can simple embed that in ppm_url.

It's important to make sure FundAmerica has access to the offering as soon as possible. If customer service has to reach out to you for more information it can greatly delay the escrow service application approval process.

Response Attributes

  • denial_message: If your application is denied, this will list the reason why. Typically, this is either due to a problem with the PPM or a mismatch of information between the PPM and what was provided to the API (e.g. different amounts listed, incorrect issuer, etc.).
  • status: It can be one of three values:
    • pending: Being reviewed.
    • accepted: The escrow account has been opened and your offering can now accept investments.
    • denied: There was a problem with the application that customer service was unable to resolve.

Example Create

curl https://apps.fundamerica.com/api/escrow_service_applications \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d escrow_agreement_id="XSB4gInwSBa4eA8BX7mhXg" \
-d ppm_username="fundamerica" \
-d ppm_url="http%3A%2F%2Fwww.example.com%2Fppm.html" \
-d ppm_password="secret" \
-d offering_id="7QSCpUdORjyWJseekYjD6g"

Escrow Disbursements

Once an Offering has received its minimum amount in funds, you can begin disbursing funds from escrow, either to the issue or another party.

API Endpoints

GET    https://apps.fundamerica.com/api/disbursements
POST   https://apps.fundamerica.com/api/disbursements
GET    https://apps.fundamerica.com/api/disbursements/:id
PATCH  https://apps.fundamerica.com/api/disbursements/:id
DELETE https://apps.fundamerica.com/api/disbursements/:id
GET    https://apps.fundamerica.com/api/offerings/:id/disbursements
PATCH  https://apps.fundamerica.com/api/test_mode/disbursements/:id

Example Object

{
  "object": "disbursement",
  "id": "ZgCRtVDZQB--joz_Di_DMw",
  "url": "https://apps.fundamerica.com/api/disbursements/ZgCRtVDZQB--joz_Di_DMw",
  "amount": "15000.0",
  "bank_transfer_method_url": "https://apps.fundamerica.com/api/bank_transfer_methods/iQ9NhN8ORFGc1dfqQi7byA",
  "check_mailing_address": null,
  "check_payee": null,
  "city": "New York",
  "contact_name": "John Johnson",
  "country": "US",
  "created_at": "2015-07-06T20:51:46.540Z",
  "disbursed_at": null,
  "email": "john.johnson@johnson.com",
  "name": "John Johnson",
  "offering_url": "https://apps.fundamerica.com/api/offerings/U3f6sp1PS1ik1j7OtgxVRg",
  "payment_details": null,
  "payment_method": "wire",
  "phone": "12025551212",
  "postal_code": "10022",
  "reference": "Property ID: 1234567890",
  "region": "NY",
  "status": "pending",
  "street_address_1": "520 Park Ave",
  "street_address_2": "Ste 31",
  "updated_at": "2015-07-06T20:51:46.540Z"
}

Example Create

curl https://apps.fundamerica.com/api/disbursements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d status="pending" \
-d amount="15000.0" \
-d city="New+York" \
-d country="US" \
-d email="john.johnson%40johnson.com" \
-d name="John+Johnson" \
-d phone="12025551212" \
-d postal_code="10022" \
-d region="NY" \
-d street_address_1="520+Park+Ave" \
-d street_address_2="Ste+31" \
-d reference="Property+ID%3A+1234567890" \
-d bank_transfer_method_id="O-TgPyiqStSEmIm60rEqog" \
-d offering_id="Hg3dwB8WSRGahccfaqxLlg"

Request Attributes

  • amount: The amount to disburse to the named party.
  • bank_transfer_method_id: Must be an ACH bank transfer method. Use if paying via ACH or wire.
  • check_mailing_address: If paying by check, the address to mail the check to.
  • check_payee: If paying by check, the entity to make the check out to.
  • reference: Details about the disbursement. Note: If the disbursement is going to a third party in a manner that needs to be identified, you must use either a check or wire as the method. The reason for this is there is no way to designate any sort of reference in a standard ACH payment. So, for example, if you wanted funds disbursed from escrow directly to another company to purchase property and needed to include a property ID in the reference, you would need to use check or wire. When used on an ACH type, reference is purely for internal purposes.

Response Attributes

  • disbursed_at: When the actual disbursement was made.
  • payment_details: Details about the disbursement when it was paid such as the ACH batch ID or the check number.
  • payment_method: The method that the disbursement was made. ach, check or wire.
  • status:
    • pending: Information about the disbursement specifics has been received.
    • disbursed: Funds have transfered.
    • voided: In the event of an error or the cancellation of a distributions, an investor disbursement becomes voided.

Disbursement Test Mode

On the sandbox, test calls can be made to update the status on a disbursement.

Example Test Mode Update

curl https://apps.fundamerica.com/api/test_mode/disbursements/ZIVJyEasS-q9GUwt7_kcFA \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="disbursed"

Escrow Ledger

An escrow ledger tracks the transactions of an offering's escrow.

Example Object

{
  "object":"ledger_entry",
  "id":"ZzHv4JuDEeSY79ehFBfhbg",
  "balance":"12500.0",
  "created_at":"2015-01-14T00:22:20.227Z",
  "credit":"500.0",
  "debit":null,
  "description":"Received funds from investor John Smith",
  "investment_payments":[{"status":"received","url":"https://apps.fundamerica.com/api/investment_payments/truzQuU6TcS8pAS1ZzwF6w"}]
}

Example Get

curl https://apps.fundamerica.com/api/offerings/:id/escrow_ledger \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Response Attributes

  • balance: The total balance after this transaction cleared.
  • credit: Amount credited to the escrow ledger.
  • debit: Amount debited from the escrow ledger.
  • description: A description of the ledger entry.
  • investment_payments: Related investment payments.

Investments

Investments are made when an investor wants to invest in an offering and send funds for said investment. Investments are probably the single most complex object in the system. It's important to understand all the status settings and payment methods involved.

An AML check is automatically processed on every single investment. FundAmerica customer service will do a follow-up if there are any issues with the background check and may cancel the result if there are problems. The results of this background check are available to your account if you have requested permission and been accepted for processing AML checks on your account. Please see AML and Bad Actors Checks for more information on this process and details on the API calls.

When an investment is made, customer service will review the details before changing the status type. They may even opt to cancel the investment if there is a problem. If you want to give immediate feedback to your investors, it's important to utilize webhooks for status updates.

Update: Although the examples below show the use of entity_id, it's better to use Investors instead. This is a fairly new API, so if you have have an older implementation, this is worth having a look at.

Note: An offering must have accept_investments set to true to create investments, otherwise you will receive a 403 error. This is done by having an escrow service application accepted.

API Endpoints

GET    https://apps.fundamerica.com/api/investments
POST   https://apps.fundamerica.com/api/investments
GET    https://apps.fundamerica.com/api/investments/:id
PATCH  https://apps.fundamerica.com/api/investments/:id
DELETE https://apps.fundamerica.com/api/investments/:id
GET    https://apps.fundamerica.com/api/offerings/:id/investments
PATCH  https://apps.fundamerica.com/api/test_mode/investments/:id
PATCH  https://apps.fundamerica.com/api/test_mode/trade_reviews/:id

Example Object

{
  "object": "investment",
  "id": "Tj0DEEYGSzCLqU6RFkfI7g",
  "url": "https://apps.fundamerica.com/api/investments/Tj0DEEYGSzCLqU6RFkfI7g",
  "offering_url": "https://apps.fundamerica.com/api/offerings/8KzwIcdfTLSL1igSP8tEXA",
  "amount": "50000.0",
  "amount_in_escrow": "0.0",
  "amount_received": "0.0",
  "amount_refunded": "0.0",
  "aml_exception": true,
  "background_check_url": null,
  "brokerage_fee": "0.0",
  "check_mailing_address": "FundAmerica Securities\n3455 Peachtree Road, NE\n5th Floor\nAtlanta, GA 30326",
  "check_mailing_instructions": "Please make checks payable to \"FundAmerica Securities\" and include a note with your name, phone number and email address in case we have any questions.",
  "cleared": false,
  "clearing_failures": [

  ],
  "created_at": "2015-11-12T22:30:33.134Z",
  "data": {
  },
  "debt_face_value": null,
  "debt_par_value": null,
  "entity_url": "https://apps.fundamerica.com/api/entities/PH4PLkkJR1eBbwFcpSWYWw",
  "equity_share_count": "10.0",
  "equity_share_price": "5000.0",
  "financial_adviser_name": null,
  "funds_disbursable": 0,
  "investor_url": "https://apps.fundamerica.com/api/investors/AcDqHluSTJy1nPjo7om1Ww",
  "payment_method": "wire",
  "payment_reference": "Dale Mulford - Example Offering 2",
  "review_trade": true,
  "status": "not_received",
  "subscription_agreement_url": "https://apps.fundamerica.com/api/subscription_agreements/hXu5U0-ETjSu35u0bSW9BQ",
  "technology_fee": "0.0",
  "trade_review_status": "pending",
  "trade_review_url": "https://apps.fundamerica.com/api/trade_reviews/MXVor9IfSVGSaHUe5fcKeA",
  "updated_at": "2015-11-12T22:30:33.134Z",
  "wire_details": {
    "account_number": "200000147849",
    "bank_address": "1 Bank Road\nLas Vegas, NV 89102",
    "bank_name": "Common Bank",
    "bank_phone": "(702) 555-1234",
    "beneficiary_address": "3455 Peachtree Road, NE\n5th Floor\nAtlanta, GA 30326",
    "beneficiary_name": "FundAmerica Securities, LLC",
    "routing_number": "123456789",
    "swift_code": null
  }
}

Example Create (Equity with ACH)

curl https://apps.fundamerica.com/api/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d amount="1000000.0" \
-d equity_share_count="10" \
-d offering_id="D9rgFWCxQBOX2kik7hMswA" \
-d payment_method="ach" \
-d entity_id="3ErEdqaBRzyaOHI-wymgDA" \
-d ach_authorization_id="c1iNJPrgToCWwLOD3pAhgg"

Example Create (Debt with Check)

curl https://apps.fundamerica.com/api/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d debt_face_value="1000000.0" \
-d offering_id="f6U4DkfyRc-pYtRAuxx9dQ" \
-d entity_id="_JstKMneSDOsKPf-4JxtQw" \
-d payment_method="check"

Example Create (Trade Review with Wire)

curl https://apps.fundamerica.com/api/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d amount="50000" \
-d equity_share_count="10" \
-d offering_id="8KzwIcdfTLSL1igSP8tEXA" \
-d payment_method="wire" \
-d entity_id="PH4PLkkJR1eBbwFcpSWYWw" \
-d review_trade="true" \
-d subscription_agreement_id="hXu5U0-ETjSu35u0bSW9BQ"

Example Update

curl https://apps.fundamerica.com/api/investments/p72dNostTdeR52HtBC5qiQ \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d subscription_agreement_id="TmBvoxXFRDO1moomLexgKg"

Request Attributes

  • ach_authorization_id: The ACH authorization used for an ACH payment. Required if payment_method is set to ach. See ACH Authorizations for information on creating ACH authorizations.
  • aml_check_investor: Whether or not to process an AML check on the investor.
  • amount: The amount in USD of the investment. Required.
  • confirm_accreditation: If you want to prevent the investment from clearing until accreditation is confirmed via a service working with FundAmerica, set this to true. If false (the default), confirmation of investor accreditation is presumed to be issuer's responsibility. Even if using your service, without setting this flag to true investments can still clear regardless of the status. This option allows platforms to mix and max how accreditation is performed and cleared.
  • debt_face_value: The face value of a debt investment. This is just an alias for amount since they are one in the same, but for the sake of clarity in some code, you can use debt_face_value instead.
  • debt_par_value: The par value of the debt investment. Must match what is detailed in the subscription agreement. Required if offering type is debt. If left blank, it will be set to the same value as amount.
  • entity_id: The entity making the investment. If entity parameters are provided instead, the entity created or updated will be used. Required.
  • equity_share_count: The number of shares being purchased. Must match what is detailed in the subscription agreement. Required if offering type is equity.
  • investor_id: The investor to use. Can be used in place of entity_id.
  • offering_id: The offering to invest in.
  • payment_method: Must be set to one of three values: ach, check, wire. Required.
  • review_trade: This must be set to true in order to use broker-dealer services. If it is true then Jumpstart Securities is the broker-dealer of record for the investor on this investment. On offerings using the broker-dealer services this value can be manually set to false.
  • subscription_agreement_id: The ID of a Subscription Agreement created using the FundAmerica API. If using our broker-dealer services, it will be required to be provided for the investment before the offering closes. In all other cases it is entirely optional.
  • subscription_agreement_url: A URL containing the signed subscription agreement. (Preferably a PDF.) If using our broker-dealer services, it will be required to be provided for the investment before the offering closes. In all other cases it is entirely optional. See External Subscription Agreements for more details.

Response Attributes

  • aml_exception: true if the background check was questionable for some reason. This could mean anything from the entity appearing on a global watch list to a mistyped tax ID number.
  • amount_in_escrow: The amount of funds in the escrow account in USD.
  • amount_received: The amount of funds received by FundAmerica from the investor in USD.
  • amount_refunded: The amount of funds refunded by FundAmerica from the investor in USD.
  • background_check_url: The background check that was processed on the investor entity.
  • check_mailing_address: Where to mail checks if payment_method is set to check. Additionally, this address should be used for the address on a wire payment if the bank requires an address for the wire.
  • check_mailing_instructions: Additional instructions regarding mailing checks if payment_method is set to check.
  • cleared: true if all funds are available and possible AML exceptions and trade reviews have cleared. This will trigger a webhook when changed.
  • clearing_failures: An array of reasons an investment is not cleared. These only appear after funds are eligible or a disbursement occurs. All investments begin with cleared set to false. Possible values are:
    • accreditation_pending
    • aml_pending
    • funds_not_cleared
    • subscription_agreement_not_signed
    • trade_review_pending
  • equity_share_price: The price per share.
  • payment_reference: A short code that the investor should include with any manually initiated (e.g. check or wire) transfer.
  • status: See next section.
  • trade_review_status: The status of a trade review. It can be set to one of four values:
    • null: The offering either isn't using our broker-dealer services or review_trade has been set to false.
    • pending: The trade review is currently being reviewed by customer service.
    • accepted: The trade review has been accepted and FundAmerica Securities will act as the broker-dealer of record for this investor on this investment.
    • denied: The trade review has been denied and the investment has been cancelled.
  • trade_review_url: Location of the specific trade review object.
  • wire_details: Information that the investor should use when wiring their investment.

Investment Status

An investment object has a status field which indicates the status of the investment. There are six possible settings: not_received, received, cancelled, voided, refunded and invested.

  • not_received: The funds for an investment have not been received and accepted.
  • received: The funds for an investment have been received and accepted. This means customer service has verified the funds, reviewed the subscription agreement and made sure everything looks correct. If there is a problem, customer service will either cancel the investment or contact the issuer and/or investor to resolve the issue. Even in the case of ACH investments, the investment will not be updated as "received" until this has occured. Customer service review will generally happen within one business day of receipt of funds.
  • cancelled: The investment has been cancelled. If the previous status was not_received then the investment will be immediately voided. If the previous status was received then a refund will be processed.
  • voided: An investment was cancelled before funds were received.
  • refunded: An investment was cancelled after funds were received and the actual refund has been issued.
  • invested: The offering related to the investment has been closed or partially closed. An investment cannot be cancelled at this point.

Updating Investments

Certain investment details can be updated once an investment has been created under certain circumstances. These include:

  • ach_authorization_id
  • payment_method
  • subscription_agreement_url

Cancelling Investments

Investments need to be able to be cancelled at any time before they are invested by both the issuer and investor. Additionally, if there is a problem with an investment, customer service may cancel an investment.

It's worth noting that changing state via test mode calls will trigger webhooks.

Example Cancel

curl https://apps.fundamerica.com/api/investments/O09RLSh-QBKED7BbeLQ2KQ \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X DELETE

Investment Test Mode

On the sandbox, test calls can be made to update the status on an investment.

Status Update

curl https://apps.fundamerica.com/api/test_mode/investments/1zo3pMT-SYOjwL_9cHuc3A \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="received"

Aditionally, on the sandbox, test calls can be made to update the status on a trade review.

Trade Review Update

curl https://apps.fundamerica.com/api/test_mode/trade_reviews/TgsH7PaQRIW14swYmWAMVw \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="accepted"

External Subscription Agreements

Subscription agreements are required for investments where Broker Dealer Services are used. They must be provided before an offering is closed, but can be provided either at the creation of the investment, or updated later.

When subscription_agreement_url is provided, our system will attempt to download and archive the provided link. This attempt will take place shortly after the investment is created. In the event of a failure, our system will try again once every minute for ten minutes. This way, if your final documents are created asynchronously and aren't ready immediately, our system will get them within a few minutes.

At this point you'll need to update the investment with a different subscription_agreement_url in order to have it try again.

Investors

When this API was first created, Entities were used directly as the investor. This model was not suitable for joint investors as they are multiple entities, but unlike a trust or company, they cannot be represented in an hierarchical manner as another entity. As such, a separate investor object was introduced to deal with this. Since joint investors have been available, the creation of joint investors has been entirely transparent. However, the investors are being extended to encompass additional investor types, such as IRAs and, in the future, it is likely their functionality will be expanded to meet the needs of different possible investor types.

When investing using an entity_id, a default investor is created for the entity if one does not already exist and is used for the investment. Simple investors, also known as "proxy investors," are investors with the same type as an entity. When an entity is updated, for instance, when their name is updated, said entity's vesting_name is also updated. For many operations, such as determining address or other contact information, the primary_entity of the investor is delegated to.

Investors, for the most part, are just a collection of entities and a type designation which is used for validation. Sometimes it's a single entity in the case of a simple investor. Sometimes it's multiple entities in the case of a joint investor. IRAs also use multiple entities (the primary and the custodian) but in a different way.

It is recommended that if you're not supporting a legacy system, you explicitly create and track investors and use them for investments instead of entities. In the next version of this API, this will be required.

API Endpoints

GET    https://apps.fundamerica.com/api/investors
POST   https://apps.fundamerica.com/api/investors
GET    https://apps.fundamerica.com/api/investors/:id
PATCH  https://apps.fundamerica.com/api/investors/:id

Example Object

{
  "object": "investor",
  "id": "mLybIF_1Ql-HySEe7kZXcg",
  "url": "https://apps.fundamerica.com/api/investors/mLybIF_1Ql-HySEe7kZXcg",
  "custodian_entity_url": null,
  "entity_urls": [
    "https://apps.fundamerica.com/api/entities/U0DcNMn3TKK6zpNXwY1W9g%2FxAgo_mOYQ3umdavnlviVHg"
  ],
  "primary_entity_url": "https://apps.fundamerica.com/api/entities/U0DcNMn3TKK6zpNXwY1W9g",
  "type": "jtwros",
  "vesting_name": "John Jr. and Jane Johnson"
}

Example Create (Proxy)

curl https://apps.fundamerica.com/api/investors \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d primary_entity_id="-9ymE6xLQsmZQOxU4d5JDQ"

Passing a lone entity_id will create an investor with the same type as the entity and a vesting_name equal to the entity's name. The vesting_name for proxy investors is generated automatically and cannot be overridden.

Example Create (Joint)

curl https://apps.fundamerica.com/api/investors \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d other_entity_ids="z8SIMQqLQQa7fZGGAJR6Sg" \
-d primary_entity_id="GQa6QMJVSo-dkQZOBM_9_g" \
-d type="jtwros"

Passing multiple entities and an appropriate type will create a joint investor. jtic (joint tenant in common) or jtwros (joint tenant with rights of survivorship) are appropriate joint types. The vesting_name for joint investors is generated automatically and cannot be overridden.

Example Create (IRA)

curl https://apps.fundamerica.com/api/investors \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d custodian_entity_id="nWyWwtb1Rfa-Lwh9TXHEJQ" \
-d primary_entity_id="GQa6QMJVSo-dkQZOBM_9_g" \
-d type="ira" \
-d vesting_name="IRA+Trust+Company+LLC+FBO+John+Johnson+Jr.+IRA"

IRAs, like joint investors, are another example of an investor that didn't map cleanly to an entity or their hierarchical relationships. IRAs have a primary entity, which is always the beneficiary, and a custodian, which is generally the company managing the IRA. To create an IRA you must create two entities: the person investing and the custodian. The custodian must be a company and needs full contact information, including a tax_id_number. While this is not used for AML purposes, it is necessary for tax reporting purposes.

For an example flow, please visit our Invest Now demo and click "Invest Now" then choose the "Self-Directed IRA" option as your investor.

IRAs have their own vesting_name. It should generally look something like: "Example Trust Company FBO John Johnson" (FBO means For Benefit Of), however the naming is specific to each trust company, so it is not automatically generated and must be provided.

Investors using IRAs should know this information and are generally given paperwork that includes instructions on exactly how to fill out this information.

Request Attributes

  • custodian_entity_id: The custodian for an IRA. If the type is ira this is required. For all other types it should not be provided.
  • other_entity_ids: Required when creating joint investors. It must be a single entity ID or array of entity IDs. These are all the entities involved in the joint investment.
  • primary_entity_id: The primary entitiy for the investor. This is the person or company investing in most cases. For joint investors this entity has special designation as being the the main contact point.
  • type: The investor's type. This can be a proxy type (person, company), a joint type (jtic, jtwros) or an IRA (ira). It is very likely there will be additional types in the future.
  • vesting_name: The vesting name of the investor. This is usually automatically generated, but if type is ira it must be provided.

Investors Used in Place of Entities

The most obvious API where an investor would be used in place of an entity is Investments.

Investing With an Investor

curl https://apps.fundamerica.com/api/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d amount="1000000.0" \
-d equity_share_count="10" \
-d offering_id="L3YgoBHxQGKC7WzKKspR4w" \
-d payment_method="check" \
-d investor_id="gDUoIZxMTb-o-fxzuZA2SQ"

However, Holdings, Investor Payments, and Investor Customer Agreement can also use investors.

Investment Payments

Investment Payments are a way of following the lifecycle of a particular payment toward an investment from receipt to movement to escrow to refund. In practice, there will generally be a one-to-one relationship between investments and their respective payments, however this is not always the case. Everything from investor error to bank limitations on a single wire can cause some investments to require multiple payments.

Additionally, investment payments include details on how and when funds were received, moved to escrow or refunded.

Note: If you're interested in the specifics on how and when funds become available, please see our Funds Availability Policy.

Example Object

{
  "object":"investment_payment",
  "id":"Yp_Berl8SCmFUiicNHZ-lw",
  "url":"https://apps.fundamerica.com/api/investment_payments/Yp_Berl8SCmFUiicNHZ-lw",
  "offering_url":"https://apps.fundamerica.com/api/offerings/Fhw0gRzzRtm15Q5_tFCchQ",
  "amount":"5000.0",
  "disbursed_at":null,
  "failure_details":null,
  "funds_clear_at":"2015-02-01T08:00:00.000Z",
  "in_escrow_at":null,
  "investment_url":"https://apps.fundamerica.com/api/investments/_8j2O2sEQ7m28gxHHhjUyg",
  "payment_details":"TXBZ000012345",
  "payment_method":"wire",
  "received_at":"2015-01-30T12:49:48.263Z",
  "refund_details":null,
  "refund_method":null,
  "refunded_at":null,
  "status":"in_escrow"
}

Response Attributes

  • disbursed_at: When payment was disbursed from escrow.
  • failure_details: If there was a problem processing a payment, this will indicate the reason for failure.
  • in_escrow_at: When payment was moved to escrow.
  • payment_details: Details about receiving the payment as recorded by customer service. This may be a check number or a wire ID or any information that is deemed relevant.
  • payment_method: The actual method in which the payment was received. This may or may not match the payment_method for the parent investment. A common mismatch is when an investment has a payment_method or wire but the investor does a manual ACH transaction rather than sending a wire.
  • received_at: When payment was received by FundAmerica.
  • refund_details: If the payment was refunded, details about the refund.
  • refund_method: If the payment was refunded, the method that was used.
  • refunded_at: When payment was refunded by FundAmerica.
  • status:
    • received: Payment has been received and is pending transfer to escrow account.
    • in_escrow: Payment is in escrow account.
    • refunded: Payment has been refunded.
    • invested: Payment has been invested.
    • failed: In the event a check bounced or an ACH draw bounced or failed for some other reason, this status will be set. In essence, this is the same as if no funding was ever received. failure_details will explain the nature of the failure.

AML Exceptions

Whenever an investor makes an investment, an identity check is automatically processed on the investor to determine whether the investor's identifying information is correct and if that information is connected with any government watch lists.

In the event the background check shows a problem of some sort, an AML exception is thrown. While funds can be sent to escrow, investments with funds connected to an investor with an outstanding AML exception cannot be cleared, don't count toward the offering's minimum and cannot be disbursed.

In most cases, AML exceptions happen for three main reasons:

  1. In the case of an individual investing, the problem is almost always user error. Either a name or a TIN or a date of birth is entered incorrectly.
  2. In the case of businesses, the business is realtively new and can't be found in public records yet.
  3. Custodial type investors (like trusts) almost always require some kind of documentation and cannot be identified automatically because there is nothing in the public record.

AML exceptions are generated when there is either discrepency or problem in the identifying data or automatic checks cannot find a record of the investor. Sometimes, especially in the case of businesses, manual checks by customer service can verify enough to clear the exception. However, more often than not, actions are necessary on the part of the investor to provide more data or correct existing data.

AML exceptions with a status of contact_issuer require action by the part of the issuer or the portal to give further instructions. The investor entity may need to be updated or entity documents may need to be provided to clear the exception.

Once information has been either added or created, a AML exception should be updated to notify FundAmerica that the exception should be reviewed again. If everything checks out, the status will be set to cleared and the AML exception is no longer an issue for the investment.

Note: In the case of companies or joint accounts, it's possible that a single investment might have multiple AML exceptions.

A typical flow looks like this:

  1. An investment is created and a background check is processed.
  2. If there is a problem, an AML exception is generated with status of pending.
  3. FundAmerica reviews the exception and either sets the status to clear if the problems can be resolved without further input of sets the status to contact_issuer if more information is required. This update causes a webhook to be created, informing the portal that there is an issue.
  4. The portal looks at the nature of the AML exception and responds accordingly.
  5. The portal sets the status to pending by updating the AML exception.
  6. FundAmerica looks at the new data and, in most cases, will probably clear the exception. If not, the status will be set to contact_issuer again and the process will repeat until cleared or the investment is cancelled.

API Endpoints

GET    https://apps.fundamerica.com/api/aml_exceptions
GET    https://apps.fundamerica.com/api/aml_exceptions/:id
PATCH  https://apps.fundamerica.com/api/aml_exceptions/:id
GET    https://apps.fundamerica.com/api/entities/:id/aml_exceptions
GET    https://apps.fundamerica.com/api/investments/:id/aml_exceptions
PATCH  https://apps.fundamerica.com/api/test_mode/aml_exceptions/:id

Example Object

{
  "object": "aml_exception",
  "id": "yXlIZxuXRj2mkCgrxWtSRw",
  "url": "https://apps.fundamerica.com/api/aml_exceptions/yXlIZxuXRj2mkCgrxWtSRw",
  "ach_info_mismatch": false,
  "address_verified": null,
  "background_check_url": "https://apps.fundamerica.com/api/background_checks/sStUW6KMR8-DfD1lBeoH4w",
  "created_at": "2015-12-01T19:34:59.758Z",
  "dob_verified": null,
  "documentation_required": false,
  "entity_url": "https://apps.fundamerica.com/api/entities/EvahckAkQ-WiwacbwnRwtg",
  "investment_url": "https://apps.fundamerica.com/api/investments/fef-DoFASzKOxAka0jn3qg",
  "name_verified": null,
  "status": "pending",
  "status_updates": {
  },
  "tin_verified": null,
  "updated_at": "2015-12-01T19:34:59.761Z",
  "watch_lists_cleared": null
}

Example Update

curl https://apps.fundamerica.com/api/aml_exceptions/yXlIZxuXRj2mkCgrxWtSRw \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH

Test Mode

curl https://apps.fundamerica.com/api/test_mode/aml_exceptions/68MRakKFSSy2AmVfwC8gBQ \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="contact_issuer" \
-d documentation_required="true"

Response Attributes

  • ach_info_mismatch: true if the investment was created via ACH and the bank account name did not match the investor's name.
  • address_verified: true if the entity's address has been verified. (As of now, this doesn't usually matter, but it may in the future with regionally specific offerings.)
  • dob_verified: true if the entity's date of birth has been verified. This is always null for non-person entities.
  • documentation_required: true if automatic checks aren't enough and actual documentation is required. See Entity Documents.
  • name_verified: true if the entity's name has been verified.
  • status:
    • pending: FundAmerica is currently reviewing the exception
    • contact_issuer: More information is required from the issuer to clear the exception.
    • cleared: The exception has been cleared. This does not necessarily mean the issue has been resolved however. In cases where identity cannot be established or, something more serious like finding the investor is on the OFAC list, an AML exception may be cleared and the investment cancelled.
  • status_updates: A list of notes from FundAmerica related to the AML exception. This will be blank in many cases but, especially when documents come into play, there may be extra information about specifics of the exception listed here.
  • tin_verified: true if the entity's tax ID number has been verified.
  • watch_lists_cleared: true if the entity does not appear on any government watch lists.

ACH Authorizations

In order for an investor to invest in an offering using ACH, an ACH Authorization must be created. This requires an investor to provide their bank account information to FundAmerica and electronically sign an ACH Authorization Agreement. This can be accomplished in one of two ways:

FundAmerica Hosted Form

The hosted form is similar to signing an escrow agreement and is the simpler of the two to integegrate.

The process works like this:

  1. The investor is provided with an ACH token and directed to FundAmerica.
  2. The investor fills out a form, providing their bank information and electronic signature.
  3. An ach_authorization is created and its id can be passed into an investment.

An entity can have multiple ACH authorizations if you choose to support that functionality in your portal.

Note: In order to create an ACH authorization, the entity that wishes to use it must exist first. As a result, investments using ACH should always pass entity_id rather than individual entity parameters when creating an investment. The primary reason for this is that an ACH authorization is tied to an entity and another entity cannot use it for investing.

Example Create

curl https://apps.fundamerica.com/api/ach_tokens \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d entity_id="fTR1h9FnRiCc-I7sRlxQWg"

Example Response

{
  "object":"ach_token",
  "url":"https://apps.fundamerica.com/ach_authorizations/new/a5PaPUMcEELHCYhObI1vmOG7Y5zIAjd9K"
}

Note: A return_url query string can be added to the token URL and the signer will be redirected to the return_url when the ACH authorization agreement is signed. The parameter ach_authorization_id will be passed back to return_url if it is provided.

Pre-Populating ACH Authorization Form

By default, the ACH Authorization form will be filled in the entity information. However, some providers store the account information on their own system for other purposes. In order to prevent the end user from entering information multiple times, you can POST to the URL provided when creating an ACH token. The following fields can be pre-populated:

  • ach_authorization[account_type]: Must be checking or savings.
  • ach_authorization[check_type]: Must be business or personal.
  • ach_authorization[account_number]
  • ach_authorization[routing_number]: Must be a valid 9 digit routing number.
  • ach_authorization[name_on_account]
  • ach_authorization[contact_name]
  • ach_authorization[address]
  • ach_authorization[city]
  • ach_authorization[state]
  • ach_authorization[zip_code]
  • ach_authorization[email]

If you plan on pre-populating account information, DO NOT use a GET request. The account information can end up in web logs and other unsecure places. Despite being sent via HTTPS, it's still an extremely bad practice to use GET if also opting to pre-populating the form.

Direct API Creation

This is similar to FundAmerica's hosted form, but gives the portal greater flexibility in when integrating. It's also a more involved process. Since the ultimate result must be very similar to the process outlined in the FundAmerica Hosted Form process, it's suggested that you go through that process at least once to get a good idea of what your own process should look like.

API Endpoints

GET    https://apps.fundamerica.com/api/ach_authorizations
POST   https://apps.fundamerica.com/api/ach_authorizations
GET    https://apps.fundamerica.com/api/ach_authorizations/:id
DELETE https://apps.fundamerica.com/api/ach_authorizations/:id
GET    https://apps.fundamerica.com/api/ach_authorizations/agreement_html
GET    https://apps.fundamerica.com/api/entities/:id/ach_authorizations

Agreement Text

You must include the exact introduction text that appears on the hosted form. Failure to do so can lead to your account getting suspended without notice. This text should be copied directly from our API with the following call:

curl https://apps.fundamerica.com/api/ach_authorizations/agreement_html \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Example Response

{
  "agreement_html": "<p><strong>IMPORTANT: Please read before completing, signing and submitting.</strong></p>\n\n<p>Direct Payment via ACH is a transfer of funds from (or to) a bank account for the purposes of making a payment.</p>\n\n<p>I (we) hereby authorize FundAmerica Securities, LLC (&ldquo;FundAmerica&rdquo;), to electronically initiate credit and debit entries to my (our) account at the financial institution listed below (hereinafter &ldquo;Bank&rdquo;), and, if necessary, initiate adjustments for any transactions credited/debited in error.</p>\n\n<p>This authority authorizes FundAmerica to credit my (our) account to correct errors and with payments, refunds, reimbursements, and other funds, and to debit my (our) account for exact amount of investments I make, and will remain in effect until such time that FundAmerica is notified by me (us) in writing to cancel it, with such notice provided at least 3 business days in advance, delivered via overnight courier to FundAmerica Securities, LLC, attention Financial Operations Principal, at 3455 Peachtree Road NE, 5th Floor, Atlanta, GA 30326. I agree that the ACH transactions I (we) authorize comply with all applicable law.</p>"
}

Additionally, if you wish to retrieve information about the bank related to the routing number similar to the hosted form you can use the following call:

curl https://apps.fundamerica.com/api/bank_info/123456789 \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Note: The routing number parameter must be 9 digits. Anything else will result in a 404. Additionally, an invalid routing number will result in a 404.

Example Response

{
  "object": "bank_info",
  "address": "1 Bank Road",
  "city": "Las Vegas",
  "name": "Common Bank",
  "phone": "7025551234",
  "routing_number": "123456789",
  "state": "NV",
  "zip_code": "89102"
}

Using this is optional, but it does give the user instant feedback as to whether or not the routing number is correct.

Example Object

{
  "object": "ach_authorization",
  "id": "gk66607hRw2reeYYb__FJQ",
  "account_number_short": "7849",
  "bank_transfer_method_url": "https://apps.fundamerica.com/api/bank_transfer_methods/uO0cesN0Ts-Y-YKu3FY2Dg",
  "cancelled_at": null,
  "created_at": "2015-04-29T01:29:02.632Z",
  "entity_url": "https://apps.fundamerica.com/api/entities/LAMg0zqZQM2fJLfO81QqCA",
  "name": "John Q Investor (********7849)",
  "name_on_account": "John Q Investor",
  "routing_number": "122287251",
  "updated_at": "2015-04-29T01:29:02.632Z",
  "verified": false
}

Example Create

curl https://apps.fundamerica.com/api/ach_authorizations \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d account_number="0000123456789" \
-d account_type="checking" \
-d address="555+Some+St" \
-d check_type="personal" \
-d city="Las+Vegas" \
-d email="john.investor%40example.com" \
-d entity_id="gCeZ4-QzSrGlHCkfeGtVwA" \
-d ip_address="127.0.0.1" \
-d literal="John+Q+Investor" \
-d name_on_account="John+Q+Investor" \
-d routing_number="122287251" \
-d state="NV" \
-d user_agent="NO+NAME+BROWSER+1.0" \
-d zip_code="89123"

Request Attributes

  • account_number: Must be all digits.
  • account_type: Must be checking or savings.
  • address: The address for the bank account. Defaults to the entity's address.
  • check_type: Must be business or personal.
  • city: The city for the bank account. Defaults to the entity's city.
  • contact_name: A contact name if different than the entity. Defaults to the entity's name or the entity's contact_name if present.
  • name_on_account: The name on the bank account. Defaults to the entity's name.
  • routing_number: Must be a valid 9 digit routing number.
  • state: The state for the bank account. Defaults to the entity's state.
  • use_for_investor_payments: If set to true the Bank Transfer Method associated with this authorization will automatically by set as the entity's Investor Payment Method.
  • zip_code: The zip code for the bank account. Defaults to the entity's zip code.

Signature Attributes:

  • company: If the signer is represtenting a company, this is the company's name.
  • email: The email address for the signer. Default's to the entity's email address.
  • ip_address: The IP address of the client filling out the form.
  • literal: The literal signature of the client. This is whatever the client chooses to type as their signature. It will typically be their name or some variation of their name.
  • title: If the signer is respresenting a company, this is their title.
  • user_agent: The user agent header (browser identification) of the client filling out the form.

Response Attributes

  • cancelled_at: If the ACH authorization was cancelled, this is when it happened. A cancelled ACH authorization cannot be used for making an investment and will not show up in any resource lists.
  • name: The name of the ACH authorization. It's the account name with the last for digits of the account number.
  • verified: If set to true it means this ACH authorization has been successfully charged at some point in the life the ACH authorization.

It's important to remember that while an ACH authorization requires far less input on the part of the investor (i.e. they don't have to mail a check or go to their bank for a wire transfer) they are not real time and there is no way of verifying the information provided by the investor before an ACH charge is attempted. These charges occur in batches and not in real time. As such, if there is a failure the related investment payment will be marked as failed and the investor may need to create a new ACH Authorization (if the account number was incorrect).

ACH authorizations can be cancelled and they may be cancelled outside of your platform. For instance, an investor may contact FundAmerica directly and request a cancellation. When an ACH authorization is cancelled or verified, it will trigger a webhook.

Subscription Agreements

The document signing system that is currently used for both Escrow Agreements and ACH Authorizations is also available for subscription agreements.

The steps involved in setting up and using a subscription agreement for an Offering are as follows:

  1. Create a Subscription Agreement Template for the offering.
  2. Create an actual Investor Subscription Agreement.
  3. Have the investor sign the subscription agreement either by providing a signing URL or providing the signature information directly via the API.

Note: The signing system is limited to HTML documents. If you're working from a PDF or Microsoft Office Document, you'll need to convert it to acceptable HTML first. In the event that this is unacceptable, please use our External Subscription Agreements feature, which can be used in conjunction with any other signing service.

Subscription Agreement Templates

API Endpoints

GET    https://apps.fundamerica.com/api/subscription_agreement_templates
POST   https://apps.fundamerica.com/api/subscription_agreement_templates
GET    https://apps.fundamerica.com/api/subscription_agreement_templates/:id
PATCH  https://apps.fundamerica.com/api/subscription_agreement_templates/:id
GET    https://apps.fundamerica.com/api/subscription_agreement_templates/boilerplate_html

These templates contain all the content and placeholders for the actual investor subscription agreements. The template itself is simply an HTML document. Additionally, the issuer's signature is included for automatic signing.

Example Object

{
  "object": "subscription_agreement_template",
  "id": "0SlvyoFUSYGGrs1j6uKe1w",
  "url": "https://apps.fundamerica.com/api/subscription_agreement_templates/0SlvyoFUSYGGrs1j6uKe1w",
  "draft_content": "... draft legalese ...",
  "email_document_to_signers": true,
  "published_content": "... published legalese ...",
  "issuer_company": "Test Company",
  "issuer_email": "test@test.com",
  "issuer_literal": "Test Person",
  "issuer_metadata": null,
  "issuer_name": "Test Person",
  "issuer_title": "Tester"
}

Example Create

curl https://apps.fundamerica.com/api/subscription_agreement_templates \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d draft_content="%25%25VESTING_AMOUNT%25%25%2C+%25%25VESTING_AS%25%25%2C+%25%25VESTING_AS_EMAIL%25%25%2C+%25%25EQUITY_SHARE_COUNT%25%25%2C+%25%25SUBSCRIBER_SIGNATURE%25%25%2C+%25%25ISSUER_SIGNATURE%25%25" \
-d email_document_to_signers="true" \
-d issuer_company="Johnson%2C+Johnson%2C+Johnson+%26+Johnson" \
-d issuer_email="john%40johnson.com" \
-d issuer_literal="J.+Johnson" \
-d issuer_name="John+Johnson" \
-d issuer_title="CEO" \
-d offering_id="-IGfjnzlT5-y7LbuUKa9Vg"

Request Attributes

  • draft_content: The actual HTML content of the subscription agreement. Note that this can be a complete HTML document or simply the content that would go inside the <body> of the document.
  • email_document_to_signers: Defaults to true. If set to false, email's will not be sent when subscription agreements are signed and it is the responsibility of the platform operator to provide emails.
  • issuer_company: The company name of the issuer.
  • issuer_email: The email address of the person signing for the issuer.
  • issuer_literal: The signature literal of the person signing for the issuer. This is usually the same as the issuer_name but some people choose to sign with partial names or initials. (e.g. John Johnson's signature literal is "J Johnson")
  • issuer_metadata: A JSON object of any other data you wish to include with the issuer signature for verification purposes. It could include the user's ID on your own system, their IP address or any other data you want to include.
  • issuer_name: The name of the person signing for the issuer.
  • issuer_title: The title of the person signing for the issuer.
  • publish: If set to true, the template will be usable subscription agreements and published_content will be replaced by draft_content.

Note: When editing a template in the web portal, we use a WYSIWYG editor and it can mess up special formatting provided by your own HTML templates. If you're going to use subscription agreements via the API, you shouldn't edit them via the web portal for any reason.

Response Attributes

  • published_content: THe published content for the template. This is what will actually be used when creating subscription agreements.

Note: The publish/draft content feature allows for subscription agreements to be used in a standalone manner with FundAmerica. If you're storing the information on your own system---and many portal implementors do---you can safely just publish on each request and not worry about the publish/draft content distinction.

Template Placeholders

Subscription agreement templates can be filled with placeholders for arbitrary data. Some of these are system defined and others can be defined for individual documents. Placeholders are always included in a document delimited by a pair of percentage signs.

For example, to include today's date in your template you would use %%TODAY%%.

Here are the placeholders that are available by default in subscription agreements:

  • %%DEBT_PAR_VALUE%%: The par value of the debt in a debt offering. This is specified when creating an Investor Subscription Agreement.
  • %%EQUITY_SHARE_COUNT%%: The share/unit count in an equity offering. This is specified when creating an Investor Subscription Agreement.
  • %%ISSUER_SIGNATURE%%: The issuer signature block.
  • %%NOW%%: The current time as January 1, 2015 at 12:00 PM EST.
  • %%NOW_SHORT%%: The current time as 1/1/2015 - 12:00 PM EST
  • %%INVESTOR_SIGNATURES%%: The subscribers signature block.
  • %%TODAY%%: Today's date as January 1, 2015.
  • %%TODAY_SHORT%%: Today's date as 1/1/2015.
  • %%VESTING_AMOUNT%%: The amount being invested by the investor. This is specified when creating an Investor Subscription Agreement.
  • %%VESTING_AS%%: The investor's information (name, address, etc.). This is specified when creating an Investor Subscription Agreement.
  • %%VESTING_AS_EMAIL%%: The investor's email address. This is specified when creating an Investor Subscription Agreement.

Dates and times are variable up until the point a document is signed by the subscriber. From then on, %%NOW%% and %%TODAY%%` will reflect the time that the document was signed.

You can use any placeholder name you want. When creating the actual Investor Subscription Agreement you can specify the values to be used for said placeholders.

Note: Placeholders are not case sensitive. %%TODAY%% is equivalent to %%today%% or %%Today%%. By convention, they are in call caps in the templates to make them easier to spot when creating documents but this is not a requirement.

Investor Subscription Agreements

Once you have a template created for your offering, you can create individual subscription agreements. This is done by providing the vesting information, placeholder information and the template and offering information. Doing so will create a final document that is automatically signed by the issuer and can be signed by a subscriber.

API Endpoints

GET    https://apps.fundamerica.com/api/subscription_agreements
POST   https://apps.fundamerica.com/api/subscription_agreements
GET    https://apps.fundamerica.com/api/subscription_agreements/:id

Example Object

{
  "object": "subscription_agreement",
  "id": "bMb6e-T_Qpu_2-pXJowaiQ",
  "url": "https://apps.fundamerica.com/api/subscription_agreements/bMb6e-T_Qpu_2-pXJowaiQ",
  "offering_url": "https://apps.fundamerica.com/api/offerings/-ycp2jirTW6GgYluhjy99g",
  "archived_pdf_url": null,
  "body_html": "... securities legalese ...",
  "created_at": "2015-12-05T02:11:42.269Z",
  "electronic_signatures": [
    {
      "object": "electronic_signature",
      "id": "iutjmLanTNiFTpEpmCf5Fg",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/iutjmLanTNiFTpEpmCf5Fg",
      "anchor_id": "issuer_signature",
      "company": null,
      "document_url": "https://apps.fundamerica.com/api/subscription_agreements/bMb6e-T_Qpu_2-pXJowaiQ",
      "email": null,
      "literal": null,
      "metadata": {
      },
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    },
    {
      "object": "electronic_signature",
      "id": "SqIRl8lMRNKjHVh6A36h3Q",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/SqIRl8lMRNKjHVh6A36h3Q",
      "anchor_id": "subscriber_signature",
      "company": null,
      "document_url": "https://apps.fundamerica.com/api/subscription_agreements/bMb6e-T_Qpu_2-pXJowaiQ",
      "email": "test@test.com",
      "literal": null,
      "metadata": {
      },
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    }
  ],
  "signed": false,
  "signing_links": {
    "issuer_signature": {
      "expires": "2015-12-06T02:11:42.291Z",
      "url": "https://apps.fundamerica.com/sign/pIxt8Q8o7I9N2COt8TyNvSrlZEAaplIZ"
    },
    "subscriber_signature": {
      "expires": "2015-12-06T02:11:42.294Z",
      "url": "https://apps.fundamerica.com/sign/mULlENoaoMUF9VLtKWkdmhEyavwRKbgX"
    }
  },
  "updated_at": "2015-12-05T02:11:42.275Z",
  "data": {
    "debt_par_value": null,
    "equity_share_count": "2",
    "vesting_amount": "250",
    "vesting_as": "Johnny",
    "vesting_as_email": "test@test.com"
  },
  "template_url": "https://apps.fundamerica.com/api/subscription_agreement_templates/wUjUSl6-ToydJ9tLsZ7mpQ",
  "issuer_signed": false,
  "subscriber_signed": false
}

Example Create

curl https://apps.fundamerica.com/api/subscription_agreements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d equity_share_count="2" \
-d offering_id="VxD17sjBSbGNL1sGIy3XMw" \
-d vesting_amount="%245%2C000.00" \
-d vesting_as="John+Q+Investor" \
-d vesting_as_email="john.investor%40example.com"

Request Attributes

  • debt_par_value: If the offering is a debt offering, this is required.
  • equity_share_count: If the offering is an equity offering, this is required.
  • data: A JSON object of key/value pairs that will be used as for placeholder data. It's a good practice, though not required, to have all the values set to strings. They will ultimately be coerced into strings when a document is created, but if you want to avoid surprises, just set them as strings.
  • vesting_amount: The amount of money being invested. This should be formatted appropriately as this is only used to fill in the template and isn't a number that will be validated in any way.
  • vesting_as: The vesting information for the investor. It should include the legal name and address.
  • vesting_as_email: The investor's email address.

You may have noticed that the fields here are nearly identical to the template placeholders. That's because they are.

The subscription agreement service is entirely standalone from investments and while they can be used in tandem, they aren't necessary for one another. As such, entity information, the actual investment amounts, equity share counts, etc. aren't linked in any way by our platform. It's up to your system to make sure data is formatted the way you like and that it coincides with investment data.

If your subscription agreement has a vesting_amount of $5,000.00 then the investment you ultimately associate it with should have an amount of 5000.

Response Attributes

  • archived_pdf_url: Once the document has been signed, an archived PDF can be found at this URL.
  • body_html: The body HTML of the document. If you wish to embed the document in your own interface for signature collection, use this. Even if you have provided a full HTML document, this is ONLY the content inside the <body>. The only exception is that if <style> directives exist in the <head>, they will be included in the body for formatting purposes.
  • electronic_signatures: See Electronic Signatures for more details.
  • signed: Whether or not the document has been signed by the subscriber.
  • signing_links: If you wish to have the subscriber sign using FundAmerica's pass through interface, you can use the link here. You can attach a return_url querystring to this link.

Electronic Signatures

If you wish to embed the signing of documents into your own interface and not use the signing_links, this can be done via calls to the API. To do this, you must update an electronic signature object.

API Endpoints

GET   https://apps.fundamerica.com/api/electronic_signatures/external_agreement
PATCH https://apps.fundamerica.com/api/electronic_signatures/external_agreement

Example Object

{
  "object":"electronic_signature",
  "id":"uWUPYK_KQBOlJQIB-ZRywA",
  "url":"https://apps.fundamerica.com/api/electronic_signatures/uWUPYK_KQBOlJQIB-ZRywA",
  "anchor_id":"subscriber_signature",
  "company":"John Q, LLC",
  "document_url":"https://apps.fundamerica.com/api/subscription_agreements/u1sAZ_fnTKCB5x1eUs6ccg",
  "email":"john.investor@example.com",
  "literal":"J Q Investor",
  "metadata":{"portal_user_id":"123456"},
  "name":"John Q Investor",
  "signable":false,
  "signed":true,
  "signed_at":"2015-03-18T19:34:56.508Z",
  "title":"El Presidente"
}

Example Signing

curl https://apps.fundamerica.com/api/electronic_signatures/uWUPYK_KQBOlJQIB-ZRywA \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d company="John Q, LLC" \
-d email="john.investor@example.com" \
-d ip_address="127.0.0.1" \
-d literal="J Q Investor" \
-d metadata="{"portal_user_id":"123456"}" \
-d name="John Q Investor" \
-d title="El Presidente" \
-d user_agent="Some Browser 1.0"

Request Attributes

  • company: The company represented by the signer. Can be blank.
  • email: The signer's email address.
  • ip_address: The signer's IP address. This is not the IP address of your server. It must be the signer's client IP address.
  • literal: The signer's literal signature. It may differ from the signer's name.
  • metadata: And additional data you wish to include for signature verification, such as the user's ID on your local system.
  • name: The signer's name.
  • title: The title of the signer at the company. Must be blank if company is blank.
  • user_agent: The signer's user agent.

Response Attributes

  • signable: Whether the signature is signable via the API. Some documents contain multiple signatures, some of which are signed by FundAmerica. These signatures are not open for signing via the API.
  • signed: Whether the signature has been signed.
  • signed_at: When the signature was signed.

When implementing your own interface, you may very well already know the name, email, title, and company information for the signer. It's important that the signer can see this information, but not necessary that they are able to alter it for the purpose of the signature. The only attribute that must have direct input by the signer is literal.

Note: Although the documentation here relates to subscription agreements, it can currently be applied to Escrow Agreements as well should you want to embded them into your own portal.

Subscription Agreement Boilerplate

If you want to use our boilerplate as a starting place for your subscription agreements, it can be found at:

GET https://apps.fundamerica.com/api/subscription_agreement_templates/boilerplate_html

Example Object

{
  "boilerplate_html": "... a whole lot of legalese ..."
}

Broker Dealer Services

For information on what the this service does, please see the related feature list. To use this service, you must also use our escrow service. Remember, while this service requires our escrow service, our escrow service does not require the use of this service.

There is a multistep process for both the issuer and the investor:

For the Issuer

  1. Set up an offering with escrow payments.
  2. Direct the issuer to sign the Selling Agreement.

For the Investor

  1. Direct the investor to accept out an Investor Customer Agreement. This must be reviewed and approved before an investment can be made. (Also remember, this must only be completed once by the investor, not per investment.)
  2. Create an Investment with review_trade set to true. The default is false. This indicates that you want FundAmerica to review the trade and require the investor to have accepted the Investor Customer Agreement.

Note: Even though this service may be enabled on a particular offering, it is managed on a per investment basis. If you wish to not use this service on a particular investment (e.g. there is no requirement for a particular investor or another broker-dealer is representing said investor) you can set review_trade to false on the investment and said investment will operate like a normal escrow payment without the broker-dealer services enabled.

Selling Agreements

Selling agreements operate very similarly to Escrow Agreements. When an offering is approved for escrow payments, if there is a selling agreement signed by the issuer, it will also be reviewed by FundAmerica and, if approved and counter-signed, broker-dealer services will be available for the offering.

In general, this approval will happen shortly after an offering is approved for escrow.

API Endpoints

POST   https://apps.fundamerica.com/api/selling_agreements
GET    https://apps.fundamerica.com/api/selling_agreements/:id

Example Create

curl https://apps.fundamerica.com/api/selling_agreements \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d offering_id="CwbzrVJKTV-9n9KDjjHjfw"

Example Response

{
  "object": "selling_agreement",
  "id": "HvbqnBzRQRelwUuvRiW-Cw",
  "url": "https://apps.fundamerica.com/api/selling_agreements/HvbqnBzRQRelwUuvRiW-Cw",
  "offering_url": "https://apps.fundamerica.com/api/offerings/S6YxU0YkQ2umzDYv84-13A",
  "archived_pdf_url": null,
  "body_html": "... agreement HTML ...",
  "created_at": "2015-04-22T19:20:40.963Z",
  "electronic_signatures": [
    {
      "object": "electronic_signature",
      "id": "UVcZ00w1QIi2uBYDK7-UIQ",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/UVcZ00w1QIi2uBYDK7-UIQ",
      "anchor_id": "broker_dealer_signature",
      "company": null,
      "document_url": "https://apps.fundamerica.com/api/selling_agreements/HvbqnBzRQRelwUuvRiW-Cw",
      "email": null,
      "literal": null,
      "metadata": {
      },
      "name": null,
      "signable": false,
      "signed": false,
      "signed_at": null,
      "title": null
    },
    {
      "object": "electronic_signature",
      "id": "r1gU7C-gT--ANX7cBYm8EA",
      "url": "https://apps.fundamerica.com/api/electronic_signatures/r1gU7C-gT--ANX7cBYm8EA",
      "anchor_id": "issuer_signature",
      "company": null,
      "document_url": "https://apps.fundamerica.com/api/selling_agreements/HvbqnBzRQRelwUuvRiW-Cw",
      "email": null,
      "literal": null,
      "metadata": {
      },
      "name": null,
      "signable": true,
      "signed": false,
      "signed_at": null,
      "title": null
    }
  ],
  "signed": false,
  "signing_links": {
    "issuer_signature": {
      "expires": "2015-04-23T19:20:41.147Z",
      "url": "https://apps.fundamerica.com/sign/bX_NzQY5lG1tRsRaesOlUs0uiKncbIKd"
    }
  },
  "updated_at": "2015-04-22T19:20:40.963Z"
}

Request Attributes

  • offering_id: The offering related to the escrow agreement.

Response Attributes

  • archived_pdf_url: Once the document has been signed, an archived PDF copy can be found at this location.
  • signed: Whether or not the document has been signed.
  • signing_links: A list of available signatures, their signing links and when those links expire (defaults to one day from the time of creation). In the case of an escrow agreement, there will only be an "issuer_signature."

Note: A return_url query string can be added to the signing URL and the signer will be redirected to the return_url when the document is signed.

Activating Broker Dealer Services in Test Mode

To activate broker dealer services in test mode without needing to have your selling agreement approved, use the test mode API:

curl https://apps.fundamerica.com/api/test_mode/offerings/o-l2QRY0QS60MQ4bQfl7JA \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d accept_investments="true" \
-d use_broker_dealer_service="true"

Investor Customer Agreements

In order for an investor to invest in an offering using this service and have this service active for the investment, the investor must accept a customer agreement, self attest to their accreditation status and provide substitue W-9 information. In order for FundAmerica Securities to act as the broker-dealer of record for the investor on a particular investment, this must be filled out.

Note: Investor customer agreements are tracked platform-wide so it's possible that if an investor has accepted the agreement on another portal using our services we already have one on file.

Embedding the Agreement in Your Portal

As with ACH Authorizations, you must present the form information exactly as FundAmerica does on its own form.

API Endpoints

PATCH  https://apps.fundamerica.com/api/entities/:id/customer_agreement
GET    https://apps.fundamerica.com/api/entities/:id/customer_agreement/edit

Example Object

{
  "form": {
    "type": {
      "label": "I qualify as an accredited investor as follows:",
      "options": {
        "non_accredited": "I am not an accredited investor.",
        "individual_net_worth": "I have an individual net worth, or joint net worth with my spouse, that exceeds $1 million including any IRA's, 401K's and other retirement accounts, but excluding the net value of my primary residence.",
        "individual_income": "I am an individual with income of over $200,000 in each of the last two years, or joint income with my spouse exceeding $300,000 in those years, and I reasonably expect at least the same this year.",
        "business": "We are a business, trust or other non-individual entity in which all the equity owners or grantors/settlors are accredited investors.",
        "bank": "We are a bank, insurance company, pension fund, or other registered investment company with assets exceeding $5 million.",
        "corporation": "We are a corporation, partnership, or charitable organization with at least $5 million in assets.",
        "employee_benefit_plan": "We are an employee benefit plan, within the meaning of the Employee Retirement Income Security Act, if a bank, insurance company, or registered investment adviser makes the investment decisions, or if the plan has total assets in excess of $5 million.",
        "trust": "We are a trust with assets in excess of $5 million, not specifically formed to acquire the securities offered, whose purchases a sophisticated investor makes."
      },
      "meta": {
        "show_for_individuals": [
          "non_accredited",
          "individual_net_worth",
          "individual_income"
        ]
      }
    },
    "annual_income": {
      "type": "usd",
      "label": "Annual Income"
    },
    "net_worth": {
      "type": "usd",
      "label": "Net Worth"
    },
    "us_citizen_or_resident": {
      "label": "Substitute Form W-9 Statement: Under penalty of perjury, by accepting the agreement below I certify that I have provided my correct taxpayer identification number, and",
      "options": {
        "true": "I am a US citizen or other US person.",
        "false": "I am not a US citizen or other US person."
      }
    },
    "exempt_from_withholding": {
      "label": "And:",
      "options": {
        "true": "I am exempt from backup withholding.",
        "false": "I am subject to backup withholding."
      }
    },
    "accept_customer_agreement": {
      "type": "boolean",
      "label": "Accept customer agreement"
    },
    "accredited": {
      "type": "boolean",
      "label": "Are you an \"accredited\" investor (meaning do you earn over $200,000 per year, have a net worth of $1m or more, or are an institutional investor)?",
      "optional": true
    }
  },
  "action": "http://www.example.com/api/entities/7bPVr0SKQpmY1if_JY985g/customer_agreement",
  "method": "PATCH",
  "resource": {
    "object": "platform_investor",
    "accepted_customer_agreement": false,
    "accreditation_on_file": false,
    "accreditation_url": "https://apps.fundamerica.com/api/entities/7bPVr0SKQpmY1if_JY985g/investor_accreditation",
    "annual_income": null,
    "confirmation_method_map": {
      "accountant_contact_info": "accountant",
      "broker_contact_info": "broker",
      "lawyer_contact_info": "lawyer",
      "linkedin_profile": "linkedin",
      "web_search_info": "web_search",
      "website_url": "website"
    },
    "created_at": null,
    "customer_agreement": " ... customer agreement HTML ... ",
    "entity_url": "https://apps.fundamerica.com/api/entities/7bPVr0SKQpmY1if_JY985g",
    "exempt_from_withholding": null,
    "kyc_hash": "7f0e633d3ccc73d4abcec171b1e0450e",
    "net_worth": null,
    "suitability_on_file": false,
    "suitability_url": "https://apps.fundamerica.com/api/entities/7bPVr0SKQpmY1if_JY985g/investor_suitability",
    "type": null,
    "updated_at": null,
    "us_citizen_or_resident": null
  }
}

Rather than copy the form, which has parameters and text that are subject to change, a call can be made to query the contents of the form (the edit action). This will give you a structure on building the form and, in the event the form has already been filled out, it will also include the existing values.

There is a lot of text following, but it's pretty straightforward. Calling the edit action returns JSON with four primary keys:

  • form: This lists all the content in the form. The first keys represent attribute names (the HTTP form parameters) and the object contained.
    • type: The field type. This is mostly important for building HTML forms. Examples include: boolean (should generally be a checkbox), integer, decimal, and email. If blank, the default is should be a single line string.
    • label: The human friendly name for the field.
    • options: If there are a group of selectable options, this will be a hash of values and their descriptions. This should be a select tag, or list of radio buttons (or checkboxes if multivalue is true).
    • optional: Most fields are required. In the event a field is optional, this will be true.
    • multivalue: If true the, the parameter will accept multiple values.
  • action: The form action attribute when creating an HTML form.
  • method: The HTTP method that should be used. This will often be a POST or PATCH. It's important to note that some browsers will only GET or POST forms. To be safe, you can should include a hidden attribute named _method in your forms where HTTP verbs other than GET and POST aren't supported. If you find yourself getting a strange 404 when trying to submit a form, it often means you're trying to POST when you should be using a PATCH method.
  • resource: The content of the object to edit.

Note: new and edit calls will be added to most of our API calls in the near future in an attempt to make the API both discoverable and self-documenting. Although this is only currently supported by the Investor Suitability form, understanding this format will help with future API calls.

First, get the form information:

curl https://apps.fundamerica.com/api/entities/7bPVr0SKQpmY1if_JY985g/customer_agreement/edit \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:

Which will produce the above response with a form.

Build a form which should then be submitted with an equivalent call:

curl https://apps.fundamerica.com/api/entities/7bPVr0SKQpmY1if_JY985g/customer_agreement \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d accept_customer_agreement="true" \
-d annual_income="250000" \
-d exempt_from_withholding="true" \
-d net_worth="1000000" \
-d type="individual_net_worth" \
-d us_citizen_or_resident="true"

You must make the customer_agreement available to the client filling out the form. Generally, including a link to another page, using a frame or a modal all work just fine.

Here is an example of our reference implementation.

Trade Reviews

Investments made using this service must undergo a trade review wherein FundAmerica Securities must review the investment in accordance with the information provided in the investor suitability questionnaire and either accept or deny the trade. Denying a trade would subsequently cancel in the investment.

The trade_review_status is available as part of an investment. Additionally, a list of trade reviews can be using the follow API endpoint:

https://apps.fundamerica.com/api/trade_reviews (GET)

There is also a test mode API for updating the status of a trade review at:

https://apps.fundamerica.com/api/test_mode/trade_reviews (PATCH)

Trade reviews have webhooks.

# AML and Bad Actors Checks

This service allows you to run background checks on entities to check on the validity of identifying information (e.g. name, tax ID, address, etc.) and to see if the entity is listed on any global watch lists.

**Note:** If you're using our [Escrow Payments](#escrow-payments) service then AML checks are processed automatically on every investment.

## In Production

Before you can create background checks or view background check details in production, you will need to submit your account to a review process. This can be done by going to [AML & Bad Actors Checks](/accounts/default/background_checks). If you receive a warning about needing your account reviewed, please follow the instructions and submit the necessary information for approval.

## In Test Mode

This service is available in test mode even without approval, however you will need to use test data provided below as anything else will return empty responses. The test data is just a bunch of entities that background checks will return results on and can be used for test investments with the expected AML results.

## Background Checks

Background checks verify the identity information of an entity as well as whether that entity appears on any global watch lists. Background check responses differ somewhat depending on whether or not the entity is a person or a company.

**Note:** Background checks are limited to US entities as of right now. Support for some international checks is slated for a future release.

### Example Object (person)

```json
{
  "object":"background_check",
  "id":"4gakGJ3kQMOCpJayhmSKrw",
  "url":"https://apps.fundamerica.com/api/background_checks/4gakGJ3kQMOCpJayhmSKrw",
  "offering_url":"https://apps.fundamerica.com/api/offerings/KqrdBJ-PQn2eByMbnHp_Xw",
  "cleared":true,
  "entity_url":"https://apps.fundamerica.com/api/entities/NgWPuTgLRwGvNW55_KJqCA",
  "identity_check":{
    "aml_exception":false,
    "details":{
      "dob_match_level":"Only Day and Month Match.",
      "name_address_phone_summary":"Address and Phone matched.",
      "name_address_ssn_summary":"Input First name, Last name, Address and SSN matched.",
      "risk_indicators":[
        "The input SSN is associated with multiple last names",
        "The input date-of-birth may have been miskeyed"
      ],
      "verification_summary":"Full name, address, phone and SSN verified.",
      "watch_lists":[]
    },
    "failure":false,
    "processed_at":"2014-11-10T16:49:48.837Z",
    "type":"person"
  }
}

Example Object (company)

{
  "object":"background_check",
  "id":"fWzqzVw9T0O2I4J4U9I6pQ",
  "url":"https://apps.fundamerica.com/api/background_checks/fWzqzVw9T0O2I4J4U9I6pQ",
  "offering_url":"https://apps.fundamerica.com/api/offerings/KqrdBJ-PQn2eByMbnHp_Xw",
  "cleared":false,
  "entity_url":"https://apps.fundamerica.com/api/entities/HfBlYStTSpaTpQxXCG2TNw",
  "identity_check":{
    "aml_exception":true,
    "details":{
      "bankruptcy_count":"0",
      "business_description":"Unknown",
      "filing_name":null,
      "name_address_fein_summary":"Input not verified.",
      "name_address_phone_summary":"Input Phone number returns a different Name and Address.",
      "risk_indicators":[
        "The input name matches the OFAC file",
        "Unable to verify name, address, SSN/TIN, and phone",
        "Unable to verify name",
        "Unable to verify address",
        "Unable to verify phone number",
        "Unable to verify SSN/TIN",
        "Address mismatch between city/state and zip code",
        "The input phone number is potentially invalid"
      ],
      "verification_summary":"Significant contradictory findings or an OFAC match exists or only the input address and phone are valid.",
      "watch_lists":[
        {
          "country":"HONDURAS",
          "entity_name":"MARIA PAULA LAINEZ RODRIGUEZ",
          "name":{
            "prefix":null,
            "first":"MARIA",
            "middle":null,
            "last":"LAINEZ RODRIGUEZ",
            "suffix":null
          },
          "record_number":"IMW2008_35",
          "table":"Interpol Most Wanted"
        },
        {
          "country":"CROATIA",
          "entity_name":"IVAN RODOSEVIC",
          "name":{
            "prefix":null,
            "first":"IVAN",
            "middle":null,
            "last":"RADOSEVIC",
            "suffix":null
          },
          "record_number":"IMW2006_48",
          "table":"Interpol Most Wanted"
        },
        {
          "country":null,
          "entity_name":"Vercillo, Margaret",
          "name": {
            "prefix":null,
            "first":"MARGARET",
            "middle":null,
            "last":"VERCILLO",
            "suffix":null
          },
          "record_number":"FARA3301-1",
          "table":"Foreign Agents Registration Act"
        },
        {
          "country":null,
          "entity_name":"AL-HAMATI SWEETS BAKERIES",
          "name":{
            "prefix":null,
            "first":"SWEETS",
            "middle":null,
            "last":"AL-HAMATI",
            "suffix":null
          },
          "record_number":"AQO2356",
          "table":"United Nations Named Terrorists"
        },
        {
          "country":null,
          "entity_name":"F'RAJI IL LIBICO",
          "name":{
            "prefix":null,
            "first":"FRAJI",
            "middle":null,
            "last":"LIBICO",
            "suffix":null
          },
          "record_number":"AQ12207",
          "table":"United Nations Named Terrorists"
        },
        {
          "country":null,
          "entity_name":"AHMAD, Tariq Anwar al-Sayyid",
          "name":{
            "prefix":null,
            "first":"TARIQ",
            "middle":null,
            "last":"AHMAD",
            "suffix":null
          },
          "record_number":"OFAC6908",
          "table":"Office of Foreign Asset Control"
        },
        {
          "country":null,
          "entity_name":"THI HA",
          "name":null,
          "record_number":"OFAC10688",
          "table":"Office of Foreign Asset Control"
        }
      ]
    },
    "failure":false,
    "processed_at":"2014-11-18T01:45:54.819Z",
    "type":"company"
  }
}

Request Attributes

  • entity_id: The entity you wish to process a background check on.
  • offering_id: The related offering. Background checks must always be processed with a related offering.

Response Attributes

  • cleared: true if background check was successful and entity did not appear on any watch lists.
  • identity_check: Details about the identity check.
    • aml_exception: If true it means that there were issues with the identity check, ranging from an incorrect tax ID to being on listed on a global watch list. This investor needs to be manually reviewed. (If using our escrow service, FundAmerica will follow up appropriately and potentially cancel an associated investment.)
    • details: The details of the background check. (See examples for fields. More documentation coming soon. Contact support if you need further assistance.)
    • risk_indicators: A list of issues or potential issues with the entity. These can be as severe as being on a watch list or as trivial as a person's address being used for business purposes. The existence of a risk indicator doesn't mean there is a problem with the check.
    • type: The type of entity the background check was processed on. Can be person or company. Some attributes in details differ depending on the entity type.

Example Create

curl https://apps.fundamerica.com/api/background_checks \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d offering_id="KqrdBJ-PQn2eByMbnHp_Xw" \
-d entity_id="NgWPuTgLRwGvNW55_KJqCA"

Example Entities

Below is a list of entities that will return example background checks in the sandbox environment.

People

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Artie" \
-d date_of_birth="1980-01-01" \
-d email="dale.mulford@example.com" \
-d name="Dale Mulford" \
-d phone="13048540483" \
-d postal_code="25008" \
-d region="WV" \
-d street_address_1="1038 White Oak Creek Rd" \
-d tax_id_number="520102674" \
-d type="person"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Grayslake" \
-d date_of_birth="1980-01-01" \
-d email="linda.carpenter@example.com" \
-d name="Linda Carpenter" \
-d phone="18478271922" \
-d postal_code="60030" \
-d region="IL" \
-d street_address_1="1331 Wild Indigo Rd" \
-d tax_id_number="516322134" \
-d type="person"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Jacksonville" \
-d date_of_birth="1953-05-01" \
-d email="nancy.lebo@example.com" \
-d name="Nancy Lebo" \
-d phone="19046548849" \
-d postal_code="32209" \
-d region="FL" \
-d street_address_1="1519 W 5 Th St" \
-d tax_id_number="520093807" \
-d type="person"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Kekaha" \
-d date_of_birth="1961-02-01" \
-d email="james.hall@example.com" \
-d name="James Hall" \
-d phone="1085551212" \
-d postal_code="96752" \
-d region="HI" \
-d street_address_1="4807 N Wildwood Dr" \
-d tax_id_number="577699840" \
-d type="person"

Companies

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="San Diego" \
-d country="US" \
-d email="herbert.atiyat@example.com" \
-d contact_name="Herbert Atiyat" \
-d name="Net Land Sports" \
-d phone="13193240031" \
-d postal_code="92129" \
-d region="CA" \
-d region_formed_in="CA" \
-d street_address_1="22 Sherwood Hts" \
-d tax_id_number="570426249" \
-d type="company"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Saratoga" \
-d country="US" \
-d email="joseph.avena@example.com" \
-d contact_name="Joseph Avena" \
-d name="Copper Lantern Bar" \
-d phone="17168330032" \
-d postal_code="95070" \
-d region="CA" \
-d region_formed_in="CA" \
-d street_address_1="10011 67 Th Rd" \
-d tax_id_number="570425503" \
-d type="company"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="Fairfax" \
-d country="US" \
-d email="nancy.babula@example.com" \
-d contact_name="Nancy Babula" \
-d name="Shield Home Security" \
-d phone="17137470033" \
-d postal_code="94930" \
-d region="CA" \
-d region_formed_in="CA" \
-d street_address_1="6421 Booth St Apt 6 H" \
-d tax_id_number="539164707" \
-d type="company"

curl https://sandbox.fundamerica.com/api/entities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d city="St Cloud" \
-d country="US" \
-d email="barney.stone@example.com" \
-d contact_name="Barney Stone" \
-d name="IM CRAZY INTERNATIONAL" \
-d phone="13202418143" \
-d postal_code="56301" \
-d region="MN" \
-d region_formed_in="MN" \
-d street_address_1="123 Happy St" \
-d tax_id_number="566689992" \
-d type="company"

Payment Processing

The Payment Processing API is used for making payments to investors. Payments include interest, revenue-share, principal, preferred distributions, profit-sharing, dividends, royalties, etc.

Once an offering is closed, whether the close is partial or complete, this service to can be used to make payments directly to your investors via check or ACH transfer.

Process Overview

If you're already familiar with Investments, the flow of payment processing is quite similar.

  1. Associated a security with an offering.
  2. Close an offering.
  3. If the issuer plans on making a payment via ACH, configure an ACH Authorization for the issuer entity.
  4. If you plan on paying your investors via ACH, configure a Bank Transfer Method for each investor.
  5. Assign an Investor Payment Method to an investor entity.
  6. Create a Distribution.
  7. If the issuer is paying via a method other than ACH, provide the issuer with check mailing and/or wire details.
  8. Once a Distribution has been received, Investor Payments will be created to show the current status of individual payments.

Once the funds are received by FundAmerica and have cleared, they will be distributed to your investors accordingly.

A few things to keep in mind:

  • Steps 1 and 2 can be done in either order. You can create a security before or after you've closed on an offering.
  • In order for payment processing to calculate amounts accurately, investments must have included correct values for debt_par_value in the case of debt offerings and equity_share_count in the case of equity offerings. If this wasn't the case, please see Holdings.
  • Before investments can have the associated securities issued to an investor for payment, a Close Offering Request must be accepted for the Offering. Investments must have a status of invested before payments can be made on a particular investment.
  • As a special note to serial issuers, remember that ACH Authorization can be used by an entity's children. This means if you create an entity that operates as a parent for all your serial issuers, they can all use a single ACH authorization for making payments, avoiding the need for creating a new ACH authorization for each issuer.

Bank Transfer Methods

Bank transfer methods are non-check payment instructions for investors. They allow ACH or wire information to be specified for the payout.

You might notice that the parameters are very similar to ACH Authorizations. That's because an ACH authorization is nothing but a Bank Transfer Method with an authorization form attached that allows for both debits and credits. Since bare Bank Transfer Methods lack the authorization portion, they can only be used to credit accounts (which is all you need to make a payment).

You can get the appropriate Bank Transfer Method related to an ACH Authorization by doing a GET on the coorsponding ACH Authorization.

Note: wire payments are not currently available for payment processing due to the prohibitive costs involved. However, Bank Transfer Methods will also be used in the future for advanced closing instructions added to offerings, so the functionality is still noted here.

API Endpoints

POST   https://apps.fundamerica.com/api/bank_transfer_methods
GET    https://apps.fundamerica.com/api/bank_transfer_methods/:id
DELETE https://apps.fundamerica.com/api/bank_transfer_methods/:id
GET    https://apps.fundamerica.com/api/entities/:id/bank_transfer_methods

Example Object

{
  "object": "bank_transfer_method",
  "id": "F71VflgRQCip6JJGW5AhOw",
  "account_number_short": "7849",
  "cancelled_at": null,
  "created_at": "2015-04-29T01:37:31.888Z",
  "entity_url": "https://apps.fundamerica.com/api/entities/3YISq1JNRWSrbci4uwogug",
  "name": "FUNDAMERICA SECURITIES, LLC (********7849)",
  "name_on_account": "FUNDAMERICA SECURITIES, LLC",
  "routing_number": "122287251",
  "type": "ach",
  "updated_at": "2015-04-29T01:37:31.888Z",
  "verified": false
}

Example Create (ACH)

curl https://apps.fundamerica.com/api/bank_transfer_methods \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d account_number="000000000000" \
-d entity_id="dlKzuyNBTxeUWpO8iLq9_Q" \
-d name_on_account="FUNDAMERICA+SECURITIES%2C+LLC" \
-d routing_number="122287251" \
-d type="ach" \
-d account_type="checking" \
-d check_type="business" \
-d use_for_investor_payments="true"

Example Create (wire)

curl https://apps.fundamerica.com/api/bank_transfer_methods \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d account_number="000000000000" \
-d entity_id="IJ8xscNfQqqVs7OTf7QYEA" \
-d name_on_account="FUNDAMERICA+SECURITIES%2C+LLC" \
-d routing_number="122287251" \
-d type="wire"

Request Attributes

  • account_number: The bank account number.
  • account_type: Must be set to either checking or savings if the type is ach. Otherwise, it must be left blank.
  • check_type: Must be set to either personal or business if the type is ach. Otherwise, it must be left blank.
  • name_on_account: The name on the bank account.
  • routing_number: The bank's routing number. Must be a valid routing number, even when testing.
  • type: Must be set to ach or wire depending on how the transfer should be initiated.
  • use_for_investor_payments: If set to true this bank transfer method will automatically by set as the entity's Investor Payment Method.

Response Attributes

  • account_number_short: This will be the last 4 digits of the account number.
  • cancelled_at: If and when the method is cancelled. Cancelled methods will not be used for future transactions. The DELETE will initiate a cancellation.
  • name: A friendly name combining the name_on_account and account_number_short.
  • verified: true if a there has ever been a successful transaction using this method.

Investor Payment Methods

Investor payment methods dictate how an investor is to be paid when a Distribution is distributed. These do not have to be specified, however if they are not, one of three defaults will be used:

  1. If an investor has successfully invested using ACH, the Bank Transfer Method associated with the ACH Authorization that was used for the investor's most recent investent will be used.
  2. If the entity has an ACH Authorization, the most recently created will be used.
  3. If the investor has never used ACH, a check will be made out to the investor and mailed to the entity address on record.

This behavior can be a little confusing. You can always look at the current default by:

GET    https://apps.fundamerica.com/api/entities/:id/investor_payment_method

If id is null that means the default is being used and you have no specified a method.

If you want complete control and predictability over how your investors are paid, manually specify the payment method.

Additionally, investor payment methods can be specified when creating an ACH Authorization or Bank Transfer Method by setting use_for_investor_payments to true.

API Endpoints

GET    https://apps.fundamerica.com/api/entities/:id/investor_payment_method
POST   https://apps.fundamerica.com/api/investor_payment_methods
GET    https://apps.fundamerica.com/api/investor_payment_methods/:id
PATCH  https://apps.fundamerica.com/api/investor_payment_methods/:id
DELETE https://apps.fundamerica.com/api/investor_payment_methods/:id

Using the DELETE call will revert investor payment method back to the default for the entity.

Example Object (Default)

{
  "object": "investor_payment_method",
  "id": null,
  "bank_transfer_method_url": null,
  "check_mailing_address": "555 Some St\nLas Vegas, NV 89123",
  "check_payee": "John Q Investor",
  "created_at": null,
  "entity_url": "https://apps.fundamerica.com/api/entities/jrcZH8_0RwOtcL6Lm6Q4bA",
  "type": "check",
  "updated_at": null
}

Example Object

{
  "object": "investor_payment_method",
  "id": "_UMy5kdwRc6M0WIMHwVuvg",
  "bank_transfer_method_url": "https://apps.fundamerica.com/api/bank_transfer_methods/c173KsM2R1-w3h_wkQtNAg",
  "check_mailing_address": null,
  "check_payee": null,
  "created_at": "2015-04-29T01:36:16.000Z",
  "entity_url": "https://apps.fundamerica.com/api/entities/jQBFghRDRm6SJ2LW7sO3Gw",
  "type": "ach",
  "updated_at": "2015-04-29T01:36:16.000Z"
}

Example Create (ACH Authorization)

curl https://apps.fundamerica.com/api/investor_payment_methods \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d ach_authorization_id="BebOM6IRTUGoml8oWev0ww" \
-d entity_id="zMGHNAwGTX6k85LME4DJXQ" \
-d type="ach"

Example Create (ACH Bank Transfer Method)

curl https://apps.fundamerica.com/api/investor_payment_methods \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d bank_transfer_method_id="_swMhmtZSi6dDK1HCwPkcw" \
-d entity_id="UiECHBGvRV-YjN-eExNHzg" \
-d type="ach"

Example Update (Check)

curl https://apps.fundamerica.com/api/investor_payment_methods \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d check_mailing_address="555+SOME+ST%0ALAS+VEGAS%2C+NV+89123" \
-d check_payee="JOHN+Q+INVESTOR" \
-d entity_id="VE2_iUuMQgCDwjf_-OeqSQ" \
-d type="check"

Request Attributes

  • ach_authorization_id: The ID of the ACH Authorization to be used for payments. When provided, a bank_transfer_method_id will be inferred from it.
  • bank_transfer_method_id: The ID of the Bank Transfer Method to be used for payments.
  • check_mailing_address: The address to mail checks to if type is check. If this is not specified, the entity's current address will be used.
  • check_payee: The name to make checks out to if type is check. If this is not specified, the entity's current name will be used.
  • type: Must be set to:
    • ach: If this is selected, either an ach_authorization_id or bank_transfer_method_id must be provided.
    • check: If this is selected, ach_authorization_id and bank_transfer_method_id must be left blank. The entity name and address will be used when mailing the check.

Note: While Bank Transfer Methods support ach and wire, only ach is supported investor payments.

Distributions

Distributions are the bulk payments meant to be distributed to your investors. Their lifecycle is similar to Investments themselves in how payment methods are specified and how funds are received. Once funds are received, they will be disbursed to individual investors according to defaults or specific instructions set forth in Investor Payment Methods.

Note: Offerings must have accepted close requests before any payments can be made. Also remember to correct any incorrect security information related to the investor with Holdings before processing a distribution. This is mainly important if your implementation wasn't giving accurate debt_par_value or equity_share_count information.

API Endpoints

GET    https://apps.fundamerica.com/api/distributions
POST   https://apps.fundamerica.com/api/distributions
GET    https://apps.fundamerica.com/api/distributions/:id
PATCH  https://apps.fundamerica.com/api/distributions/:id
DELETE https://apps.fundamerica.com/api/distributions/:id
PATCH  https://apps.fundamerica.com/api/test_mode/distributions/:id

Example Object

{
  "object": "distribution",
  "id": "yH1T12DhSlmggRhvNQBTQQ",
  "url": "https://apps.fundamerica.com/api/distributions/yH1T12DhSlmggRhvNQBTQQ",
  "ach_authorization_url": "https://apps.fundamerica.com/api/ach_authorizations/-4grA9Y3SOuNv5comPkH3w",
  "amount": "12500.0",
  "amount_distributed": "0.0",
  "amount_received": "0.0",
  "authorized_name": "John Johnson",
  "authorized_title": "CEO",
  "company_name": "Johnson, Johnson, Johnson & Johnson",
  "contact_email": "john.johnson@johnson.com",
  "contact_name": "John Johnson",
  "contact_phone": "12025551212",
  "created_at": "2015-06-05T23:47:21.743Z",
  "distributed_at": null,
  "dividend_amount": "0.0",
  "interest_amount": "12500.0",
  "ordinary_income_amount": "0.0",
  "other_amount": "0.0",
  "other_type": null,
  "payment_method": "ach",
  "principal_amount": "0.0",
  "profit_share_amount": "0.0",
  "received_at": null,
  "revenue_share_amount": "0.0",
  "royalty_amount": "0.0",
  "security_url": "https://apps.fundamerica.com/api/securities/QGBZn2VzRh2PP_BGGOPGlg",
  "status": "draft",
  "updated_at": "2015-06-05T23:47:21.743Z"
}

Example Create

curl https://apps.fundamerica.com/api/distributions \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d authorized_name="John+Johnson" \
-d authorized_title="CEO" \
-d principal_amount="50000" \
-d payment_method="ach" \
-d security_id="8ng0cmXsSlKK-V2MoypvwA" \
-d ach_authorization_id="Dma24SoFTteyfMBYyGBOIA" \
-d ready="true"

Example Update

curl https://apps.fundamerica.com/api/distributions/IZOl6bi_Qb6zJlkVSbbIjg \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d interest_amount="65000"

Request Attributes

  • ach_authorization_id: If payment_method is set to ach this is the ID of the ACH Authorization to be used to make the payment.
  • authorized_name: The name of the person authorizating the payment.
  • authorized_title: The title of the person authorizating the payment.
  • company_name: The legal name of the company.
  • contact_email: The contact email address for the company.
  • contact_name: The name of the contact person for the company.
  • contact_phone: The contact phone number for the company.
  • dividend_amount: The amount of the payment in USD applied to dividends.
  • interest_amount: The amount of the payment in USD applied to interest.
  • ordinary_income_amount: The amount of the payment in USD applied to ordinary income.
  • other_type: If other is amount greater than 0, this must specify the type of payment.
  • other_amount: The amount of the payment in USD applied to other.
  • payment_method: Must be set to one of three values: ach, check, wire.
  • principal_amount: The amount of the payment in USD applied to the principal.
  • profit_share_amount: The amount of the payment in USD applied to profit sharing.
  • ready: Set to true once you are ready to process a distribution. This should occur after the calculated Investor Payments have been reviewed as correct.
  • revenue_share_amount: The amount of the payment in USD applied to revenue sharing.
  • royalty_amount: The amount of the payment in USD applied to royalities.
  • security_id: The Security to make a distribution on.

Note: Many of these values are populated automatically by the security's issuer's values.

Response Attributes

  • amount_distributed: The total amount in USD paid out to individual investors.
  • amount_received: The total amount in USD received by FundAmerica.
  • amount: The total amount in USD to be paid to investors. This value is set automatically and is a sum of dividend_amount, interest_amount, ordinary_income_amount, other_amount, principal_amount, profit_share_amount, revenue_share_amount and royalty_amount.
  • distributed_at: The timestamp when all funds were released to investors.
  • received_at: The timestamp when all funds were received.
  • status: The current status of the remittance.
    • draft: Amounts and individual Investor Payments can be altered. Once the numbers are correct, set ready to true to submit the distribution and notify FundAmerica to expect a funds from the issuer.
    • not_received: Processing and all funds have not been received.
    • received: All funds have been received.
    • distributed: All funds have been paid to individual investors.
    • voided: Payment has been voided via DELETE. Planned payments can only be voided if no funds have been received.

Note: The DELETE call will void a distribution. This is only possible before funds have been received. (Status must be not_received.)

Distribution Test Mode

On the sandbox, test calls can be made to update the status on a distribution.

Example Test Mode Update

curl https://apps.fundamerica.com/api/test_mode/distributions/xBvLGzzmTO2_7bviQgNI1g \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="received"
curl https://apps.fundamerica.com/api/test_mode/distributions/xBvLGzzmTO2_7bviQgNI1g \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="distributed"

Investor Payments

Investor Payments are the actual payments distributed to individual investors. While a Distribution is still in draft mode, the details can be altered.

API Endpoints

GET    https://apps.fundamerica.com/api/distributions/:id/investor_payments
GET    https://apps.fundamerica.com/api/entities/:id/investor_payments
GET    https://apps.fundamerica.com/api/holdings/:id/investor_payments
GET    https://apps.fundamerica.com/api/investor_payments
GET    https://apps.fundamerica.com/api/investor_payments/:id
PATCH  https://apps.fundamerica.com/api/investor_payments/:id
GET    https://apps.fundamerica.com/api/investors/:id/investor_payments

Example Object

{
  "object": "investor_payment",
  "id": "mc77CzBOTy6I5nEUF0ex-Q",
  "url": "https://apps.fundamerica.com/api/investor_payments/mc77CzBOTy6I5nEUF0ex-Q",
  "amount": "2500.0",
  "bank_transfer_method_url": null,
  "check_mailing_address": "555 Some St.\nLas Vegas, NV 89123",
  "check_payee": "Example-9 Person",
  "city": "Las Vegas",
  "contact_name": "Example-9 Person",
  "country": "US",
  "created_at": "2015-11-13T00:00:18.065Z",
  "distribution_url": "https://apps.fundamerica.com/api/distributions/UfRWx0-pTVSqKp_5OHMwDA",
  "email": "user-13@example.com",
  "entity_url": "https://apps.fundamerica.com/api/entities/ZSL19f5fQPSywqDpULVddQ",
  "holding_url": "https://apps.fundamerica.com/api/holdings/UV_m9Yo9TCWRZ4goSmTPcw",
  "investor_url": "https://apps.fundamerica.com/api/investors/nQu5cn5_R9OsafRux3jCFw",
  "ledger_description": null,
  "name": "Example-9 Person",
  "paid_at": null,
  "payment_details": null,
  "payment_method": "check",
  "phone": "17025551212",
  "postal_code": "89123",
  "region": "NV",
  "security_url": "https://apps.fundamerica.com/api/securities/Lon-BA-gTR2mXMBuLz5HxQ",
  "status": "pending",
  "street_address_1": "555 Some St.",
  "street_address_2": null,
  "updated_at": "2015-11-13T00:00:18.065Z"
}

Example Update

curl https://apps.fundamerica.com/api/investor_payments/Noj952bqTmmc8Pq0tGEX1A \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d amount="5000"

Request Attributes

  • amount: The amount to pay the investor.
  • bank_transfer_method_id: Must be an ACH bank transfer method. Use if paying via ACH.
  • check_mailing_address: If paying by check, the address to mail the check to.
  • check_payee: If paying by check, the entity to make the check out to.

Response Attributes

Most of the attributes are pretty obvious as they line up with entities. Keep in mind that if an entity changes information after a Distribution is created, the information used at the time of the payment creation is what will be used for the investor payment. This is particularly important if mailing checks.

  • paid_at: When the actual payment was made.
  • payment_details: Details about the payment when it was paid such as the ACH batch ID or the check number.
  • payment_method: The method that the payment was made. ach or check.
  • status:
    • pending: Information about the payment specifics has been received.
    • processing: The current payment is being reviewed and queued for payment.
    • paid: Actual payment has been sent to the investor.
    • voided: In the event of an error or the cancellation of a distributions, an investor payment becomes voided.

Non-Investor Payments

Non-Investor Payments are arbitrary payments in a distribution not related to investors. While a Distribution is still in draft mode, the details can be altered. In many cases, it is easiest to create a distribution without factoring in the amounts for non-investor payments, create the non-investor payments and then update the other_amount on your distribution with the non-investor payment total.

API Endpoints

GET    https://apps.fundamerica.com/api/distributions/:id/non_investor_payments
GET    https://apps.fundamerica.com/api/non_investor_payments
POST   https://apps.fundamerica.com/api/non_investor_payments
GET    https://apps.fundamerica.com/api/non_investor_payments/:id
PATCH  https://apps.fundamerica.com/api/non_investor_payments/:id
DELETE https://apps.fundamerica.com/api/non_investor_payments/:id

Example Object

{
  "object": "non_investor_payment",
  "id": "HBCtRO15TkyaIzMoMaGquw",
  "url": "https://apps.fundamerica.com/api/non_investor_payments/HBCtRO15TkyaIzMoMaGquw",
  "amount": "5000.0",
  "bank_transfer_method_url": null,
  "check_mailing_address": "520 Park Ave\nSte 31\nNew York, NY 10022",
  "check_payee": "John J Johnson",
  "city": "New York",
  "contact_name": "John Johnson",
  "country": "US",
  "created_at": "2015-06-05T23:53:49.843Z",
  "email": "john.johnson@johnson.com",
  "name": "John Johnson",
  "paid_at": null,
  "payment_details": null,
  "payment_method": "check",
  "phone": "12025551212",
  "distribution_url": "https://apps.fundamerica.com/api/distributions/NdB3p-g8QWugfzO503GbMw",
  "postal_code": "10022",
  "region": "NY",
  "status": "pending",
  "street_address_1": "520 Park Ave",
  "street_address_2": "Ste 31",
  "updated_at": "2015-06-05T23:53:49.843Z"
}

Example Create

curl https://apps.fundamerica.com/api/non_investor_payments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d status="pending" \
-d amount="5000.0" \
-d check_mailing_address="520+Park+Ave%0ASte+31%0ANew+York%2C+NY+10022" \
-d check_payee="John+J+Johnson" \
-d city="New+York" \
-d country="US" \
-d email="john.johnson%40johnson.com" \
-d name="John+Johnson" \
-d phone="12025551212" \
-d postal_code="10022" \
-d region="NY" \
-d street_address_1="520+Park+Ave" \
-d street_address_2="Ste+31" \
-d distribution_id="lGxZM6oYQ0Kau_AjnROHvA"

Request Attributes

  • amount: The amount to pay the investor.
  • bank_transfer_method_id: Must be an ACH bank transfer method. Use if paying via ACH.
  • check_mailing_address: If paying by check, the address to mail the check to.
  • check_payee: If paying by check, the entity to make the check out to.

Response Attributes

  • paid_at: When the actual payment was made.
  • payment_details: Details about the payment when it was paid such as the ACH batch ID or the check number.
  • payment_method: The method that the payment was made. ach or check.
  • status:
    • pending: Information about the payment specifics has been received.
    • processing: The current payment is being reviewed and queued for payment.
    • paid: Actual payment has been sent to the investor.
    • voided: In the event of an error or the cancellation of a distributions, an investor payment becomes voided.

Securities

Securities represent the actual security details on what an offering has issued to investors. If you don't plan on using Payment Processing, the actual security information related to an offering doesn't matter.

If a security is associated with an offering, securities will be automatically issued to the investors of investments with a status of invested. This is currently the only way to issue securities although, this is likely to change in the future.

API Endpoints

GET    https://apps.fundamerica.com/api/securities
POST   https://apps.fundamerica.com/api/securities
GET    https://apps.fundamerica.com/api/securities/:id
PATCH  https://apps.fundamerica.com/api/securities/:id

Example Object

{
  "object": "security",
  "id": "LujDQne4R9GNbh2ogmiHgg",
  "url": "https://apps.fundamerica.com/api/securities/LujDQne4R9GNbh2ogmiHgg",
  "created_at": "2015-05-20T22:51:40.372Z",
  "debt_interest_rate": "0.25",
  "debt_maturity_date": "2015-05-21",
  "description": "This is common debt.",
  "entity_url": "https://apps.fundamerica.com/api/entities/b6Zka_J9Qra5gXHVpCnqMA",
  "equity_share_price": null,
  "issuer_name": "Johnson, Johnson, Johnson & Johnson",
  "legends": null,
  "name": "Common Debt",
  "offering_url": "https://apps.fundamerica.com/api/offerings/DO1tVrRQQ3W_DLUlMpYU4g",
  "type": "debt",
  "updated_at": "2015-05-20T22:51:40.372Z"
}

Example Create

curl https://apps.fundamerica.com/api/securities \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d debt_interest_rate="0.25" \
-d debt_maturity_date="2015-05-21" \
-d description="This+is+common+debt." \
-d name="Common+Debt" \
-d offering_id="Dbr2wavJSiCoseeZYZh8nw"

Request Attributes

  • debt_interest_rate: If type is debt, the interest rate associated with the security. Otherwise, it should be omitted.
  • debt_maturity_date: If type is debt, the maturity date or term associated with the security. Otherwise, it should be omitted.
  • description: An optional description of the security.
  • name: The name of the security.
  • type: Must be set to debt or equity and must match the associated offering's type. If this is omitted, the associated offering's type will be used.

Note: While debt securities require some actual information about the nature of the security, equity securities are really nothing more than a name and description.

Holdings

Holdings represent a security issued to a particular investor and the details of that holding, whether it be a total number of shares of the par value of debt.

Holdings are created automatically for an investor when an investment is set to invested and the offering has a security associated with it. Additionally, they may be created manually.

Note: Issuances can also be created by transfer of ownership calls, however this feature is not yet available, but will be by the time this API is out of beta.

API Endpoints

GET    https://apps.fundamerica.com/api/entities/:id/holdings
GET    https://apps.fundamerica.com/api/holdings
POST   https://apps.fundamerica.com/api/holdings
GET    https://apps.fundamerica.com/api/holdings/:id
PATCH  https://apps.fundamerica.com/api/holdings/:id
GET    https://apps.fundamerica.com/api/investors/:id/holdings
GET    https://apps.fundamerica.com/api/securities/:id/holdings

Example Object

{
  "object": "holding",
  "id": "oOCYK0jUSkulfXyoEcUKhg",
  "url": "https://apps.fundamerica.com/api/holdings/oOCYK0jUSkulfXyoEcUKhg",
  "created_at": "2015-11-13T00:00:39.266Z",
  "debt_par_value": "5000.0",
  "entity_url": "https://apps.fundamerica.com/api/entities/OCYsp_ciQ5KDsPOPTkLa8Q",
  "equity_share_count": null,
  "investment_url": "https://apps.fundamerica.com/api/investments/rWmgAjHeTSWox21jAwjKrQ",
  "investor_url": "https://apps.fundamerica.com/api/investors/2kYYEtEwTW-P2bjocLoGFg",
  "security_url": "https://apps.fundamerica.com/api/securities/Y1e27PAmRQKxFYXcpc7sIA",
  "type": "debt",
  "updated_at": "2015-11-13T00:00:39.266Z"
}

Example Create (Equity)

curl https://apps.fundamerica.com/api/holdings \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d equity_share_count="25.0" \
-d entity_id="0l26BON0RxmaGgKKmVMMvw" \
-d security_id="7xwKQvvkStyKtVR49H6b_g"

Example Create (Debt)

curl https://apps.fundamerica.com/api/holdings \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X POST \
-d debt_par_value="10000.0" \
-d entity_id="_Vppvmt4Q0isZUV7pFkkHA" \
-d security_id="maPPPg3TRhmsOaZEW6o3jw"

Example Update (Equity)

curl https://apps.fundamerica.com/api/holdings/k86O3Z_ISoWPCQ1nR4oB-A \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d equity_share_count="25.0"

Example Update (Debt)

curl https://apps.fundamerica.com/api/holdings/MoKqnHSoQRmDGKDSXOrd9Q \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d debt_par_value="10000.0"

Request Attributes

  • debt_par_value: If type is debt, the par value of the debt security issued to the entity. Otherwise, it should be omitted.
  • equity_share_count: If type is equity, the number of shares issued to the entity. Otherwise, it should be omitted.

Response Attributes

  • type: debt or equity. It will always match the type of the associated security.

Additional API Actions

Billing Transactions

Billing information related to your account can be found with the billing transactions API calls. You can view items that will be billed to your account by:

  • Account: https://apps.fundamerica.com/api/billing_transactions (GET)
  • Investment: https://apps.fundamerica.com/api/investments/:id/billing_transactions (GET)
  • Offering: https://apps.fundamerica.com/api/offerings/:id/billing_transactions (GET)

Example Object

{
  "object":"billing_transaction",
  "id":"jMBnoll9QUiOY8IWroEfSQ",
  "amount":"2.0",
  "billed_at":null,
  "created_at":"2015-01-09T18:02:51.442Z",
  "description":"Background Check - Investor"
}

Response Attributes

  • amount: The amount to be billed.
  • billed_at: The date a billing transaction was charged successfully.
  • description: A description of the item to be billed.

E-mail Logs

We keep track of all outgoing e-mails in the system. You can also resend an e-mail.

Object List

  • https://apps.fundamerica.com/api/email_logs (GET)

Example Object

  • https://apps.fundamerica.com/api/email_logs/:id (GET)
{
  "object":"email_log",
  "id":"rIuIXdpMQlaz728y_eL2yg",
  "url":"https://apps.fundamerica.com/api/email_logs/rIuIXdpMQlaz728y_eL2yg",
  "attachments":[],
  "bcc":null,
  "body":"We got money!",
  "cc":null,
  "created_at":"2015-11-07T02:30:55.993Z",
  "email_hash":"8c6c7eb8d8e0a9745cb6857520103cb8",
  "from":"Grey Emerson <issuer@offering.com>",
  "investment_url":"https://apps.fundamerica.com/api/investments/cVrRs2FSQGGnBGDz2vEg2Q",
  "sent_at":"2015-11-07T02:30:56.025Z",
  "status":"sent",
  "subject":"Investor Funds Received",
  "to":"John Smith <investor@company.com>",
  "offering_url":"https://apps.fundamerica.com/api/investments/Dadfjalk822hal0asSqQjs"
}

Response Attributes

  • attachments: List of files included with the e-mail. This will be an array of strings.
  • email_hash: related (duplicate) e-mails will have the same e-mail hash. this is useful when an e-mail is resent and you want to find the original or resent e-mail.
  • status: Can be either not_sent or sent.

Resend E-mail

No parameters are necessary when calling this endpoint.

  • https://apps.fundamerica.com/api/email_logs/:id/resend (PATCH)

API Endpoint Reference

Below are a list of all current API calls. If there are no specific examples above, the error responses are mostly self-documenting. DELETE calls don't take parameters. PATCH calls take the same parameters as POST calls.

  • https://apps.fundamerica.com/api/info (GET)
  • https://apps.fundamerica.com/api/ach_authorizations (GET)
  • https://apps.fundamerica.com/api/ach_authorizations (POST)
  • https://apps.fundamerica.com/api/ach_authorizations/:id (GET)
  • https://apps.fundamerica.com/api/ach_authorizations/:id (DELETE)
  • https://apps.fundamerica.com/api/ach_authorizations/agreement_html (GET)
  • https://apps.fundamerica.com/api/ach_tokens (POST)
  • https://apps.fundamerica.com/api/background_checks (GET)
  • https://apps.fundamerica.com/api/background_checks (POST)
  • https://apps.fundamerica.com/api/bank_info/:routing_number (GET)
  • https://apps.fundamerica.com/api/bank_transfer_methods (POST)
  • https://apps.fundamerica.com/api/bank_transfer_methods/:id (GET)
  • https://apps.fundamerica.com/api/bank_transfer_methods/:id (DELETE)
  • https://apps.fundamerica.com/api/billing_transactions (GET)
  • https://apps.fundamerica.com/api/billing_transactions/:id (GET)
  • https://apps.fundamerica.com/api/background_checks/:id (GET)
  • https://apps.fundamerica.com/api/cancel_offering_requests (GET)
  • https://apps.fundamerica.com/api/cancel_offering_requests (POST)
  • https://apps.fundamerica.com/api/cancel_offering_requests/:id (GET)
  • https://apps.fundamerica.com/api/close_offering_requests (GET)
  • https://apps.fundamerica.com/api/close_offering_requests (POST)
  • https://apps.fundamerica.com/api/close_offering_requests/:id (GET)
  • https://apps.fundamerica.com/api/disbursements (GET)
  • https://apps.fundamerica.com/api/disbursements (POST)
  • https://apps.fundamerica.com/api/disbursements/:id (GET)
  • https://apps.fundamerica.com/api/disbursements/:id (PATCH)
  • https://apps.fundamerica.com/api/disbursements/:id (DELETE)
  • https://apps.fundamerica.com/api/distributions (GET)
  • https://apps.fundamerica.com/api/distributions (POST)
  • https://apps.fundamerica.com/api/distributions/:id (GET)
  • https://apps.fundamerica.com/api/distributions/:id (PATCH)
  • https://apps.fundamerica.com/api/distributions/:id (DELETE)
  • https://apps.fundamerica.com/api/distributions/:id/non_investor_payments (GET)
  • https://apps.fundamerica.com/api/offerings/:id/disbursements (GET)
  • https://apps.fundamerica.com/api/electronic_signatures/:id (GET)
  • https://apps.fundamerica.com/api/electronic_signatures/:id (PATCH)
  • https://apps.fundamerica.com/api/entities (GET)
  • https://apps.fundamerica.com/api/entities (POST)
  • https://apps.fundamerica.com/api/entities/:id (GET)
  • https://apps.fundamerica.com/api/entities/:id (PATCH)
  • https://apps.fundamerica.com/api/entities/:id (DELETE)
  • https://apps.fundamerica.com/api/entities/:id/bank_transfer_methods (GET)
  • https://apps.fundamerica.com/api/entities/:entity_id/ach_authorizations (GET)
  • https://apps.fundamerica.com/api/entities/:id/cash_blotter (GET)
  • https://apps.fundamerica.com/api/entities/:id/entity_documents (GET)
  • https://apps.fundamerica.com/api/entities/:id/investor_payment_method (GET)
  • https://apps.fundamerica.com/api/entities/:id/investor_suitability (GET)
  • https://apps.fundamerica.com/api/entities/:id/investor_suitability (PATCH)
  • https://apps.fundamerica.com/api/entity_documents/:id (GET)
  • https://apps.fundamerica.com/api/entity_documents (POST)
  • https://apps.fundamerica.com/api/entity_relationships (GET)
  • https://apps.fundamerica.com/api/entity_relationships (POST)
  • https://apps.fundamerica.com/api/entity_relationships/:id (GET)
  • https://apps.fundamerica.com/api/entity_relationships/:id (PATCH)
  • https://apps.fundamerica.com/api/entity_relationships/:id (DELETE)
  • https://apps.fundamerica.com/api/escrow_agreements (GET)
  • https://apps.fundamerica.com/api/escrow_agreements (POST)
  • https://apps.fundamerica.com/api/escrow_agreements/:id (GET)
  • https://apps.fundamerica.com/api/escrow_service_applications (GET)
  • https://apps.fundamerica.com/api/escrow_service_applications (POST)
  • https://apps.fundamerica.com/api/escrow_service_applications/:id (GET)
  • https://apps.fundamerica.com/api/holdings (GET)
  • https://apps.fundamerica.com/api/holdings (POST)
  • https://apps.fundamerica.com/api/holdings/:id (GET)
  • https://apps.fundamerica.com/api/holdings/:id (PATCH)
  • https://apps.fundamerica.com/api/investors/:id/holdings (GET)
  • https://apps.fundamerica.com/api/securities/:id/holdings (GET)
  • https://apps.fundamerica.com/api/entities/:id/holdings (GET)
  • https://apps.fundamerica.com/api/investment_payments (GET)
  • https://apps.fundamerica.com/api/investment_payments/:id (GET)
  • https://apps.fundamerica.com/api/investments (GET)
  • https://apps.fundamerica.com/api/investments (POST)
  • https://apps.fundamerica.com/api/investments/:id (GET)
  • https://apps.fundamerica.com/api/investments/:id (PATCH)
  • https://apps.fundamerica.com/api/investments/:id (DELETE)
  • https://apps.fundamerica.com/api/investments/:id/billing_transactions (GET)
  • https://apps.fundamerica.com/api/investments/:id/investment_payments (GET)
  • https://apps.fundamerica.com/api/investments/:id/investor_payments (GET)
  • https://apps.fundamerica.com/api/investor_payment_methods/:id (GET)
  • https://apps.fundamerica.com/api/investor_payment_methods/:id (PATCH)
  • https://apps.fundamerica.com/api/investor_payment_methods/:id (DELETE)
  • https://apps.fundamerica.com/api/investor_payment_methods (POST)
  • https://apps.fundamerica.com/api/investors (GET)
  • https://apps.fundamerica.com/api/investors (POST)
  • https://apps.fundamerica.com/api/investors/:id (GET)
  • https://apps.fundamerica.com/api/investors/:id (PATCH)
  • https://apps.fundamerica.com/api/investor_suitbility_tokens (POST)
  • https://apps.fundamerica.com/api/ledger_entries/:id (GET)
  • https://apps.fundamerica.com/api/non_investor_payments (GET)
  • https://apps.fundamerica.com/api/non_investor_payments (POST)
  • https://apps.fundamerica.com/api/non_investor_payments/:id (GET)
  • https://apps.fundamerica.com/api/non_investor_payments/:id (PATCH)
  • https://apps.fundamerica.com/api/non_investor_payments/:id (DELETE)
  • https://apps.fundamerica.com/api/offerings (GET)
  • https://apps.fundamerica.com/api/offerings (POST)
  • https://apps.fundamerica.com/api/offerings/:id (GET)
  • https://apps.fundamerica.com/api/offerings/:id (PATCH)
  • https://apps.fundamerica.com/api/offerings/:id (DELETE)
  • https://apps.fundamerica.com/api/offerings/:id/billing_transactions (GET)
  • https://apps.fundamerica.com/api/offerings/:id/escrow_ledger (GET)
  • https://apps.fundamerica.com/api/offerings/:id/investment_payments (GET)
  • https://apps.fundamerica.com/api/offerings/:id/subscription_agreement_template (GET)
  • https://apps.fundamerica.com/api/securities (GET)
  • https://apps.fundamerica.com/api/securities (POST)
  • https://apps.fundamerica.com/api/securities/:id (GET)
  • https://apps.fundamerica.com/api/securities/:id (PATCH)
  • https://apps.fundamerica.com/api/selling_agreements (POST)
  • https://apps.fundamerica.com/api/selling_agreements/:id (GET)
  • https://apps.fundamerica.com/api/subscription_agreement_templates (GET)
  • https://apps.fundamerica.com/api/subscription_agreement_templates (POST)
  • https://apps.fundamerica.com/api/subscription_agreement_templates/:id (GET)
  • https://apps.fundamerica.com/api/subscription_agreement_templates/:id (PATCH)
  • https://apps.fundamerica.com/api/subscription_agreement_templates/:id (DELETE)
  • https://apps.fundamerica.com/api/subscription_agreement_templates/boilerplate_html (GET)
  • https://apps.fundamerica.com/api/subscription_agreement (GET)
  • https://apps.fundamerica.com/api/subscription_agreement (POST)
  • https://apps.fundamerica.com/api/subscription_agreement/:id (GET)
  • https://apps.fundamerica.com/api/trade_reviews (GET)
  • https://apps.fundamerica.com/api/trade_reviews/:id (GET)
  • https://apps.fundamerica.com/api/webhook_logs (GET)
  • https://apps.fundamerica.com/api/webhook_logs/:id (GET)

Test Mode Endpoint Reference

Test mode calls allow objects created on the sandbox to have their state changed the same way customer service would in production. Additionally, the "clear_data" call will initate wiping out all data for an account. These calls are currently undocumented here, but the error messages document their usage entirely.

  • https://sandbox.fundamerica.com/api/test_mode/clear_data (POST)
  • https://sandbox.fundamerica.com/api/test_mode/cancel_offering_requests/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/close_offering_requests/:id (PATCH)
  • https://apps.fundamerica.com/api/test_mode/disbursements/:id (PATCH)
  • https://apps.fundamerica.com/api/test_mode/distributions/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/entities/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/escrow_service_applications/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/investments/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/offerings/:id (PATCH)
  • https://sandbox.fundamerica.com/api/test_mode/trade_reviews/:id (PATCH)

Investment Quick Start Example

If you want to create an offering and immediately begin testing investments, here's a set of steps to do it:

1. Create an offering:

curl https://sandbox.fundamerica.com/api/offerings \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d amount="5000000" \
-d description="A really big deal." \
-d max_amount="5500000" \
-d min_amount="4500000" \
-d name="Big Deal" \
-d entity[city]='New York' \
-d entity[country]='US' \
-d entity[email]='john.johnson@johnson.com' \
-d entity[contact_name]='John Johnson' \
-d entity[name]='Johnson, Johnson, Johnson and Johnson' \
-d entity[phone]='12025551212' \
-d entity[postal_code]='10005' \
-d entity[region]='NY' \
-d entity[region_formed_in]='NY' \
-d entity[street_address_1]='60 Wall St.' \
-d entity[tax_id_number]='999999999' \
-d entity[type]='company'

2. Use the test mode API to open the offering for investing.

(You can go through the trouble of creating an escrow agreement, signing it, creating an escrow service application and then use the test mode API to accept it as well, but that's not "quick.")

curl https://sandbox.fundamerica.com/api/test_mode/offerings/3E2NEf0nS4OtRrRWM4JngA \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d accept_investments="true"

3. Make an investment.

curl https://sandbox.fundamerica.com/api/investments \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-d amount="5000" \
-d entity[city]='Las Vegas' \
-d entity[country]='US' \
-d entity[date_of_birth]='1980-01-01' \
-d entity[email]='john.investor@example.com' \
-d entity[name]='John Q Investor' \
-d entity[phone]='17025551212' \
-d entity[postal_code]='89123' \
-d entity[region]='NV' \
-d entity[street_address_1]='555 Some St' \
-d entity[tax_id_number]='000000000' \
-d equity_share_count="10" \
-d offering_id="3E2NEf0nS4OtRrRWM4JngA" \
-d payment_method="wire"

Make a bunch.

4. Change the investment status to received.

curl https://sandbox.fundamerica.com/api/test_mode/investments/LckF85F4R8Soe3Why-NZzw \
-u XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: \
-X PATCH \
-d status="received"

That's it. You can make as many investments as you want and eventually close or cancel the offering and review the changes.

Sign up for sandbox bf350e8bad5867495f9cb5ae5dc841b91972faa88d848d1b981003349487682e