Intro to APIs

We are RESTful

Synapse has built a RESTful JSON API for you. Which means, we use:

  • POST to create a document.

  • PATCH to update it.

  • GET to query one or more documents.

  • DELETE to cancel or delete a document (subtext: nothing gets deleted. It is either unindexed in case of a user or a bank account, or its canceled in case of a transaction).

To make things easier, all GET calls that get multiple documents support pagination and since our primary database is mongoDB (thats why we call everything documents), it also supports mongo filters. Example call for retrieving LOCKED users, page 2 with max 10 documents:

GET /users?page=2&limit=10&filter={"permission":"LOCKED"}

We use Headers

Mostly all requests (with some minor exceptions) require various kinds of headers. Here are some examples

Header

Example Value

Description

X-SP-GATEWAY

your_client_id|your_client_key

Your client id and secret, separated by a pipe.

X-SP-USER-IP

user_oauth_key|user_device_fingerprint

User's OAuth key and their device fingerprint, separated by a pipe.

X-SP-USER

user_ip

User's IP Address.

X-SP-IDEMPOTENCY-KEY

idempotency_key

Idempotency key to go along with the POST API call.

Not all headers are needed for all API calls. Some require client level authentication while some require user level authentication. More on this later, but a good rule of thumb is that any resources that require actions performed by the user (open deposit account, create a transaction, etc.) require user credentials (X-SP-USER-IP) while others require client level credentials (X-SP-GATEWAY).

We are Easy

All Synapse fictionality can be broken down into the following core resources:

  • Users: Individual or Business accounts you create in our System. User objects store all KYC and Authentication information for each user.

  • Nodes: Nodes are either deposit accounts, credit accounts that you open with us, or 3rd party accounts you link with us to be able to move funds on behalf of the user. Each user can link or create multiple nodes under them.

  • Transactions: Transactions resource enables you to send money between various nodes. Just supply addresses of from and to nodes, and we will move money between both accounts. This is handy because this gives you one unified way of creating all kinds of transactions -- Internal Transfers, ACH Debit, ACH Credit, Interchange Pulls, Push to Card, Wires, BillPay, etc.

  • Statements: Each deposit or credit node (accounts we open for your users) automatically generate statements each month. This is comply with regulations like Reg E and Z. The idea is that we will generate the statements and you will distribute them.

  • Subnets: With Transactions resource, you can create transactions between two nodes that exist in the Synapse system. But what if you wanted other networks and platforms to be able to interface with the Synapse system? Thats where subnets come handy. If a node is hosted by Synapse (deposit or credit), you can issue a Subnet on top of that node to interface with other platforms. Thats the general idea. Currently it supports two kinds of interfaces -- Account and Routing Numbers and Card Numbers.

  • Shipments: If a Subnet is a card number, this resource enables you to ship a physical card to the user.

  • Subscriptions: Since its not efficient to poll our entire system with API calls, Subscriptions enables you to set up webhook alerts with us so that whenever updates to objects happen, you system can automatically stay in sync.