Syntage Corporate Structure Insight API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage Corporate Structure Insight API
  contact:
    name: Email
    email: support@syntage.com
  description: '# Introduction


    The Syntage API is organized around REST.'
servers:
- url: https://api.syntage.com
  description: Production
- url: https://api.sandbox.syntage.com
  description: Sandbox
security:
- ApiKey: []
tags:
- name: Corporate Structure Insight
paths:
  /entities/{entityId}/insights/corporate-structure/current-powers:
    get:
      tags:
      - Corporate Structure Insight
      operationId: GetCorporateStructureCurrentPowersInsight
      summary: Get current powers
      description: 'List the people and companies that hold at least one currently

        effective power of attorney, drawn from the most recent Company

        Verification report registered for the entity.


        This is a simplified projection of the report''s found entities: each

        row carries only the holder''s identity and their current powers — no

        cap-table holdings, share totals, or ownership percentages. Holders

        whose powers have all expired, and pure shareholders with no powers,

        are omitted. For the full cap-table picture, use the Company

        Verification report''s found-entities endpoint.


        When the entity has no Company Verification report yet, the response

        is an empty collection (`hydra:totalItems` of `0`).'
      parameters:
      - $ref: '#/components/parameters/entityId'
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: itemsPerPage
        in: query
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
      responses:
        '200':
          description: Corporate Structure Current Powers Insight
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/Collection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/CorporateStructureCurrentPowersEntityResponse
                    '@id':
                      example: /entities/91ab5678-1234-5678-9abc-def012345678/insights/corporate-structure/current-powers
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/CorporateStructureCurrentPowersEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    entityId:
      name: entityId
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
  schemas:
    CorporateStructureCurrentPowersPower:
      type: object
      description: A single currently effective power of attorney granted to a holder.
      required:
      - status
      - grantedAt
      - documentSource
      - documentNumber
      - externalReference
      - exerciseJointlyRequired
      - exerciseSubstitutionAllowed
      - realEstateCanAcquire
      - realEstateCanDispose
      properties:
        status:
          type: string
          description: Always `current` for this insight — expired powers are filtered out of the response.
          enum:
          - current
          example: current
        power:
          type:
          - string
          - 'null'
          description: 'Canonical power type (for example, `administrative_acts` or

            `lawsuits_and_collections`). `null` when the upstream pipeline

            classified the power as `external` (a reference to another document).

            '
          example: administrative_acts
        grantedAt:
          type: string
          format: date
          description: Date the power was granted, as recorded in the source document.
          example: '2020-01-15'
        expirationDate:
          type:
          - string
          - 'null'
          format: date
          description: Date the power expires, when known.
          example: '2025-01-15'
        expirationSource:
          type:
          - string
          - 'null'
          description: Source used to derive the expiration date (for example, `document` or `inference`).
          example: document
        documentSource:
          type: string
          description: Where the granting document was sourced from.
          example: rpc
        documentNumber:
          type: string
          description: Identifier of the granting document (NCI, protocol number, etc.).
          example: '12345'
        grantingState:
          type:
          - string
          - 'null'
          description: Mexican state where the granting document was issued, when known.
          example: CDMX
        externalReference:
          type: boolean
          description: True when the power refers to a separate external document instead of being defined inline.
          example: false
        referenceText:
          type:
          - string
          - 'null'
          description: Verbatim text of the external reference, when present.
        referenceDocumentNumber:
          type:
          - string
          - 'null'
          description: Document number of the external reference, when present.
        exerciseJointlyWith:
          type:
          - string
          - 'null'
          description: Name of the co-grantee with whom the power must be exercised jointly, when applicable.
        exerciseJointlyRequired:
          type: boolean
          description: Whether the power can only be exercised jointly with the co-grantee.
          example: false
        exerciseSubstitutionAllowed:
          type: boolean
          description: Whether the power may be substituted or delegated to another party.
          example: false
        exerciseLimitations:
          type:
          - string
          - 'null'
          description: Free-text limitations recorded in the source document.
        realEstateCanAcquire:
          type: boolean
          description: Whether the grantee may acquire real estate on behalf of the principal.
          example: false
        realEstateCanDispose:
          type: boolean
          description: Whether the grantee may dispose of or sell real estate on behalf of the principal.
          example: false
    HydraView:
      type: object
      properties:
        '@context':
          type: string
        '@id':
          type: string
        '@type':
          type: string
          default: hydra:Collection
        hydra:member:
          type: array
          items:
            type: object
        hydra:totalItems:
          type: integer
          description: Total number of items found
          minimum: 0
          example: 1
        hydra:view:
          type: object
          description: Pagination information
          properties:
            '@id':
              type: string
              format: iri-reference
              description: Current page IRI reference
            '@type':
              type: string
              default: hydra:PartialCollectionView
            hydra:first:
              type: string
              format: iri-reference
              description: First page IRI reference; omitted when there is no pagination
            hydra:next:
              type: string
              format: iri-reference
              description: Next page IRI reference; omitted when there is no pagination
            hydra:last:
              type: string
              format: iri-reference
              description: Last page IRI reference; omitted when there is no pagination
    Collection:
      allOf:
      - $ref: '#/components/schemas/HydraView'
      - type: object
        properties:
          hydra:search:
            type: object
            properties:
              '@type':
                type: string
              hydra:template:
                type: string
              hydra:variableRepresentation:
                type: string
              hydra:mapping:
                type: array
                items:
                  type: object
                  properties:
                    '@type':
                      type: string
                    variable:
                      type: string
                    property:
                      type: string
                    required:
                      type: boolean
    CorporateStructureCurrentPowersEntity:
      type: object
      description: 'A person or company appearing in the latest Company Verification

        report for the entity with at least one currently effective power of

        attorney. A simplified projection of a found entity, limited to the

        holder''s identity and their current powers — no cap-table holdings,

        share totals, or ownership percentages.

        '
      required:
      - name
      - entityType
      - powers
      properties:
        name:
          type: string
          description: Full name of the holder, as resolved by the upstream pipeline.
          example: Juan Pérez García
        entityType:
          type: string
          description: Whether the holder is a natural person or a legal entity.
          enum:
          - person
          - company
          example: person
        powers:
          type: array
          description: Currently effective powers of attorney granted to this holder, ordered by grant date ascending.
          items:
            $ref: '#/components/schemas/CorporateStructureCurrentPowersPower'
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Your API key is available in the [Production](https://app.syntage.com/settings/api-keys) and [Sandbox](https://app.sandbox.syntage.com/settings/api-keys) dashboards.

        '
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true