Create A Personal Customer

Overview

A person is one of the core entities in the Synctera platform: accounts, ACH, and cards are all tied to the person resource. The object holds personal identification information (name, Social Security Number, address, phone number, email) and status attributes that track its lifecycle from prospect, to active customer, to inactive former customer. Creating a person is the first step in onboarding a customer. You build the record up over time — starting from a partial PROSPECT, gathering the rest of the identification, running identity verification, and finally linking the person to accounts, cards, and other resources. Key characteristics:

Progressive — create a person with only a subset of identification as a PROSPECT, then fill in the rest and activate it.
Dual-status — an editable status (administrative state) and a read-only verification_status (identity-verification result) together gate what the person can do.
Verified — most banking activity requires the person to pass a Know Your Customer (KYC) check, which sets verification_status to ACCEPTED.
Reusable — the returned id links the person to disclosures, accounts, cards, relationships, and watchlists.

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

Synctera is planning breaking changes to the customers API endpoints for v1. To ease migration, new endpoints are available under /v0/persons that reflect the new approach — we recommend using /v0/persons (instead of /v0/customers).These endpoints provide a different style of accessing the same data. Resources created by one endpoint can be accessed through the other with the same ID, which is usable in any API that references a personal customer via a customer_id or person_id attribute.

Prerequisites

This guide assumes you are familiar with:

The curl examples authenticate with an apikey environment variable. Some examples depend on identifiers generated by previous steps; these are shown as placeholders like {PERSON_ID}.

The person object

A person contains the following key fields:

Field	Description
`id`	Unique identifier (read-only, assigned on creation). Used for `GET`, `PATCH`, and `DELETE`, and to link the person to other resources.
`status`	Editable. Administrative state of the person (`PROSPECT`, `ACTIVE`, `FROZEN`, etc.). See Person status.
`verification_status`	Read-only. Result of the verification process (`UNVERIFIED`, `ACCEPTED`, etc.). See Verification status.
`is_customer`	Whether the person is a customer of the platform.
`first_name` / `last_name`	Legal name. Required for all statuses except `PROSPECT`.
`chosen_name`	Preferred name. Searching by `first_name` also matches this field.
`dob`	Date of birth.
`ssn`	Social Security Number. Stored in a vault; returned masked or omitted. See Handling sensitive attributes.
`email` / `phone_number`	Contact details.
`legal_address` / `shipping_address`	Structured address objects.

{
  "id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
  "status": "ACTIVE",
  "verification_status": "ACCEPTED",
  "first_name": "Anne",
  "chosen_name": "Annie",
  "last_name": "Baker",
  "dob": "2000-01-01",
  "ssn": "6789",
  "email": "anne@example.com",
  "phone_number": "+12124567890",
  "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"
  },
  "creation_time": "2022-04-13T01:52:40.690387Z",
  "last_updated_time": "2022-04-13T18:09:12.881517Z",
  "verification_last_run": "2022-04-13T18:09:12.880623Z"
}

See the API reference for the full request and response schemas.

Creating and activating a person

Create the person

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

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/persons \
  --data-binary '
  {
    "status": "PROSPECT",
    "email": "anne@example.com",
    "is_customer": true
  }'

The response includes the system-generated id, which links the person to disclosures, accounts, and other resources:

{
  "id": "{PERSON_ID}",
  "status": "PROSPECT",
  "verification_status": "UNVERIFIED",
  "email": "anne@example.com",
  "creation_time": "2022-04-13T01:52:40.690387Z",
  "last_updated_time": "2022-04-13T01:52:40.690387Z"
}

Record disclosures

Onboarding typically involves disclosing information such as terms of service. See Customer Disclosures for details.To record that the person acknowledged a disclosure, use POST /v0/disclosures with the person’s ID and the disclosure they acknowledged:

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

The response is a disclosure object:

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

Activate the person

Once you have gathered the rest of the identification, use PATCH /v0/persons/{PERSON_ID} to add the remaining data and move the person to ACTIVE status:

curl \
  -X PATCH \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/persons/{PERSON_ID} \
  --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"
    }
  }'

When listing persons, searching by first_name also searches the chosen_name field.

Run KYC verification

An ACTIVE person whose verification_status is still UNVERIFIED cannot perform most banking activities. Verify their identity with a Know Your Customer (KYC) check using POST /v0/verifications/verify:

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v0/verifications/verify \
  --data-binary '
  {
    "customer_consent": true,
    "customer_ip_address": "{IP_ADDRESS}",
    "person_id": "{PERSON_ID}"
  }'

This returns a list of all the verifications that were run and a result for each. See the KYC/KYB Verification guide for the full range of verification and risk checks.If the verifications pass, the person’s verification_status becomes ACCEPTED. Confirm with GET /v0/persons/{PERSON_ID}:

curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  https://api.synctera.com/v0/persons/{PERSON_ID}

{
  "id": "{PERSON_ID}",
  "status": "ACTIVE",
  "verification_status": "ACCEPTED",
  "verification_last_run": "2022-04-13T18:09:12.880623Z",
  "first_name": "Anne",
  "chosen_name": "Annie",
  "last_name": "Baker",
  "dob": "2000-01-01",
  "ssn": "6789",
  "email": "anne@example.com",
  "phone_number": "+12124567890",
  "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"
  },
  "creation_time": "2022-04-13T01:52:40.690387Z",
  "last_updated_time": "2022-04-13T18:09:12.881517Z"
}

Use the person with other APIs

An active, verified person can be used across the platform:

The Accounts API creates and manages accounts with the person as an account holder or authorized signer.
The Cards API creates and manages credit or debit cards linked to the person.
The Relationships API links the person to a business as a beneficial owner or officer.
The Watchlists API subscribes the person to watchlist monitoring so you can check for their presence on security risk watchlists.

Person status attributes

A person carries two independent status attributes, and both gate money movement, card issuance, and other operations:

status — an editable attribute representing the administrative state of the person. Use it to indicate whether you consider the person active, dormant, etc.
verification_status — a read-only attribute set by the platform to reflect the result of the verification process (e.g. KYC checks).

Person status

The status attribute is controlled by your API client. It is up to you to decide what you consider an ACTIVE, FROZEN, or INACTIVE customer. All states other than ACTIVE are restricted and do not allow most banking operations.

Status	Description
`ACTIVE`	An active customer.
`DECEASED`	The person is deceased.
`DENIED`	The customer was turned down.
`DORMANT`	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`	No longer active, e.g. a former customer.
`PROSPECT`	A potential customer, used for information-gathering and disclosures.

There are no restrictions on state transitions, but certain fields (e.g. first_name, last_name) are required by all states except PROSPECT. Typical transitions:

Verification status

To initiate transactions, an active person must also pass verification (KYC, watchlists, and other checks). All states other than ACCEPTED are restricted and do not allow most banking operations.

Verification status	Description
`ACCEPTED`	The person is successfully verified.
`PENDING`	Verification is in progress.
`PROVISIONAL`	Partially verified or verified with restrictions.
`REJECTED`	The person was rejected.
`REVIEW`	Verification ran and identified issues that require review.
`UNVERIFIED`	Verification has not been completed.

See the KYC/KYB Verification guide for how verifications are performed and what the results mean.

Handling sensitive attributes

Some information you collect is personally identifiable information (PII) that can identify an individual directly or indirectly. The Synctera platform encrypts all data at rest. Some PII, such as an SSN, is especially confidential and requires further safeguards. Synctera stores those values in a vault to control access. When an endpoint later retrieves a resource containing such protected attributes, they are either omitted from the response or returned masked.

Best practices

A person cannot perform most banking operations until both status is ACTIVE and verification_status is ACCEPTED. Check both before attempting money movement or card issuance.

Start as a PROSPECT — capture partial identification early, then enrich the record and activate it once you have the full data set.
Record disclosures before activation — keep a clear audit trail of what the customer acknowledged and when.
Capture consent for KYC — always send customer_consent and customer_ip_address when running verification.
Never rely on status alone — an ACTIVE person may still be UNVERIFIED; gate sensitive actions on both attributes.
Treat PII carefully — expect vaulted fields like ssn to be returned masked, and never log full values.

Record Disclosure Acceptance

Record the disclosures a customer acknowledges during onboarding.

KYC/KYB Verification

Understand the verification checks that set verification_status.

Create Accounts

Open accounts with the person as an account holder or authorized signer.

Create a Business Customer

Onboard an organization and link people to it as owners or managers.

Enhanced Due Diligence

Submit extra information for high-risk customers and CRR responses.

Overview

Onboard a personal customer

Onboard a business customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Platform Tools

Create A Personal Customer

Overview

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

Prerequisites

The person object

Creating and activating a person

Person status attributes

Person status

Verification status

Handling sensitive attributes

Best practices

Record Disclosure Acceptance

KYC/KYB Verification

Create Accounts

Create a Business Customer

Enhanced Due Diligence

API reference

​Overview

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

​Prerequisites

​The person object

​Creating and activating a person

​Person status attributes

​Person status

​Verification status

​Handling sensitive attributes

​Best practices

​Related guides

Record Disclosure Acceptance

KYC/KYB Verification

Create Accounts

Create a Business Customer

Enhanced Due Diligence

​API reference

Overview

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

Prerequisites

The person object

Creating and activating a person

Person status attributes

Person status

Verification status

Handling sensitive attributes

Best practices

Related guides

API reference