Overview

This guide explains how to authenticate with and call the Flinks Upload API from your application. The API uses two security layers that must both be satisfied on every request:

Credentials You Will Receive from Flinks

Before you can integrate, Flinks will securely deliver the following items to you:

• Client ID — a unique identifier for your OAuth2 application
• Client Secret — a secret passphrase paired with the Client ID
• Signed Certificate (.pem or .crt) — issued by Flinks' Certificate Authority, used for mTLS

You already generated a private key when you created your Certificate Signing Request (CSR). Keep it safe — you will need it alongside the signed certificate Flinks returns. If you don't have one, please contact the Flinks integration team help-integration@flinks.com

Authentication Flow

Every API call follows this two-step sequence:

Step 1 — Obtaining an Access Token

Endpoint: POST https://upload-mtls.flinksapp.com/api/v1/token
Grant Type: client_credentials
Authentication: HTTP Basic Auth (Base64-encoded client_id:client_secret)

The token request must be sent over mTLS (with your certificate). The body must be URL-encoded form data.

Headers

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

Body

grant_type=client_credentials
scope=ocr.write

Successful Response

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 300
}

Step 2 — Calling the Upload API

Once you have a valid access token, include it in the Authorization header for every request to the Upload API. Your mTLS certificate must also be presented on the same connection.

Authorization Header

Authorization: Bearer <access_token>

Code Examples

Python

The example below uses the requests library. Install it with: pip install requests

Step 1: Get Access Token

import requests
import base64

# Paths to your certificate files
CERT_PATH = "/path/to/your/certificate.pem"
KEY_PATH  = "/path/to/your/private-key.pem"

# Your credentials (store these in environment variables, not hardcoded)
CLIENT_ID     = "your-client-id"
CLIENT_SECRET = "your-client-secret"

TOKEN_URL = "https://upload-mtls.flinksapp.com/api/v1/token"

# Build Basic Auth header: base64(client_id:client_secret)
credentials = f"{CLIENT_ID}:{CLIENT_SECRET}"
encoded = base64.b64encode(credentials.encode()).decode()

response = requests.post(
    TOKEN_URL,
    headers={
        "Authorization": f"Basic {encoded}",
        "Content-Type": "application/x-www-form-urlencoded",
    },
    data={"grant_type": "client_credentials", "scope": "ocr.write"},
    cert=(CERT_PATH, KEY_PATH),  # mTLS: present your certificate + private key
    verify=True,                  # Verify Flinks server certificate
)

token_data = response.json()
access_token = token_data["access_token"]
# Token is valid for 5 minutes — cache it and reuse across requests

Step 2: Call the Upload API

UPLOAD_URL = "https://upload-mtls.flinksapp.com/api/v1/upload"

api_response = requests.post(
    UPLOAD_URL,
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={"your": "payload"},
    cert=(CERT_PATH, KEY_PATH),
    verify=True,
)

print(api_response.json())

C# (.NET)

The example below uses HttpClient with an X509Certificate2 for mTLS. Requires .NET 5+.

Step 1: Get Access Token

using System;
using System.Net.Http;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var certificate = new X509Certificate2(
    "/path/to/certificate-and-key.pfx",
    "pfx-password-if-any"
);

var handler = new HttpClientHandler();
handler.ClientCertificates.Add(certificate);

using var httpClient = new HttpClient(handler);

string clientId     = "your-client-id";
string clientSecret = "your-client-secret";
string credentials  = Convert.ToBase64String(
    Encoding.UTF8.GetBytes($"{clientId}:{clientSecret}")
);

string tokenUrl = "https://upload-mtls.flinksapp.com/api/v1/token";

var tokenRequest = new HttpRequestMessage(HttpMethod.Post, tokenUrl);
tokenRequest.Headers.Add("Authorization", $"Basic {credentials}");
tokenRequest.Content = new FormUrlEncodedContent(new[] {
    new KeyValuePair<string, string>("grant_type", "client_credentials"),
    new KeyValuePair<string, string>("scope", "ocr.write")
});

var tokenResponse = await httpClient.SendAsync(tokenRequest);
var tokenJson     = await tokenResponse.Content.ReadAsStringAsync();
var tokenData     = JsonSerializer.Deserialize<JsonElement>(tokenJson);
string accessToken = tokenData.GetProperty("access_token").GetString();
// Token is valid for 5 minutes — cache it and reuse across requests

Step 2: Call the Upload API

string uploadUrl = "https://upload-mtls.flinksapp.com/api/v1/upload";

