Prospecting: new companies and segments

Endpoints for sales teams: commercial data and score of a company, the radar of newly incorporated companies and company segments by activity, province and size.

Base URL: https://spaincompanyapi.com/api/v1 · API key in the X-API-KEY header · Get a free API key (100 requests, no card) · Full documentation

5. Commercial Capabilities (Pro & Business)

Power your prospecting with enriched data and real-time business signals.

GET /companies/score Pro

Commercial score from 0 to 100 for a company: its recent BORME activity, how complete its record is and whether it has a phone, email or website. It does not measure solvency (use /companies/risk-profile for that). On Free it returns the number only, without using requests (within the cap of 25 previews a day); priority, reasons and last_signal come back locked.

{
  "success": true,
  "data": {
    "cif": "B12345678",
    "score": 82,
    "priority": "muy_alta",
    "reasons": ["OPP:95|QUAL:80|CONT:60 · Ampliación de capital"],
    "last_signal": { "type": "Ampliación de capital", "date": "2026-09-15", "url_pdf": "https://www.boe.es/borme/dias/2026/09/15/pdfs/BORME-A-2026-176-15.pdf" },
    "source": "radar"
  }
}
FieldTypeDescription
data.scoreintegerCommercial score from 0 to 100.
data.priorityenumProspecting priority from the score: muy_alta (75 or more), alta (60), media (40), baja (20) or muy_baja.
data.reasonsarrayList of reasons behind the score.
data.last_signalobjectLatest BORME act that counts towards the score: type, date and url_pdf (official BORME PDF for that day; null if not recorded).
GET /companies/signals Pro

The latest BORME act that counts towards the company's commercial score. The list has one item at most. Free plan: 403 PLAN_RESTRICTION with the number of events in upsell_opportunities.eventos_ocultos.

{
  "success": true,
  "data": {
    "cif": "A46103834",
    "signals": [
      {
        "type": "borme_event",
        "label": "Ampliación de capital",
        "date": "2026-09-15",
        "probability": "muy_alta",
        "url_pdf": "https://www.boe.es/borme/dias/2026/09/15/pdfs/BORME-A-2026-176-15.pdf"
      }
    ]
  }
}
FieldTypeDescription
signals[]array[object]One item at most: type (always borme_event), label (type of act) and date.
signals[].probabilitystringThe company's commercial priority, the same as priority on /companies/score: muy_alta, alta, media, baja or muy_baja. It is not the reliability of the event.
signals[].url_pdfstring | nullOfficial BORME PDF for the day of the signal (null if not recorded).
GET /companies/insights Business

AI-powered analysis of the commercial profile and probable needs of a company. On Pro (or Free with credits) there is a preview that does not use requests, within the cap of 25 a day: only profile and conversion_probability; pain_points, buyer_persona and sales_arguments come back locked, with message and checkout_url. Free plan: 403 PLAN_RESTRICTION.

{
  "success": true,
  "data": {
    "profile": "Servicios de Tecnología",
    "summary": "Empresa enfocada en desarrollo software...",
    "needs": ["Presencia Web", "Gestión Cloud"],
    "conversion_probability": "Alta",
    "estimated_ticket": "Medio-Alto"
  }
}
FieldTypeDescription
needs[]array[string]List of software needs detected through AI inference.
conversion_probabilitystringEstimated B2B cross-selling probability.
GET /companies/contact-prep Business

AI-generated sales pitch and objection handling for a target company.

{
  "success": true,
  "data": {
    "sales_approach": "Consultative and direct approach...",
    "suggested_message": "Hi, I noticed the recent growth of...",
    "likely_objection": "Temporary budget constraints",
    "attack_angle": "Demonstrate immediate ROI..."
  }
}
FieldTypeDescription
sales_approachstringSuggested commercial outreach strategy.
likely_objectionstringMost likely objection from the prospect.
GET /companies/network Pro

