From first key to first file

Connect in three steps

Credifin supplies the key name, permissions and API address. The key remains valid until revoked and is masked but copyable by authorised users.

1. 1

   Credifin enables the integration

   After activation, you will see Integrations → API in the client portal.

2. 2

   The customer administrator creates the key

   Click Generate API key. Name and permissions are preconfigured; the key remains valid until revoked.

3. 3

   Copy and validate

   Store the key in your secret manager and run the safe validation cURL. The prefix stays visible for management; the secret stays hidden and can be copied on request.

API address

https://crm.credifin.nl

Authentication header

Api-Key

Preferred route

POST /api/v1/dossiers

The API address is the same for every customer. The key automatically links each request to the correct customer.

How the API works

One address, one header, JSON in and JSON out. Everything below applies to every route.

Agencies

Customers and agencies use the same API and documentation. A customer key grants access to that customer. An agency key grants access to the companies currently assigned to the agency; a group key also covers its own branches. Access is determined again for every request.

POST /api/creditor: use creditors:create and Idempotency-Key to create a company under your own agency. Use the returned uuid or reference as creditor. This request does not create a user login.

If you manage multiple customers as an agency, you receive one key for the whole agency. Credifin enables access per agency; the agency administrator then creates the key under Integrations → API. New customers within your agency are immediately covered by the same key.

Migrating from CollectOnline

Switch in five steps

1. Request activation. Credifin enables the API for your customer and maps existing CollectOnline identifiers.
2. Create a key under Integrations → API and store it in your secret manager. The old CollectOnline key does not work here.
3. Replace the address https://credifin.collectonline.eu by https://crm.credifin.nl. The paths under /api/... remain unchanged.
4. Run an acceptance test: retrieve your file list, read one file with /financial and submit a test file through POST /api/v1/dossiers/validate.
5. Review the differences in the table below and switch over. Tell us which routes you use so we can check them specifically.

Interest, history and credit notes

These features are available to all customers and agencies with the required permissions. They are part of the general API; there is no separate customer-specific version. Open the route for its conditions, fields and responses:

• Set a fixed interest amount on an invoice — PUT /api/invoice/{invoice}/interest
• Read case status history — GET /api/dossier/{dossier}/status/history
• Upload a credit note PDF — POST /api/creditnote/{creditNote}/attachment

For these three routes, the UUID in the path identifies the company the request belongs to. An agency key does not need to supply an additional creditor here. File and customer access boundaries still apply.

A linked CollectOnline UUID remains usable within your current access rights. A missing source link or a resource outside your access returns 404. An ambiguous source link returns 409. Report the route, UUID and X-Request-Id to Credifin in that case; do not create a replacement file.

Status history uses the actual status date in Dutch local time. Use the transition to lost to identify a write-off; closed means a positive closure. Empty history does not establish a write-off date. A historical note without a file has attachmentName: null; there is no file to download.

Identities and credit note attachments

Imported files can have several historical debtor records for one source UUID. The file list and detail use the same stable debtor UUID as a lookup by that source UUID. Existing file records are not merged.

With agency access, the same old debtor UUID may occur for several customers. Use GET /api/debtor/{debtor}?creditor={creditor}. Without a customer the response is 409 LEGACY_ID_AMBIGUOUS. The UUID from debtorUuid can be retrieved directly.

Credit notes include hasAttachment and invoice. Only visible attachments count. invoice is null when no invoice link is recorded. Downloads also require document access; internal or blocked files are not released.

GET /api/creditnote/{creditNote}/attachment

Testing with a test customer

Tests use the same API address with a separate test customer and its own customer key. Use only fictitious files and agreed test contact details. The test key belongs to that customer; it does not grant access to the real customer. There is no separate sandbox.

Ask Credifin to create a separate test customer. Select it under Integrations → API and create its own key. An agency key may cover several companies; do not use it to restrict a test to one company. Test files follow the same processing as regular files. Use only a test receiver for webhooks.

POST /api/dossier/{dossier}/close
Api-Key: YOUR_API_KEY
Idempotency-Key: withdrawal-your-unique-reference
Content-Type: application/json

{"reason":"incorrect_submission","note":"Incorrectly submitted by Ominimo; please stop collection."}

Complete debtor addresses

For every debtor, supply the street, house number including any suffix, postal code, city and country. Check this for all companies and branches. Missing address details can block file processing.