var apiRequest = new HttpRequestMessage(HttpMethod.Post, uploadUrl);
apiRequest.Headers.Add("Authorization", $"Bearer {accessToken}");
apiRequest.Content = new StringContent(
    JsonSerializer.Serialize(new { your = "payload" }),
    Encoding.UTF8,
    "application/json"
);

var apiResponse = await httpClient.SendAsync(apiRequest);
var result      = await apiResponse.Content.ReadAsStringAsync();
Console.WriteLine(result);

Upload Endpoint Flow

Once authenticated, a complete upload session requires calling two endpoints in sequence: one to upload the file(s), and one to signal that the upload is complete and trigger OCR processing.

Each file must be converted to base64 before being included in the request body. Send one file per request. Multiple files can be grouped under the same AggregationId by repeating the upload call before calling the complete endpoint.

Base URL

https://upload-mtls.flinksapp.com

Full Flow Summary

Step 1 — Upload a File

Endpoint: POST /upload

Upload one base64-encoded file. Repeat for each additional file, including the AggregationId returned from the first call to group files under the same upload session.

Request Body — First file (no AggregationId)

{
  "Files": [
    {
      "FileName": "statement_january.pdf",
      "Content": "<base64-encoded file content>"
    }
  ],
  "Tag": "optional-tag",
  "ClientName": "Optional Client Name"
}

Request Body — Subsequent files (include AggregationId to group)

{
  "AggregationId": "d521ae0d-9cf1-40e1-a1ee-474983800601",
  "Files": [
    {
      "FileName": "statement_february.pdf",
      "Content": "<base64-encoded file content>"
    }
  ],
  "Tag": "optional-tag",
  "ClientName": "Optional Client Name"
}

Successful Response

{
  "HttpStatusCode": 200,
  "AggregationId": "d521ae0d-9cf1-40e1-a1ee-474983800601",
  "Message": "The files were uploaded successfully. Please send the next file(s)."
}

Step 2 — Complete the Upload

Endpoint: POST /upload/complete

Signal that all files have been uploaded. This triggers the OCR processing pipeline. OCR processing will not start until this endpoint is called.

Request Body

{
  "AggregationId": "d521ae0d-9cf1-40e1-a1ee-474983800601"
}

Successful Response

{
  "HttpStatusCode": 200,
  "AggregationId": "d521ae0d-9cf1-40e1-a1ee-474983800601",
  "Login": {
    "Id": "aabf32b7-2f4e-4248-8895-b47b7ebc5a3c"
  },
  "Message": "All files were uploaded successfully. The OCR process will start shortly."
}

File and Size Limits

Fraud Analysis Endpoint

Once the upload and OCR processing are complete, you can retrieve the fraud analysis results for the uploaded documents.

Endpoint: GET https://{instance}-api.private.fin.ag/v3/{customerId}/upload/fraudanalysis/{loginId}

Response — No Fraud Detected (200)

{
  "HttpStatusCode": 200,
  "Message": "No Fraud Signal Detected",
  "Login": {
    "LoginId": "aabf32b7-2f4e-4248-8895-b47b7ebc5a3c",
    "RequestId": "c3d4e5f6-..."
  },
  "DocumentAnalysis": [
    {
      "Status": "COMPLETED",
      "FullAnalysis": [
        {
          "DocumentType": "BANK_STATEMENT",
          "FraudSignals": []
        }
      ]
    }
  ]
}

Response — Fraud Signals Detected (200)

{
  "HttpStatusCode": 200,
  "Login": {
    "LoginId": "aabf32b7-2f4e-4248-8895-b47b7ebc5a3c",
    "RequestId": "c3d4e5f6-..."
  },
  "DocumentAnalysis": [
    {
      "Status": "COMPLETED",
      "FullAnalysis": [
        {
          "DocumentType": "BANK_STATEMENT",
          "FraudSignals": [
            {
              "Type": "SIGNAL_TYPE",
              "PageNumber": 1,
              "Count": 2,
              "UnderlyingData": [
                {
                  "Details": [
                    {
                      "SpecificType": "delta",
                      "Value": "0.85",
                      "DataType": "float"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

For full API reference, see the Flinks public documentation.

Common Errors

Support

If you encounter issues not covered in this guide, contact your Flinks contact with the following information:

• The full error message and HTTP status code received
• The timestamp and endpoint you were calling
• Confirmation of whether the issue occurs on the token request, the API call, or both
• Your environment (language, library version)