Integration Guide

Findo Score API

This integration guide describes how to query Findo Score Express, a real-time credit scoring API. It covers the authentication flow, available query services, and expected response formats.

Integration Flow

The integration starts by requesting an access_token using the provided credentials. In subsequent requests, that token is sent in the Authorization header together with the client_id.

Base URL

Environment	BASE_URL	Use
Production	https://api.score.findo.com.ar	Production environment.
QA	https://qa.api.score.findo.com.ar	Testing and integration environment.

The examples in this documentation use the QA environment. Personal identifiers and names shown in examples are obfuscated; replace them with data enabled for the corresponding environment. To run against production, change only the value of BASE_URL.

Endpoints

Method	Endpoint	Use
POST	{BASE_URL}/v1/oauth/token	Access token retrieval.
GET	{BASE_URL}/v1/express	Express query by CUIT/CUIL.
GET	{BASE_URL}/v1/express/dni	Express query by DNI.

Authentication endpoint

Authentication

This endpoint returns the access token to be sent in subsequent requests.

Endpoint

Method	Path	Content-Type
POST	/v1/oauth/token	application/x-www-form-urlencoded

Body Parameters

Parameter	Type	Req.	Description
client_id	string	YES	Client identifier provided by Findo.
client_secret	string	YES	Client secret provided by Findo.

200 OK Body

Field	Type	Description
access_token	string	RS256-signed JWT. It is sent in the `Authorization` header of each query.
expires_in	integer	Token validity in seconds (86400 = 24 hours).

Authentication Example

cURL

BASE_URL="https://qa.api.score.findo.com.ar"

curl "${BASE_URL}/v1/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<tu_client_id>' \
  --data-urlencode 'client_secret=<tu_client_secret>'

200 · JSON

{
  "access_token": "eyJhbGciOiAiUlMyNTYi...",
  "expires_in":   86400
}

Query endpoint

Express by CUIT/CUIL

Queries the Express score using a CUIT/CUIL as the main identifier.

Request

Method	Path	Description
GET	/v1/express	Returns the score for the queried CUIT/CUIL.

Headers

Header	Value	Req.	Description
Authorization	<token>	YES	Access token obtained from `/v1/oauth/token`.
client_id	<tu_client_id>	YES	Client identifier provided by Findo.
Content-Type	application/json	YES	Submitted content format.

Parameters

Name	Type	Req.	Description
legal_id	string	YES	CUIT or CUIL without hyphens or spaces. Ex: <cuit_or_cuil>
phone_number	string	NO	Phone number associated with the query. Ex: <phone_number>

200 OK Body

Field	Type	Description
request_id	string	Unique query identifier.
status	string	Query status. Possible values: `COMPLETED`.
findo_score	object	Result returned by the scoring engine for the queried CUIT/CUIL.
findo_score.request_id	string	Query identifier in the scoring engine.
findo_score.findo_score	number	Score returned by the service.
findo_score.estimated_income	number	Estimated income returned by the service.
findo_score.individual_data_report	object	Credit report with aggregated financial-history variables.
findo_score.positive_report	object	Positive variables associated with regular behavior.
findo_score.negative_report	object	Negative variables associated with delinquency or irregular behavior. It may be empty.

Query Example

cURL

BASE_URL="https://qa.api.score.findo.com.ar"

curl \
  "${BASE_URL}/v1/express?legal_id=<cuit_or_cuil>" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <token>' \
  --header 'client_id: <tu_client_id>'

200 OK Example

200 · JSON

{
  "request_id":  "97ed5055-100d-42ce-8356-544185aab784",
  "status":      "COMPLETED",
  "findo_score": {
    "request_id":       "6873536b-c0a5-4b25-b273-23aaaee0a380",
    "findo_score":      3,
    "estimated_income": 2.0,
    "individual_data_report": {
      "finantial_history_number_ent_1": 1.0,
      "finantial_history_number_ent_3": 1.0,
      "finantial_history_number_ent_6": 1.0,
      "finantial_history_number_ent_9": 1.0,
      "finantial_history_number_ent_12": 1.0,
      "finantial_history_number_ent_18": 1.0,
      "finantial_history_number_ent_24": 1.0,
      "finantial_history_amount_total_due_3": 0.0,
      "finantial_history_amount_total_due_6": 0.0,
      "finantial_history_amount_total_due_9": 0.0,
      "finantial_history_amount_total_due_12": 0.0,
      "finantial_history_amount_total_due_18": 4.0,
      "finantial_history_amount_total_due_24": 4.0,
      "finantial_history_variation_amount_total_due_between_3_1": null,
      "finantial_history_variation_amount_total_due_between_6_3": null,
      "finantial_history_variation_amount_total_due_between_9_6": null,
      "finantial_history_variation_amount_total_due_between_12_9": null,
      "finantial_history_variation_amount_total_due_between_18_12": -100.0,
      "finantial_history_variation_amount_total_due_between_24_18": 0.0
    },
    "positive_report": {
      "finantial_history_max_sit_1": 0.0,
      "finantial_history_max_sit_3": 0.0,
      "finantial_history_max_sit_6": 0.0,
      "finantial_history_max_sit_9": 0.0,
      "finantial_history_max_sit_12": 0.0
    },
    "negative_report": {
      "finantial_history_amount_sit345_18": 4.0,
      "finantial_history_amount_sit345_24": 4.0,
      "finantial_history_max_sit_18": 5.0,
      "finantial_history_max_sit_24": 5.0
    }
  }
}

