Data Source Runs Guide

This guide explains how Data Source Runs work in the V2 API, including the paginatable records pattern for handling large datasets.

Overview

What is a DataSourceRun?

A DataSourceRun represents a single execution of a data source check against an entity. Each run:

• Belongs to an EntityValidation
• Has a specific data source type (e.g., cl/tax_situation_search, cl/bulletins_search)
• Transitions through a status lifecycle
• Contains the retrieved data when successful

Status Lifecycle

Status	Description
created	Run has been created, not yet started or still processing
succeeded	Run completed successfully with data
temporary_error	Run failed but may be retried
definitive_error	Run failed permanently (e.g., invalid TIN)
missing_input_data	Run is paused waiting for required inputs

API Endpoints

Show Data Source Run

Retrieves a data source run with its full data payload.

txt

GET /api/v2/data_source_runs/:id

Response:

JSON

{
  "data_source_run": {
    "id": "dsr_5a6141dec2bc384e",
    "type": "cl/tax_situation_search",
    "entity_validation_id": "evl_abc123",
    "data_source_run_batch_id": "dsrb_xyz789",
    "created_at": "2024-01-15T19:48:18.056Z",
    "succeeded_at": "2024-01-15T19:48:20.056Z",
    "status": "succeeded",
    "data": {
      "id": "tss_6d6a705304d3b568",
      "has_activity_initiation": true,
      "activity_initiation_date": "2018-12-06",
      "business_name": "EMPRESA EJEMPLO SPA",
      "..."
    }
  }
}

Get Paginated Records

Retrieves paginated records from a data source that uses the paginatable data pattern.

txt

GET /api/v2/data_source_runs/:data_source_run_id/records

Query Parameters:

Parameter	Required	Description
page	No	Page number (default: 1)
per_page	No	Items per page (max/default: 50)
type	Conditional	Record type for multi-array data sources

Response Headers:

Header	Description
X-Total	Total number of items
X-Page	Current page number
X-Per-Page	Items per page
Link	Pagination links (first, last, next, prev)

Response Structure

Data Source Run Schema

All data source runs share these common fields:

JSON

{
  "id": "dsr_...",
  "type": "cl/tax_situation_search",
  "entity_validation_id": "evl_...",
  "data_source_run_batch_id": "dsrb_...",
  "created_at": "2024-01-15T19:48:18.056Z",
  "succeeded_at": "2024-01-15T19:48:20.056Z",
  "status": "succeeded",
  "data": { ... }
}

The data field structure varies by data source type. See Data Source Types Reference below.

Paginatable Data Pattern

Why Pagination?

Some data sources can return hundreds or thousands of records (e.g., legal cases, debt bulletins, labor fines). Instead of embedding all records in the response:

• Records are counted and a URL is provided
• Clients fetch records on-demand via the /records endpoint
• This keeps responses fast and manageable

How It Works

Data sources with large datasets return a pagination object instead of the full array:

JSON

{
  "data": {
    "id": "lcs_abc123",
    "legal_cases": {
      "count": 150,
      "records_url": "/api/v2/data_source_runs/dsr_xyz/records"
    }
  }
}

The records_url points to the records endpoint where you can fetch the actual items with pagination.

Single vs Multi-Array Data Sources

Single-array data sources have one paginatable collection:

JSON

{
  "legal_cases": {
    "count": 150,
    "records_url": "/api/v2/data_source_runs/dsr_123/records"
  }
}

Multi-array data sources have multiple collections requiring the type parameter:

JSON

{
  "vehicles": {
    "count": 5,
    "records_url": "/api/v2/data_source_runs/dsr_123/records?type=vehicles"
  },
  "real_estate_assets": {
    "count": 3,
    "records_url": "/api/v2/data_source_runs/dsr_123/records?type=real_estate_assets"
  }
}

Data Source Types Reference

Simple Data Sources (Embedded Data)

These data sources return all data inline without pagination:

Type	Description
cl/tax_situation_search	Chilean tax status from SII
cl/ndf_situation_search	NDF (difficult to audit) status
cl/nonprofit_status_search	Nonprofit organization status
cl/public_market_situation_search	MercadoPublico registration
cl/cmf_debts_search	CMF monthly debt history
mx/rfc_information_search	Mexican RFC information

Single Paginatable Data Sources

These have one collection of records:

Type	Collection	Record Schema
cl/bankruptcy_bulletins_search	bankruptcy_bulletins	Bulletin item
cl/labor_fines_search	labor_fines_search_results	Labor fine item
cl/business_legal_cases_search	legal_cases	Legal case item
cl/person_legal_cases_search	legal_cases	Legal case item
cl/snifa_sanctions_search	sanctions	SNIFA sanction item
cl/relations_search	relations	Relation item
cl/sernageomin_fines_search	sernageomin_fines_search_results	Sernageomin fine item
cl/social_security_debts_search	social_security_debt_search_results	Social security debt item
cl/public_market_contracts_search	public_market_contracts_search_results	Contract item

