User Object Details
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 | Unix timestamp (in ms) value of when the account will auto close. Only utilized in instances of a flagged account that needs to be closed. Go to Intro to Risk to learn more. |
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 | Represents if the user is on a meaningful screenings list. Go to Possible Watchlists Values to learn more. |
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 |
Permission | Description | Next Steps | Set By |
UNVERIFIED | User KYC review unfinished. No account or payment activity allowed. | Ensure all KYC has been supplied and is marked as valid by us. Go to Intro to Spec Sheet to learn more. | us |
RECEIVE | User KYC review finished. User is allowed to only receive payments, not originate or authorize any payments. | If this is an acceptable final permission, no additional steps needed. If you also wish to originate or authorize payments on behalf of the user, ensure all KYC has been supplied and is marked as valid by us. Go to Intro to Spec Sheet to learn more. | us |
SEND-AND-RECEIVE | User KYC review finished. User is allowed to operate the account as allowed by the spec sheet. Go to Intro to Spec Sheet to learn more. | 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 |
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.
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. | We will automatically run sanctions screenings, you can poll GET user or use Subscriptions to be able to notified of the update. |
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. | Traverse through documents to see which base document is watchlists:SOFT_MATCH|PENDING_UPLOAD . If it's a business base doc, please upload a valid EIN_DOC . If individual base doc, please upload a valid GOVT_ID or DRIVER_LICENSE . Go to Physical Document Schema to learn more. |
MATCH | User Object is a match on a sanctions screenings list. | Lock user account for an appropriate Permission Code. In this case that would be UNUSUAL_ACTIVITY|LEGAL_REQUEST . |
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. |
Key | Type | Required | Description |
address_city | String | Yes | Address city of the business location or individual's residence. If the user wishes to receive mail elsewhere, you can add that as a MAILING_ADDRESS social document. Go to Social Document Schema to learn more. We recommend verifying your address to prevent failure. |
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 | Included for business user's business base document. Possible values: VALID , INVALID , REVIEWING . Go to KYC, Risk and Compliance to learn more. |
email | String | Yes | Email of the individual/entity associated with this base document. |
entity_scope | String | Yes | Industry or profession of business or individual. Go to Allowed Entity Scopes response section to see all the possible values. |
entity_type | String | Yes | Type of business or gender of the individual. Go to Allowed Entity Types response section to see all the possible values. |
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 | Included for an individual's base document (either for business, joint or individual accounts). Value ranges from 0-1. Go to ID Score to learn more. |
trust_level | String | N.A. Included in API response | Included for an individual's base document (either for business, joint or individual accounts). Value can be low , med or high . Go to ID Score to learn more. |
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 | This object contains all the sanctions screenings lists the user has been run against. This object is just a detailed response that decides the value of watchlists . Our recommendation is not to pay attention to this field but just the watchlists key instead. Go to Screenings Results Details to learn more. |
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 | Represents if the document is on a meaningful screenings list. Go to Possible Watchlists Values to learn more. |
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:{
"ofac_sdn": "MATCH",
"ofac_ssi_list": "MATCH",
"ofac_ukraine-eo13662": "MATCH",
"usa_csl_list": "MATCH",
"hm_treasury_sanctions": "NO_MATCH",
"futures_sanctions": "NO_MATCH",
"fincen_311_sanctions": "NO_MATCH",
"mas_sanctions": "NO_MATCH",
"ofac_fse_list": "NO_MATCH",
"ofac_iran": "NO_MATCH",
"usa_tel_list": "NO_MATCH",
"ofac_ns-plc": "NO_MATCH",
"ofac_sdgt": "NO_MATCH",
"ofac_561_list": "NO_MATCH",
"ofac_syria": "NO_MATCH",
"ofac_fse-sy": "NO_MATCH",
"osfi": "NO_MATCH",
"fbi_counter_intelligence": "NO_MATCH",
"fbi_domestic": "NO_MATCH",
"fbi_cyber": "NO_MATCH",
"fbi_white_collar": "NO_MATCH",
"fbi_crimes_against_children": "NO_MATCH",
"fbi_bank_robbers": "NO_MATCH",
"fbi_wanted_terrorists": "NO_MATCH",
"bis_dpl_sanctions": "NO_MATCH",
"fbi_violent_crimes": "NO_MATCH",
"fbi_domestic_terrorism": "NO_MATCH",
"fbi_human_trafficking": "NO_MATCH",
"fbi_criminal_enterprise_investigations": "NO_MATCH",
"fbi_terrorism": "NO_MATCH",
"fbi_murders": "NO_MATCH",
"pep": "NO_MATCH",
"aucl": "NO_MATCH",
"eucl": "NO_MATCH",
"uk_sanctions": "NO_MATCH",
"switzerland_sanctions": "NO_MATCH",
"dtc_list": "NO_MATCH",
"cftc_sanctions": "NO_MATCH",
"finra_sanctions": "NO_MATCH",
"euro": "NO_MATCH",
"fto_sanctions": "NO_MATCH",
"hardcode_list": "NO_MATCH",
"russian_sanctions": "NO_MATCH",
"singapore_sanctions": "NO_MATCH",
"nk_sanctions": "NO_MATCH",
"cftc_reparations_sanctions": "NO_MATCH",
"interpol": "NO_MATCH",
"usa_rfj": "NO_MATCH",
"belgian_list": "NO_MATCH",
"canada_sema": "NO_MATCH",
"canada_rcmp": "NO_MATCH",
"cftc_red": "NO_MATCH",
"ice_sanctions": "NO_MATCH",
"unsc_cons": "NO_MATCH",
"cons_sdn": "NO_MATCH"
}
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 | Base Document is a soft or actual match on the screenings list. Final determination will happen at the watchlists level. |
Key | Type | Required | Description |
document_type | String | Yes | Type of virtual document being submitted. Go to Allowed Document Types response section to see all the possible values. |
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 | ISO Alpha-2 formatted Address country code of the issuing country of the virtual document. Go to Allowed Document Types response section to see which virtual documents require this field. This field will not be returned in any user responses. |
meta.sub_type | String | Depends (Required with usage of BUS_REGISTRATION document type.) | Native government issued name or common name of the document type of issuing country of virtual document. eg for Brazil sole proprietors they may have a “CNPJ” number. This would be the meta.sub_type of BUS_REGISTRATION. Go to Allowed Document Types response section to see which virtual documents require this field. This field will not be returned in any user responses. |
Key | Type | Required | Description |
document_type | String | Yes | Type of social document being submitted. Go to Allowed Document Types response section to see all the possible values. |
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 | ISO Alpha-2 formatted Address country code of the issuing state of the virtual document. Go to Allowed Document Types response section to see which social documents require this field. This field will not be returned in any user responses. |
meta.country_code | String | Depends | ISO Alpha-2 formatted Address country code of the issuing country of the virtual document. Go to Allowed Document Types response section to see which social documents require this field. This field will not be returned in any user responses. |
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. |
Key | Type | Required | Description |
document_type | String | Yes | Type of physical document being submitted. Go to Allowed Document Types response section to see all the possible values.
For additional details on passports click Passports. |
document_value | String | Yes | Value of the document. Physical documents must be encoded Base64 before being uploaded to our system. Please ensure that the image is clear, with all corners visible in case of a document with legible text. In case of videos, please ensure that the video is clear with ample light and audio is clear and without distortion or disturbance. 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 | If the document status is SUBMITTED|INVALID , invalid_reasons describes the reasons for why the document was marked as invalid. Go to Possible Invalid Reasons Values to learn more. |
meta.state_code | String | Depends | ISO Alpha-2 formatted state code of the issuing state of the physical document. Go to Allowed Document Types response section to see which physical documents require this field. This field will not be returned in any user responses. |
meta.country_code | String | Depends | ISO Alpha-2 formatted country code of the issuing country of the physical document. Go to Allowed Document Types response section to see which physical documents require this field. This field will not be returned in any user responses. |
meta.id_number | String | Depends | ID number associated with the physical document. Go to Allowed Document Types response section to see which physical documents require this field. This field will not be returned in any user responses. |
Permission | Description | Next Steps |
wrong_file_extension | Incorrect file type (e.g. not png, jpeg, jpg). Go to Allowed Document Types response section to see which file extensions are allowed per physical document. | 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 |