Intro to APIs
Synapse has built a RESTful JSON API for you. Which means, we use:
POSTto create a documentPATCHto update itGETto query one or more documentsDELETEto cancel or delete a document (Subtext: nothing gets deleted. It is either unindexed in case of a user or a bank account or it's 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 (that's 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"}
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 | user_oauth_key|user_device_fingerprint | User's OAuth key and their device fingerprint, separated by a pipe. |
X-SP-USER-IP | 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 any resource that requires 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).To prevent duplicate creation of users, nodes, transactions and subnets, it's important provide retry attempts with idempotency keys.
All
POST calls support idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transaction fails due to a network connectivity error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.Notes to keep in mind when making idempotent requests:
- Idempotency keys expire after 24 hours.
- It is best practice to wait for a failure response from the
POSTcall before attempting to retry the call.
All Synapse functionality 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 for
fromandtonodes, 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 generates statements each month. This is to 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? That's where subnets come in 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. That's 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 it's 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, your system can automatically stay in sync.
The following is a table of the the most common API calls and their respective rate limits. These limits cannot be increased. Please take this into account when building out your application.
HTTP Verb | URL | Functionality | Rate Limits (per min/per user) |
|---|---|---|---|
POST | /oauth/<user:id> | This API call allows you to get oauth_key for users. | 30 |
POST | /oauth/<user:id>/login | Using basic auth to get refresh_token for users. | 30 |
GET | /users | View all users created with your client keys (paginated). | 100 |
POST | /users | Allows you to register a new user. | 100 |
GET | /users/<user:id> | View user info and refresh_token. | 30 |
PATCH | /users/<user:id> | Add/update KYC, log in credentials, profile, etc. | 30 |
GET | /users/<user:id>/nodes | View all nodes linked to a user (paginated). | 100 |
POST | /users/<user:id>/nodes | Allows you to create a deposit account or link an external bank account to a user. | 100 |
GET | /users/<user:id>/nodes/<node:id> | View node info. | 100 |
PATCH | /users/<user:id>/nodes/<node:id> | Update supp_id, verify micro-deposits, etc. | 100 |
DELETE | /users/<user:id>/nodes/<node:id> | Unindex node from a user. | 100 |
POST | /users/<user:id>/nodes/<node:id>/subnets | Allows you to issue a virtual account number on top of a node. | 100 |
GET | /users/<user:id>/nodes/<node:id>/subnets | View all subnets linked to a node (paginated). | 100 |
GET | /users/<user:id>/nodes/<node:id>/subnets/<subnet:id> | View subnet info. | 100 |
PATCH | /users/<user:id>/nodes/<node:id>/subnets/<subnet:id> | Update subnet info. | 100 |
GET | /users/<user:id>/trans | View all transactions of a user (paginated). | 100 |
GET | /users/<user:id>/nodes/<node:id>/trans | View all transactions of a node (paginated). | 100 |
POST | /users/<user:id>/nodes/<node:id>/trans | Allows you to create a transaction. | 100 |
GET | /users/<user:id>/nodes/<node:id>/trans/<trans:id> | View transaction info. | 100 |
PATCH | /users/<user:id>/nodes/<node:id>/trans/<trans:id> | Update notes on a transaction. | 100 |
DELETE | /users/<user:id>/nodes/<node:id>/trans/<trans:id> | Only works if transaction has been created or queued. | 100 |
GET | /subscriptions | View all subscriptions created with your client keys (paginated). | 10 |
POST | /subscriptions | Create a subscription with webhook preferences. | 10 |
GET | /subscriptions/<subscription:id> | View a subscription. | 10 |
PATCH | /subscriptions/<subscription:id> | Update scope, url, is_active, etc. | 10 |
GET | <:user_id>/statements | View a users statement | 30 |
GET | <:node_id>/statements | View a node statements | 30 |
Last modified 10mo ago