Spec Sheet Integration

Spec sheet resource and guide

CIP stands for "Customer Identification Program". A CIP document is custom to each platform and outlines the requirements and KYC (Know Your Customer) documents that need to be collected from each user on the platform. There are 3 different types of KYC documents that can be collected: physical documents, virtual documents, and social documents.

This guide will show you how to integrate with the Synapse API according to your platform's CIP document. The integration process discussed in this guide is based on the common flow and uses sandbox test values in the request examples.

The example CIP used in this guide has 2 different types of users: individuals and businesses.

KYC requirements/permissions for individual users.

KYC requirements/permissions for individual users.

KYC requirements/permissions for business users.

KYC requirements/permissions for business users.

1. Create User

The first step is to create a user on your platform. The cip_tag in addition to the user type (individual vs. business) assigned to the user determines what information/KYC documents are required for the user to be verified and also determines the user's permissions, types of accounts (nodes) they're allowed to create, transaction limits, acceptable flow of funds, and the maximum number of nodes they can have under their user account.

According to the example CIP above, the platform has 2 types of users: individuals with cip_tag: 1 and businesses with cip_tag: 1. The requests to create these users would look something like the example below:

POST /v3.1/users HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: |fingerprint
Content-Type: application/json

{
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "123-456-7777"
  ],
  "legal_names": [
    "Test User"
  ],
  "extra": {
    "cip_tag": 1,
    "is_business": false
  }
}
{
  "_id": "590bae4deba6500022ca53e0",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1493937740425,
    "extra_security": false,
    "is_business": false,
    "last_updated": 1493937740425,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Test User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "123-456-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_eff4c99a311a11e7aba90230ada41dd6"
}
POST /v3.1/users HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: |fingerprint
Content-Type: application/json