Gets the corporate network linking companies through their directors. Requires the cif parameter. Pro, Business and Free with credits; on Free without credits, 403 PLAN_RESTRICTION with the counts in data.stats. If the company has no known directors, it returns 200 with only the company node, no stats and a message (charged like any other request).

{
  "success": true,
  "data": {
    "nodes": [
      { "id": "C_123", "type": "company", "label": "EMPRESA DE EJEMPLO SL", "cif": "B12345678", "root": true },
      { "id": "A_abc", "type": "administrator", "label": "JUAN PEREZ GARCIA" }
    ],
    "edges": [
      { "source": "A_abc", "target": "C_123", "label": "Administrador" }
    ],
    "stats": {
      "total_administrators": 1,
      "total_linked_companies": 1
    }
  }
}
FieldTypeDescription
nodes[]array[object]Graph nodes (companies or directors).
edges[]array[object]Connections (links) between nodes.
GET /companies/match Business

B2B Match calculator. Requires cif and seller_sector parameters. Returns the commercial fit level and a personalised sales argument.

{
  "success": true,
  "data": {
    "match_score": 85,
    "fit_level": "Alto",
    "pain_points_addressed": ["Ineficiencia operativa", "Falta de digitalización"],
    "sales_argument": "Our software eliminates manual work...",
    "recommendation": "Contact immediately."
  }
}
FieldTypeDescription
match_scoreintegerB2B fit level (0–100).
sales_argumentstringSales argument tailored to the match.
POST /companies/batch Pro Business

Query up to 100 companies in a single request by sending an array of CIFs. The cost is variable: 1 credit from your monthly quota or wallet per company found (HTTP 200). If you don't have enough credits to cover the entire batch, the response will be automatically trimmed to the number of companies you can afford. Pro or Business plan only: Free with credits gets 403.

Request Body (JSON)
{
  "cifs": ["B12345678", "A87654321", "B00000000"],
  "admin": true
}
Success response
{
  "success": true,
  "data": [
    { "cif": "B12345678", "name": "EMPRESA DE EJEMPLO SL", "status": "ACTIVA" },
    { "cif": "A87654321", "name": "OTRA EMPRESA SA", "status": "ACTIVA" }
  ],
  "meta": {
    "requested": 3,
    "found": 2,
    "cost": 2,
    "truncated": false
  }
}
FieldTypeDescription
meta.requestedintegerNumber of CIFs sent in the request.
meta.costintegerCredits deducted from your plan for companies found.

7. Company Radar

Companies incorporated in the period you ask for (today by default), sorted by commercial score, highest first.

  • Free: 10 results with name and CIF hidden. Uses 1 request.
  • Pro and Free with credits: up to 100 results. Business: up to 1,000.
  • If there are more companies than fit, meta.oportunidades_ocultas says how many are missing.
  • All filters work on every plan.
GET /companies/radar Pro

Optional parameters

Field Description
province Filter by Spanish province (e.g. MADRID).
range Time window. Accepts hoy (today, the default) or an integer for days back (e.g. 7, 30).
priority Commercial priority: muy_alta, alta, media, baja or muy_baja (very high to very low).
cnae One or more comma-separated CNAE prefixes (e.g. 62 or 4711,4719).
min_score Minimum opportunity score, 0 to 100.
main_act_type Type of the latest relevant BORME act (e.g. Constitución, Ampliación de capital).
has_phone With true, only companies with a phone number.

Success response (200 OK)

{
  "success": true,
  "meta": {
    "plan": "business",
    "count": 50,
    "limit": 1000,
    "total_disponibles": 50
  },
  "data": [
    {
      "id": 4812345,
      "company_name": "NUEVA EMPRESA SL",
      "cif": "B12345678",
      "fecha_constitucion": "2026-10-13",
      "cnae": "6201",
      "cnae_label": "Actividades de programación informática",
      "registro_mercantil": "MADRID",
      "municipality": "MADRID",
      "score_total": 78,
      "priority_level": "alta",
      "main_act_type": "Constitución"
    }
  ]
}
FieldTypeDescription
data[].fecha_constitucionstringDate the company was incorporated.
data[].score_totalinteger | nullCommercial score (0-100). With priority_level and main_act_type, the latest relevant BORME act.
meta.planstringYour current plan.
meta.total_disponiblesintegerTotal companies in the Radar. If your plan is capped at limit, you'll see the real total here.

