Even Developer Documentation

API Overview

Welcome to the Even Financial API! To the extent possible, this API conforms to the most widely accepted best practices for RESTful APIs. The guidelines on this page apply to all resources in the API. You can find resource-specific information in the API Reference.

Authentication

All requests must be authenticated by specifying an access token in the Authorization header. The value of the header must be the string “Bearer”, followed by a single space, followed by the access token. So, for example:

Authorization: Bearer f8fde494_8f2bd89f

If you do not include an Authorization header, or the value of the header is malformed, or the specified access token does not exist, the endpoint will respond with a 401 Unauthorized.

Authorization

The access token that you use to authenticate your request will have scopes associated with it. Every endpoint will require that your access token has a particular scope (this requirement will be specified in the documentation for the endpoint). If your access token does not have the required scope, the endpoint will respond with a 401 Unauthorized.

Versioning

Requests will receive the most recent version of the API by default (currently, v1). So, to avoid issues when a new version of the API is released, you should explicitly request the version you would like via the Accept header. To request v1 of the API, add the following header to your request:

Accept: application/vnd.evenfinancial.v1+json

If you make a request to a path that is supported in some version of the API, but not the one you specified (i.e., it was deprecated or added later), the endpoint will respond with a 415 Unsupported Media Type.

Mime Types

The API only supports JSON request bodies, so if your request includes a body (e.g. POST, PUT), it must also include the appropriate Content-Type header:

Content-Type: application/json

Similarly, all response bodies will be in JSON, so they will include the same header.

Response Codes

The API responds with a consistent set of HTTP status codes.

200 OK

When a GET request completes successfully. Will include a body with the requested resources.

201 Created

When a write request (POST, PUT) completes successfully. Will include a body with the newly created or updated resource.

204 No Content

When a DELETE request completes successfully. The response will not have a body.

400 Bad Request

When the URL or the body of a request is malformed or invalid. For example, if the URL expects a segment to be a UUID but isn’t, or if the body is not valid JSON, or if the body is valid JSON but violates business rules.

401 Unauthorized

When authentication or authorization fails for a request. So, if an access token cannot be associated with the request, or if the access token does not have a scope required by the endpoint.

404 Not Found

When a specified resource ID cannot be found, or the entire URL does not exist.

415 Unsupported Media Type

When the requested endpoint exists in a different version of the API than the one specified by the request’s Accept header.