{
  "logins": [
    {
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    "111-222-7777"
  ],
  "legal_names": [
    "Business User"
  ],
  "extra": {
    "cip_tag": 1,
    "is_business": true
  }
}
{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494433713318,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

In the request payload, is_business corresponds to letter A in the CIP document above and cip_tag corresponds to letter B.

User ID

In the response from Create User, please remember to store _id of the user in your database so you can access that user's account in the future.

In the response, notice that the user permission is UNVERIFIED. In order to verify each user, the appropriate KYC information/documents listed in the CIP need to be added to the corresponding user.

2. OAuth User

To make further requests on the user's behalf, you need to OAuth the user. Grab the refresh_token from the response in step one and make the following request:

POST /v3.1/oauth/590bae4deba6500022ca53e0 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: |fingerprint
Content-Type: application/json

{
  "refresh_token": "refresh_eff4c99a311a11e7aba90230ada41dd6"
}
{
  "client_id": "589a9eed86c2736412ce7e21",
  "client_name": "Client Platform",
  "expires_at": "1493966006",
  "expires_in": "7200",
  "oauth_key": "oauth_fafccf28314b11e7aba90230ada41dd6",
  "refresh_expires_in": 9,
  "refresh_token": "refresh_eff4c99a311a11e7aba90230ada41dd6",
  "scope": [
    "USER|PATCH",
    "USER|GET",
    "NODES|POST",
    "NODES|GET",
    "NODE|GET",
    "NODE|PATCH",
    "NODE|DELETE",
    "TRANS|POST",
    "TRANS|GET",
    "TRAN|GET",
    "TRAN|PATCH",
    "TRAN|DELETE"
  ],
  "user_id": "590bae4deba6500022ca53e0"
}
POST /v3.1/oauth/59135352ce9311001e3a8f43 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: |fingerprint
Content-Type: application/json

{
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}
{
  "client_id": "589a9eed86c2736412ce7e21",
  "client_name": "Client Platform",
  "expires_at": "1494441077",
  "expires_in": "7200",
  "oauth_key": "oauth_1778a554359e11e799b90230ad640784",
  "refresh_expires_in": 9,
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e",
  "scope": [
    "USER|PATCH",
    "USER|GET",
    "NODES|POST",
    "NODES|GET",
    "NODE|GET",
    "NODE|PATCH",
    "NODE|DELETE",
    "TRANS|POST",
    "TRANS|GET",
    "TRAN|GET",
    "TRAN|PATCH",
    "TRAN|DELETE"
  ],
  "user_id": "59135352ce9311001e3a8f43"
}

The oauth_key from the response will need to be included in the request headers for subsequent API calls for the user. You can read more about OAuth keys and refresh tokens here.

OAuth keys & Refresh tokens

An oauth_key expires in 2 hours (from the time it was generated). After an oauth_key expires, you can use the refresh_token to generate a new oauth_key. When the oauth_key is refreshed, a new refresh_token might be issued as well. Refresh tokens expire after 10 uses and update periodically. We manage this complexity for you. To get the most recent refresh_token, make a request to Get User and grab the refresh_token from the response.

3. Add KYC Info/Documents

KYC Individual User

According to the example CIP, the following information needs to be collected from the individual user: the base document info, SSN (virtual document), and GOVT_ID (physical document). This corresponds to letters C and D in the diagram.

When submitting a photo ID (GOVT_ID), please review the list of suggestions to improve accuracy for Photo ID uploads.

PATCH /v3.1/users/590bae4deba6500022ca53e0 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "documents":[
    {
      "email":"[email protected]",
      "phone_number":"123-456-7777",
      "ip":"12134323",
      "name":"Test User",
      "alias":"Individual User",
      "entity_type":"M",
      "entity_scope":"Arts & Entertainment",
      "day":2,
      "month":5,
      "year":1989,
      "address_street":"170 St Germain Ave",
      "address_city":"SF",
      "address_subdivision":"CA",
      "address_postal_code":"94114",
      "address_country_code":"US",
      "virtual_docs":[
        {
          "document_value":"222-22-2222",
          "document_type":"SSN"
        }
      ],
      "physical_docs":[
        {
          "document_value": "data:image/gif;base64,R0lGODlhMAAwAPf/AK==",
          "document_type": "GOVT_ID"
        }
      ]
    }
  ]
}
{
  "_id": "590bae4deba6500022ca53e0",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [
    {
      "id": "e69f8e970a13b01ce5ace6dda9f4370bdb890524963bdc04b629da88c7e43a9b",
      "name": "Test User",
      "permission_scope": "UNVERIFIED",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "5ad560b44bde1e4eafd291aae4c7ae4b4c7c4052350ec093a41a572cafcc3320",
          "last_updated": 1493962763409,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1493962765233,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "c1048b947148bdf1c21207b28864222b8db3da274bc2eb15299bbdc680e94f86",
          "last_updated": 1493962764727,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "d8592542a7142adaf1e4bd21a3fe16ddbaf877cacae4348152b545170e49056f",
          "last_updated": 1493962764206,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1493962762801,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1493937740425,
    "extra_security": false,
    "is_business": false,
    "last_updated": 1493962762269,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Test User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "123-456-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_eff4c99a311a11e7aba90230ada41dd6"
}

As you can see from the response above, the SSN and GOVT_ID have a status of SUBMITTED|VALID, but the user permission and document permission_scope is UNVERIFIED. This is because the user permission and document permission_scope is updated asynchronously, so you will have to use polling (GET User) or subscriptions to get the most recent information on the user.

After a few seconds, making a request to GET User will return the following response:

{
  "_id": "590bae4deba6500022ca53e0",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "SUBMITTED|VALID",
    "virtual_doc": "SUBMITTED|VALID"
  },
  "documents": [
    {
      "id": "e69f8e970a13b01ce5ace6dda9f4370bdb890524963bdc04b629da88c7e43a9b",
      "name": "Test User",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "5ad560b44bde1e4eafd291aae4c7ae4b4c7c4052350ec093a41a572cafcc3320",
          "last_updated": 1493962763409,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1493962765233,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "c1048b947148bdf1c21207b28864222b8db3da274bc2eb15299bbdc680e94f86",
          "last_updated": 1493962764727,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "d8592542a7142adaf1e4bd21a3fe16ddbaf877cacae4348152b545170e49056f",
          "last_updated": 1493962764206,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1493962762801,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1493937740425,
    "extra_security": false,
    "is_business": false,
    "last_updated": 1493962762269,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Test User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "SEND-AND-RECEIVE",
  "phone_numbers": [
    "123-456-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_eff4c99a311a11e7aba90230ada41dd6"
}

Notice in the response above that now permission is SEND-AND-RECEIVE and the document permission_scope is SEND|RECEIVE|2000|DAILY. These fields correspond to letters E and H in the diagram. The user was given SEND-AND-RECEIVE permissions because the appropriate KYC documents (letters C and D in diagram) were submitted and valid. You can learn more about user permissions, document status, and document permission scope in our docs.

What if one (or more) of the KYC documents was considered invalid? Depending on the requirements listed in the CIP, user and document permissions could change. In the example CIP (section D), both SSN (virtual document) and GOVT_ID (physical document) must be valid in order for the user to be verified. However, if the SSN was invalid (document status of SUBMITTED|INVALID), then the user could submit their SSN_CARD (physical document) as a backup document for the SSN requirement. So a valid SSN_CARD in addition to a valid GOVT_ID would verify the user and give them SEND-AND-RECEIVE permissions. But if the SSN requirement or GOVT_ID was invalid, then the user permission and document permission_scope would be UNVERIFIED.

KYC Business User

According to the example CIP, the business user needs to submit at least 2 sets of KYC information/documents: one set for business information and another set for beneficial owner information.

The following information/documents are required for the business info set: base document fields, TIN (virtual document), EIN_DOC (physical document), BYLAWS_DOC (physical document), AOI (physical document).

Physical Documents

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

The following information/documents are required for the beneficial owner info set: base document fields, SSN (virtual document), and GOVT_ID (physical document).

To submit the 2 sets of KYC documents, you should make 2 separate calls to Add Documents: one call to add business info/documents and another call to add beneficial owner info/documents.

Let's first add KYC documents corresponding to the beneficial owner:

PATCH /v3.1/users/59135352ce9311001e3a8f43 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "documents":[
  	{
      "email":"[email protected]",
      "phone_number":"444-333-5555",
      "ip":"12134323",
      "name":"Beneficial Owner",
      "alias":"Business Owner",
      "entity_type":"M",
      "entity_scope":"Bank & Financial Services",
      "day":13,
      "month":8,
      "year":1989,
      "address_street":"130 St Germain Ave",
      "address_city":"SF",
      "address_subdivision":"CA",
      "address_postal_code":"94114",
      "address_country_code":"US",
      "virtual_docs":[
        {
          "document_value":"222-22-2222",
          "document_type":"SSN"
        }
      ],
      "physical_docs":[
        {
          "document_value": "data:image/gif;base64,R0lGOD==",
          "document_type": "GOVT_ID"
        }
      ]
    }
  ]
}
{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [
    {
      "id": "4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844",
      "name": "Beneficial Owner",
      "permission_scope": "UNVERIFIED",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "fbab7ed1d3e7b5391c54e3e60ab0db148d6fb6016b3c20aecdeb45b6f27f4cb4",
          "last_updated": 1494434566951,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "PHONE_NUMBER",
          "id": "95a6638a9d700ac4a26cbf55d97ee72abb5f85c7ff75de6aa66c316218960730",
          "last_updated": 1494434567924,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494434568410,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "1776f9e6ce198edc4feb3f158692c6eb4bb42fe66cb9eb819bf7e884f0c54b45",
          "last_updated": 1494434567439,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1494434566461,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494434565964,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

In the next step, we'll add KYC documents corresponding to the business info. However, the business info requires 3 physical documents to be submitted. Since submitting more than one physical document at a time can result in a delayed response, we'll split this step into 3 separate API calls:
A) Add Documents to add the base document + TIN (virtual document) + EIN_DOC (physical document),
B) Update Existing Document to add the second physical document (BYLAWS_DOC) to the business info set,
C) Update Existing Document to add the third physical document (AOI) to the business info set.

Here's the request for step A: base document + TIN + EIN_DOC

PATCH /v3.1/users/59135352ce9311001e3a8f43 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "documents":[
  	{
      "email":"[email protected]",
      "phone_number":"222-333-4444",
      "ip":"12134323",
      "name":"Business Name",
      "alias":"Business Name",
      "entity_type":"LLC",
      "entity_scope":"Bank & Financial Services",
      "day":2,
      "month":6,
      "year":2010,
      "address_street":"120 Mission St",
      "address_city":"SF",
      "address_subdivision":"CA",
      "address_postal_code":"94114",
      "address_country_code":"US",
      "virtual_docs": [
        {
          "document_value":"2222",
          "document_type":"TIN"
        }
      ],
      "physical_docs": [
        {
          "document_value":"data:image/gif;base64,R0lGODl===",
          "document_type":"EIN_DOC"
        }
      ]
    }
  ]
}
{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [
    {
      "id": "4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844",
      "name": "Beneficial Owner",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "fbab7ed1d3e7b5391c54e3e60ab0db148d6fb6016b3c20aecdeb45b6f27f4cb4",
          "last_updated": 1494434569630,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "EMAIL",
          "id": "1776f9e6ce198edc4feb3f158692c6eb4bb42fe66cb9eb819bf7e884f0c54b45",
          "last_updated": 1494434569633,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494434569633,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "95a6638a9d700ac4a26cbf55d97ee72abb5f85c7ff75de6aa66c316218960730",
          "last_updated": 1494434569633,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1494434569628,
          "status": "SUBMITTED|VALID"
        }
      ]
    },
    {
      "id": "e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "name": "Business Name",
      "permission_scope": "UNVERIFIED",
      "physical_docs": [
        {
          "document_type": "EIN_DOC",
          "id": "d96c7d22b5c4e33809952c00df524f1c83a4706e8d9af8b891d01675b162190c",
          "last_updated": 1494436045671,
          "status": "SUBMITTED"
        }
      ],
      "social_docs": [
        {
          "document_type": "PHONE_NUMBER",
          "id": "510a94628812b825a1703cf34c13f5c16329562954fa8dcd176ef31412424256",
          "last_updated": 1494436046648,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494436047140,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "e5b7a9b26fbe3d7da4b6cff02325e8e44797497ba0a9683c28badb96d86c5540",
          "last_updated": 1494436046161,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "TIN",
          "id": "a55cc12f46e8091f741b978d5fa556b2f8772a75007a82aae10a2fd810f644cb",
          "last_updated": 1494436045169,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494436044640,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

As you can see in the response from step A, there are now 2 base document objects in the documents array: one corresponds to the beneficial owner and the other corresponds to the business info.

Looking at the base document object that corresponds to the beneficial owner (document id: 4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844), we can see that the document permission_scope is SEND|RECEIVE|2000|DAILY. This means that the appropriate KYC documents for the beneficial owner (SSN and GOVT_ID) were submitted and valid.

However, the base document object that corresponds to the business info (document id: e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81) has a document permission_scope of UNVERIFIED. This is because we have only added the TIN and EIN_DOC, so we still need to submit the BYLAWS_DOC and AOI in order to have a document permission_scope of SEND|RECEIVE|2000|DAILY.

In addition, notice that the overall user permission is still UNVERIFIED. When there are multiple document objects in the documents array, the lowest document permission_scope ends up being the permission associated with the user account. In this case, the business info object has the lowest document permission_scope of UNVERIFIED so the overall user permission remains at UNVERIFIED.

Step B: Add the second physical document (BYLAWS_DOC) to the business info set

Grab the document id that corresponds to the business info (e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81) so you can make a call to Update Existing Document in order to add the BYLAWS_DOC to the physical_docs in the business info object.

PATCH /v3.1/users/59135352ce9311001e3a8f43 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "documents":[
    {
      "id":"e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "physical_docs": [
        {
          "document_value":"data:image/gif;base64,R0lGODlhM===",
          "document_type":"BYLAWS_DOC"
        }
      ]
    }
  ]
}
{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [
    {
      "id": "4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844",
      "name": "Beneficial Owner",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "fbab7ed1d3e7b5391c54e3e60ab0db148d6fb6016b3c20aecdeb45b6f27f4cb4",
          "last_updated": 1494436048372,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494436048376,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "1776f9e6ce198edc4feb3f158692c6eb4bb42fe66cb9eb819bf7e884f0c54b45",
          "last_updated": 1494436048375,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "95a6638a9d700ac4a26cbf55d97ee72abb5f85c7ff75de6aa66c316218960730",
          "last_updated": 1494436048376,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1494436048369,
          "status": "SUBMITTED|VALID"
        }
      ]
    },
    {
      "id": "e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "name": "Business Name",
      "permission_scope": "UNVERIFIED",
      "physical_docs": [
        {
          "document_type": "EIN_DOC",
          "id": "d96c7d22b5c4e33809952c00df524f1c83a4706e8d9af8b891d01675b162190c",
          "last_updated": 1494436048905,
          "status": "SUBMITTED"
        },
        {
          "document_type": "BYLAWS_DOC",
          "id": "eddd2fe8fc8e9192bfc159261ab6b44591660ce9eca3a38e7ea003b5cff1d26a",
          "last_updated": 1494437106093,
          "status": "SUBMITTED"
        }
      ],
      "social_docs": [
        {
          "document_type": "PHONE_NUMBER",
          "id": "510a94628812b825a1703cf34c13f5c16329562954fa8dcd176ef31412424256",
          "last_updated": 1494436048908,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494436048908,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "e5b7a9b26fbe3d7da4b6cff02325e8e44797497ba0a9683c28badb96d86c5540",
          "last_updated": 1494436048908,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "TIN",
          "id": "a55cc12f46e8091f741b978d5fa556b2f8772a75007a82aae10a2fd810f644cb",
          "last_updated": 1494436048901,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494437106083,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

As you can see in the response from step B, the physical_docs (in the business info object) now contains 2 documents: the EIN_DOC from step A and the BYLAWS_DOC that was just added.

Step C) Add the third physical document (AOI) to the business info set:

PATCH /v3.1/users/59135352ce9311001e3a8f43 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id|client_secret
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "documents":[
    {
      "id":"e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "physical_docs": [
        {
          "document_value":"data:image/gif;base64,R0lGODlhMAA==",
          "document_type":"AOI"
        }
      ]
    }
  ]
}
{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "MISSING|INVALID",
    "virtual_doc": "MISSING|INVALID"
  },
  "documents": [
    {
      "id": "e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "name": "Business Name",
      "permission_scope": "UNVERIFIED",
      "physical_docs": [
        {
          "document_type": "EIN_DOC",
          "id": "d96c7d22b5c4e33809952c00df524f1c83a4706e8d9af8b891d01675b162190c",
          "last_updated": 1494437107870,
          "status": "SUBMITTED"
        },
        {
          "document_type": "BYLAWS_DOC",
          "id": "eddd2fe8fc8e9192bfc159261ab6b44591660ce9eca3a38e7ea003b5cff1d26a",
          "last_updated": 1494437107870,
          "status": "SUBMITTED"
        },
        {
          "document_type": "AOI",
          "id": "32cc21dc86f3aab063b3b2ee28c32926a067aad2b9aab3a786656250f4fe98c7",
          "last_updated": 1494438154135,
          "status": "SUBMITTED"
        }
      ],
      "social_docs": [
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "510a94628812b825a1703cf34c13f5c16329562954fa8dcd176ef31412424256",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "e5b7a9b26fbe3d7da4b6cff02325e8e44797497ba0a9683c28badb96d86c5540",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "TIN",
          "id": "a55cc12f46e8091f741b978d5fa556b2f8772a75007a82aae10a2fd810f644cb",
          "last_updated": 1494437107866,
          "status": "SUBMITTED|VALID"
        }
      ]
    },
    {
      "id": "4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844",
      "name": "Beneficial Owner",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "fbab7ed1d3e7b5391c54e3e60ab0db148d6fb6016b3c20aecdeb45b6f27f4cb4",
          "last_updated": 1494437107362,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "EMAIL",
          "id": "1776f9e6ce198edc4feb3f158692c6eb4bb42fe66cb9eb819bf7e884f0c54b45",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "95a6638a9d700ac4a26cbf55d97ee72abb5f85c7ff75de6aa66c316218960730",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1494437107359,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494438154125,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "UNVERIFIED",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

Since the user permission and document permission_scope is updated asynchronously, make a request to Get User to get the most recent information on the user.

{
  "_id": "59135352ce9311001e3a8f43",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43"
    }
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "doc_status": {
    "physical_doc": "SUBMITTED|VALID",
    "virtual_doc": "SUBMITTED|VALID"
  },
  "documents": [
    {
      "id": "e82fc224a90cb7696a07361b788c71d78f6eb2ff628c6ecf014b5b63cf5d6b81",
      "name": "Business Name",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "EIN_DOC",
          "id": "d96c7d22b5c4e33809952c00df524f1c83a4706e8d9af8b891d01675b162190c",
          "last_updated": 1494437107870,
          "status": "SUBMITTED"
        },
        {
          "document_type": "BYLAWS_DOC",
          "id": "eddd2fe8fc8e9192bfc159261ab6b44591660ce9eca3a38e7ea003b5cff1d26a",
          "last_updated": 1494437107870,
          "status": "SUBMITTED"
        },
        {
          "document_type": "AOI",
          "id": "32cc21dc86f3aab063b3b2ee28c32926a067aad2b9aab3a786656250f4fe98c7",
          "last_updated": 1494438154135,
          "status": "SUBMITTED"
        }
      ],
      "social_docs": [
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "510a94628812b825a1703cf34c13f5c16329562954fa8dcd176ef31412424256",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "EMAIL",
          "id": "e5b7a9b26fbe3d7da4b6cff02325e8e44797497ba0a9683c28badb96d86c5540",
          "last_updated": 1494437107873,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "TIN",
          "id": "a55cc12f46e8091f741b978d5fa556b2f8772a75007a82aae10a2fd810f644cb",
          "last_updated": 1494437107866,
          "status": "SUBMITTED|VALID"
        }
      ]
    },
    {
      "id": "4c3d01727e2f554e51c0cf92c114c763b1291a58bdc783a82e5e18e8fc70b844",
      "name": "Beneficial Owner",
      "permission_scope": "SEND|RECEIVE|2000|DAILY",
      "physical_docs": [
        {
          "document_type": "GOVT_ID",
          "id": "fbab7ed1d3e7b5391c54e3e60ab0db148d6fb6016b3c20aecdeb45b6f27f4cb4",
          "last_updated": 1494437107362,
          "status": "SUBMITTED|VALID"
        }
      ],
      "social_docs": [
        {
          "document_type": "EMAIL",
          "id": "1776f9e6ce198edc4feb3f158692c6eb4bb42fe66cb9eb819bf7e884f0c54b45",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "PHONE_NUMBER",
          "id": "95a6638a9d700ac4a26cbf55d97ee72abb5f85c7ff75de6aa66c316218960730",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        },
        {
          "document_type": "IP",
          "id": "745b7c6016a8a18f60017a5e921bdc8ca46891fa387d05adaf2fe4f3df640fbe",
          "last_updated": 1494437107365,
          "status": "SUBMITTED|VALID"
        }
      ],
      "virtual_docs": [
        {
          "document_type": "SSN",
          "id": "a0e9fe45c418a2a9ace120d044e13793c60a3eec9cd84bc8c662349cb4e9ee03",
          "last_updated": 1494437107359,
          "status": "SUBMITTED|VALID"
        }
      ]
    }
  ],
  "emails": [],
  "extra": {
    "cip_tag": 1,
    "date_joined": 1494433713318,
    "extra_security": false,
    "is_business": true,
    "last_updated": 1494438154125,
    "public_note": null,
    "supp_id": null
  },
  "is_hidden": false,
  "legal_names": [
    "Business User"
  ],
  "logins": [
    {
      "email": "[email protected]",
      "scope": "READ_AND_WRITE"
    }
  ],
  "permission": "SEND-AND-RECEIVE",
  "phone_numbers": [
    "111-222-7777"
  ],
  "photos": [],
  "refresh_token": "refresh_b67096cc359d11e7bd770230ad3f183e"
}

As you can see from the response, the business user (_id: 59135352ce9311001e3a8f43) now has SEND-AND-RECEIVE permissions so they can send and receive funds with a daily transaction limit of 2000.

4. Add Nodes (Link Bank Accounts)

Add Nodes for Individual User

According to the example CIP, individuals (with cip_tag: 1) are allowed to have 2 node types (section F) under their user account: ACH-US and SYNAPSE-US.

There are two ways to add an ACH-US node to a user: via bank login credentials OR account/routing numbers. ACH-US nodes that are added via account/routing numbers require micro-deposit verification. If an ACH-US node is added by supplying the user's online banking login credentials (for personal user accounts only), then micro-deposit verification is not required and the node instantly receives CREDIT-AND-DEBIT privileges (assuming the login credentials were correct). Node permissions are dependent on the node type and are separate from user permissions.

In addition, the node limit (section G) is 3 nodes per user. This means that there can be a maximum of 3 nodes under the user account. If a user adds an ACH-US node via bank login, the response may contain multiple ACH-US nodes. The response returns all nodes that the user has under that bank login. For example, if there were 4 bank accounts/nodes associated with the user's bank login, then those 4 accounts would be added as ACH-US nodes to the user's account. This puts the user over their node limit of 3 nodes so we suggest displaying all of the nodes returned in the response and allowing the user to select the bank account/node they would like to use, then delete the other nodes.

The request to add an ACH-US node via bank login would look similar to the example below:

Supported Institutions

ACH-US Accounts added with Online Banking Logins are for consumer accounts only. For a full list of banks supported by online logins, visit: https://synapsefi.com/api/v3/institutions/show.

POST /v3.1/users/590bae4deba6500022ca53e0/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "type": "ACH-US",
  "info":{
    "bank_id":"synapse_good",
    "bank_pw":"test1234",
    "bank_name":"fake"
  }
}
{
  "error_code": "10",
  "http_code": "202",
  "mfa": {
    "access_token": "fake_cd60680b9addc013ca7fb25b2b704be324d0295b34a6e3d14473e3cc65aa82d3",
    "message": "I heard you like questions so we put a question in your question?",
    "type": "question"
  },
  "success": true
}

