User Object Details
User Schema
Key
Type
Required
Description
_id
String
N.A. Included in API response
Primary Key of the user object.
account_closure_date
Number
N.A. Included in API response
client.id
String
N.A. Included in API response
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response
Your common name in our system.
documents
Array of Dict
Optional
Contains all the KYC information associated with the user profile.
extra.cip_tag
Int
Optional
extra.date_joined
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the user object was created.
extra.is_business
Boolean
Optional
If the user profile is a business, the value is true
. Default is false
.
extra.last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the user object was last updated.
flag
String
Depends. Only required if you are trying to flag a user.
If FLAGGED
, the user is flagged in our system. Default is NOT-FLAGGED
.
flag_code
String
Depends. Only required if you are trying to flag a user.
permission
String
Depends. Only required if you are trying to close or lock a user account.
permission_code
String
Depends. Only required if you are trying to close or lock a user account.
ips
Array of Strings
N.A. Included in API response. You will be supplying this in the request header when creating a user account X-SP-USER-IP
Known IPs that the user is using to operating their account.
legal_names
Array of Strings
Required during POST
Legal names the user profile will be using.
logins.email
String
Required during POST
email of user.
logins.password
String
Depends. Only required if you wish to use Synapse email/password authentication
password associated with login.
logins.scope
String
Depends. Only required if you wish to use Synapse email/password authentication
If READ
, the user credentials can only read user info. Default is READ-AND-WRITE
.
phone_numbers
Array of Strings
Required during POST
Phone number associated with user login credentials.
refresh_token
String
N.A. Included in API response
supp_id
String
Optional
Unique platform side identifier
watchlists
String
N.A. Included in API response
Possible Flag Codes
Flag Code
Description
Next Steps
Set By
NOT_KNOWN
Flag reason unknown.
No next steps recommend here since legacy tag.
Legacy tag, deprecated now.
ACCOUNT_CLOSURE|BLOCKED_INDUSTRY
User operates in a blocked industry.
Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
ACCOUNT_CLOSURE|HIGH_RISK
User is deemed high risk.
Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|CIP
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|CIP
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|UAR
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|UAR
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|SECURITY
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|SECURITY
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_REVIEW|DOC_REQUEST|CIP
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|DOC_REQUEST|UAR
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|DOC_REQUEST|SECURITY
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|ACCOUNT_CLOSURE|BLOCKED_INDUSTRY
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|ACCOUNT_CLOSURE|HIGH_RISK
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
Possible User Permissions
Permission
Description
Next Steps
Set By
UNVERIFIED
User KYC review unfinished. No account or payment activity allowed.
us
RECEIVE
User KYC review finished. User is allowed to only receive payments, not originate or authorize any payments.
us
SEND-AND-RECEIVE
If this is an acceptable final permission, no additional steps needed.
us
LOCKED
User KYC review finished and user has been locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
CLOSED
User KYC review finished and user has been closed.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
MAKE-IT-GO-AWAY
User account has been unindexed. It's like the account never existed.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
Possible Permission Codes
Permission
Description
Next Steps
Set By
NOT_KNOWN
Permission reason unknown.
No next steps recommend here since legacy tag.
Legacy tag, deprecated now.
UNUSUAL_ACTIVITY|COMPLIANCE_SUSPICIOUS
The user conducted suspicious activity and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
UNUSUAL_ACTIVITY|LEGAL_REQUEST
The user account has been closed due to some legal request that was received.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
KYC_FRAUD|BLOCKED_LIST
User is in a blocked list and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
KYC_FRAUD|FRAUDULENT_DOCS
User supplied fraudulent KYC documents and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
BLOCKED_INDUSTRY
User is operating in a blocked industry and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
HIGH_RETURNS
User has high returns increasing the risk of loss of funds and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
NEGATIVE_BALANCE
User account has been closed due to a negative balance in their account.
Once the user is able to fund their account, either with direct deposit or payment origination, the account will return back to its previous state.
us
PLATFORM_REQUEST
User account has been closed or locked by you or by our team based on your request
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you
USER_REQUEST
User account has been closed or locked by you or by our team based on user request
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
DUPLICATE_ACCOUNT
The user account has been closed because another account with the same KYC on your platform exists in our system
Please ensure that the user has access to their open account thus eliminating the need to open a new duplicate account. You can also view all duplicate accounts for a particular user and then swap the account closure decision from one account to another.
us
Please note that the user will be cashed out automatically from the system if any one of the codes are picked:
UNUSUAL_ACTIVITY|COMPLIANCE_SUSPICIOUS
BLOCKED_INDUSTRY
PLATFORM_REQUEST
USER_REQUEST
PLATFORM_TERMINATED
NO_ACTIVITY
PERMANENT_CLOSURE
When a user is auto cashed out, we will issue a check to their mailing address, if avaliable or else to the base document address on file.
Possible Watchlists Values
Unless your program is configured differently, all values except NO_MATCH
and FALSE_POSITIVE
will impact user permissions and will keep the permission as UNVERIFIED
until further review.
Permission
Description
Next Steps
PENDING
User Object is pending screenings review.
SOFT_MATCH|PENDING_UPLOAD
User is a soft match on one or more relevant sanctions list. A document upload is needed to further evaluate the soft match.
MATCH
User Object is a match on a sanctions screenings list.
SOFT_MATCH
User is a soft match on one or more relevant sanctions list.
No action required on your side. We will review the user object to either decision it as MATCH
or FALSE_POSITIVE
.
NO_MATCH
User Object is a not a match on any relevant sanctions screenings list.
No action required.
FALSE_POSITIVE
User Object was a soft match on one or more relevant sanctions screenings list. But now has been decisioned as a FALSE_POSITIVE
match.
No action required.
Base Document Schema
Key
Type
Required
Description
address_city
String
Yes
address_country_code
String
Yes
ISO Alpha-2 formatted Address country code of the business location or individual's residence.
address_postal_code
Integer
Yes
Address zip/postal code of the business location or individual's residence.
address_street
String
Yes
Address street of the business location or individual's residence.
address_subdivision
String
Yes
Address subdivision (state) of the business location or individual's residence.
alias
String
No
Common name for the individual/entity.
day
Integer
Yes
Day of entity formation for business or Birth date for individual.
month
Integer
Yes
Month of entity formation for business or Birth month for individual.
year
Integer
Yes
Year of entity formation for business or Birth year for individual.
company_activity
Array of String
Yes if business base doc
Allowed values: "MSB","LENDING","NON-US_OFFICE","NON-US_ACTIVITY","CRYPTO","PUBLIC","PRIVATE","REGISTERED_WITH_SEC","OTHER","NBFI-US","NBFI-FOREIGN","LISTED-US","LISTED-FOREIGN","NFP","BANK-US","BANK-FOREIGN","FUND"
.
desired_scope
String
No
doc_option_key
String
No
docs_key
String
No
docs_title
String
No
edd_status
String
N.A. Included in API response
email
String
Yes
Email of the individual/entity associated with this base document.
entity_scope
String
Yes
entity_type
String
Yes
entity_relationship
String
Yes if individual base doc on business user
Allowed values: CONTROLLING_PERSON
,UBO
.
id
String
Yes if you wish to PATCH
an existing base doc
Primary key of the base document. This value is a local primary key, meaning, it's only unique within a user object. Different user objects can have same base doc IDs.
id_score
Number
N.A. Included in API response
trust_level
String
N.A. Included in API response
ip
String
Yes
IP of the individual/entity associated with this base document.
is_active
Boolean
No
If false
, base document wont participate in user permission decisioning. Default is true
.
name
String
Yes
Name of the individual/entity associated with this base document.
maiden_name
String
No
Maiden name of the individual. Helpful to provide this in instances where the individual's maiden name is still associated with their TIN/SSN.
ownership_percentage
Number
Yes if individual base doc on business user
Percentage of the business owned by the beneficial owner.
permission_scope
String
N.A. Included in API response
phone_number
String
Yes
Phone number of the individual/entity associated with this base document.
physical_docs
Array of Objects
No
required_edd_docs
Array of String
N.A. Included in API response
screening_results
Object
N.A. Included in API response
social_docs
Array of Objects
No
Social documents linked to the base document. More details below.
title
String
Yes if individual base doc on business user
Title of the beneficial owner.
virtual_docs
Array of Objects
No
Virtual documents linked to the base document. More details below.
watchlists
String
N.A. Included in API response
Screenings Results Details
Please note that not all sanctions lists will be appropriate for your use-case. Your spec sheet dictates which sanctions lists affect the Possible Watchlists Values. Go to Intro to Spec Sheet to learn more.
Here is an example object for screening_results
object:
Here are all the possible values for individual screenings lists:
Value
Description
FAILED
Screenings have failed, we will auto-retry.
PENDING
Screenings have not been attempted yet. We will auto-run.
FALSE_POSITIVE
Base Document is a false positive on the screenings list.
MATCH
Virtual Document Schema
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
Value of the document.
id
String
Yes if you wish to PATCH
an existing virtual document
Primary key of the virtual document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same virtual document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the virtual document was last updated.
status
String
N.A. Included in API response
meta.country_code
String
Depends
meta.sub_type
String
Depends (Required with usage of BUS_REGISTRATION document type.)
Social Document Schema
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
Value of the document.
id
String
Yes if you wish to PATCH
an existing social document
Primary key of the social document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same social document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the social document was last updated.
status
String
N.A. Included in API response
info.address_city
String
N.A. Included in API response
Address city associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_country_code
String
N.A. Included in API response
ISO Alpha-2 formatted Address country code associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_postal_code
String
N.A. Included in API response
Address zip or postal code associated with the social document. Currently a response in MAILING_ADDRESS
social document.
into.address_street
String
N.A. Included in API response
Address street associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_subdivision
String
N.A. Included in API response
Address subdivision (state) associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_care_of
String
N.A. Included in API response
C/O name associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.invalid_reasons
Array of String
N.A. Included in API response
Currently a response in MAILING_ADDRESS
social document. Two reasons: invalid_address
and address_has_incorrect_unit
.
meta.state_code
String
Depends
meta.country_code
String
Depends
meta.address_street
String
Depends
Address street associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_city
String
Depends
Address city associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_subdivision
String
Depends
Address subdivision (state) associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_country_code
String
Depends
ISO Alpha-2 formatted Address country code associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_postal_code
Integer
Depends
Address zip or postal code associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_care_of
String
No
C/O name associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
Physical Document Schema
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
In case of VIDEO_AUTHORIZATION
, please ensure that the user's face is clearly visible and the audio is clear and states the user saying "I authorize account opening at <name_of_platform>
."
Allowed file types for VIDEO_AUTHORIZATION
: ["mov","mp4","webm","avi","flv","mkv","ogg"]. Please limit video to 5-seconds.
id
String
Yes if you wish to PATCH
an existing virtual document
Primary key of the virtual document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same virtual document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the virtual document was last updated.
status
String
N.A. Included in API response
invalid_reasons
Array of String
N.A. Included in API response
meta.state_code
String
Depends
meta.country_code
String
Depends
meta.id_number
String
Depends
Possible Invalid Reasons Values for Physical Docs
Permission
Description
Next Steps
wrong_file_extension
Prompt the user to upload physical document with a valid file format.
image_not_found
No image found in provided file (e.g. file is empty).
Ensure that this is not a bug on your side and then request the user to re-upload document.
black_and_white_image
Image is black and white (e.g. a high-contrast photoscan of an ID rather than a color picture of an ID).
Prompt the user to upload the physical document in natural color.
palettised_image
The image only has a single color channel (i.e. is an indexed 256-color image) instead of having 3 (RGB) channels.
Prompt the user to upload the physical document in natural color.
poor_image_quality
The image does not contain a recognizable document, has abnormal colors, or is otherwise difficult to read.
Prompt the user to upload a higher resolution physical document in natural color.
name_mismatch
Name on physical document does not match name on Base Doc.
This can happen if the user did not submit their full legal name when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
dob_mismatch
DOB on physical document does not match DOB on Base Doc.
This can happen if the user did accidentally submitted the wrong date
, month
and year
on the base document. Prompt the user to update their dob on the base document and then resubmit the physical document.
face_undetected
No human face found in image, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document in natural color.
mrz_undetected
[Applicable Only to Passports] Machine Readable Zone (MRZ) field not found.
Prompt the user to upload a passport photo with MRZ visible.
name_mismatch_mrz
[Applicable Only to Passports] Name extracted from Machine Readable Zone (MRZ) doesn’t match Base Doc.
This can happen if the user did not submit their full legal name when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
flagged_for_failing_security_feature
Flagged due to image missing missing corners, unable to read information due to glasses or flash, or ID has unusual patterns/formats (e.g. library card, non-DOD military ID card, suspected fake ID, etc.)
Prompt the user to upload a higher resolution physical document in natural color with all corners visible.
flagged_for_potential_fraud
Flagged due to information match with IDV internal blocked database.
company_name_mismatch
Name on physical document does not match name on Base Doc.
This can happen if the user did not submit their full legal name of the company when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
tax_id_mismatch
Tax ID number (TIN) on the physical document does not match the TIN
virtual document.
This can happen if the user did accidentally submitted the wrong TIN
as a virtual documents. Prompt the user to update their TIN
and then resubmit the physical document.
irs_logo_undetected
IRS logo not detected on an IRS issued document.
Prompt the user to upload a higher resolution physical document in natural color with all corners visible.
poor_video_quality
Unable to process video due to poor image quality.
Prompt the user to upload a higher resolution physical document in natural color.
poor_image_and_video_quality
Unable to process image and video files.
Prompt the user to upload a higher resolution physical document in natural color.
image_face_undetected
No human face found in image, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document with face visible.
video_face_undetected
No human face found in video, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document with face visible.
face_mismatch
Face from the video does not match face from previously submitted ID.
Prompt the user to upload a higher resolution physical document with face visible.
audio_comparision_failed
Audio does not match expected statement for comparison.
Prompt the user to upload a video with valid audio artifacts.
audio_undetected
No sound from the video detected.
Prompt the user to upload a video with valid audio artifacts.
image_too_large
File larger than allowed limit (4MB) for or image has higher than allowed pixel density.
Prompt the user to upload a lower resolution physical document in natural color with all corners visible.
address_mismatch
Address on physical document does not match Address on Base Doc.
This can happen if the user has submitted a different address on the base document. Prompt the user to update their address on the base document and then resubmit the physical document.
expired_document
Document is expired.
Prompt the user to upload a non-expired document.
expired_document_possible_misread_retry
Expiration field on physical document is not recognizable, or difficult to read.
Prompt the user to upload a higher resolution document in natural color.
date_not_detected
No date detected on the document.
Prompt the user to upload a non-expired document. In most cases this means that the user is submitting an incorrect type of document.
logo_not_detected
No logo detected on the document.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
unable_to_classify_as_bank_or_bill
Logo on document could not be classified as a known bank or utility provider.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
date_or_logo_failed
Date or logo missing in the document.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
atleast_one_text_field_failed
At least one text field (e.g. name, address, or date) was missing missing or couldn't be matched with Base Doc.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
hq_logo_hq_address_or_date
Logo detected with a high level of confidence, and either address or date detected with a high level of confidence.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
hq_logo_mq_address_and_date
Logo detected with a high level of confidence, but date and address only detected with a medium level of confidence
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
Possible Sub-Document Status Values
Status
Description
Next Steps
SUBMITTED|REVIEWING
Document is pending review.
SUBMITTED|VALID
Document is valid.
Document has been marked as valid.
SUBMITTED|INVALID
Document is invalid.
Prompt the user to upload a valid document.
SUBMITTED
Document has been submitted to us. This status means we currently lack the capability to verify this type of document automatically.
In most cases we recommend using a third-party provider to automatically verify the authenticity of the document before submitting. Once submitted to us, the user is free to be moved to the next onboarding step.
[1] In some instances, if we are unable to automatically verify a document. In those instances the document is queued to be reviewed manually by an agent on our side. This review is completed in 2 business days or less.
Additional Details
Passports
The following details will help assist on proper setup when submitting passports.
Passport Document Types
document_type = GOVT_ID,
used when submitting a passport issued by the United States of America.document_type = PASSPORT_BIODATA
, used when submitting a passport issued by a country other then the United States of America.
When submitting a passport, the country code will be validated based on the value being US or not if you submit the incorrect document_type. document_types that will fail this check, including PASSPORT_BIODATA, are:
NATIONAL_ID
DRIVER_LICENSE
VOTER_REGISTRATION_CARD
PERMANENT_RESIDENT_CARD
PASSPORT_BIODATA
For users submitting passports issued in the United States of America, verification of a Social Security Number is also required. This is regardless of the user's country of residence.
Last updated