Intro to APIs
We are RESTful
Synapse has built a RESTful JSON API for you. Which means, we use:
POST
to create a documentPATCH
to update itGET
to query one or more documentsDELETE
to 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:
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
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)
.
Idempotent Requests
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
POST
call before attempting to retry the call.
We are Easy
All Synapse functionality can be broken down into the following core resources:
API Rate Limits
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.
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
Max HTTP Request Body Size
HTTP request body size is limited to 30 MB maximum.
Last updated
Was this helpful?