logo

API Basics

API Basics

The below sections contain important information about how to get started using our API.
    Signing Up
    First, sign up for our API through our website. Once you finish registering there, you’ll be able to set up your API and connect accounts, as well as get access to three of our core products:
    1. Account Aggregation
    2. Instant Account Authentication
    3. Connect
    For access to other Quovo API products that may be covered in this guide, please contact our sales team.
    Note: Signing up for Quovo through our website creates your API user — so make sure the email and password you choose are the credentials you want to use for ongoing API access at your organization.
    Making Requests
    The base URL for all Quovo API requests is https://api.quovo.com/v3
    Our API is built on RESTful principles with resource-oriented URL endpoints. HTTP status codes are used to indicate any API errors and all responses are returned in JSON format. All requests must be made over an HTTPS connection to ensure the secure transmission of data. Following a RESTful structure, requests should hit API endpoints using the appropriate HTTP method, which will depend on the desired action:
    • GET: Use the GET method to retrieve information about your users, their accounts, and any associated financial data. This will always be a read-only request, so queried objects will never be modified by a GET request.
    • POST: Use a POST method to create a new object, such as a new user or connection. Request parameters should be given in JSON format. The response body will typically return the newly created resource.
    • PUT: Use a PUT method to update an object, such as updating account credentials. As with a POST request, parameters should be given in JSON format. If successful, the response body will typically return the modified object.
    • DELETE: Use a DELETE method to delete an object, such as deleting one of your users. Successful DELETE requests will typically return an empty response body.
    Throughout the documentation, you’ll see sample requests using cURL. These will help demonstrate actual API calls (though you’ll have to replace our access tokens, User IDs, etc. with your own parameters).
    Curly braces {} are used to indicate variables. While making requests, make sure to replace the entire {variable} with the appropriate parameter or value.
    Here is a sample curl request:
    curl -X GET \
        -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
        "https://api.quovo.com/v3/users/162703/transactions"
    Getting Responses
    All filled response bodies, including errors, will be formatted as a JSON object. In general, a successful GET request (or any other request that retrieves data) will return an object with the data contained inside a single key-value pair. This key is always associated with the relevant endpoint. For example, GET /v3/users will return an object with   “users”   as the key and the list of users as its value.
    If you are fetching multiple entries, such as retrieving information on all of your end users, the data will be returned as a list. If you are fetching a single entry, such as a GET call for a specific end user, the data will be returned as a single object.
    Here is an example response body:
    {
        "users": [
            {
                "email": "testuser@quovo.com",
                "id": 162703,
                "name": "Quovo Testuser",
                "username": "quovo_test_user",
                "value": 173471.15110
            },
            {
                "email": "another.testuser@quovo.com",
                "id": 162713,
                "name": "Quovo Testuser II",
                "username": "quovo_test_user_2",
                "value": 2944.11
            }
        ]
    }
    Additionally, Quovo’s APIs use standard HTTP status codes to indicate the status of a request. You can review standard HTTP codes here. If there’s an error with your request, a JSON containing an error ID and message will be returned.
    Access Tokens
    To verify incoming API requests, Quovo’s APIs use access tokens, similar to OAuth application-only authentication. Use the/tokens endpoint to manage your access tokens. To authenticate to the /tokens endpoint, you’ll need to use the API user credentials you used to sign up for API access. This is one of the few API endpoints where you will need to use your API user credentials—most other endpoints are authenticated through access tokens.
    Pass your API credentials to the /tokens endpoint using Client-side Basic Auth.
    In order to manage API tokens, you should:
    • POST https://api.quovo.com/v3/tokens to create a new token. You should pass a unique name for your token as a string in the   name   parameter.  Response fields will include the   name  ,  created   date, and   expires   date for the token you’ve created.
    • GET https://api.quovo.com/v3/tokens to see all of your access tokens. The response body will include the  name  ,  created   date, and   expires   date for your tokens. The response body will not include the access token itself.
    • PUT https://api.quovo.com/v3/tokens to rename a token. Pass through the current   name   of the token and the   new_name   you’d like to give it.
    • DELETE https://api.quovo.com/v3/tokens and pass through the   name   of the token you’d like to delete in order to eliminate a token.
    curl -X POST --user "my_api_username:my_api_password" \
        -H "Content-Type: application/json" \
        -d '{"name": "main_token"}' \
        "https://api.quovo.com/v3/tokens"
    Once you have an access token, you can authenticate to any other API endpoint to which you have access. Pass the access token in the request header in the format   Authorization: Bearer {token}  , where   {token}   is your newly created access token.
    This token authenticates your API user without having to send API user credentials in every request. The token will be referenced at the start of an API call (in the header); when sending the token in the header, only pass along the token itself (which should look like a string of numbers and letters), not the entire token JSON object.
    API Dashboard
    When you sign up for our API, you’ll also get access to our API dashboard, which you can log into here. The API dashboard allows you to generate tokens, access documentation, upgrade your service and modify your API user email and password.
    Note: Our API dashboard is a great way to generate tokens when you’re getting started, but in ongoing production you’ll need to programmatically generate them to remain authenticated as you and your end users hit our API.
    Verifying API User Info
    If you’d like to retrieve and review your API user info, send a GET call to  https://api.quovo.com/v3/me. The /me endpoint is authenticated with your API username and password, not with an API access token. 
    The response will include the email of your API user, as well as an array of available API endpoints. This array will reflect the products for which you’ve been permissioned, based on the package you purchased from Quovo. If you’ve only signed up for the free trial products available through our self-service portal, the endpoints in this array will include account Aggregation, Instant Auth, and Connect.
    To change your API user password make a PUT call to /me. Changing your API password means that all future request to/tokens must use this new password to properly authenticate, although changing your password won’t affect current live access tokens.
    API passwords have several requirements:
    • Must be at least 6 characters long
    • Must contain a letter, a number, and a special character
    • Must not contain or be similar to your registered email
    Postman
    In addition to the cURL examples, we have also provided a Postman collection containing all available API calls. Postman is a tool that helps generate and test API calls by providing a clean interface to build and save HTTP requests, and to check and test API responses. Find out more about accessing the Quovo API using Postman here.
    Note: These docs are for our v3 API. If you’re an existing user of v2, you can access our Aggregation, Authentication, and Connect docs via the provided links.