The response from online bank logins can contain a MFA question so it's important that you correctly handle the MFA verification. Notice in the response above that a MFA question was returned. MFAs can be triggered once or multiple times. Even when banks send multiple MFA questions, they will do so one at a time. It is recommended that you send an answer back for the first question and then re-check the response for an http_code of "202", which means another MFA question was sent. Cycle through the questions in this way until http_code is "200".

Grab the access_token from the response above and submit the answer to the MFA question with this request:

POST /v3.1/users/590bae4deba6500022ca53e0/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "access_token":"fake_cd60680b9addc013ca7fb25b2b704be324d0295b34a6e3d14473e3cc65aa82d3",
  "mfa_answer":"test_answer"
}
{
  "error_code": "0",
  "http_code": "200",
  "limit": 2,
  "node_count": 2,
  "nodes": [
    {
      "_id": "5910ac9465c7dd002aa469ae",
      "_links": {
        "self": {
          "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0/nodes/5910ac9465c7dd002aa469ae"
        }
      },
      "allowed": "CREDIT-AND-DEBIT",
      "client": {
        "id": "589a9eed86c2736412ce7e21",
        "name": "Client Platform"
      },
      "extra": {
        "other": {},
        "supp_id": ""
      },
      "info": {
        "account_num": "8902",
        "address": "PO BOX 85139, RICHMOND, VA, US",
        "balance": {
          "amount": "750.00",
          "currency": "USD"
        },
        "bank_long_name": "CAPITAL ONE N.A.",
        "bank_name": "CAPITAL ONE N.A.",
        "class": "SAVINGS",
        "match_info": {
          "email_match": "no_match",
          "name_match": "match",
          "phonenumber_match": "no_match"
        },
        "name_on_account": " ",
        "nickname": "SynapsePay Test Savings Account - 8902",
        "routing_num": "6110",
        "type": "BUSINESS"
      },
      "is_active": true,
      "timeline": [
        {
          "date": 1494264979718,
          "note": "Node created."
        }
      ],
      "type": "ACH-US",
      "user_id": "590bae4deba6500022ca53e0"
    },
    {
      "_id": "5910ac9565c7dd002ba607f0",
      "_links": {
        "self": {
          "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0/nodes/5910ac9565c7dd002ba607f0"
        }
      },
      "allowed": "CREDIT-AND-DEBIT",
      "client": {
        "id": "589a9eed86c2736412ce7e21",
        "name": "Client Platform"
      },
      "extra": {
        "other": {},
        "supp_id": ""
      },
      "info": {
        "account_num": "8901",
        "address": "PO BOX 85139, RICHMOND, VA, US",
        "balance": {
          "amount": "800.00",
          "currency": "USD"
        },
        "bank_long_name": "CAPITAL ONE N.A.",
        "bank_name": "CAPITAL ONE N.A.",
        "class": "CHECKING",
        "match_info": {
          "email_match": "no_match",
          "name_match": "match",
          "phonenumber_match": "no_match"
        },
        "name_on_account": " ",
        "nickname": "SynapsePay Test Checking Account - 8901",
        "routing_num": "6110",
        "type": "PERSONAL"
      },
      "is_active": true,
      "timeline": [
        {
          "date": 1494264980379,
          "note": "Node created."
        }
      ],
      "type": "ACH-US",
      "user_id": "590bae4deba6500022ca53e0"
    }
  ],
  "page_count": 1,
  "success": true
}

