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 to start exploring and building solutions using our services.

Key concepts

Authenticated request

Before you can access any of the available resources you must obtain a valid authentication key, in the form of an API key. Each method is explained in the Authentication section. Failure to provide a valid key will result in a failed request.

Callback URL

You can specify a Callback URL value in each of your requests to receive the data in a service you set up. In this way, your request will run through an asynchronous process and the data will be pushed as soon as it is received. See the definition of each method to see 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 ensures that every effort is made to extract the data to fulfil your request within a reasonable timeframe. If you require an immediate response and wish to run the service in synchronous mode, omit the CallbackUrl field, but be aware that this may result in timeouts depending on the size of the result data and network conditions.

To receive the data in your endpoint, remember to:

• Use a publicly available URL (our push service will not work if you are running an authenticated service).
• Your service must be RESTful and accept the POST verb.
• Your service must be able to understand and parse the JSON that our API sends to it. Check the response scheme with HTTP status code 200 for the method you want to call asynchronously.
• Make a note of your OperationId value, as it will be used to match your request with the final response, as well as for support and tracking purposes.

Lifespan

When you make an asynchronous request, you will receive an immediate response containing a LifeSpan field, which indicates the maximum time our service has to send the data to your specified callback URL. You can expect the response to be delivered within this time frame (usually it will be much sooner). If something prevents our service from completing successfully, the response you receive will contain the error description as detailed in the Errors section.

Staging environment

For selected data sources, we offer a sandbox (staging) environment with dummy data so you can test your developments and integrations without the requests counting against your account quota/billing. Please see the Sandbox section 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 writing a single line of code. Understanding this documentation page will put you on the right track to integrate our APIs into your solutions.

The OpenAPI definitions can be found in the Open Data API section of the left sidebar:

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

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

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

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

The right pane 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 check that it is working correctly.

Authentication

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

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

You are then ready to edit the body content.

Completing the request

In "Body", you are offered a sample request with all the available fields, we will use AccountLink and AccountNumber, and omit CallbackUrl as 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.

When everything is ready, select the server you want to use ("Production", for this example) and hit the "Send" button 🚀.

Understanding the response

On completion, the request will switch 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 that the service worked fine, and the OperationId shows the unique identifier for this request. The Data element contains all the transactions made during the current day.

Next steps

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