Best Practices

Overview

This guide provides essential insights for efficient and reasonable utilization of Kyriba APIs to avoid excessive calls. Whether you are well-versed or exploring them for the first time, these best practices will help you make the most of our APIs for your development projects.

Optimize Token Management

Authentication is required to make calls to Kyriba APIs. When we make a request to the authentication endpoint with the right set of credentials for the first time, it generates an access token in response with a default expiration time of 3600 seconds. If another valid request to the authentication endpoint is made in the next 3500 seconds, the same access token will be returned.

How to Update the Existing Resource

In order to update the existing resource, the PUT method is used.

It is crucial to keep in mind that using PUT method on a resource will overwrite the values of the fields mentioned in the payload by the provided data. Any unmentioned field will have its value reset to either nothing or to the default field value.

To achieve a partial update, make sure to perform the following steps:

  • Retrieve all the fields and their values by performing a GET request on the resource.

  • Change the values of the fields you want to update (keeping the others unchanged).

  • Send the whole in the PUT payload.

Gather Resource Details in a Single Call

When requesting multiple resource details of the same type (e.g. accounts), querying each one individually may prove inefficient, particularly when retrieving a considerable number of resources.

The POST /v1/accounts/details endpoint empowers users to retrieve up to 100 entity details in bulk with a single API call, streamlining the retrieval process significantly.

The endpoint is available for the following APIs:

Usage Example

The request body includes an array of entity references ("refs") allowing their bulk retrieval.

POST /v1/accounts/details

• Request body ▾ 
{
  "refs": [
    "BNP_EUR_338",
    "SG_EUR_412",
    // Additional entity references...
  ]
}

The response comprises detailed information for each entity referenced in the request.

• Response ▾ 
{
  "results": [
    {
      "status": 200,
      "ref": {
        "uuid": null,
        "code": "BNP_EUR_338"
      },
      "details": {
        "uuid": "66ae18ae-0395-42f9-ac43-54a6a3478ccb",
        "code": "BNP_EUR_338",
        // Detailed entity information...
      },
      "error": null
    },
    {
      "status": 200,
      "ref": {
        "uuid": null,
        "code": "SG_EUR_412"
      },
      "details": {
        "uuid": "936b0310-7fce-4882-a054-537f4f148b10",
        "code": "SG_EUR_412",
        // Detailed entity information...
      },
      // More entity details...
    }
  ]
}

Get Cash Balance for all Bank Accounts

The Cash Balances API is meant to retrieve cash balances of your accounts.

In order to get a balance of a single account, it can be queried either by the account’s reference (code or uuid) or statement identifier.

However, when it comes to requesting the cash balance of all or multiple accounts, such an approach becomes inefficient, especially if the number of accounts is significant. In this case, we strongly recommend using the aggregation endpoint POST /v1/cash-balances/aggregation that allows you to get cash balances of multiple accounts in one API call, as opposed to making multiple ones.

Note❗ This endpoint provides cash balances in a designated currency specified within the currencyConversion object. To retrieve cash balances for all accounts in their account currency (without conversion), it is necessary to submit a separate API request for each currency.

The example below demonstrates how to retrieve cash balances of all the EUR accounts:

• Example ▾ 
{
    "accountType": "ALL",
    "cashFlowStatus": {
        "actual": true,
        "confirmedForecasts": true,
        "estimatedForecasts": true,
        "intraday": true
    },
    "currencyConversion": {
        "currency": {
            "code": "EUR"
        },
        "currencyRate": {
            "fixingDate": "2023-03-03",
            "mode": "FIXING"
        }
    },
    "datePeriod": {
        "dateType": "TRANSACTION",
        "endDate": "2023-03-03",
        "startDate": "2023-03-03"
    },
    "displayEntity": "ACCOUNT",
    "entities": [
        {
            "code": "EUR"
        }
    ],
    "entityType": "CURRENCY"
}

Fields to pay attention to:

  • displayEntity - an entity type to aggregate the balance for. For example, ACCOUNT will return balances aggregated per account, COMPANY - balances aggregated per company.

  • entityType - an entity type to filter accounts by. For example, CURRENCY will filter accounts that have one of the currencies specified in the field “entities”.

  • entities - a list of entities of the selected entityType.