As you can see in the response from submitting the MFA answer, the http_code is "200" meaning that the answer was correct, no additional MFA question was sent, and all the nodes associated with the bank login was returned.

Add Nodes for Business User

According to the example CIP, business users (with cip_tag: 1) are allowed to have 2 node types under their user account: ACH-US and SYNAPSE-US.

Let's add a SYNAPSE-US node and an ACH-US node (using account/routing numbers because business accounts are not allowed to add ACH-US nodes via the bank login method) to the business user:

POST /v3.1/users/59135352ce9311001e3a8f43/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "type": "SYNAPSE-US",
  "info":{
  "nickname":"Business Deposit Account"
  }
}
{
  "error_code": "0",
  "http_code": "200",
  "limit": 20,
  "node_count": 1,
  "nodes": [
    {
      "_id": "5913ebb3980216001f2a9925",
      "_links": {
        "self": {
          "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43/nodes/5913ebb3980216001f2a9925"
        }
      },
      "allowed": "CREDIT-AND-DEBIT",
      "client": {
        "id": "589a9eed86c2736412ce7e21",
        "name": "Client Platform"
      },
      "extra": {
        "other": {},
        "supp_id": ""
      },
      "info": {
        "balance": {
          "amount": 0,
          "currency": "USD"
        },
        "name_on_account": " ",
        "nickname": "Business Deposit Account"
      },
      "is_active": true,
      "timeline": [
        {
          "date": 1494477747715,
          "note": "Node created."
        }
      ],
      "type": "SYNAPSE-US",
      "user_id": "59135352ce9311001e3a8f43"
    }
  ],
  "page_count": 1,
  "success": true
}
POST /v3.1/users/59135352ce9311001e3a8f43/nodes HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "type": "ACH-US",
  "info": {
    "nickname": "Fake Account",
    "account_num": "123567412124234",
    "routing_num": "051000017",
    "type": "BUSINESS",
    "class": "CHECKING"
  }
}
{
  "error_code": "0",
  "http_code": "200",
  "limit": 20,
  "node_count": 1,
  "nodes": [
    {
      "_id": "5913ee0998021600202ab863",
      "_links": {
        "self": {
          "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43/nodes/5913ee0998021600202ab863"
        }
      },
      "allowed": "CREDIT",
      "client": {
        "id": "589a9eed86c2736412ce7e21",
        "name": "Client Platform"
      },
      "extra": {
        "other": {},
        "supp_id": ""
      },
      "info": {
        "account_num": "4234",
        "address": "8001 VILLA PARK DRIVE, HENRICO, VA, US",
        "balance": {
          "amount": "0.00",
          "currency": "USD"
        },
        "bank_long_name": "BANK OF AMERICA, N.A.",
        "bank_name": "BANK OF AMERICA, N.A.",
        "class": "CHECKING",
        "match_info": {
          "email_match": "not_found",
          "name_match": "not_found",
          "phonenumber_match": "not_found"
        },
        "name_on_account": " ",
        "nickname": "Fake Account",
        "routing_num": "0017",
        "type": "BUSINESS"
      },
      "is_active": true,
      "timeline": [
        {
          "date": 1494478345223,
          "note": "Node created."
        }
      ],
      "type": "ACH-US",
      "user_id": "59135352ce9311001e3a8f43"
    }
  ],
  "page_count": 1,
  "success": true
}

