Create User

POST User to Create a User

Before you do anything else, create a User. The user object can be created with minimal parameters (such as login, password and scope), or you can create the user object with more information (including the KYC documents outlined in your Spec Sheet).

API Endpoint

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

PATH PARAMETER

logins :
required
array of objects

User emails used for logins.

phone_numbers :
required
array of strings

All the phone numbers you wish to register with this account

legal_names :
required
array of strings

All the legal names you wish to register with this account

documents :
array of objects

User KYC documents. See Documents Object

extra.note :
string

Any note that you wish to supply to Synapse about the user (not returned with user object)

extra.public_note :
string

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

extra.supp_id :
string

Any ID you wish to register to the user

extra.is_business :
boolean

If the user is a business user, send us True. False by default

extra.cip_tag :
integer

CIP tag associated with the account.

extra.extra_security :
boolean false

If you wish for the user to get a 2FA code every time they OAuth or Login themselves, set this to true

is_hidden :
boolean false

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

EXAMPLE REQUEST

Create a user with or without a base document. We recommend with the base document because you can supply KYC all at once.

POST /v3.1/users 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: |e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "901.111.1111",
    "[email protected]"
  ],
  "legal_names": [
    "Test User"
  ],
  "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":"San Francisco",
        "address_subdivision":"CA",
        "address_postal_code":"94114",
        "address_country_code":"US",
        "desired_scope": "SEND|RECEIVE|TIER|1",
        "doc_option_key": "INVESTOR_DOCS",
        "docs_key": "GOVT_ID_ONLY",
        "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"
        }]
    }],
  "extra": {
    "supp_id": "122eddfgbeafrfvbbb",
    "cip_tag":1,
    "is_business": false
  }
}
POST /v3.1/users 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: |e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "901.111.1111",
    "[email protected]"
  ],
  "legal_names": [
    "Test User"
  ],
  "extra": {
    "supp_id": "122eddfgbeafrfvbbb",
    "cip_tag":1,
    "is_business": false
  }
}
body = {
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "901.111.1111",
    "[email protected]"
  ],
  "legal_names": [
    "Test User"
  ],
  ...
}

new_user = client.create_user(body)
const body = {
  logins: [
    {
      email: '[email protected]'
    }
  ],
  phone_numbers: [
    '901.111.1111',
    '[email protected]'
  ],
  legal_names: [
    'Test User'
  ],
  ...
};

client.createUser(body);
body = {
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "901.111.1111",
    "[email protected]"
  ],
  "legal_names": [
    "Test User"
  ],
  ...
}

client.create_user(payload: body)
$logins_object = (object) [
  'email' => '[email protected]'
];
$legalnames_array = array();
$legalnames_array[] = 'test';

$phoneNumbers_array = array();
$phoneNumbers_array[] = '901.111.1111';

$logins_array = array();
$logins_array[] = $logins_object;
$body = (object) [
  'login_obj' => $logins_obj
  'legal_names' => '$legal_names',
  'phone_number' => '$phone_number'
];

$client->create_user($body);
body = `{
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "901.111.1111",
    "[email protected]"
  ],
  "legal_names": [
    "Test User"
  ],
  ...
}`

data, err := client.CreateUser(body)

Fingerprints
You can either submit unique device fingerprints for each user or static fingerprints. Read more about Fingerprints before creating your first user.

CIP Tags
Refer to your Spec Sheet to determine the appropriate cip_tag for each user.

EXAMPLE SUCCESSFUL 200 RESPONSE

