Create A Personal Customer

In the Synctera platform, a person represents a natural person, including account holders, beneficial owners of a business and authorized signers. A person can hold multiple of these roles at the same time.

A person object contains personal identification information such as name, social security number, address, phone number and email address. It is one of the core entities in the Synctera platform, Accounts, ACH and cards are all tied to the person resource. A person also contains status attributes to manage the lifecycle of the object. A person can progress from a prospect to an active customer to an inactive former customer. Accounts, ACH and cards are all tied to the person resource.

📘

Breaking changes are planned for the Persons and Customers APIs in v1

Listening to feedback, Synctera is planning on making breaking changes to the customers API endpoints for v1.

To ease migration to the future v1 API, we have introduced new endpoints under /v0/persons which reflect the new API approach.

We recommend using /v0/persons (instead of /v0/customers) as it will be closer to the future version.

Note that these endpoints provide a different style of accessing the same data.
Resources created by one endpoint can be accessed using the other, with the same ID.
This ID can be used in other APIs that reference a personal customer using either a customer_id or person_id attribute.

Person Creation Steps

The following steps will walk you through the creation of a Person and getting the Person 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 URL and Authentication for instructions. Some examples depend on identifiers generated by previous steps. These are indicated like {BUSINESS_ID}.

1. Create Person

To create a person, use POST /v0/persons. If you have only a subset of the identifcation (e.g. email but not name), create it with PROSPECT status:

curl \
  -X POST \
  $baseurl/v0/persons \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
  {
    "status": "PROSPECT",
    "email": "[email protected]",
    "is_customer": true
  }'

This will return a response with the created person:

{
  "creation_time": "2022-04-13T01:52:40.690387Z",
  "email": "[email protected]",
  "id": "{PERSON_ID}",
  "last_updated_time": "2022-04-13T01:52:40.690387Z",
  "status": "PROSPECT",
  "verification_status": "UNVERIFIED"
}

Note the returned id attribute. This is used for future GET, PATCH and DELETE requests, as well as to link this person to other objects like disclosures and accounts.

2. Disclosures

The next step when onboarding a customer 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 person acknowledged the disclosure, use POST /v0/disclosures passing in the id of the person and the disclosure they acknowledged:

curl \
  -X POST \
  $baseurl/v0/disclosures \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
  {
    "person_id": "{PERSON_ID}",
    "type": "REG_DD",
    "version": "1.0",
    "event_type": "ACKNOWLEDGED",
    "disclosure_date": "2022-04-17T02:04:34Z"
  }'

This will respond with a disclosure object:

{
  "creation_time": "2022-04-13T02:17:34.895861Z",
  "disclosure_date": "2022-04-17T00:00:00Z",
  "event_type": "ACKNOWLEDGED",
  "id": "{DISCLOSURE_ID}",
  "last_updated_time": "2022-04-13T02:17:34.895861Z",
  "person_id": "{PERSON_ID}",
  "type": "REG_DD",
  "version": "1.0"
}

3. Activating the Person

After gathering the rest of the identification, use PATCH /v0/persons/{PERSON_ID} to add the other data and move it to ACTIVE status:

curl \
  -X PATCH \
  $baseurl/v0/persons/{PERSON_ID} \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
  {
    "status": "ACTIVE",
    "first_name": "Anne",
    "last_name": "Baker",
    "chosen_name": "Annie",
    "dob": "2000-01-01",
    "phone_number": "+12124567890",
    "ssn": "123-45-6789",
    "legal_address": {
      "address_line_1": "50 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "12345",
      "country_code": "US"
    },
    "shipping_address": {
      "address_line_1": "99 Elm St",
      "city": "San Antonio",
      "state": "TX",
      "postal_code": "77777",
      "country_code": "US"
    }
  }'

📘

Note when listing persons, searching by first_name will search first_name and chosen_name fields.

4. Run KYC

While the new person has a status of ACTIVE, their verification_status is still UNVERIFIED, so they will not be able to perform most banking activities. The next step is verify the person's identity using a Know Your Customer (KYC) verification. See the KYC/KYB Verification 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": "{IP_ADDRESS}",
  "person_id": "{PERSON_ID}"
}'

This will return a list of all the verifications that were run, and a result for each.

If the verifications passed, the person's verification_status will now be ACCEPTED. This can be checked by a GET /v0/persons/{PERSON_ID}:

curl \
  -H "Authorization: Bearer $apikey" \
  $baseurl/v0/verifications/verify

which will respond with:

{
  "creation_time": "2022-04-13T01:52:40.690387Z",
  "dob": "2000-01-01",
  "email": "[email protected]",
  "first_name": "Anne",
  "id": "{PERSON_ID}",
  "chosen_name": "Annie",
  "last_name": "Baker",
  "last_updated_time": "2022-04-13T18:09:12.881517Z",
  "legal_address": {
    "address_line_1": "50 Main St",
    "city": "New York",
    "country_code": "US",
    "postal_code": "12345",
    "state": "NY"
  },
  "phone_number": "+12124567890",
  "shipping_address": {
    "address_line_1": "99 Elm St",
    "city": "San Antonio",
    "country_code": "US",
    "postal_code": "77777",
    "state": "TX"
  },
  "ssn": "6789",
  "status": "ACTIVE",
  "verification_last_run": "2022-04-13T18:09:12.880623Z",
  "verification_status": "ACCEPTED"
}

5. Use the Person with Other APIs

An active person can be used with other Synctera APIs:

• The Accounts can create and manage accounts with the person as an account holder or authorized signer.
• The Cards API can create and manage credit or debit cards linked to the person.
• The Relationships API can link the person to a business as a beneficial owner or officer.
• The Watchlists API can link a person with one or more watchlist monitoring subscriptions so that you can check for a person's presence on security risk watchlists.

Person Status Attributes

The person object contains two status attributes:

• status is an editable attribute representing the administrative state of the person. The integrator can use this to indicate whether they consider the person 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. KYC checks, are performed.

The ability to participate in money movement transactions, issue cards, etc, is limited by both the status and verification_status attributes.

Person Status

The person 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 customer.

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. first_name and last_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 --> DORMANT: No activity
    DORMANT --> ACTIVE
    ACTIVE --> DECEASED
    ACTIVE --> DENIED: Turned down

Verification Status

In order to initiate transactions, an active person must also pass verification. There are different types of verification, including Know Your Customer (KYC) and watchlists.

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 verifications are performed and the meaning of the results.

Handling Sensitive Attributes

Some of the information you collect about customers is personal identifiable information (PII) that can identify an individual directly or indirectly. The Synctera platform encrypts all data at rest so that it’s not easily accessible through attack.

Some PII, e.g. a SSN, is very confidential and requires further safeguards. Synctera stores those attribute values in a vault to control access. When a endpoint later retrieves a resource containing such protected attributes, they will either be omitted from the response, or a masked value will be returned.