As you can see in the response from adding the SYNAPSE-US node that allowed is CREDIT-AND-DEBIT. This corresponds to the node permissions. By default all node types except ACH-US and RESERVE-US receive CREDIT-AND-DEBIT node permissions when created.

Notice in the response from adding the ACH-US node that allowed is CREDIT only. ACH-US nodes added with account/routing numbers usually require micro-deposit verification in order to receive CREDIT-AND-DEBIT node permissions.

Micro-deposit Verification

Micro-deposits are automatically triggered after account / routing numbers are submitted. It can take 1-2 business days for the micro-deposits to appear in the user's bank account. To learn more about how micro-deposits work, read this FAQ.

Please do not try to guess micro-deposit amounts. Nodes lock after 5 incorrect attempts. Also please note that micro-deposits are not sent to the bank account until the KYC process is finished for the user.

Let's verify micro-deposit amounts for the ACH-US account (node _id: 5913ee0998021600202ab863):

PATCH /v3.1/users/59135352ce9311001e3a8f43/nodes/5913ee0998021600202ab863 HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "micro":[0.1,0.1]
}
{
  "_id": "5913ee0998021600202ab863",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43/nodes/5913ee0998021600202ab863"
    }
  },
  "allowed": "CREDIT-AND-DEBIT",
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "extra": {
    "other": {},
    "supp_id": ""
  },
  "info": {
    "account_num": "4234",
    "address": "8001 VILLA PARK DRIVE, HENRICO, VA, US",
    "balance": {
      "amount": "0.00",
      "currency": "USD"
    },
    "bank_long_name": "BANK OF AMERICA, N.A.",
    "bank_name": "BANK OF AMERICA, N.A.",
    "class": "CHECKING",
    "match_info": {
      "email_match": "not_found",
      "name_match": "not_found",
      "phonenumber_match": "not_found"
    },
    "name_on_account": " ",
    "nickname": "Fake Account",
    "routing_num": "0017",
    "type": "BUSINESS"
  },
  "is_active": true,
  "timeline": [
    {
      "date": 1494478345223,
      "note": "Node created."
    },
    {
      "date": 1494478345892,
      "note": "Micro deposits initiated."
    },
    {
      "date": 1494522868395,
      "note": "Correct Micro Deposit amounts attempted. Node's 'allowed' changed to 'CREDIT-AND-DEBIT'"
    }
  ],
  "type": "ACH-US",
  "user_id": "59135352ce9311001e3a8f43"
}

