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.

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.

See the KYC/KYB Verification section of this guide for details on how verfications are performed and the meaning of the results.