French Business Registry Lookup (SIREN / SIRET / Company Name)

{
  "type": "object",
  "required": [
    "siren"
  ],
  "properties": {
    "siren": {
      "type": "string",
      "description": "SIREN (9 digits), SIRET (14 digits), or company name"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "city": {
      "type": [
        "string",
        "null"
      ]
    },
    "siren": {
      "type": "string",
      "description": "The 9-digit SIREN, echoed back or resolved from the input."
    },
    "siret": {
      "type": [
        "string",
        "null"
      ],
      "description": "14-digit SIRET of the company's registered headquarters. Null when not found."
    },
    "status": {
      "type": "string",
      "description": "'active' on a real, matched company; observed as the literal string 'unknown' on a non-matching SIREN. Not a reliable found/not-found signal by itself -- check `company_name` for that."
    },
    "address": {
      "type": [
        "string",
        "null"
      ],
      "description": "Full postal address, single string."
    },
    "directors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Officer names with their role in parentheses, e.g. 'ALEXANDRE BOMPARD (Président du conseil d'administration et directeur général)'. Observed as a single empty string on a non-matching SIREN, not a genuine officer list -- check `company_name` before trusting this field."
    },
    "legal_form": {
      "type": "string",
      "description": "Coded legal form. Not present on a non-matching SIREN."
    },
    "legal_name": {
      "type": "string",
      "description": "The company's registered legal name. Not present on a non-matching SIREN."
    },
    "vat_number": {
      "type": "string",
      "description": "Intra-community VAT number, derived from the SIREN. Observed present even on a non-matching SIREN as a mechanically-derived, not-meaningful value -- do not treat its presence as confirmation the company exists."
    },
    "postal_code": {
      "type": [
        "string",
        "null"
      ]
    },
    "company_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Observed null when the SIREN does not match any registered company -- treat null here as the not-found signal, regardless of what other fields contain."
    },
    "activity_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "French APE/NAF activity classification code, e.g. '64.20Z'."
    },
    "business_type": {
      "type": [
        "string",
        "null"
      ]
    },
    "creation_date": {
      "type": "string",
      "description": "Company incorporation date, YYYY-MM-DD. Observed present even on a non-matching SIREN with a plausible-looking but not-meaningful value -- do not treat this field's mere presence as confirmation the company exists; check `company_name` first."
    },
    "employee_range": {
      "type": [
        "string",
        "null"
      ],
      "description": "Coded employee headcount bracket."
    },
    "total_directors": {
      "type": "number",
      "description": "Count backing `directors`/`legal_representatives`. Observed as 1 on a non-matching SIREN (matching the single placeholder empty-string entry), not a real officer count."
    },
    "tier_2_available": {
      "type": "boolean",
      "description": "Whether the extended officer/legal-representative data below was available."
    },
    "ubo_availability": {
      "type": "string",
      "description": "Typically 'restricted' -- beneficial-owner (UBO) data access is restricted at the source under EU law regardless of whether the company is found."
    },
    "registered_address": {
      "type": "string",
      "description": "The registered-office address. Not present on a non-matching SIREN."
    },
    "directors_truncated": {
      "type": "boolean",
      "description": "True if the full officer list exceeds what this response includes."
    },
    "legal_representatives": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Typically the same content as `directors`. Observed as a single empty string on a non-matching SIREN -- check `company_name` before trusting this field."
    },
    "tier_2_available_reason": {
      "type": "string",
      "description": "Human-readable note on where the extended officer data was sourced from."
    },
    "ubo_availability_reason": {
      "type": "string",
      "description": "Human-readable note on why beneficial-owner data is restricted."
    }
  },
  "description": "The company record. A `company_name` of null is the authoritative not-found signal -- see the fields below flagged as unreliable in that case.",
  "additionalProperties": true
}