/ Guides / Get started / About the Equals Money API

About the Equals Money API

Learn how to access, authenticate with, and use the Equals Money API.

Base URL

Every request uses one of the two following URLs, depending on whether you're working in your live environment (production) or your test environment (sandbox).

https://api.equalsmoney.com

https://api-sandbox.equalsmoney.com

Authentication

The Equals Money API uses API keys to authenticate requests. These are provided to you during the onboarding process.

To authenticate, you need to include an Authorization header in all of your requests. In this header, you must state that you're using an API key (similar to HTTP basic access authentication).

For example:

curl -i -X GET \
  'https://api.equalsmoney.com/v2/webhooks' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

If the API key isn’t valid, you’ll receive a 403 response. If you don’t provide an Authorization header at all, you’ll receive a 401.

Access levels

Every API key has an access level that determines its permissions. Currently there are two: product-level and user-level.

A product is a collection of accounts, which can be configured and managed together in a single request. If you have product-level access, request responses will include results for all accounts associated with the product by default. You can then use optional parameters or search to narrow down your results to one or several specific accounts. Typically, admins will be granted product-level access.

If you have user-level access, you have access to one or more accounts but can only work with one at a time. You'll need to specify which account you're working with by supplying an accountId in your requests.

Whitelisting

In order to access the Equals Money API, your IP address has to be whitelisted. We whitelist IP address provided to us during the onboarding process.

Depending on your permissions, you can whitelist additional IPs using the following request:

curl -i -X POST 'https://api.equalsmoney.com/v2/ipaddresses' \
-H 'Authorization: ApiKey {apiKey}' \ # Your API key
-H 'Content-Type: application/json' \
-d '{
  "ip": "8.8.8.8", # The IP address you want to add to the allowlist
  "description": "John Smith home IP" # A description of who this IP address belongs to
}'

curl -i -X POST 'https://api-sandbox.equalsmoney.com/v2/ipaddresses' \
-H 'Authorization: ApiKey {apiKey}' \ # Your API key
-H 'Content-Type: application/json' \
-d '{
  "ip": "8.8.8.8", # The IP address you want to add to the allowlist
  "description": "John Smith home IP" # A description of who this IP address belongs to
}'

Idempotency

The Equals Money API supports idempotent requests, so you can safely retry a request without the risk of performing the same action twice. For example, if you experience a network connection issue while creating a payment.

To make an idempotent request, simply add the optional x-idempotency-key header to your request. You'll need to provide a globally unique key of your choice. We recommend a UUID v4 or ULID. This key will be stored for 24 hours before being auto-deleted.

All GET, DELETE, and PUT requests are idempotent by default. Setting the header for them will have no effect and should be avoided.

Rate limits

Requests to the Equals Money API have rate limits. A rate limit is a maximum number of requests that you can make to an endpoint during a given time interval.

The rate limit is set to 5 requests per API key per second, with an additional burst rate limit of up to 100 requests per minute. This limit is per API key and applies to all endpoints in both sandbox and production environments. If you exceed this limit, your request will fail and you will receive a 429 response. You'll then need to wait for the rate limit to reset before you can successfully send a request again.

Every response header includes the following information related to rate limits:

Pagination

Several endpoints return paginated results.

By default, the Equals Money API only returns the first 100 results for those endpoints. You can use optional query parameters to increase or decrease the number of results, as well as skip results.

Supported endpoints

Search results

Several endpoints allow you to include a search parameter in your query in order to narrow down results.

For example, to find only transactions related to Jane Doe:

curl -i -X GET \
  'https://api.equalsmoney.com/v2/activity/{accountId}?search=Jane+Doe' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Supported endpoints

Status codes

The Equals Money API uses conventional HTTP response codes to indicate whether a request was successful (2XX codes) or resulted in an error (4XX and 5XX codes).

Webhook retries

If a webhook fails to deliver, we'll retry sending it every 5 minutes for a period of two weeks until we get a 200 Success response.