Streaming data

Overview

Akkuro Lending offers streaming APIs for large-scale data extraction, allowing your application to download large datasets. Streaming helps reduce server memory overhead and lets the client start processing data immediately as it arrives, without waiting for the entire dataset to load.

To start streaming, open a connection through the API. After the connection is established, data is delivered incrementally as JSON objects over a persistent connection, instead of requiring the entire dataset to be available before sending.

The stream remains open until all data has been delivered, or until you choose to close the connection. If the connection is interrupted, our indexing system lets you resume and recover any missing data.

The streaming APIs support two content types:

• JSON Lines: Each line is a standalone JSON object, delimited by a newline character (\n). Easy to parse line by line.
• JSON Text Sequences: RFC 7464–compliant format using ASCII RS (0x1E) as a record separator.

Locate streaming APIs

All available streaming APIs can be found on the API schemas. Streaming data APIs are organized by functional group, and some groups have their own set of related streaming APIs. To locate streaming APIs, do as follows:

1. Go to the API Schemas. Select Lending.
2. Select a functional group and look for APIs with “streaming” in the name. Note that not all groups include streaming APIs.
   Alternatively, you can search for the keyword “streaming” in the search bar. All available streaming APIs will appear.

Here are a few examples of streaming APIs:

• Counterparties streaming API: Streams a list of counterparties.
• Payments streaming API: Streams a collection of payments.

Streaming APIs are versioned in the same way as other APIs. Refer to API Versioning for more information.

Connect to the streaming API

Once you've found your preferred streaming endpoint, make an initial call to the streaming API to start a connection. This connection opens a continuous data stream and remains open until all data has been delivered.

Send a GET request and include the following in the Accept headers:

• (Required) Specify your preferred format, either application/jsonl or application/json-seq.
• Specify the API version. We recommend including an API version to avoid breaking changes. Refer to API Versioning for more information.

Note

To specify both the format and version in an Accept header, separate them with a semicolon. For example: Accept: application/json-seq;api-version=2025.1.0.

Optionally, you can include a query parameter:

Parameter	Type	Description	Required
continue-from	integer	The index number of the first object to return in the stream. Use this parameter to resume from a specific index.	No

Each object in the stream is assigned an index field. Use the continue-from query parameter to start the response from a specific index. This is useful for recovering missing data after a streaming disconnection. See Handle stream disconnection for more details.

For example, if you set continue-from=100, the API will resume the stream starting from the object at index 100.

Request example

The following example uses the Counterparties streaming API to stream data related to counterparties:

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/counterparties/stream' \
--header 'Accept: application/json-seq;api-version=2025.1.0' \
--header 'Authorization: Bearer your_JWT_here'

Read streaming responses

After the connection is established, the API sends data in the format you specified.

Understand the index fields

Each streamed object includes an index field. The index value is a sequential counter that indicates the order of the object within the stream.

JSON Lines responses

JSON Lines is a text format where each line is a complete JSON object, separated by a newline character (\n). This format allows clients to parse each object as soon as the newline is received.

To process a JSON Lines response, read the stream line by line. Treat each line as a valid JSON string and use the newline character (\n) to separate individual objects.

Example response:

{"type":"StreamingOrganisationCounterparty","associatedParties":[],"index":0,"organisationName":"Example","countryOfIncorporation":"NL","referenceId":"ef65bcca-1ea2-4cfe-8b66-49ab398bad50","countryCode":"NL","preferredCommunicationLanguage":"en-GB","telephoneNumbers":[],"relations":[] ...}
{"type":"StreamingPersonCounterparty","associatedParties":[],"index":1,"nationalities":["NL"],"salutation":"De heer","initials":"E.J.","firstName":"Erik Jan","surnamePrefix":"van der","surname":"Maas (eigenaar)","sex":"male","dateOfBirth":"1968-11-19","income":{},"countryCode":"NL","preferredCommunicationLanguage":"en-GB","emailAddress":"test@test.com","telephoneNumbers":[],"relations":[] ...}
{"type":"StreamingOrganisationCounterparty","associatedParties":[],"index":2,"organisationName":"[143327] BV 3 Parts","countryOfIncorporation":"NL","countryCode":"NL","preferredCommunicationLanguage":"en-GB","telephoneNumbers":[],"relations":[] ...}
{"type":"StreamingPersonCounterparty","associatedParties":[],"index":3,"nationalities":["NL"],"salutation":"De heer","initials":"E.J.","firstName":"Erik Jan","surnamePrefix":"van der","surname":"Maas (eigenaar)","sex":"male","dateOfBirth":"1968-11-19","income":{},"countryCode":"NL","preferredCommunicationLanguage":"en-GB","emailAddress":"test@test.com","telephoneNumbers":[],"relations":[] ...}

JSON Text Sequences responses

JSON Text Sequences, defined in RFC 7464, provide a format for representing a sequence of multiple JSON objects within a single stream or file. Each JSON object is prefixed with the Record Separator control character (0x1E), which marks the beginning of a new object.

To process a JSON Text Sequences response, your client should read the stream as a sequence of bytes. Use the Record Separator (0x1E) to detect the start of each JSON object, and treat the following newline (\n) as the end of that object.

Example response (using rs to represent the Record Separator):

rs {"type":"StreamingOrganisationCounterparty","associatedParties":[],"index":0,"organisationName":"example","referenceId":"ef65bcca-1ea2-4cfe-8b66-49ab398bad50","lifecycleStatus":"counterparty","preferredCommunicationLanguage":"en-GB","telephoneNumbers":[],"relations":[] ...}
rs {"type":"StreamingPersonCounterparty","associatedParties":[],"index":1,"nationalities":["NL"],"salutation":"De heer","initials":"E.J.","firstName":"Erik Jan","surnamePrefix":"van der","surname":"Maas (eigenaar)","sex":"male","dateOfBirth":"1968-11-19","income":{},"telephoneNumbers":[],"relations":[] ...}
rs {"type":"StreamingOrganisationCounterparty","associatedParties":[],"index":2,"organisationName":"[143327] BV 3 Parts","cocNumber":"12345678","countryCode":"NL","lifecycleStatus":"counterparty","preferredCommunicationLanguage":"en-GB","telephoneNumbers":[],"relations":[] ...}

Handle stream disconnections

If the connection to the stream closes, your client application can send a new request to re-establish it.

Since streaming occurs in real time, you are potentially missing data that would be sent through the time your application disconnects from the stream. To ensure that no data is missed, track the index of the last object you received and use the continue-from query parameter in the new request to resume from that point.

For example, if the stream stops at index 99, set continue-from=100 to resume the stream starting from the object at index 100.