The example preserves the variables from the response sample. Detailed semantics for each variable are documented in the report reference.

Query endpoint

Express by DNI

Queries the Express score using a DNI as the main identifier. If the DNI is associated with more than one CUIT/CUIL, the body will include more than one result.

Request

Method	Path	Description
GET	/v1/express/dni	Returns a list of results associated with the queried DNI.

Headers

Header	Value	Req.	Description
Authorization	<token>	YES	Access token obtained from `/v1/oauth/token`.
client_id	<tu_client_id>	YES	Client identifier provided by Findo.
Content-Type	application/json	YES	Submitted content format.

Parameters

Name	Type	Req.	Description
dni	string	YES	DNI without dots, hyphens, or spaces. Ex: <dni>

200 OK Body

Field	Type	Description
request_id	string	Unique identifier for the DNI query.
status	string	Overall DNI query status. Possible values: `COMPLETED`, `PARTIAL`, `FAILURE`. `PARTIAL` indicates that the DNI resolved to more than one CUIT/CUIL and at least one individual query failed.
dni	string	Queried DNI.
results	array	List of individual CUIT/CUIL queries associated with the DNI.
results[].legal_id	string	CUIT/CUIL used to execute the Express query.
results[].name	string	Name associated with the CUIT/CUIL.
results[].request_id	string	Unique identifier for the individual query.
results[].status	string	Individual query status. Possible values: `COMPLETED`, `FAILURE`.
results[].findo_score	object	Result returned by the scoring engine for that CUIT/CUIL. Present when the individual query ends in `COMPLETED`.
results[].findo_score.request_id	string	Query identifier in the scoring engine.
results[].findo_score.findo_score	number	Score returned for that CUIT/CUIL.
results[].findo_score.estimated_income	number	Estimated income returned for that CUIT/CUIL.
results[].findo_score.individual_data_report	object	Credit report with aggregated financial-history variables.
results[].findo_score.positive_report	object	Positive variables associated with regular behavior.
results[].findo_score.negative_report	object	Negative variables associated with delinquency or irregular behavior. It may be empty.
results[].error	object	Error detail. Present when the individual query ends in `FAILURE`.
results[].error.code	string	Individual query error code.
results[].error.description	string	Individual query error description.

status summarizes all individual query results: COMPLETED if all completed, PARTIAL if some completed and others failed, and FAILURE if none completed.

Query Example

cURL

BASE_URL="https://qa.api.score.findo.com.ar"

curl \
  "${BASE_URL}/v1/express/dni?dni=<dni>" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <token>' \
  --header 'client_id: <tu_client_id>'

200 OK Example

200 · JSON