For v1 file submission, these fields are required in debtor.address. A suffix can be supplied separately in houseNumberAddition. Legacy debtor routes use street, houseNumber (including any suffix), postalCode, city and country at the top level. Legacy acceptance of omitted fields does not mean the address is complete.

Complete an existing address using PUT /api/debtor/{debtor}, dossiers:create and a new Idempotency-Key for each change. Reuse the same key and content for a retry. An agency key must also supply creditor. Read the debtor again afterwards to check the stored details. POST /api/debtor does not update an existing debtor.

PUT /api/debtor/{debtor}
Content-Type: application/json
Api-Key: <uw-api-key>
Idempotency-Key: debtor-address-1042-v1

{
  "creditor": "KLANT-1042",
  "street": "Keizersgracht",
  "houseNumber": "100 A",
  "postalCode": "1015CS",
  "city": "Amsterdam",
  "country": "NL"
}

Omitted fields are preserved; null or an empty value clears optional fields. A 409 SHARED_DEBTOR response means nothing was changed: coordinate the update with Credifin. The change applies to the resolved debtor record, not automatically to separate historical copies.

Authentication and safe retries

Send the API key only over HTTPS in the request header. Never place keys in a URL, browser code or application log.

Api-Key: <uw-api-key>
Idempotency-Key: order-73145-dossier-v1

Quickstart: safe validation

Store the key outside your shell history as CREDIFIN_API_KEY. This route checks the same fields as the production route, but saves nothing and starts no workflow.

test -n "$CREDIFIN_API_KEY" || { echo 'Sla uw API-key eerst veilig op als CREDIFIN_API_KEY.' >&2; exit 1; }

curl -X POST 'https://crm.credifin.nl/api/v1/dossiers/validate'   -H 'Content-Type: application/json'   -H "Api-Key: $CREDIFIN_API_KEY"   --data '{
    "reference": "DOS-2026-0042",
    "currency": "EUR",
    "debtor": {
      "reference": "KLANT-1042",
      "companyName": "Voorbeeld Handel B.V.",
      "language": "nl",
      "address": {
        "street": "Keizersgracht",
        "houseNumber": "100",
        "postalCode": "1015CS",
        "city": "Amsterdam",
        "country": "NL"
      }
    },
    "invoices": [{
      "reference": "INV-2026-0815",
      "date": "2026-12-01",
      "dueDate": "2026-12-31",
      "amount": 847.50
    }]
  }'

Sending additional file details

The more details a file contains, the more often Credifin can answer a debtor’s question straight away.

You choose the field names yourself. Always use the same name for the same kind of detail. Examples are shown below.

Include these fields when submitting, as a list of name and value:

"meta": [
  { "name": "kenteken", "value": "GF-132-X" },
  { "name": "opzegdatum", "value": "2026-05-01" }
]

Send documents such as a cancellation letter, a confirmation email (.eml or .msg) or an account statement as attachments.

You can add or change details per file later. A field with the same name is overwritten.

POST /api/dossier/{dossier}/meta
POST /api/dossier/{dossier}/attachment

Common workflows

Four patterns needed by almost every integration. Store your key as CREDIFIN_API_KEY and copy the examples.

curl -sS -D - 'https://crm.credifin.nl/api/dossier'   -H "Api-Key: $CREDIFIN_API_KEY"   -H 'X-API-FILTER-FROM: 2026-09-01 00:00:00'   -H 'X-API-PAGE-LIMIT: 200'   -H 'X-API-NEXT-PAGE: 1'

async function gewijzigdeDossiers(sinds) {
  const alles = [];
  let pagina = '1';
  while (pagina) {
    const antwoord = await fetch('https://crm.credifin.nl/api/dossier', {
      headers: {
        'Api-Key': process.env.CREDIFIN_API_KEY,
        'X-API-FILTER-FROM': sinds,
        'X-API-PAGE-LIMIT': '200',
        'X-API-NEXT-PAGE': pagina,
      },
    });
    if (!antwoord.ok) throw new Error('Credifin gaf ' + antwoord.status);
    alles.push(...(await antwoord.json()));
    pagina = antwoord.headers.get('X-API-NEXT-PAGE') || '';
  }
  return alles;
}

