Getting started with Khipu Open Data API

Assuming you already have access to the Khipu Open Data API (see our main website for details on how to register), this section explains how you can start exploring and building solutions using our services.

Key concepts

Authenticated request

Before you can access any of the available resources you need to obtain a valid authentication key, in the form of an Api key or an Oauth token. Each method is explained in the Authentication section. Failing to provide a valid key will result in a bad request.

Callback URL

You can specify a Callback URL value in each of your requests to receive the data in a service set up by you. This way, your request will run through an asynchronous process, and the data will be push as soon as it is obtained. See each method definition to know which ones support this feature (there will be services that will only work in asynchronous mode, due to the time needed to process the data).

Using this option is the preferred way to interact with our services, as it assures that all efforts will be made to extract the data to fulfill your request within a reasonable time frame. If you want the response immediately and execute the service in synchronous mode, omit the field CallbackUrl but bear in mind that it can result in timeouts depending on the data's result size and the network conditions.

To receive the data in your endpoint, remember to:

  • Use a public available URL (our push service will not work if you are running a service with authentication).
  • Your service must be RESTful, and accept the POST verb.
  • Your service must be able to understand and parse the JSON that our API will send to it. Check the response schema with HTTP status code 200 for the method that you want to call asynchronously.
  • Keep record of your OperationId value, as it will serve to match your request with the final response, and also for support and tracking purposes.

Lifespan

When you make an asynchronous request, an immediate response is shown containing a LifeSpan field that indicates the maximum time our service have to send the data to your defined callback URL. You can expect the response delivered within this time frame (usually it will be much sooner). If something prevents our service to complete successfully, you also will receive a response, with the error message as detailed in the Errors section.

Staging environment

For selected data sources we will offer a sandbox (staging) environment with dummy data so you can test your developments and integrations without counting the requests against your account's quota/billing. Stay tuned for more details.

Preparing your first request

We will use a method in the Chile/Banking/Personal/DemoBank route as an example to show how you can start making requests in less than 10 minutes, without the need of a single line of code. Understanding this documentation site will put you in a good path to integrate our APIs in your solutions.

The OpenAPI definitions are in the Open Data API section of the left sidebar:

sidebar

You can expand the menu tree and navigate to the desired service. We want to use the DemoBank Transactions method:

transactions

The main section of the documentation has three sections: Security, Request and Responses:

sections

Read them carefully to understand the schemas and the data types and lengths you can use in your requests. The request needs the bank account data (user credentials, usually). We will not be using the optional CallbackUrl field, as we want to view the data in the console.

request

If you call the service in a synchronous way (without the CallbackUrl field), a correct response will have a 200 HTTP status code (the 202 code is reserved for the asynchronous calls). You can see the details of the response object, and examples:

response

The right-hand section has a "Try it" console where you can see the service in action. Pressing the button will open the Request/Response panel, so you can verify its correct operation.

try-it

Authentication

Once opened, the "Try it" panel shows the sections Security, Body and Target server. Let's start with Security, choosing "Api-Key" in the available "Security scheme" drop-down list:

When you enter your assigned key, the padlock turns green, and the credentials are maintained in your browser during the session:

api-key

You are ready then to adjust the body content.

Completing the request

You are offered a sample request with all available fields, we will use AccountLink and AccountNumber, and omit CallbackUrl since we don't want to make an asynchronous call. As a side note, you can use Username and Password instead of AccountLink. To create a reusable account link for the account, go to Account Link Generator.

With everything ready, you select your desired server ("Production", for this example) and hit the "Send" button 🚀.

body-request

Understanding the response

Upon completion, the request changes to the "Response" tab and you can view the result. In this case it was a 200 status code. In the body, the "Status": "OK" indicates the service worked well, and the OperationId shows the unique identifier for this request. The Data element has all the transactions made during the current day.

status-response body-response

Next steps

If you never used RESTful APIs before, in the "Request samples" of the right-hand section of each service definition you will encounter tailored code snippets in popular programming languages (also curl) to help you with your solution. Just remember to always use a header to authenticate your request (Authorization: Bearer or x-api-key), and another header for Content-Type: application/json.

samples