As you can see in the response, allowed is CREDIT-AND-DEBIT so this ACH-US node can now be used to send or receive funds.

5. Create a Transaction

An example flow of funds.

An example flow of funds.

According to the example flow of funds above, individuals (with cip_tag: 1) are allowed to send funds from their ACH-US node to the business's deposit account (SYNAPSE-US node). The business user can then send funds from their SYNAPSE-US node to their ACH-US node.

If users try to create a transaction that is outside their allowed flow of funds, then the transaction will be canceled.

Let's create 2 transactions where transaction 1 will be sending funds from the individual's ACH-US account to the business's SYNAPSE-US account, and transaction 2 will be sending funds from the business's SYNAPSE-US account to their ACH-US account.

Transaction 1: Individual's ACH-US (node id: 5910ac9565c7dd002ba607f0) --> Business's SYNAPSE-US (node id: 5913ebb3980216001f2a9925)

POST /v3.1/users/590bae4deba6500022ca53e0/nodes/5910ac9565c7dd002ba607f0/trans HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "to": {
    "type": "SYNAPSE-US",
    "id": "5913ebb3980216001f2a9925"
  },
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1",
    "note": "Test transaction",
    "process_on": 0
  }
}
{
  "_id": "5914bf20a396d9002212e72c",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/590bae4deba6500022ca53e0/nodes/5910ac9565c7dd002ba607f0/trans/5914bf20a396d9002212e72c"
    }
  },
  "_v": 2,
  "amount": {
    "amount": 20.1,
    "currency": "USD"
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "extra": {
    "created_on": 1494531872160,
    "ip": "192.168.0.1",
    "latlon": "0,0",
    "note": "Test transaction",
    "process_on": 1494531872160,
    "supp_id": ""
  },
  "fees": [
    {
      "fee": 0,
      "note": "Facilitator Fee",
      "to": {
        "id": "None"
      }
    }
  ],
  "from": {
    "id": "5910ac9565c7dd002ba607f0",
    "nickname": "Fake Account",
    "type": "ACH-US",
    "user": {
      "_id": "590bae4deba6500022ca53e0",
      "legal_names": []
    }
  },
  "recent_status": {
    "date": 1494531872160,
    "note": "Transaction Created.",
    "status": "CREATED",
    "status_id": "1"
  },
  "timeline": [
    {
      "date": 1494531872160,
      "note": "Transaction Created.",
      "status": "CREATED",
      "status_id": "1"
    }
  ],
  "to": {
    "id": "5913ebb3980216001f2a9925",
    "nickname": "",
    "type": "SYNAPSE-US",
    "user": {
      "_id": "",
      "legal_names": []
    }
  }
}