The API response contains an object per each account and its cash balances.

Below is an example of the response body:

• Response example ▾ 
{
    "currency": {
        "uuid": "a6dca752-2fcf-4693-b0ed-a769c7f059fb",
        "code": "EUR"
    },
    "dateType": "TRANSACTION",
    "entities": [
        {
            "displayEntity": {
                "uuid": "cb6e6eee-04b0-47e0-9bba-8d291dd6642a",
                "code": "BNP_EUR_338"
            },
            "balances": [
                {
                    "date": "2023-03-03",
                    "amount": 337098588.845
                }
            ]
        },
        {
            "displayEntity": {
                "uuid": "f59f6982-5749-4bcd-8211-8ec021b278c9",
                "code": "SG_EUR_412"
            },
            "balances": [
                {
                    "date": "2023-03-03",
                    "amount": 161615.010
                }
            ]
        },
        // ... (more entries)
    ]
}

Retrieve Transfers Status

The Transfers Status API is designed to provide real-time status information for payment transfers.

While API users can query transfers individually by reference or uuid, the API offers a more efficient approach when dealing with a large number of transfers originating from a common input file.

When the payment input file is integrated, the system associates each transfer with a fileName identifier. Instead of making multiple calls for individual transfers, you can use the fileName filter to retrieve all transfers associated with that file in a single call.

• Usage example ▾ 
GET /v1/payment/transfers/status?fileName=Oracle-payment-file-16102023.txt

This query will return the status information for all transfers that were part of the file with the name Oracle-payment-file-16102023.txt.

Note❗ If the payment input file contains more than 20,000 transfers, the filtering method will not function.

The API response contains an object per each account and its cash balances.

Below is an example of the response body:

• Response example ▾ 
{
    "metadata": {
        ...
    },
    "results": [
        {
            "transactionNumber": "HOLDACH000024",
            "uuid": "547636a4-c07f-48fb-8577-6f553a6e35d9",
            "reference": "INV-8993-4",
            "remittanceIdentifier1": null,
            "remittanceIdentifier2": null,
            "fileName": "Oracle-payment-file-16102023.txt",
            "status": "PREPARED",
            "nextAction": "GENERATE",
            "ackInfo": null,
            "remittance": {
                "batchId": "DOMTACH02167",
                "status": "CONSTITUTED"
            }
        },
        {
            "transactionNumber": "HOLDACH000025",
            "uuid": "9b2f06ec-fbd4-479c-899a-22bab6e46455",
            "reference": "INV-7332-1",
            "remittanceIdentifier1": null,
            "remittanceIdentifier2": null,
            "fileName": "Oracle-payment-file-16102023.txt",
            "status": "PREPARED",
            "nextAction": "GENERATE",
            "ackInfo": null,
            "remittance": {
                "batchId": "DOMTACH02167",
                "status": "CONSTITUTED"
            }
        },
        // ... (more entries)
    ]
}

When to Use Process Templates

With Process templates API, you can retrieve a wider array of information than what the standard API response offers in some cases. For example, if you want to include the amount of a payment, its transaction date, or any other information which is not returned by the Transfers Status API, Process Templates will allow you to do so seamlessly.

Moreover, some Kyriba modules or functions, for example, the Access Profile function, are not covered by the APIs yet. Thanks to the Process templates API, you can launch and retrieve the results of the reports and data exports.

When using Process Templates, you can configure:

  • The fields you want to include in the response

  • Filters to apply for proper data selection

Note❗ Process template parameters cannot be passed via API. All the configurations are done in the Kyriba application.

Discover Product Subscription/Service Token Assignment

Depending on the database, a set of services that a given user has access to is managed either by Product Subscription or Service Token.

Product Subscription

The self-service feature empowers administrators to swiftly and effortlessly allocate services to users. Kyriba offers the following capabilities to automate subscription assignment and user management through the API, streamlining the process.

Path in the Kyriba application:

Core Data ⇨ Admin ⇨ Security ⇨ Processing options ⇨ Automatic subscription assignment



In this menu, 3 options are made available:

