Add User KYC

PATCH User to add new Base Document or Sub-Document for KYC

Previous Step: Create User and OAuth User

This call is used to add a new base document or sub-document for your user's KYC.

Additional Base Documents: A second base document is used for joint accounts or businesses. For example, a business may require a business base document and a beneficial owner base document.

Additional Sub-Documents: An additional sub-document may be added separately to speed up response times (in the case of multiple physical documents). They may also be added for enhanced due diligence or higher KYC tiers.

API ENDPOINT

https://uat-api.synapsefi.com/v3.1/users/:user_id

PATH PARAMETER

user_id :
required
string

The user ID of the user you wish to update documents for

BODY PARAMETER

If successful, the response will include the new base document or sub-document object with the updated user information. To view the complete user document, View User.

documents :
required
string

User KYC documents. See full Documents Object Below

BASE DOCUMENT OBJECT

refresh_token :
string

User's refresh_token

update.legal_name :
string

Updated legal name of the user

update.login.email :
string

Updated login email of the user

update.login.password :
string

Updated login password of the user

update.login.read_only :
boolean

If this is a read-only user or an admin user. By default all users added via this API call are admin users

update.phone_number :
string

Updated phone number of the user

update.remove_login.email :
string

Login email that you wish to remove

update.remove_phone_number :
string

Phone number that you wish to remove

update.remove_legal_name :
string

Legal name that you wish to remove

update.cip_tag :
integer

Updated CIP tag of the user

update.is_hidden :
boolean

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

update.public_note :
string

Any note that you wish to attach to the user (returned with user object)

permission :
string

This field only accepts LOCKED and MAKE-IT-GO-AWAY. Any other value will be ignored. LOCKED locks a user account, MAKE-IT-GO-AWAY will unindex it.

SUB-DOCUMENT OBJECT

documents :
required
string

User KYC documents. See full Documents Object above

EXAMPLE REQUEST