Information in the to node object is populated asynchronously so use subscriptions or GET Transaction to retrieve the most recent information on the transaction. We highly suggest creating a subscription to TRAN|PATCH so you can be notified of transaction status updates.

Transaction 2: Business's SYNAPSE-US (node id: 5913ebb3980216001f2a9925) --> Business's ACH-US (node id: 5913ee0998021600202ab863)

POST /v3.1/users/59135352ce9311001e3a8f43/nodes/5913ebb3980216001f2a9925/trans HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 127.0.0.1
X-SP-USER: oauth_key|fingerprint
Content-Type: application/json

{
  "to": {
    "type": "ACH-US",
    "id": "5913ee0998021600202ab863"
  },
  "amount": {
    "amount": 11.0,
    "currency": "USD"
  },
  "extra": {
    "ip": "192.168.0.1",
    "note": "Test transaction 2",
    "process_on": 0
  }
}
{
  "_id": "5914ca482ee6920021d0ace8",
  "_links": {
    "self": {
      "href": "https://uat-api.synapsefi.com/v3.1/users/59135352ce9311001e3a8f43/nodes/5913ebb3980216001f2a9925/trans/5914ca482ee6920021d0ace8"
    }
  },
  "_v": 2,
  "amount": {
    "amount": 11,
    "currency": "USD"
  },
  "client": {
    "id": "589a9eed86c2736412ce7e21",
    "name": "Client Platform"
  },
  "extra": {
    "created_on": 1494534728969,
    "ip": "192.168.0.1",
    "latlon": "0,0",
    "note": "Test transaction 2",
    "process_on": 1494534728969,
    "supp_id": ""
  },
  "fees": [
    {
      "fee": 0,
      "note": "Facilitator Fee",
      "to": {
        "id": "None"
      }
    }
  ],
  "from": {
    "id": "5913ebb3980216001f2a9925",
    "nickname": "Business Deposit Account",
    "type": "SYNAPSE-US",
    "user": {
      "_id": "59135352ce9311001e3a8f43",
      "legal_names": []
    }
  },
  "recent_status": {
    "date": 1494534728969,
    "note": "Transaction Created.",
    "status": "CREATED",
    "status_id": "1"
  },
  "timeline": [
    {
      "date": 1494534728969,
      "note": "Transaction Created.",
      "status": "CREATED",
      "status_id": "1"
    }
  ],
  "to": {
    "id": "5913ee0998021600202ab863",
    "nickname": "",
    "type": "ACH-US",
    "user": {
      "_id": "",
      "legal_names": []
    }
  }
}

To get a better understanding of the status updates for transactions, review the transaction codes and read this guide on how to handle transaction errors.

Spec Sheet Integration


Spec sheet resource and guide

Suggested Edits are limited on API Reference Pages

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