Multi-Type Paginatable Data Sources

These have multiple collections requiring the type parameter:

Type	Collections
cl/bulletins_search	commercial_bulletins, financial_bulletins, labor_bulletins, cobranzaonline_bulletins
cl/general_bulletins_search	commercial_bulletins, financial_bulletins, labor_bulletins
cl/assets_search	vehicles, real_estate_assets, residences
cl/equifax_business_data_search	commercial_bulletins, financial_bulletins, labor_bulletins, dicom_bulletins, bankruptcy_bulletins
cl/equifax_person_data_search	commercial_bulletins, financial_bulletins, labor_bulletins, dicom_bulletins

Example Flows

Fetching a Simple Data Source

Bash

# Get the data source run with embedded data
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_abc123"

Response includes all data inline:

JSON

{
  "data_source_run": {
    "id": "dsr_abc123",
    "type": "cl/tax_situation_search",
    "status": "succeeded",
    "data": {
      "id": "tss_xyz",
      "has_activity_initiation": true,
      "business_name": "EMPRESA SPA",
      "direct_employees": 15,
      "activity_registrations": [...]
    }
  }
}

Fetching All Records from a Paginatable Source

Step 1: Get the data source run

Bash

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_def456"

Response shows count and records_url:

JSON

{
  "data_source_run": {
    "id": "dsr_def456",
    "type": "cl/business_legal_cases_search",
    "status": "succeeded",
    "data": {
      "id": "lcs_xyz",
      "legal_cases": {
        "count": 75,
        "records_url": "/api/v2/data_source_runs/dsr_def456/records"
      }
    }
  }
}

Step 2: Fetch records page by page

Bash

# First page (default)
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_def456/records"

# Second page
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_def456/records?page=2"

Response:

JSON

{
  "records": [
    {
      "id": "lc_001",
      "case_type": "OJV - Causas Civiles",
      "date": "2022-03-29",
      "label": "Company A S.A./Company B SPA",
      "legal_id": "C-9374-2021",
      "court": "Corte de Apelaciones"
    },
    { "..." }
  ]
}

Check response headers for pagination info:

X-Total: 75
X-Page: 1
X-Per-Page: 50
Link: <...?page=2>; rel="next", <...?page=2>; rel="last"

Fetching from Multi-Array Data Source

Step 1: Get the data source run

Bash

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_ghi789"

Response shows multiple collections:

JSON

{
  "data_source_run": {
    "id": "dsr_ghi789",
    "type": "cl/assets_search",
    "status": "succeeded",
    "data": {
      "id": "das_xyz",
      "vehicles": {
        "count": 3,
        "records_url": "/api/v2/data_source_runs/dsr_ghi789/records?type=vehicles"
      },
      "real_estate_assets": {
        "count": 2,
        "records_url": "/api/v2/data_source_runs/dsr_ghi789/records?type=real_estate_assets"
      }
    }
  }
}

Step 2: Fetch each collection using the type parameter

Bash

# Get vehicles
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_ghi789/records?type=vehicles"

# Get real estate
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.plutto.cl/api/v2/data_source_runs/dsr_ghi789/records?type=real_estate_assets"

Record Schemas

Bulletin Item

JSON

{
  "id": "bul_123",
  "bulletin_type": "commercial",
  "issuer_or_creditor": "Banco de Chile",
  "date": "2019-01-01",
  "payment_date": "2019-01-15",
  "description": "Deuda de 1000 UF",
  "amount": "1000",
  "debtor": "Juan Perez"
}

Legal Case Item

JSON

{
  "id": "lc_123",
  "case_type": "OJV - Causas Civiles",
  "date": "2022-03-29",
  "last_update_date": "2022-05-15",
  "label": "Company A S.A./Company B SPA",
  "legal_id": "C-9374-2021",
  "court": "Corte de Apelaciones",
  "legal_stance": "against"
}

Vehicle Item

JSON

{
  "id": "cvh_123",
  "brand": "TOYOTA",
  "model": "HILUX",
  "year": "2020",
  "vehicle_type": "CAMIONETA",
  "license_plate": "ABCD12",
  "value": "15000000"
}

Real Estate Asset Item

JSON

{
  "id": "cra_123",
  "address": "Av. Principal 123",
  "location": "Santiago, Providencia",
  "value": "50000000",
  "role": "00631-000XX"
}

Labor Fine Item

JSON

{
  "id": "lfe_123",
  "origin": "FISCALIZACION",
  "fine_id": "XXXX/22/033-2",
  "status": "PAGADA",
  "execution_date": "2024-01-01",
  "amount": "40,00",
  "currency": "UTM",
  "description": "Multa por incumplimiento"
}

Relation Item

JSON

{
  "id": "dr_123",
  "tin": "16224182-6",
  "name": "Victor David",
  "surname": "Mendoza Guerra",
  "entity_name": "Victor David Mendoza Guerra",
  "entity_category": "person",
  "relations": ["shareholder", "director"]
}