Skip to content

Quickstart

From a sandbox key to your first answer: one header, one request, one envelope.

  1. Get a sandbox key

    Verifying your email gives your organisation sandbox access and test credit. Create a sandbox key in the FinSour console: it starts with fs_test_. Keep it on your server, in an environment variable such as FINSOUR_API_KEY, and never in code that runs in a browser.

    See Authentication and Sandbox and production.

  2. Make your first call

    Every API is a POST to its own path under https://gateway.staging.finsour.io. This looks up a vehicle registration. The sandbox reaches the real data source, so use a registration number you are entitled to look up.

    cURL

    curl -X POST https://gateway.staging.finsour.io/v1/vehicle/rc \
      -H "X-Api-Key: $FINSOUR_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
      "input": {
        "registrationNumber": "<registrationNumber>"
      }
    }'

    Node.js

    const response = await fetch("https://gateway.staging.finsour.io/v1/vehicle/rc", {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.FINSOUR_API_KEY,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        "input": {
          "registrationNumber": "<registrationNumber>"
        }
      }),
    });
    
    console.log(response.status, await response.json());

    Python

    import os
    import uuid
    
    import requests
    
    response = requests.post(
        "https://gateway.staging.finsour.io/v1/vehicle/rc",
        headers={
            "X-Api-Key": os.environ["FINSOUR_API_KEY"],
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json={
            "input": {
                "registrationNumber": "<registrationNumber>",
            },
        },
        timeout=30,
    )
    
    print(response.status_code, response.json())

    Replace each value in angle brackets with your own. The key is read from the FINSOUR_API_KEY environment variable.

  3. Read the answer

    A definitive answer is 200, whether or not the record exists. The body is the same envelope for every API: success, data, requestId, latencyMs and meta. A record the source does not hold comes back as data.found: false with every other field null, never as an error.

    An error is a 4xx or 5xx with success: false and an error object whose retryable flag says whether trying again can help. See Making a request and Errors.

  4. Find your API

    Each API’s page has its path, every request and response field, samples in cURL, Node.js and Python, and the errors it can return. Browse them by category from the menu, or press / to search.

Written from FinSour platform API contract (finsour development at 80e8b83bf), last changed . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.