← Back to blog

October 1, 2026 · 2 min read

externalId: the field that decides whether your integration can retry

A timeout makes the originating system resend the request and the same loan gets disbursed twice. Fineract ships the mechanism to prevent it, but it only works if you pick the right value.

Note · Integration · Idempotency

The network fails once every thousand requests, and a thousand requests is a quiet week. The scenario is always the same: your origination system calls Fineract to create a loan, the response never arrives because of a timeout, the originator retries because it was written properly, and the client ends up with two identical loans. The error does not surface that day: it surfaces when the portfolio balance stops matching the ledger.

Fineract ships the mechanism to prevent this and almost nobody uses it: the externalId field.

What it actually does

externalId is an identifier you choose and Fineract stores alongside the entity. It is not decorative: the Loan entity declares a uniqueness constraint on that column, named loan_externalid_UNIQUE. A second attempt to create a loan with the same value creates nothing — it hits the database constraint.

And it does not blow up in just any way. The creation service intercepts that specific violation and returns a readable business error, error.msg.loan.duplicate.externalId, instead of a generic 500. Your integration can tell “this already existed” from “this genuinely failed”, which is exactly the distinction it needs in order to retry without fear.

The loop closes with the lookup routes for that identifier: GET /loans/external-id/{loanExternalId} and its variants. Faced with a duplicate, the originator queries and recovers the loan that was actually created, without depending on having received the original response.

The detail that ruins it

The value has to come from the system that originates the operation: the application number, the case file identifier, the reference from the core you are migrating off.

If you generate a random identifier at the moment of sending the request, every retry carries a different one and you are back where you started — with the added nuisance of a field full of data that serves no purpose. The value has to be the same on the first attempt and on the fifth, because what it identifies is not the request: it is the business event.

Two minutes of work

Go through your integrations. If any of them creates clients, loans, accounts or transactions in Fineract without sending an externalId, it cannot retry safely, and that means it will duplicate something eventually. Today, while nothing has failed, the change costs one line.