User Intro

Intro to Users and their documents

Know Your Customer (KYC) is an important component of running a successful FinTech business. There is no one-size-fits-all, and when it comes to on-boarding customers ("users") there is a fine balance between maintaining compliance, reducing risk and simplifying the experience.

To properly perform KYC on your customers, our team will work with you to develop your Customer Identification Program (CIP). This program determines what your customers should submit to receive SEND-AND-RECEIVE permissions. We support up to 3,000 different CIPs to fit your needs.

To onboard a user and submit their KYC, use the following User Flow:

  1. Create User
  2. OAuth User to perform actions on behalf of the user
  3. Submit KYC (this can also be done when creating the user)

The following types of KYC can be uploaded to a user object:

  1. Base Document:
    Basic information required for all users (ex: Name, DOB, Address, Email, Phone)

  2. Sub-Documents:
    Physical Documents: Images of Documentation (ex: Photo ID, Articles of Incorporation)
    Social Documents: Authenticated Social Profiles (ex: Facebook, LinkedIn, Twitter tokens)
    Virtual Documents: Meta Data (ex: SSN, TIN, Passport Number)

After the user receives SEND-AND-RECEIVE permissions (or other appropriate permissions as noted on your Spec Sheet), they can add accounts ("nodes") and create transactions.

User Object

_id :

Object ID of a user object

_links.self.href :

HAL style link for the user object :

ID of the client where the user was created :

Name of the client that created the user

doc_status.physical_doc :

[DEPRECATED] Status of physical document verification

doc_status.virtual_doc :

[DEPRECATED] Status of virtual document verification

documents[id ] :

ID of the document

documents[id_score ] :

`id_score` is based on documents submitted for user and can be found in the base document. If the ID score is above an agreed-upon threshold, user will be `SEND-AND-RECEIVE`. If the score is below a certain threshold, user will be `UNVERIFIED` and additional KYC will be required.

documents[name ] :

Name of the document owner

documents[permission_scope] :

Permission scope of the document. More Details.

documents.physical_docs.[id ] :

ID of the physical document

documents.physical_docs.[document_type ] :

Type of the physical document

documents.physical_docs.[last_updated ] :

Date when the document was last updated. The value is a unix timestamp in milliseconds.

documents.physical_docs.[status ] :

Status of the physical document.

documents.social_docs.[id ] :

ID of the social document

documents.social_docs.[document_type ] :

Type of the social document

documents.social_docs.[last_updated ] :

Date when the document was last updated. The value is a unix timestamp in milliseconds.

documents.social_docs.[status ] :

Status of the social document.

documents.virtual_docs.[id ] :

ID of the virtual document

documents.virtual_docs.[document_type ] :

Type of the virtual document

documents.virtual_docs.[last_updated ] :

Date when the document was last updated. The value is a unix timestamp in milliseconds

documents.virtual_docs.[status ] :

Status of the virtual document

extra.date_joined :

Date when the user was created. The value is a unix timestamp in milliseconds

extra.is_business :
boolean false

Boolean that denotes if the user object is a business account or personal

extra.supp_id :

Any supplied ID given by the client that created the user

extra.cip_tag :
integer 1

CIP tag assigned to the user profile

is_hidden :
boolean false

Value denotes if the user can be searched by email/name on Synapse services

legal_names :
array of strings

Legal names/Full names associated with the user object

logins[email ] :

Email associated with the login

logins[password ] :

Password associated with the login

logins[scope ] :

Value denotes what permissions the login credentials has. Currently only two scopes are supported: READ_AND_WRITE & READ

permission :

Denotes the account standing. Look at the user permissions section below to learn more

phone_numbers :
array of strings

Phone numbers/2FA devices associated with the user in the following format: +1(123)123-1234

photos :
array of strings

Public avatars associated with the account

refresh_token :

The refresh token associated with the user and your platform

User Permissions

Every user in Synapse has a set of permissions. The permissions dictate what the user can and cannot do within the network. You can find the user permission associated with each user under the permissions key on the user JSON response.

Following are the user permissions and what they mean.

User Permission


User has been created in the system but has not been verified yet. This means the user instance has been created, but no KYC information has been supplied to the user.


User has been created in the system and only has permissions to receive funds.


User has been created in the platform and has permissions to send and receive funds.


User account has been locked and all API actions associated with this user will be blocked. User account may be locked for various reasons
(i.e. fraud, suspicious activity, etc.) There may be additional documentation OR steps needed to unlock the user.


User is unindexed and will be removed from the platform dashboard.


User account is closed but still on record for search

User Intro

Intro to Users and their documents

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.