PATCH /v3.1/users/594e0fa2838454002ea317a0 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id_2bb1e412edd311e6bd04e285d6015267|client_secret_2bb1e714edd311e6bd04e285d6015267
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_1mtgLwhYHDVKop04XOEjyWJSsnQqZbGkfRF5ux9v|e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "documents":[{
        "email":"[email protected]",
        "phone_number":"901.111.1111",
        "ip":"::1",
        "name":"Test User",
        "alias":"Test",
        "entity_type":"M",
        "entity_scope":"Arts & Entertainment",
        "day":2,
        "month":5,
        "year":1989,
        "address_street":"1 Market St.",
        "address_city":"SF",
        "address_subdivision":"CA",
        "address_postal_code":"94114",
        "address_country_code":"US",
        "virtual_docs":[{
            "document_value":"2222",
            "document_type":"SSN"
        }],
        "physical_docs":[{
            "document_value": "data:image/gif;base64,SUQs==",
            "document_type": "GOVT_ID"
        }],
        "social_docs":[{
            "document_value":"https://www.facebook.com/valid",
            "document_type":"FACEBOOK"
        }]
    }]
}
body = {
  "documents":[{
        "email":"[email protected]",
        "phone_number":"901.111.1111",
        "ip":"::1",
        "name":"Test User",
        "alias":"Test",
        "entity_type":"M",
        "entity_scope":"Arts & Entertainment",
        "day":2,
        "month":5,
        "year":1989,
        "address_street":"1 Market St.",
        "address_city":"SF",
        "address_subdivision":"CA",
        "address_postal_code":"94114",
        "address_country_code":"US",
        "virtual_docs":[{
            "document_value":"2222",
            "document_type":"SSN"
        }]
        ....
}

user.user_update(body)
const body = {
  documents:[{
    email: '[email protected]',
    phone_number: '901.111.1111',
    ip: '::1',
    name: 'Test User',
    alias: 'Test',
    entity_type: 'M',
    entity_scope: 'Arts & Entertainment',
    day: 2,
    month: 5,
    year: 1989,
    address_street: '1 Market St.',
    address_city: 'SF',
    address_subdivision: 'CA',
    address_postal_code: '94114',
    address_country_code: 'US',
    ...
  }]
};

user.addUserKyc(body);
body = {
  "documents":[{
        "email":"[email protected]",
        "phone_number":"901.111.1111",
        "ip":"::1",
        "name":"Test User",
        "alias":"Test",
        "entity_type":"M",
        "entity_scope":"Arts & Entertainment",
        "day":2,
        "month":5,
        "year":1989,
        "address_street":"1 Market St.",
        "address_city":"SF",
        "address_subdivision":"CA",
        "address_postal_code":"94114",
        "address_country_code":"US",
        "virtual_docs":[{
            "document_value":"2222",
            "document_type":"SSN"
        }]
        ....
}

user.user_update(payload: body)
$body = array (
  'documents' =>
  array (
    array (
      'email' => '[email protected]',
      'phone_number' => '901.111.1111',
      'ip' => '::1',
      'name' => 'Test User',
      'alias' => 'Test',
      'entity_type' => 'M',
      'entity_scope' => 'Arts & Entertainment',
      'day' => 2,
      'month' => 5,
      'year' => 1989,
      'address_street' => '1 Market St.',
      'address_city' => 'San Francisco',
      'address_subdivision' => 'CA',
      'address_postal_code' => '94114',
      'address_country_code' => 'US',
      'virtual_docs' =>
      array (
        array (
          'document_value' => '2222',
          'document_type' => 'SSN',
        ),
				.....
      ),
    ),
  ),
);

$user = $client->update_info($body);
body := `{
  "documents":[{
        "email":"[email protected]",
        "phone_number":"901.111.1111",
        "ip":"::1",
        "name":"Test User",
        "alias":"Test",
        "entity_type":"M",
        "entity_scope":"Arts & Entertainment",
        "day":2,
        "month":5,
        "year":1989,
        "address_street":"1 Market St.",
        "address_city":"SF",
        "address_subdivision":"CA",
        "address_postal_code":"94114",
        "address_country_code":"US",
        "virtual_docs":[{
            "document_value":"2222",
            "document_type":"SSN"
        }]
        ....
}`

data, err := user.Update(body)

EXAMPLE RESPONSE

Sub-documents are verified asynchronously. Upon submission, they will have a status SUBMITTED|REVIEWING. To check on the verification status of a document, View User or subscribe to user|post and user|patch webhooks. Learn more about subscription webhooks.

{
    "_id": "594e0fa2838454002ea317a0",
    "_links": {
        "self": {
            "href": "https://uat-api.synapsefi.com/v3.1/users/594e0fa2838454002ea317a0"
        }
    },
    "client": {
        "id": "589acd9ecb3cd400fa75ac06",
        "name": "SynapseFI"
    },
    "doc_status": {
        "physical_doc": "SUBMITTED|VALID",
        "virtual_doc": "SUBMITTED|VALID"
    },
    "documents": [
        {
            "id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8",
            "name": "Test User",
            "permission_scope": "SEND|RECEIVE|1000|DAILY",
            "physical_docs": [
                {
                    "document_type": "GOVT_ID",
                    "id": "c486c2cb8c1bce695fcfae3197e14aa5b8ddec184c2779d00d581abee5d9a04c",
                    "last_updated": 1498288034877,
                    "status": "SUBMITTED|VALID"
                },
                {
                    "document_type": "GOVT_ID",
                    "id": "70e3f32d8feba746347b5c0d820e8d7a218b955afbb612291a0a9922c93e8277",
                    "last_updated": 1498288359656,
                    "status": "SUBMITTED|REVIEWING"
                }
            ],
            "social_docs": [
                {
                    "document_type": "IP",
                    "id": "28d9177b22c127d9a51d8903893864accf6e553ac326704a4c0d585eaad2516a",
                    "last_updated": 1498288361711,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "FACEBOOK",
                    "id": "8f314a6a53f36ee569455761e49a2a7fe790d251c5611c65255befdb303602b7",
                    "last_updated": 1498288360174,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "PHONE_NUMBER",
                    "id": "fda60784d6375bc44edafaaeae149626c4c13dcb92e85a2a7a00eec2cdfd2b6f",
                    "last_updated": 1498288361200,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "EMAIL",
                    "id": "2c45158f6431ca874bbe82f63d5905567854dde4d8b81539944e5779e5eee741",
                    "last_updated": 1498288360686,
                    "status": "SUBMITTED|REVIEWING"
                }
            ],
            "virtual_docs": [
                {
                    "document_type": "SSN",
                    "id": "ee596c2896dddc19b76c07a184fe7d3cf5a04b8e94b9108190cac7890739017f",
                    "last_updated": 1498288359140,
                    "status": "SUBMITTED|REVIEWING"
                }
            ]
        }
    ],
    "emails": [],
    "extra": {
        "cip_tag": 1,
        "date_joined": 1498288029784,
        "extra_security": false,
        "is_business": false,
        "last_updated": 1498288358611,
        "public_note": null,
        "supp_id": "122eddfgbeafrfvbbb"
    },
    "is_hidden": false,
    "legal_names": [
        "Test User"
    ],
    "logins": [
        {
            "email": "[email protected]",
            "scope": "READ_AND_WRITE"
        }
    ],
    "permission": "SEND-AND-RECEIVE",
    "phone_numbers": [
        "901.111.1111",
        "[email protected]"
    ],
    "photos": [],
    "refresh_token": "refresh_ehG7YBS8ZiD0sLa6PQHMUxryovVkJzElC5gWROXq"
}

Submitting Physical Documents

The base64 you send via this API call should be padded. See example below:

"data:text/csv;base64,<actual_file_data>

Submitting more than one physical document at a time might result in a delay in response time. If you have more than one physical document, it is recommended that you perform separate calls to add each document.

document_value
Result
Document Type

.png / .jpg / .jpeg

Validation is successful.

GOVT_ID

.png / .jpg / .jpeg

Validation is successful.

GOVT_ID_BACK

.png / .jpg / .jpeg

Validation is successful.

GOVT_ID_INT

.png / .jpg / .jpeg

Validation is successful.

GOVT_ID_INT_BACK

.mov / .mp4 / .webm

Validation is successful.

VIDEO_AUTHORIZATION

.png / .jpg / .jpeg

Validation is successful.

SELFIE

.png / .jpg / .jpeg / .pdf

Validation is successful.

PROOF_OF_ADDRESS

.png / .jpg / .jpeg / .pdf

Validation is successful.

PROOF_OF_INCOME

.png / .jpg / .jpeg / .pdf

Validation is successful.

PROOF_OF_ACCOUNT

.png / .jpg / .jpeg

Validation is successful.

AUTHORIZATION

.png / .jpg / .jpeg /.pdf

Validation is successful.

BG_CHECK

.png / .jpg / .jpeg / .pdf

Validation is successful.

SSN_CARD

.png / .jpg / .jpeg / .pdf

Validation is successful.

EIN_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

W9_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

W2_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

W8_DOC

.png / .jpg / .jpeg

Validation is successful.

VOIDED_CHECK

.png / .jpg / .jpeg / .pdf

Validation is successful.

AOI

.png / .jpg / .jpeg / .pdf

Validation is successful.

BYLAWS_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

LOE

.png / .jpg / .jpeg / .pdf

Validation is successful.

CIP_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

SUBSCRIPTION_AGREEMENT

.png / .jpg / .jpeg / .pdf

Validation is successful.

PROMISSORY_NOTE

.png / .jpg / .jpeg / .pdf

Validation is successful.

LEGAL_AGREEMENT

.png / .jpg / .jpeg / .pdf

Validation is successful.

REG_GG

.png / .jpg / .jpeg / .pdf

Validation is successful.

DBA_DOC

.png / .jpg / .jpeg / .pdf

Validation is successful.

DEPOSIT_AGREEMENT

.png / .jpg / .jpeg / .pdf

Validation is successful.

OTHER

Submitting Virtual Documents

Following are test values for Virtual Document verification in Sandbox. The last 4 digits of your virtual document must be one of the following values (ex: SSN = 777772222).

Note that you cannot verify real identities and document information in sandbox.

document_value
Result
Document Type

2222

Validation is successful.

SSN

2222

Validation is successful.

PASSPORT

2222

Validation is successful.

DRIVERS_LICENSE

2222

Validation is successful.

PERSONAL_IDENTIFICATION

2222

Validation is successful.

TIN

2222

Validation is successful.

DUNS

2222

Validation is successful.

OTHER

Submitting Social Documents

Following are test values for Social Document verification

document_value
Result
Document Type

Validation Fails (i.e. identity related information is a complete fail).

FACEBOOK

Validation Fails (i.e. identity related information is a complete fail).

LINKEDIN

Validation Fails (i.e. identity related information is a complete fail).

TWITTER

Validation Fails (i.e. identity related information is a complete fail).

EMAIL (supplied via base doc)

255.255.255.0

Validation Fails (i.e. identity related information is a complete fail).

IP (supplied via base doc)

541-754-3010

Validation Fails (i.e. identity related information is a complete fail).

PHONE_NUMBER (supplied via base doc)

123456

Validation Succeeds during SUBMITTED|MFA_PENDING

EMAIL_2FA and PHONE_NUMBER_2FA

Important Values
Save the base document id located under documents.id. You will need this when creating DEPOSIT-US or SUBACCOUNT-US nodes.

Deprecated Field: doc_status

The permission field will show you the overall user permissions, which is determined by the permission_scope of the base document(s). The permission scope is determined by whether or not the required sub-documents are acceptable, and you can check each sub-document's status field for this.

The doc_status object is deprecated and scheduled to be removed.