Sign in

v3

latestOpenAPI 3.0.3Apache 2.02026-07-312637031.3 MB
Persons

Create a person

Create a person who may act as a personal customer or a director/officer/owner of a business. You can then verify the identity of this customer and associate them with other people and accounts. Note that if no shipping_address attribute is provided in the request, the shipping_address will be set to a copy of the legal_address.

post/persons

Headers

Idempotency-Keystring
Example:7d943c51-e4ff-4e57-9558-08cab6b963c7

An idempotency key is an arbitrary unique value generated by client to detect subsequent retries of the same request. It is recommended that a UUID or a similar random identifier be used as an idempotency key. A different key must be used for each request, unless it is a retry.

Request body

ban_status'ALLOWED' | 'BANNED' | 'SUSPENDED'

(beta) Ban status of the person. One of the following:

  • ALLOWED – person is not banned or suspended
  • SUSPENDED - person is manually suspended due to fraud
  • BANNED – person is banned due to matching ban rules Note: changing the ban status to or from BANNED can only be performed by the Synctera platform based on ban rules.
chosen_namestring

Person's chosen name.

creation_timestring date-time

The date and time the resource was created.

customer_activestring date-time

The date and time this person became a bank customer.

dobstring date

Person's date of birth in RFC 3339 full-date format (YYYY-MM-DD). Must be on or after 1900-01-01 and before current date.

emailstring

Person's email.

first_namestring

Person's first name.

has_accountsboolean

This flag indicates whether the person or business has accounts.

idstring uuid

Person's unique identifier.

is_customerboolean required

True for personal and business customers with a direct relationship with the fintech or bank. Set this to true for any customer related to an account.

is_userboolean

True for console users. Set this to true for any users direct access to the Synctera console.

last_namestring

Person's last name.

last_updated_timestring date-time

The date and time the resource was last updated.

metadataMetadata

Optional field to store additional information about the resource. Intended to be used by the integrator to store non-sensitive data.

middle_namestring

Person's middle name.

phone_numberstring

Person's mobile phone number with country code in E.164 format. Must have a valid country code. Area code and local phone number are not validated

spend_control_idsstring[]

List of spend control IDs to control spending for the customer

ssnstring

Person's full tax ID eg SSN formatted with hyphens. The response contains the last 4 digits only (e.g. 6789).

ssn_source'MANUAL' | 'PREFILL'

Describes the collection method for the customer's SSN:

  • MANUAL – the full 9 digits of the customer's SSN was collected.
  • PREFILL – the customer's SSN was collected using SSN Prefill.
status'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION' required

Status of the person. One of the following:

  • ACTIVE – is an integrator defined status. Integrators should set a person to active if they believe the person to be qualified for conducting business. Synctera will combine this status with other statuses such a verification to determine if the person is eligible for specific actions such as initiating transactions or issuing a card.
  • DECEASED – person is deceased.
  • DENIED – customer was turned down.
  • DORMANT – person is no longer active.
  • ESCHEAT – person's assets are abandoned and are property of the state.
  • FROZEN – person's actions are blocked for security, legal, or other reasons.
  • INACTIVE – an inactive status indicating that the person is no longer active.
  • PROSPECT – a potential customer, used for information-gathering and disclosures.
  • SANCTION – person is on a sanctions list and should be carefully monitored.
tenantstring

The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces.

verification_last_runstring date-time

Date and time KYC verification was last run on the person.

verification_status'ACCEPTED' | 'PENDING' | 'PROVISIONAL' | 'REJECTED' | 'REVIEW' | 'UNVERIFIED'

The result of a KYC/KYB verification. One of the following:

  • UNVERIFIED – verification has not been completed for this customer.
  • PENDING – verification is in progress for this customer.
  • PROVISIONAL – partially verified or verified with restrictions.
  • ACCEPTED – the customer has been verified.
  • REVIEW – verification has run and issues have been identified and require review.
  • REJECTED – the customer was rejected and should not be allowed to take certain actions e.g., open an account.
notestring

Text to be added to a note when creating a person. A note is required when creating a person with a ban_status of SUSPENDED.

Example request

{
  "ban_status": "ALLOWED",
  "chosen_name": "Annie",
  "creation_time": "2010-05-06T12:23:34.321Z",
  "customer_active": "2010-05-06T12:23:34.321Z",
  "dob": "2000-01-01",
  "email": "alice@example.com",
  "first_name": "Jane",
  "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
  "is_customer": true,
  "is_user": true,
  "last_name": "Smith",
  "last_updated_time": "2010-05-06T12:23:34.321Z",
  "legal_address": {
    "address_line_1": "100 Main St.",
    "address_line_2": "Suite 99",
    "address_type": "SHIPPING",
    "city": "New York",
    "country_code": "US",
    "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "is_registered_agent": true,
    "nickname": "Home",
    "postal_code": "28620",
    "state": "NY"
  },
  "middle_name": "Anne",
  "phone_number": "+14374570680",
  "shipping_address": {
    "address_line_1": "100 Main St.",
    "address_line_2": "Suite 99",
    "address_type": "SHIPPING",
    "city": "New York",
    "country_code": "US",
    "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "is_registered_agent": true,
    "nickname": "Home",
    "postal_code": "28620",
    "state": "NY"
  },
  "spend_control_ids": [
    "7d943c51-e4ff-4e57-9558-08cab6b963c7"
  ],
  "ssn": "123-45-6789",
  "status": "ACTIVE",
  "tenant": "abcdef_ghijkl",
  "verification_last_run": "2010-05-06T12:23:34.321Z",
  "verification_status": "ACCEPTED",
  "personal_ids": [
    {
      "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
      "id_type": "SSN",
      "identifier": "123-45-6789",
      "expiry_date": "2020-01-01",
      "issue_date": "2020-01-01"
    }
  ]
}