7.2 Company Segments

Filter companies by activity, area, size and other criteria. Counting is free on every plan (count_only=true): you see how many companies match before paying anything. Downloading the rows is a Business feature and costs 5 requests per returned row.

GET /companies/filter Business
ParameterDescription
cnaeComma-separated CNAE prefixes (e.g. 62 or 4711,4719).
provinceMercantile Registry province (e.g. MADRID).
municipalityMunicipality (e.g. GETAFE).
statusactive (default: active in the Registry), active_or_unknown (also those with no registered status) or any.
founded_from / founded_toIncorporation date, YYYY-MM-DD.
has_phoneWith true, only companies with a phone number. The number is not returned.
size_bandComma-separated revenue bands: NO_REVENUE, LT_500K, 500K_1M, GT_1M.
size_categoryHeadcount size, comma-separated: micro (under 10 employees), small (10-49), medium (50-249) or large (250 or more, or a large company according to its contract awards). Only returns companies with this data (Kit Digital, Kit Consulting, TED or PLACSP); it is never estimated. Each row includes the size block.
min_accounts_yearLatest filed accounts year equal or later (e.g. 2023).
count_onlyWith true, only the count. Free.
limit / cursorRows per page (1-1000, default 100) and meta.next_cursor from the previous page.

At least one of cnae, province or municipality is required.

Count only (all plans, free)

// GET /companies/filter?cnae=62&province=MADRID&has_phone=true&count_only=true
{
  "success": true,
  "data": { "total": 3412 },
  "meta": {
    "filters": { "cnae": ["62"], "province": "MADRID", "status": "active", "has_phone": true },
    "cost": 0,
    "counted_at": "2026-09-29T09:30:00+02:00"
  }
}

Rows (Business)

// GET /companies/filter?cnae=62&province=MADRID&has_phone=true&limit=100
{
  "success": true,
  "data": [
    {
      "cif": "B12345678",
      "name": "EMPRESA DE EJEMPLO SL",
      "cnae": "6201",
      "cnae_label": "Actividades de programación informática",
      "province": "MADRID",
      "municipality": "MADRID",
      "founded": "2019-03-01",
      "status": "ACTIVA",
      "status_code": "ACTIVE",
      "status_source": "registry",
      "financials": { "size_band": "GT_1M", "size_band_label": "Más de 1 M€", "last_accounts_year": 2023 },
      "size": { "employees_min": 10, "employees_max": 49, "label": "De 10 a 49 empleados", "category": "small", "source": "kit_digital", "as_of": "2024-05-14" },
      "has_phone": true
    }
  ],
  "meta": {
    "total": 3412,
    "returned": 100,
    "limit": 100,
    "has_more": true,
    "next_cursor": "eyJpZCI6ODgxMjM0NX0",
    "cost": 500,
    "cost_per_row": 5,
    "truncated": false,
    "filters": { "cnae": ["62"], "province": "MADRID", "status": "active", "has_phone": true }
  }
}
  • Only returned rows are charged: meta.cost = rows × 5. If your quota is not enough, the page is cut (truncated: true) to the rows you can pay for.
  • For the next page, pass meta.next_cursor as cursor with the same filters.
  • Counts are cached for 6 hours: repeating the same search is not recalculated.
  • Without a Business plan, asking for rows returns 403 PLAN_RESTRICTION with the count in upsell_opportunities.total.
  • Phone numbers and emails are never returned: only has_phone.

🚀 Ready to get started?

Get your API Key in seconds and start integrating real data into your applications.

Go to Control Panel
🤖
Asistente IA En línea
¡Hola! Soy el asistente de APIEmpresas. ¿En qué puedo ayudarte hoy?