{
    "_id": "594e0fa2838454002ea317a0",
    "_links": {
        "self": {
            "href": "https://uat-api.synapsefi.com/v3.1/users/594e0fa2838454002ea317a0"
        }
    },
    "client": {
        "id": "589acd9ecb3cd400fa75ac06",
        "name": "SynapseFI"
    },
    "doc_status": {
        "physical_doc": "MISSING|INVALID",
        "virtual_doc": "MISSING|INVALID"
    },
    "documents": [
        {
            "id": "2a4a5957a3a62aaac1a0dd0edcae96ea2cdee688ec6337b20745eed8869e3ac8",
            "id_score": 0.95,
            "name": "Test User",
            "permission_scope": "UNVERIFIED",
            "physical_docs": [
                {
                    "document_type": "GOVT_ID",
                    "id": "c486c2cb8c1bce695fcfae3197e14aa5b8ddec184c2779d00d581abee5d9a04c",
                    "last_updated": 1498288031319,
                    "status": "SUBMITTED|REVIEWING"
                }
            ],
            "social_docs": [
                {
                    "document_type": "EMAIL",
                    "id": "2c45158f6431ca874bbe82f63d5905567854dde4d8b81539944e5779e5eee741",
                    "last_updated": 1498288032328,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "FACEBOOK",
                    "id": "8f314a6a53f36ee569455761e49a2a7fe790d251c5611c65255befdb303602b7",
                    "last_updated": 1498288031824,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "PHONE_NUMBER",
                    "id": "fda60784d6375bc44edafaaeae149626c4c13dcb92e85a2a7a00eec2cdfd2b6f",
                    "last_updated": 1498288032830,
                    "status": "SUBMITTED|REVIEWING"
                },
                {
                    "document_type": "IP",
                    "id": "28d9177b22c127d9a51d8903893864accf6e553ac326704a4c0d585eaad2516a",
                    "last_updated": 1498288033333,
                    "status": "SUBMITTED|REVIEWING"
                }
            ],
            "virtual_docs": [
                {
                    "document_type": "SSN",
                    "id": "ee596c2896dddc19b76c07a184fe7d3cf5a04b8e94b9108190cac7890739017f",
                    "last_updated": 1498288030812,
                    "status": "SUBMITTED|REVIEWING"
                }
            ]
        }
    ],
    "emails": [],
    "extra": {
        "cip_tag": 1,
        "date_joined": 1498288029784,
        "extra_security": false,
        "is_business": false,
        "last_updated": 1498288029784,
        "public_note": null,
        "supp_id": "122eddfgbeafrfvbbb"
    },
    "is_hidden": false,
    "legal_names": [
        "Test User"
    ],
    "logins": [
        {
            "email": "[email protected]",
            "scope": "READ_AND_WRITE"
        }
    ],
    "permission": "UNVERIFIED",
    "phone_numbers": [
        "901.111.1111",
        "[email protected]"
    ],
    "photos": [],
    "refresh_token": "refresh_ehG7YBS8ZiD0sLa6PQHMUxryovVkJzElC5gWROXq"
}
{
    "_id": "594e0f151acea2002e6665bb",
    "_links": {
        "self": {
            "href": "https://uat-api.synapsefi.com/v3.1/users/594e0f151acea2002e6665bb"
        }
    },
    "client": {
        "id": "589acd9ecb3cd400fa75ac06",
        "name": "SynapseFI"
    },
    "doc_status": {
        "physical_doc": "MISSING|INVALID",
        "virtual_doc": "MISSING|INVALID"
    },
    "documents": [],
    "emails": [],
    "extra": {
        "cip_tag": 1,
        "date_joined": 1498287892583,
        "extra_security": false,
        "is_business": false,
        "last_updated": 1498287892583,
        "public_note": null,
        "supp_id": "122eddfgbeafrfvbbb"
    },
    "is_hidden": false,
    "legal_names": [
        "Test User"
    ],
    "logins": [
        {
            "email": "[email protected]",
            "scope": "READ_AND_WRITE"
        }
    ],
    "permission": "UNVERIFIED",
    "phone_numbers": [
        "901.111.1111",
        "[email protected]"
    ],
    "photos": [],
    "refresh_token": "refresh_bI0gEY4hv5jZsteonkcrD6qyO3fz2KTd8HFCW9mp"
}

Important Values to Store
Upon successful creation of a user, the user is assigned a unique object ID (_id) and a refresh token (refresh_token). Please store these to reference the user and generate an OAuth token.

Asynchronous User Verification:
User verification is asynchronous. If multiple documents are submitted, it will take longer to verify all of them. Check the appropriate document status to determine whether the required sub-documents are accepted. Check the user's overall permission to show whether all KYC requirements were met.

View all user permissions, base document permissions and sub-document statuses.

Testing in Sandbox
Refer to our Sandbox Test Values to test different responses, including address validation and virtual/physical/social document verification.

Idempotent Requests

Indempotent Requests:
Idempotency allows you to safely retry requests without accidentally performing the same operation twice. For example, if a request to create a user fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a user object is created.

To perform an idempotent request, attach a unique key to any POST request made to the API via the X-SP-IDEMPOTENCY-KEY: <key> header.

Idempotency keys expire after 24 hours.

Subscribe to Webhooks

Please subscribe to user webhooks to monitor permissions and statuses of users and their documents.

Deprecated Field: doc_status

The doc_status object is deprecated and scheduled to be removed.

Next Step: OAuth User to perform actions on the user.

Create User


POST User to Create a User

Suggested Edits are limited on API Reference Pages

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