Create A Business Customer
In the Synctera platform, a business represents an organization that is an account holder or the owner of another business.
Use this API if your account holders are businesses, including sole proprietorships. If they are individuals, refer to the Persons section of this guide.
A business object contains identification information such as name, employer identification number, address, phone number and email address. It also contains status attributes to manage the lifecycle of the object. A business can progress from a prospect to an active business to an inactive former customer. A business is one of the core entities on Synctera. Accounts, ACH and cards are all tied to the business resource.
Business Creation Steps
The following steps will walk you through the creation of a business that can be used to hold accounts. The business will then be ready to use with other features such as Accounts, Cards and ACH.
The curl
examples assume you have set up baseurl
and apikey
environment variables. See Base URLs and Authentication for instructions. Some examples depend on identifiers generated by previous steps. These are indicated like {BUSINESS_ID}
.
1. Create Business
When you initially create a business customer, use the PROSPECT
status to indicate that it is not yet fully configured. If not all attributes (e.g. addresses) are available, they can be added later. Set is_customer
to true
to indicate that this business can be an account holder, rather than just an owner.
curl \
-X POST \
$baseurl/v0/businesses \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
--data-binary '
{
"status": "PROSPECT",
"is_customer": true,
"entity_name": "Acme Trap Company",
"trade_names": [
"Acme",
"Acme Corp",
"CorporationID#77231"
],
"formation_date": "2000-01-01",
"formation_state": "NY",
"structure": "CORPORATION",
"phone_number": "+12124567890",
"ein": "12-3456789",
"legal_address": {
"address_line_1": "50 Main St",
"city": "New York",
"state": "NY",
"postal_code": "12345",
"country_code": "US"
}
}'
This will return a response with the created business:
{
"creation_time": "2022-04-29T21:12:55.179008Z",
"ein": "12-3456789",
"entity_name": "Acme Trap Company",
"formation_date": "2000-01-01",
"formation_state": "NY",
"id": "{BUSINESS_ID}",
"is_customer": true,
"last_updated_time": "2022-04-29T21:12:55.179008Z",
"legal_address": {
"address_line_1": "50 Main St",
"city": "New York",
"country_code": "US",
"postal_code": "12345",
"state": "NY"
},
"phone_number": "+12124567890",
"status": "PROSPECT",
"structure": "CORPORATION",
"trade_names": ["Acme", "Acme Corp", "CorporationID#77231"],
"verification_status": "UNVERIFIED"
}
Note the returned id
attribute. This is used for future GET
, PATCH
and DELETE
requests, as well as to link this business to other objects like disclosures and accounts.
2. Disclosures
The next step when onboarding a business is typically disclosing information to them, e.g. terms of service. See the Customer Disclosures section of this guide for more details.
To record that the business acknowledged the disclosure, use POST /v0/disclosures, passing in the id of the business and the disclosure they acknowledged:
curl \
-X POST \
$baseurl/v0/disclosures \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
--data-binary '
{
"business_id": "{BUSINESS_ID}",
"type": "REG_E",
"version": "1.0",
"event_type": "ACKNOWLEDGED",
"disclosure_date": "2022-04-17T02:04:34Z"
}'
This will respond with a disclosure object:
{
"creation_time": "2022-04-29T21:14:24.953307Z",
"disclosure_date": "2022-04-17T00:00:00Z",
"event_type": "ACKNOWLEDGED",
"id": "{DISCLOSURE_ID}",
"last_updated_time": "2022-04-29T21:14:24.953307Z",
"business_id": "{BUSINESS_ID}",
"type": "REG_E",
"version": "1.0"
}
3. Business Ownership
You must now capture the ownership structure of the business. This is required to perform KYB verification.
A business can have owners that are persons or other businesses. We refer to persons that are owners as beneficial owners. Businesses that are owners can in turn have owners and beneficial owners. For this example, we will use them simplest ownership structure: a single beneficial owner. See KYC/KYB Verification for more details and complex examples.
Create the person representing the beneficial owner:
curl \
-X POST \
$baseurl/v0/persons \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
--data-binary '
{
"first_name": "Christopher",
"middle_name": "James",
"last_name": "Albertson",
"dob": "1985-06-14",
"email": "[email protected]",
"phone_number": "+16045551212",
"ssn": "456-78-9999",
"legal_address": {
"address_line_1": "456 Main St.",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country_code": "US"
},
"is_customer": false,
"status": "ACTIVE"
}'
The response body to this request will contain the id of the newly created person. Use this id to create a relationship between the person and the business by calling the POST /relationships endpoint specifying the BENEFICIAL_OWNER_OF
relationship type.
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
$baseurl/v0/relationships \
--data-binary '
{
"from_person_id": "{PERSON_ID}",
"relationship_type": "BENEFICIAL_OWNER_OF",
"to_business_id": "{BUSINESS_ID}",
"additional_data": {
"percent_ownership": 100
}
}'
4. Business Officers and Directors
KYB also requires capturing the officers and directors of the business. Create any additional persons, and link them using an MANAGING_PERSON_OF
relationship, with a title of OFFICER
or DIRECTOR
:
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
$baseurl/v0/relationships \
--data-binary '
{
"from_person_id": "{PERSON_ID}",
"relationship_type": "MANAGING_PERSON_OF",
"to_business_id": "{BUSINESS_ID}",
"additional_data": {
"title": "OFFICER"
}
}'
5. Activating the Business
If any information was missing when the business was initially created (e.g. shipping address) add it now and change the status to ACTIVE
using PATCH /v0/businesses/{BUSINESS_ID}:
curl \
-X PATCH \
$baseurl/v0/businesses/{BUSINESS_ID} \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
--data-binary '
{
"status": "ACTIVE",
"shipping_address": {
"address_line_1": "99 Elm St",
"city": "San Antonio",
"state": "TX",
"postal_code": "77777",
"country_code": "US"
}
}'
6. Run KYB
While the new business now has a status
of ACTIVE
, its verification_status
is still UNVERIFIED
, so its will not be able to perform most banking activities. The next step is to verify the business's identity using a Know Your Business (KYB) verification. See the KYC/KYB Verification section of this guide for more details as well as descriptions of other types of verification and risk checks.
Run a verification using POST /v0/verifications/verify, e.g.:
curl \
-X POST \
$baseurl/v0/verifications/verify \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
--data-binary '
{
"customer_consent": true,
"customer_ip_address": "{CUSTOMER_IP_ADDRESS}",
"business_id": "{BUSINESS_ID}"
}'
This will return a list of all the verifications that were run, and a result for each.
If the verifications passed, the business's verification_status
will now be ACCEPTED
. This can be checked by a GET /v0/businesses/{BUSINESS_ID}:
curl \
-H "Authorization: Bearer $apikey" \
$baseurl/v0/businesses/{BUSINESS_ID}
which will respond with:
{
"creation_time": "2022-04-29T21:12:55.179008Z",
"ein": "12-3456789",
"entity_name": "Acme Trap Company",
"formation_date": "2000-01-01",
"formation_state": "NY",
"id": "{BUSINESS_ID}",
"is_customer": true,
"last_updated_time": "2022-04-29T21:19:09.521182Z",
"legal_address": {
"address_line_1": "50 Main St",
"city": "New York",
"country_code": "US",
"postal_code": "12345",
"state": "NY"
},
"phone_number": "+12124567890",
"status": "ACTIVE",
"structure": "CORPORATION",
"trade_names": ["Acme", "Acme Corp", "CorporationID#77231"],
"verification_last_run": "2022-04-29T21:19:09.432601Z",
"verification_status": "ACCEPTED"
}
7. Use the Business with Other APIs
An active business can be used with other Synctera APIs:
- The Accounts API can create and manage accounts with the business as an account holder.
- The Cards API can create and manage credit or debit cards linked to the business.
- The Relationships API can link the business to another business as an owner.
- The Watchlists API can link a business with one or more watchlist monitoring subscriptions so that you can check for a business's presence on security risk watchlists.
Business Status Attributes
The business object contains two status attributes:
status
is an editable attribute representing the administrative state of the business. The integrator can use this to indicate whether they consider the business to be active, dormant, etc.verification_status
is a read-only attribute representing the results of the verification process. This is updated by the Synctera platform when verification actions, e.g. KYB checks, are performed.
The ability to participate in money movement transactions, issue cards, etc, is limited by both the status
and verification_status
attributes.
Business Status
The business object's status attribute can have the following values.
It is up to the integrator to decide what they consider an ACTIVE
, FROZEN
or INACTIVE
business.
Note that all states other than ACTIVE
are restricted and do not allow most banking operations.
Status Value | Description |
---|---|
ACTIVE | An active business |
CANCELLED | The business has filed a cancellation, or has failed to file its periodic report after notice of forfeiture of its rights to do business |
CONVERTED | The business type has changed to another type within the same jurisdiction |
DISSOLVED | The business has filed articles of dissolution or a certificate of termination to terminate its existence |
FROZEN | The business's actions are blocked for security, legal, or other reasons |
INACTIVE | The business is marked as no longer active, e.g. a former customer |
MERGED | The business has ceased to exist by merging into another business entity. |
PROSPECT | A potential business customer, used for information-gathering and disclosures |
SUSPENDED | The business has lost the right to operate in its registered jurisdiction |
These states are controlled by the integrator's API client. While there are no restrictions on state transitions, certain fields, e.g. entity_name, are required by all states except PROSPECT
. Typical state transitions are:
%%{init: {"fontFamily": "sans-serif"}}%%
stateDiagram-v2
[*] --> PROSPECT: Prospect identified
PROSPECT --> ACTIVE: Prospect qualified
ACTIVE --> INACTIVE: Closed accounts
ACTIVE --> FROZEN: Anomalous<br>activity
FROZEN --> ACTIVE: Anomalies<br>resolved
ACTIVE --> CANCELLED
ACTIVE --> CONVERTED
ACTIVE --> DISSOLVED
ACTIVE --> MERGED
ACTIVE --> SUSPENDED
Verification Status
In order to initiate transactions, an active business must also pass verification. There are different types of verification, including identity and watchlist checks.
Note that all states other than ACCEPTED
are restricted and do not allow most banking operations.
Verification Status Value | Description |
---|---|
ACCEPTED | The business is successfully verified |
PENDING | The business's verification is in progress |
PROVISIONAL | The business is partially verified or verified with restrictions |
REJECTED | The business was rejected |
REVIEW | The business's verification has run and issues have been identified which require review |
UNVERIFIED | The business's verification has not been completed |
See the KYC/KYB Verification section of this guide for details on how verfications are performed and the meaning of the results.
Updated about 1 year ago