> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt > Use this file to discover all available pages before exploring further. # Supersociedades Shareholders > Shareholders or partners a Colombian company declared in the notes of its annual financial statements filed with the Superintendencia de Sociedades, by NIT: each holder's name, identity document, shares and percentage, plus the foreign investors, subsidiaries, associates and officers (legal representatives, accountant, revisor fiscal) declared in the same filing. Latest fiscal year by default, or a given year. Only companies that file with the Superintendencia (about 30,000 a year) are covered. ## OpenAPI ````yaml /api-reference/openapi.json post /co/supersociedades/shareholders/v1 openapi: 3.1.0 info: title: Croma Marketplace API version: 1.0.0 description: >- Government-data APIs for Colombia, Peru, Mexico, and global web search. Croma normalizes public-sector data into structured JSON for product teams and AI agents. Every operation is a POST with a JSON body and an organization API key as a bearer token; every operation is an idempotent lookup and accepts an optional `Idempotency-Key` header. Paths carry their major version (`/v1`); the versioning and deprecation policy, including the `Deprecation` and `Sunset` headers a retiring endpoint sends, is at https://docs.usecroma.com/versioning. Rate limits are per organization and reported on every response (`RateLimit-Policy`, `X-RateLimit-*`): https://docs.usecroma.com/rate-limits. termsOfService: https://usecroma.com/en/terms contact: name: Croma support url: https://usecroma.com/en/support email: tomas@usecroma.com servers: - url: https://api.croma.run security: [] paths: /co/supersociedades/shareholders/v1: post: tags: - Colombia - Supersociedades summary: Supersociedades Shareholders description: >- Shareholders or partners a Colombian company declared in the notes of its annual financial statements filed with the Superintendencia de Sociedades, by NIT: each holder's name, identity document, shares and percentage, plus the foreign investors, subsidiaries, associates and officers (legal representatives, accountant, revisor fiscal) declared in the same filing. Latest fiscal year by default, or a given year. Only companies that file with the Superintendencia (about 30,000 a year) are covered. operationId: supersociedades_shareholders parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - document_number properties: document_number: type: string minLength: 4 maxLength: 15 pattern: ^\d{4,15}$ description: Colombian NIT (numeric, no verification digit). 4-15 digits. year: type: integer minimum: 0 maximum: 2100 default: 0 description: >- Optional fiscal year of the filing to read (2016 or later). 0 reads the latest filing. additionalProperties: false example: document_number: '900249127' responses: '200': description: Successful response headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Cache: $ref: '#/components/headers/X-Cache' content: application/json: schema: $ref: '#/components/schemas/SupersociedadesShareholdersResponse' '400': description: Invalid request body headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Missing or invalid API key headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Rate limit exceeded headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal error headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '502': description: Upstream source returned an error headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] externalDocs: description: Interactive documentation and examples url: https://docs.usecroma.com/guides/colombia/supersociedades components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-chosen key for this request (any string up to 255 characters, e.g. a UUID). Every Croma operation is an idempotent lookup: repeating a request with the same body returns the same result and creates nothing, so retrying after a timeout or network failure is always safe. The key is echoed back in the `Idempotency-Key` response header so you can correlate a retry with its first attempt. Each attempt that reaches the API counts against the rate limit. schema: type: string maxLength: 255 example: 0f8e9a42-6b7c-4d1e-9a3f-2c5d7e8f9a0b headers: X-Request-Id: description: Unique id for the request (req_…). Include it in support reports. schema: type: string RateLimit-Policy: description: >- Quota policy for this endpoint as an IETF RateLimit-Policy structured field, e.g. `"default";q=100;w=86400` (100 requests per 86400-second window per organization). Endpoints with an extra hourly ceiling list both policies, e.g. `"webSearch";q=10;w=3600, "default";q=100;w=86400`. Present on every response, including 401 and 429. schema: type: string example: '"default";q=100;w=86400' Idempotency-Key: description: >- The `Idempotency-Key` the request carried, echoed back unchanged. Absent when the request sent none. schema: type: string Deprecation: description: >- Present only on an endpoint version scheduled for removal: the date the deprecation took effect (RFC 9745). A `Sunset` header and a `Link` with `rel="successor-version"` accompany it. Policy: https://docs.usecroma.com/versioning schema: type: string example: '@1767225600' Sunset: description: >- Present only on an endpoint version scheduled for removal: the date after which it answers 410 (RFC 8594). Announced in the changelog at least 90 days ahead. schema: type: string format: date-time example: Wed, 01 Apr 2026 00:00:00 GMT X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left before you are throttled. schema: type: integer X-RateLimit-Reset: description: ISO 8601 timestamp when the window resets. schema: type: string format: date-time X-Cache: description: >- HIT or MISS. Cached hits spend no credits, but still count toward an hourly ceiling. schema: type: string enum: - HIT - MISS Retry-After: description: Seconds to wait before retrying. schema: type: integer schemas: SupersociedadesShareholdersResponse: type: object required: - data properties: data: $ref: '#/components/schemas/SupersociedadesShareholdersData' ApiError: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string description: >- Broad category: invalid_request_error, authentication_error, not_found_error, rate_limit_error, upstream_error, api_error. code: type: string description: Machine-readable specific code. message: type: string description: Human-readable explanation, safe to surface in UI. param: type: string description: Field that triggered the error. Present on validation errors. details: type: object description: Free-form structured detail. SupersociedadesShareholdersData: type: object properties: found: type: boolean description: False when the NIT has no filing with these notes. document_number: type: string description: Echoes the request's `document_number` (NIT, no check digit). company: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' required: - name - type: 'null' filing: anyOf: - type: object properties: year: type: number description: Fiscal year of the filing. cutoff_date: type: string description: Fiscal-year cutoff (yyyy-mm-dd). filing_id: anyOf: - type: string - type: 'null' description: Filing number (radicado). statement_type: anyOf: - type: string enum: - individual - separado - consolidado - combinado - type: 'null' niif_group: anyOf: - type: string enum: - plenas - pymes - type: 'null' required: - year - cutoff_date - filing_id - statement_type - niif_group - type: 'null' shareholders: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' description: Name as declared. document_type: anyOf: - type: string - type: 'null' description: >- Identity document type as declared, e.g. "CEDULA DE CIUDADANIA", "NIT", "CEDULA DE EXTRANJERIA", "PASAPORTE". document_number: anyOf: - type: string - type: 'null' description: Identity document number or NIT as declared. country: anyOf: - type: string - type: 'null' description: Country as declared, e.g. "169 - COLOMBIA". shares: anyOf: - type: number - type: 'null' description: Shares or cuotas held, as declared. participation_pct: anyOf: - type: number - type: 'null' description: Share of the capital, in percent, as declared. required: - name - document_type - document_number - country - shares - participation_pct description: Shareholders or partners as declared in the filing's notes. foreign_investors: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' description: Name as declared. document_type: anyOf: - type: string - type: 'null' description: >- Identity document type as declared, e.g. "CEDULA DE CIUDADANIA", "NIT", "CEDULA DE EXTRANJERIA", "PASAPORTE". document_number: anyOf: - type: string - type: 'null' description: Identity document number or NIT as declared. country: anyOf: - type: string - type: 'null' description: Country as declared, e.g. "169 - COLOMBIA". shares: anyOf: - type: number - type: 'null' description: Shares held, as declared. participation_pct: anyOf: - type: number - type: 'null' description: Share of the capital, in percent, as declared. movement: anyOf: - type: string - type: 'null' description: Movement of the stake during the fiscal year, as declared. required: - name - document_type - document_number - country - shares - participation_pct - movement description: Foreign investors as declared, when the filing carries that note. subsidiaries: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' document_number: anyOf: - type: string - type: 'null' description: The subsidiary's NIT, as declared. place_of_business: anyOf: - type: string - type: 'null' country: anyOf: - type: string - type: 'null' non_controlling_interest_pct: anyOf: - type: number - type: 'null' description: >- Share of the subsidiary's capital held by parties other than this company, in percent. non_controlling_voting_pct: anyOf: - type: number - type: 'null' description: >- Share of the subsidiary's voting rights held by parties other than this company, in percent. required: - name - document_number - place_of_business - country - non_controlling_interest_pct - non_controlling_voting_pct description: Companies this company controls, as declared. associates: type: array items: type: object properties: name: anyOf: - type: string - type: 'null' document_number: anyOf: - type: string - type: 'null' description: The associate's NIT, as declared. place_of_business: anyOf: - type: string - type: 'null' country: anyOf: - type: string - type: 'null' ownership_pct: anyOf: - type: number - type: 'null' description: This company's share of the associate's capital, in percent. voting_pct: anyOf: - type: number - type: 'null' description: >- This company's share of the associate's voting rights, in percent. required: - name - document_number - place_of_business - country - ownership_pct - voting_pct description: Companies this company holds a significant stake in, as declared. officers: type: array items: type: object properties: role: type: string description: >- `legal_representative`, `first_alternate_legal_representative`, `second_alternate_legal_representative`, `accountant`, `statutory_auditor` (revisor fiscal), `alternate_statutory_auditor`, or the filing's own label. document_type: anyOf: - type: string - type: 'null' document_number: anyOf: - type: string - type: 'null' first_names: anyOf: - type: string - type: 'null' last_names: anyOf: - type: string - type: 'null' professional_card: anyOf: - type: string - type: 'null' description: >- Tarjeta profesional, for the accountant and the revisor fiscal. chamber_registration_date: anyOf: - type: string - type: 'null' description: >- Date the appointment was registered at the chamber of commerce, yyyy-mm-dd. required: - role - document_type - document_number - first_names - last_names - professional_card - chamber_registration_date description: Legal representatives, accountant and revisor fiscal as declared. required: - found - document_number - company - filing - shareholders - foreign_investors - subsidiaries - associates - officers securitySchemes: bearerAuth: type: http scheme: bearer description: 'Use Authorization: Bearer YOUR_API_KEY' ````