1. Assign subscriptions based on access profile ONLY when creating users

Subscriptions are allocated based on the access profile exclusively during the user creation process. When users are created, they receive subscriptions from the Product Subscription Bundle linked to their access profile. It’s important to note that this functionality is not automatically activated when updating the configuration of an existing user.

2. Keep Product Subscriptions in sync with Access profiles

This option enables synchronization between Product Subscriptions and Access profiles: Subscriptions from the Product Subscriptions Bundle linked to their respective Access profiles are automatically assigned to users.

This subscription assignment process is activated under the following circumstances:

  • Creation of a new user

  • Modification of a user’s Access profile

  • Updates made to the Product Subscriptions Bundle configuration

3. Apply Product Subscriptions Bundles

Users are automatically granted subscriptions according to the Product Subscriptions Bundle assigned to them.

This subscription allocation process is initiated in the following scenarios:

  • When a new user is created using the API

  • When a user’s Product Subscriptions Bundle is modified

  • When updates are made to the configuration of a Product Subscriptions

It’s important to note that, for the purpose of subscription automation, the users’ Access profiles are not taken into consideration. If you opt for this setting, ensure that you include the productSubscriptionsBundle object in your API request body.


The Product Subscription Bundles can be accessed in Kyriba application by following this path:

Core Data ⇨ Admin ⇨ Tool ⇨ Set-up ⇨ Product subscriptions bundle

Service Token

A set of services a user has access to is defined by its Service token. If a user is not assigned a Service token, they will not be able to log in to the Kyriba application.

When managing users via API, make sure to populate your API request body with the serviceToken object.


To retrieve a list of existing Service tokens and the opened services, one can run a Process template of type Export service token with the help of Process Templates API. Follow the path below to configure the Process template in the Kyriba application.

Path in the Kyriba application:

Core Data ⇨ Set-up ⇨ Templates ⇨ Report and process template

Learn about Idempotency when Importing Payments

Problematics:

  • POST operations involving payment instructions are sensitive and prone to network failures.

  • Retries of failed POST requests should not result in duplicated backend entries.

Solution:

Set up parametrization to make the import of payment idempotent. Idempotency can help to prevent API failures and payment data uploads multiple times.

Set up Idempotency for Payment Import:

1. Process Template settings

When setting up the Process template for file import, utilize the "Duplicate file check" parameter in order to enable/disable a check of whether the newly uploaded file is a duplicate of an already existing file.

Path in the Kyriba application:

Tasks & Reports ⇨ File import/export


It can reject the files based on the three criteria:

  • File name

  • File content (MD5 hash)

  • Both file name and content (MD5 hash)

2. Duplicate Control options

The function defines the criteria for the application to apply when checking the uniqueness of transfers to be integrated against transactions that already exist in the application. When the application detects transactions that match a set of duplicate control options, the transaction is rejected.

Path in the Kyriba application:

Payment ⇨ Payments/Direct Debits ⇨ Set-up ⇨ Duplicate control options


Encode URI Component

When making API calls, it is important to note that certain characters in the request URL may need to be encoded in accordance with RFC 1738 to ensure proper transmission and interpretation. This applies both to query parameters and path parameters within the URL.

Handling of Query/Path Parameters with Special Characters

Please refer to the table below for the details on how to encode certain characters:

Character Encoded character
+ %2B
$ %24
& %26
; %3B
@ %40


You can use the encoding directly via Postman, as shown below:

Handling of . and / in Kyriba API URLs

Note❗ Characters such as a dot (.) and a forward slash (/) require specific handling when used in Kyriba API URLs, as they are not supported and may lead to unexpected behavior or errors. To ensure proper functionality and compatibility, we recommend utilizing UUIDs as substitutes.

Search for Accounts with Special Characters

If you need to reference a specific account containing either . or /, first perform a GET /v1/accounts request to retrieve it from the list of accounts using the appropriate search parameters. Ensure to include the special characters in the search query to filter the results accordingly.

Use UUID from the previous step

From the list of accounts returned by your search, retrieve the uuid of the specific account you want to reference. You can then use this uuid to manage the account such like fetching its details, updating or deleting it.