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 acustomer_id
orperson_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 searchfirst_name
andchosen_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.
Status Value | Description |
---|---|
ACTIVE | An active customer |
DECEASED | The person is deceased |
DENIED | The customer was turned down |
DORMANT | The person is inactive due to an extended period without any transactions |
ESCHEAT | The person's assets are abandoned and are property of the state |
FROZEN | The person's actions are blocked for security, legal, or other reasons |
INACTIVE | The person is marked as no longer active, e.g. a former customer |
PROSPECT | A potential customer, used for information-gathering and disclosures |
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.
Verification Status Value | Description |
---|---|
ACCEPTED | The person is successfully verified |
PENDING | The person's verification is in progress |
PROVISIONAL | The person is partially verified or verified with restrictions |
REJECTED | The person was rejected |
REVIEW | The persons's verification has run and issues have been identified which require review |
UNVERIFIED | The person's verification has not been completed |
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.
Updated 22 days ago