{
  "request_id": "bd370a97-bf03-4dc2-b04b-6a8ed4bea04a",
  "status":     "COMPLETED",
  "dni":        "<redacted_dni>",
  "results": [
    {
      "legal_id":   "<cuit_or_cuil_1>",
      "name":       "<redacted_name_1>",
      "request_id": "7fd9896d-c88a-4d0a-8929-d54a1d149911",
      "status":     "COMPLETED",
      "findo_score": {
        "request_id":       "6873536b-c0a5-4b25-b273-23aaaee0a380",
        "findo_score":      3,
        "estimated_income": 2.0,
        "individual_data_report": {
          "finantial_history_number_ent_1": 1.0,
          "finantial_history_number_ent_3": 1.0,
          "finantial_history_number_ent_6": 1.0,
          "finantial_history_number_ent_9": 1.0,
          "finantial_history_number_ent_12": 1.0,
          "finantial_history_number_ent_18": 1.0,
          "finantial_history_number_ent_24": 1.0,
          "finantial_history_amount_total_due_3": 0.0,
          "finantial_history_amount_total_due_6": 0.0,
          "finantial_history_amount_total_due_9": 0.0,
          "finantial_history_amount_total_due_12": 0.0,
          "finantial_history_amount_total_due_18": 4.0,
          "finantial_history_amount_total_due_24": 4.0,
          "finantial_history_variation_amount_total_due_between_3_1": null,
          "finantial_history_variation_amount_total_due_between_6_3": null,
          "finantial_history_variation_amount_total_due_between_9_6": null,
          "finantial_history_variation_amount_total_due_between_12_9": null,
          "finantial_history_variation_amount_total_due_between_18_12": -100.0,
          "finantial_history_variation_amount_total_due_between_24_18": 0.0
        },
        "positive_report": {
          "finantial_history_max_sit_1": 0.0,
          "finantial_history_max_sit_3": 0.0,
          "finantial_history_max_sit_6": 0.0,
          "finantial_history_max_sit_9": 0.0,
          "finantial_history_max_sit_12": 0.0
        },
        "negative_report": {
          "finantial_history_amount_sit345_18": 4.0,
          "finantial_history_amount_sit345_24": 4.0,
          "finantial_history_max_sit_18": 5.0,
          "finantial_history_max_sit_24": 5.0
        }
      }
    },
    {
      "legal_id":   "<cuit_or_cuil_2>",
      "name":       "<redacted_name_2>",
      "request_id": "d2c003fa-1951-4a39-afd2-7f41bedeb716",
      "status":     "COMPLETED",
      "findo_score": {
        "request_id":       "6873536b-c0a5-4b25-b273-23aaaee0a380",
        "findo_score":      3,
        "estimated_income": 2.0,
        "individual_data_report": {
          "finantial_history_number_ent_1": 1.0,
          "finantial_history_number_ent_3": 1.0,
          "finantial_history_number_ent_6": 1.0,
          "finantial_history_number_ent_9": 1.0,
          "finantial_history_number_ent_12": 1.0,
          "finantial_history_number_ent_18": 1.0,
          "finantial_history_number_ent_24": 1.0,
          "finantial_history_amount_total_due_3": 0.0,
          "finantial_history_amount_total_due_6": 0.0,
          "finantial_history_amount_total_due_9": 0.0,
          "finantial_history_amount_total_due_12": 0.0,
          "finantial_history_amount_total_due_18": 4.0,
          "finantial_history_amount_total_due_24": 4.0,
          "finantial_history_variation_amount_total_due_between_3_1": null,
          "finantial_history_variation_amount_total_due_between_6_3": null,
          "finantial_history_variation_amount_total_due_between_9_6": null,
          "finantial_history_variation_amount_total_due_between_12_9": null,
          "finantial_history_variation_amount_total_due_between_18_12": -100.0,
          "finantial_history_variation_amount_total_due_between_24_18": 0.0
        },
        "positive_report": {
          "finantial_history_max_sit_1": 0.0,
          "finantial_history_max_sit_3": 0.0,
          "finantial_history_max_sit_6": 0.0,
          "finantial_history_max_sit_9": 0.0,
          "finantial_history_max_sit_12": 0.0
        },
        "negative_report": {
          "finantial_history_amount_sit345_18": 4.0,
          "finantial_history_amount_sit345_24": 4.0,
          "finantial_history_max_sit_18": 5.0,
          "finantial_history_max_sit_24": 5.0
        }
      }
    }
  ]
}

In each results, findo_score keeps the same object format as the CUIT/CUIL endpoint.

Statuses and Errors

The HTTP status indicates the protocol-level result. When the endpoint returns a body with status: FAILURE, the error.code field identifies the functional case.

In /v1/express/dni, the top-level status summarizes the DNI query. Each results item has its own status because it represents an individual Express query.

HTTP Statuses

Status	Meaning	Detail
200	Query processed.	Successful bodies are documented in each endpoint. For DNI queries, also check the `status` field.
400	Invalid request.	Missing or invalid parameters, missing/invalid `client_id`, or invalid client configuration.
401	Unauthenticated.	Missing token or token not sent in the `Authorization`.
403	Not authorized.	Invalid, expired, or unauthorized token for the query.
404	Route not found.	The requested path does not exist for the API version used.
500	Internal error.	Internal failure. Retry later or contact support if it persists.

Error Body