curl -sS 'https://crm.credifin.nl/api/dossier/c3069230-ff95-4c95-aa73-9c57945ae038/financial'   -H "Api-Key: $CREDIFIN_API_KEY"

curl -sS -X POST 'https://crm.credifin.nl/api/payment'   -H "Api-Key: $CREDIFIN_API_KEY"   -H 'Content-Type: application/json'   -H 'Idempotency-Key: betaling-2026-118'   --data '{ "dossier": "c3069230-ff95-4c95-aa73-9c57945ae038", "amount": 100, "date": "2026-07-03", "reference": "Bankafschrift 2026-118" }'

Statuses

The fields status and substatus in file responses use the CollectOnline names. dossierClosed is a useful boolean for closed and lost files.

Webhooks

Choose dossier.status.changed to receive status changes automatically. data contains status, substatus, dossierClosed and previous. dossier.uuid identifies the file and creditor.uuid the customer. Use GET /api/dossier/{dossier}/status to retrieve the current state.

Webhooks are processed asynchronously. Process each event ID only once and allow for repeated or delayed notifications. A webhook notifies you of a change; retrieve additional details through the documented API routes.

Instead of polling, let Credifin send a message when something happens in a file. A customer administrator adds under Integrations → Webhooks a URL, selects events and receives a one-time secret to verify each notification. The same page shows every delivery, its content, attempts and a retry button. You can register multiple webhooks, for example one per system. Credifin enables webhooks per creditor.

Agencies. If you manage multiple customers as an agency, register one webhook for the whole agency. It receives notifications for all customers, including future ones; no per-customer setup is needed. Each notification includes under creditor the client number and name, and under agency your agency. Agents also have the event creditor.created: a new customer has been created under your agency. Credifin enables webhooks per agency.

Events

The notification

Every notification is a POST with JSON. dossier is a summary of the file; data has the same structure as its corresponding API resource, for example a payment for payment.received. For debtor and client events and test notifications, dossier is null. creditor identifies the creditor (UUID, client number, name) and agency the agency it belongs to, or null.

POST https://erp.uwbedrijf.nl/credifin/webhook
Content-Type: application/json
Credifin-Event: payment.received
Credifin-Event-Id: 5f1c4a2b-0d3e-4f6a-9b8c-7d6e5f4a3b2c
Credifin-Delivery-Id: e7c1b2a3-4d5e-4f60-8a7b-9c0d1e2f3a4b
Credifin-Timestamp: 1756729864
Credifin-Signature: t=1756729864,v1=2c3f…9a

{
  "id": "5f1c4a2b-0d3e-4f6a-9b8c-7d6e5f4a3b2c",
  "type": "payment.received",
  "version": 1,
  "occurredAt": "2026-09-01T12:30:00.000Z",
  "createdAt": "2026-09-01T12:31:04.000Z",
  "delivery": { "id": "e7c1b2a3-4d5e-4f60-8a7b-9c0d1e2f3a4b", "attempt": 1 },
  "creditor": { "uuid": "b1a7c8e2-1234-4f5a-8b9d-123456789abc", "reference": "106861", "name": "Voorbeeld B.V." },
  "agency": null,
  "dossier": {
    "uuid": "c3069230-ff95-4c95-aa73-9c57945ae038",
    "ownerReference": "IN146900",
    "reference": "ORDER-73145",
    "status": "open",
    "substatus": "IN_BEHANDELING",
    "dossierClosed": false,
    "balance": 747.5
  },
  "data": { "uuid": "a9c3d4e5-…", "amount": 100, "date": "2026-09-01", "receivedBy": "OWN_ACCOUNT" }
}

Verify signature

Calculate HMAC-SHA256 over <timestamp>.<ruwe body> with your secret and compare with v1 from the header. Reject notifications whose timestamp differs by more than five minutes.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyCredifin(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((part) => part.split('=')));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex');
  const actual = String(parts.v1 || '');
  return actual.length === expected.length && timingSafeEqual(Buffer.from(actual, 'hex'), Buffer.from(expected, 'hex'));
}

function verifyCredifin(string $secret, string $header, string $rawBody): bool {
  parse_str(str_replace(',', '&', $header), $parts);
  $timestamp = (int) ($parts['t'] ?? 0);
  if (abs(time() - $timestamp) > 300) return false;
  $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
  return hash_equals($expected, (string) ($parts['v1'] ?? ''));
}