Response

Created person representation.

ban_status'ALLOWED' | 'BANNED' | 'SUSPENDED' required

(beta) Ban status of the person. One of the following:

  • ALLOWED – person is not banned or suspended
  • SUSPENDED - person is manually suspended due to fraud
  • BANNED – person is banned due to matching ban rules Note: changing the ban status to or from BANNED can only be performed by the Synctera platform based on ban rules.
chosen_namestring

Person's chosen name.

creation_timestring date-time required

The date and time the resource was created.

customer_activestring date-time

The date and time this person became a bank customer.

dobstring date

Person's date of birth in RFC 3339 full-date format (YYYY-MM-DD). Must be on or after 1900-01-01 and before current date.

emailstring

Person's email.

first_namestring

Person's first name.

has_accountsboolean

This flag indicates whether the person or business has accounts.

idstring uuid required

Person's unique identifier.

is_customerboolean required

True for personal and business customers with a direct relationship with the fintech or bank. Set this to true for any customer related to an account.

is_userboolean

True for console users. Set this to true for any users direct access to the Synctera console.

last_namestring

Person's last name.

last_updated_timestring date-time required

The date and time the resource was last updated.

metadataMetadata

Optional field to store additional information about the resource. Intended to be used by the integrator to store non-sensitive data.

middle_namestring

Person's middle name.

phone_numberstring

Person's mobile phone number with country code in E.164 format. Must have a valid country code. Area code and local phone number are not validated

spend_control_idsstring[]

List of spend control IDs to control spending for the customer

ssnstring

Person's full tax ID eg SSN formatted with hyphens. The response contains the last 4 digits only (e.g. 6789).

ssn_source'MANUAL' | 'PREFILL'

Describes the collection method for the customer's SSN:

  • MANUAL – the full 9 digits of the customer's SSN was collected.
  • PREFILL – the customer's SSN was collected using SSN Prefill.
status'ACTIVE' | 'DECEASED' | 'DENIED' | 'DORMANT' | 'ESCHEAT' | 'FROZEN' | 'INACTIVE' | 'PROSPECT' | 'SANCTION' required

Status of the person. One of the following:

  • ACTIVE – is an integrator defined status. Integrators should set a person to active if they believe the person to be qualified for conducting business. Synctera will combine this status with other statuses such a verification to determine if the person is eligible for specific actions such as initiating transactions or issuing a card.
  • DECEASED – person is deceased.
  • DENIED – customer was turned down.
  • DORMANT – person is no longer active.
  • ESCHEAT – person's assets are abandoned and are property of the state.
  • FROZEN – person's actions are blocked for security, legal, or other reasons.
  • INACTIVE – an inactive status indicating that the person is no longer active.
  • PROSPECT – a potential customer, used for information-gathering and disclosures.
  • SANCTION – person is on a sanctions list and should be carefully monitored.
tenantstring required

The id of the tenant containing the resource. This is relevant for Fintechs that have multiple workspaces.

verification_last_runstring date-time

Date and time KYC verification was last run on the person.

verification_status'ACCEPTED' | 'PENDING' | 'PROVISIONAL' | 'REJECTED' | 'REVIEW' | 'UNVERIFIED' required

The result of a KYC/KYB verification. One of the following:

  • UNVERIFIED – verification has not been completed for this customer.
  • PENDING – verification is in progress for this customer.
  • PROVISIONAL – partially verified or verified with restrictions.
  • ACCEPTED – the customer has been verified.
  • REVIEW – verification has run and issues have been identified and require review.
  • REJECTED – the customer was rejected and should not be allowed to take certain actions e.g., open an account.
classificationsClassification[]

Specifies the classification of a party for banks. This may contain multiple values for a combined classifications list of customers.

Example response

{
  "ban_status": "ALLOWED",
  "chosen_name": "Annie",
  "creation_time": "2010-05-06T12:23:34.321Z",
  "customer_active": "2010-05-06T12:23:34.321Z",
  "dob": "2000-01-01",
  "email": "alice@example.com",
  "first_name": "Jane",
  "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
  "is_customer": true,
  "is_user": true,
  "last_name": "Smith",
  "last_updated_time": "2010-05-06T12:23:34.321Z",
  "legal_address": {
    "address_line_1": "100 Main St.",
    "address_line_2": "Suite 99",
    "address_type": "SHIPPING",
    "city": "New York",
    "country_code": "US",
    "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "is_registered_agent": true,
    "nickname": "Home",
    "postal_code": "28620",
    "state": "NY"
  },
  "middle_name": "Anne",
  "phone_number": "+14374570680",
  "shipping_address": {
    "address_line_1": "100 Main St.",
    "address_line_2": "Suite 99",
    "address_type": "SHIPPING",
    "city": "New York",
    "country_code": "US",
    "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "is_registered_agent": true,
    "nickname": "Home",
    "postal_code": "28620",
    "state": "NY"
  },
  "spend_control_ids": [
    "7d943c51-e4ff-4e57-9558-08cab6b963c7"
  ],
  "ssn": "123-45-6789",
  "status": "ACTIVE",
  "tenant": "abcdef_ghijkl",
  "verification_last_run": "2010-05-06T12:23:34.321Z",
  "verification_status": "ACCEPTED",
  "vendor_info": {
    "vendor_data": {
      "loanpro": {
        "customer_id": 12345
      }
    }
  },
  "personal_ids": [
    {
      "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
      "id_type": "SSN",
      "identifier": "123-45-6789",
      "expiry_date": "2020-01-01",
      "issue_date": "2020-01-01"
    }
  ]
}