When a query returns a structured error, the body has this format.

Field	Type	Description
request_id	string	Unique query identifier.
status	string	Error status. Possible value: `FAILURE`.
error	object	Error detail.
error.code	string	Error code.
error.description	string	Error description.

Error Example

400 · JSON

{
  "request_id": "97ed5055-100d-42ce-8356-544185aab784",
  "status":     "FAILURE",
  "error": {
    "code":        "E02",
    "description": "legal_id invalid"
  }
}

The following tables list actionable integration errors. For a 500, keep the request_id for follow-up.

Express CUIT/CUIL Errors

HTTP	Code	Case
400	E01	`client_id` required or invalid.
400	E02	`legal_id` invalid.
400	E03	`legal_id` required.
400	E04	Duplicate query.
500	-	Internal failure.

Express DNI Errors

HTTP	Code	Case
400	E01	`client_id` required.
400	E02	`dni` invalid.
400	E03	`dni` required.
500	-	Internal failure.
200	results[].error	Failure in an individual CUIT/CUIL query. The error is reported inside the corresponding `results`.

Quick Start

Integrate in minutes

This Python script covers the full flow: it obtains the access token with your credentials and queries the Express score by CUIT/CUIL or DNI. You can use it as a starting point for your integration.

Requirements

Requirement	Detail
Python	3.8 o superior
requests	`pip install requests`
FINDO_CLIENT_ID	Environment variable with your Client ID
FINDO_CLIENT_SECRET	Environment variable with your Client Secret. Never hardcode it.

Environment variables

bash

export FINDO_BASE_URL="https://qa.api.score.findo.com.ar"
export FINDO_CLIENT_ID="tu_client_id"
export FINDO_CLIENT_SECRET="tu_client_secret"

example.py

Python

import os
import sys
import requests

BASE_URL      = os.getenv("FINDO_BASE_URL", "https://qa.api.score.findo.com.ar")
CLIENT_ID     = os.getenv("FINDO_CLIENT_ID")
CLIENT_SECRET = os.getenv("FINDO_CLIENT_SECRET")


def validate_cuil(cuil):
    if not cuil.isdigit() or len(cuil) not in (10, 11):
        raise SystemExit("Invalid CUIL. Use digits only and a length of 10 or 11.")


def validate_dni(dni):
    if not dni.isdigit() or len(dni) not in (7, 8):
        raise SystemExit("Invalid DNI. Use digits only and a length of 7 or 8.")


def get_access_token():
    if not CLIENT_ID or not CLIENT_SECRET:
        raise SystemExit("Missing env vars: FINDO_CLIENT_ID and FINDO_CLIENT_SECRET")

    response = requests.post(
        f"{BASE_URL}/v1/oauth/token",
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        data={"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET},
    )
    response.raise_for_status()

    access_token = response.json().get("access_token")
    if not access_token:
        raise SystemExit("No access_token in response")

    return access_token


def build_headers(access_token):
    return {
        "Content-Type":  "application/json",
        "Authorization": access_token,
        "client_id":     CLIENT_ID,
    }


def get_express_score_by_cuil(access_token, cuil, phone_number=None):
    params = {"legal_id": cuil}
    if phone_number:
        params["phone_number"] = phone_number

    return requests.get(
        f"{BASE_URL}/v1/express", headers=build_headers(access_token), params=params
    )


def get_express_score_by_dni(access_token, dni):
    return requests.get(
        f"{BASE_URL}/v1/express/dni",
        headers=build_headers(access_token),
        params={"dni": dni},
    )


if __name__ == "__main__":
    if len(sys.argv) < 3:
        raise SystemExit("Usage: python example.py cuil <cuil> [phone_number] | python example.py dni <dni>")

    mode  = sys.argv[1]
    value = sys.argv[2]
    token = get_access_token()

    if mode == "cuil":
        validate_cuil(value)
        phone_number = sys.argv[3] if len(sys.argv) > 3 else None
        response = get_express_score_by_cuil(token, value, phone_number)
    elif mode == "dni":
        validate_dni(value)
        response = get_express_score_by_dni(token, value)
    else:
        raise SystemExit("Invalid mode. Use 'cuil' or 'dni'.")

    print("Status:", response.status_code)
    print("Body:", response.text)
    response.raise_for_status()

Execution

bash

# CUIL only
python example.py cuil <cuit_or_cuil>

# With CUIL and phone (optional)
python example.py cuil <cuit_or_cuil> <phone_number>

# By DNI
python example.py dni <dni>