> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # Create A Personal Customer > A person represents a natural person on the Synctera platform — an account holder, a beneficial owner of a business, or an authorized signer. A person can hold several of these roles at once. ## 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: * [Need to Know — Environments](/reference/need-to-know#environments) * [Need to Know — Authentication](/reference/need-to-know#authentication) 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](#person-status). | | `verification_status` | **Read-only.** Result of the verification process (`UNVERIFIED`, `ACCEPTED`, etc.). See [Verification status](#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](#handling-sensitive-attributes). | | `email` / `phone_number` | Contact details. | | `legal_address` / `shipping_address` | Structured address objects. | ```json theme={"system"} { "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](/reference/createperson) for the full request and response schemas. ## Creating and activating a person Use [POST /v0/persons](/reference/createperson). If you have only a subset of the identification (e.g. an email but not a name), create the person with `PROSPECT` status: ```shell theme={"system"} 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: ```json theme={"system"} { "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" } ``` Onboarding typically involves disclosing information such as terms of service. See [Customer Disclosures](/docs/record-disclosure-acceptance) for details. To record that the person acknowledged a disclosure, use [POST /v0/disclosures](/reference/createdisclosure) with the person's ID and the disclosure they acknowledged: ```shell theme={"system"} 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: ```json theme={"system"} { "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" } ``` Once you have gathered the rest of the identification, use [PATCH /v0/persons/\{PERSON\_ID}](/reference/updateperson) to add the remaining data and move the person to `ACTIVE` status: ```shell theme={"system"} 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. 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](/reference/verify): ```shell theme={"system"} 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](/docs/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}](/reference/getperson): ```shell theme={"system"} curl \ -X GET \ -H "Authorization: Bearer $apikey" \ https://api.synctera.com/v0/persons/{PERSON_ID} ``` ```json theme={"system"} { "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" } ``` An active, verified person can be used across the platform: * The [Accounts](/docs/create-accounts-guide) API creates and manages accounts with the person as an account holder or authorized signer. * The [Cards](/docs/personal-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: ```mermaid theme={"system"} stateDiagram-v2 [*] --> PROSPECT: Prospect identified PROSPECT --> ACTIVE: Prospect qualified ACTIVE --> INACTIVE: Closed accounts ACTIVE --> FROZEN: Anomalous
activity FROZEN --> ACTIVE: Anomalies
resolved ACTIVE --> DORMANT: No activity DORMANT --> ACTIVE ACTIVE --> DECEASED ACTIVE --> DENIED: Turned down ``` ### 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](/docs/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. ## Related guides Record the disclosures a customer acknowledges during onboarding. Understand the verification checks that set `verification_status`. Open accounts with the person as an account holder or authorized signer. Onboard an organization and link people to it as owners or managers. Submit extra information for high-risk customers and CRR responses. ## API reference * [Create a person](/reference/createperson) * [Get a person](/reference/getperson) * [List persons](/reference/listpersons) * [Update a person](/reference/updateperson) * [Run a verification](/reference/verify) * [Create a disclosure](/reference/createdisclosure)