Syntage Company Verification Reports API

openapi: 3.2.0
info:
  version: '2020-06-28'
  title: Syntage Company Verification Reports 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: Company Verification Reports
  description: Company Verification Reports provide verification of company details and supporting files extracted from trusted sources. Use these endpoints to retrieve reports for a specific entity, list all reports, or download the generated PDF report.
paths:
  /datasources/mx/company-verification/reports:
    get:
      tags:
      - Company Verification Reports
      operationId: GetCompanyVerificationReports
      summary: List company verification reports
      description: Lists company verification reports available to the organization. Use this endpoint when you need to page through reports across entities.
      parameters:
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      - $ref: '#/components/parameters/orderCreatedAt'
      - $ref: '#/components/parameters/orderUpdatedAt'
      responses:
        '200':
          description: Company Verification Reports
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/Collection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/CompanyVerificationReport
                    '@id':
                      example: /datasources/mx/company-verification/reports
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/CompanyVerificationReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasources/mx/company-verification/reports/{id}:
    get:
      tags:
      - Company Verification Reports
      operationId: GetCompanyVerificationReport
      summary: Retrieve a company verification report
      description: Retrieves one company verification report, including its verification details, metadata, and supporting file references.
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Company Verification Report
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - type: object
                  properties:
                    '@context':
                      default: /contexts/CompanyVerificationReport
                    '@id':
                      example: /company-verification/reports/91ab5678-1234-5678-9abc-def012345678
                - $ref: '#/components/schemas/CompanyVerificationReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /datasources/mx/company-verification/reports/{id}/pdf:
    get:
      tags:
      - Company Verification Reports
      operationId: GetCompanyVerificationReportPdf
      summary: Download company verification report PDF
      description: Downloads the generated PDF for a company verification report. The response body is the PDF file itself.
      parameters:
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Company Verification Report PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entities/{entityId}/datasources/mx/company-verification/reports:
    get:
      tags:
      - Company Verification Reports
      operationId: GetEntityCompanyVerificationReports
      summary: List an entity's company verification reports
      description: Lists company verification reports associated with an entity. Use this endpoint when your integration is working from a known entity ID.
      parameters:
      - $ref: '#/components/parameters/entityId'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      - $ref: '#/components/parameters/orderCreatedAt'
      - $ref: '#/components/parameters/orderUpdatedAt'
      responses:
        '200':
          description: Entity Company Verification Reports
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/Collection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/CompanyVerificationReport
                    '@id':
                      example: /entities/91ab5678-1234-5678-9abc-def012345678/datasources/mx/company-verification/reports
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/CompanyVerificationReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /datasources/mx/company-verification/reports/{reportId}/found-entities:
    get:
      tags:
      - Company Verification Reports
      operationId: GetCompanyVerificationReportFoundEntities
      summary: Get a report's found entities
      description: 'List every person or company identified in the source documents of a

        Mexican Company Verification report, with their cap-table holdings and

        powers of attorney expanded inline.'
      parameters:
      - $ref: '#/components/parameters/companyVerificationReportId'
      - $ref: '#/components/parameters/collectionCursorNextPageParam'
      - $ref: '#/components/parameters/collectionCursorPreviousPageParam'
      - $ref: '#/components/parameters/collectionLimit'
      - name: fullName
        in: query
        description: Filter by partial, case-insensitive match on `fullName`.
        example: pérez
        schema:
          type: string
      - name: entityType
        in: query
        description: Filter by entity type.
        schema:
          type: string
          enum:
          - person
          - company
      - name: isActive
        in: query
        description: Filter by whether the entity still holds shares at the report cut-off date.
        schema:
          type: boolean
      - name: order[fullName]
        in: query
        description: Order by full name.
        schema:
          $ref: '#/components/schemas/CollectionOrder'
      - name: order[totalsPercentage]
        in: query
        description: Order by ownership percentage.
        schema:
          $ref: '#/components/schemas/CollectionOrder'
      responses:
        '200':
          description: Company Verification Report Found Entities
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/Collection'
                - type: object
                  properties:
                    '@context':
                      default: /contexts/FoundEntity
                    '@id':
                      example: /datasources/mx/company-verification/reports/91ab5678-1234-5678-9abc-def012345678/found-entities
                    hydra:member:
                      type: array
                      items:
                        $ref: '#/components/schemas/CompanyVerificationFoundEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /datasources/mx/company-verification/reports/{reportId}/found-entities/{id}:
    get:
      tags:
      - Company Verification Reports
      operationId: GetCompanyVerificationReportFoundEntity
      summary: Get a specific found entity
      description: Retrieve a single found entity, with its cap-table holdings and powers expanded inline.
      parameters:
      - $ref: '#/components/parameters/companyVerificationReportId'
      - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Company Verification Report Found Entity
          content:
            application/ld+json:
              schema:
                type: object
                allOf:
                - type: object
                  properties:
                    '@context':
                      default: /contexts/FoundEntity
                - $ref: '#/components/schemas/CompanyVerificationFoundEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CompanyVerificationFoundEntity:
      type: object
      description: 'A person or company identified in the source documents of a Mexican

        Company Verification report. Includes administrators, shareholders, and

        legal representatives — disambiguated by the upstream pipeline and merged

        across name variations.

        '
      required:
      - id
      - fullName
      - nameVariations
      - entityType
      - isActive
      - holdings
      - powers
      - createdAt
      - updatedAt
      properties:
        '@id':
          type: string
          format: iri-reference
          example: /datasources/mx/company-verification/reports/91ab5678-1234-5678-9abc-def012345678/found-entities/82bc6789-2345-6789-abcd-ef0123456789
        '@type':
          type: string
          default: FoundEntity
        id:
          type: string
          format: uuid
          example: 82bc6789-2345-6789-abcd-ef0123456789
        fullName:
          type: string
          description: Full name of the entity, as resolved by the upstream pipeline.
          example: Juan Pérez García
        nameVariations:
          type: array
          description: Alternative spellings of the full name observed across source documents.
          items:
            type: string
          example:
          - Juan Perez Garcia
          - J. Pérez García
        entityType:
          type: string
          description: Whether the entity is a natural person or a legal entity.
          enum:
          - person
          - company
          example: person
        totalsShares:
          type:
          - integer
          - 'null'
          description: 'Sum of shares this entity holds across every `(capitalType, series)`

            bucket. `null` when the entity has no cap-table data extracted

            (for example, a legal representative that only appears in powers).

            '
          example: 5000
        totalsAmount:
          type:
          - string
          - 'null'
          description: Sum of monetary value this entity holds across every `(capitalType, series)` bucket.
          example: '50000.0000'
        totalsPercentage:
          type:
          - string
          - 'null'
          description: Ownership percentage held by this entity at the report cut-off date.
          example: '25.0000'
        isActive:
          type: boolean
          description: Whether this entity still holds shares at the report cut-off date.
          example: true
        firstAppearanceDate:
          type:
          - string
          - 'null'
          format: date
          description: Date on which this entity first appears as a shareholder in the report source documents.
          example: '2020-01-15'
        holdings:
          type: array
          description: Granular cap-table holdings, one row per `(capitalType, series)` bucket this entity appears in.
          items:
            $ref: '#/components/schemas/CompanyVerificationFoundEntityCapTableEntry'
        powers:
          type: array
          description: Powers of attorney granted to this entity. Includes both current and expired records, discriminated by `status`.
          items:
            $ref: '#/components/schemas/CompanyVerificationFoundEntityPower'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    File:
      type: object
      properties:
        '@id':
          type: string
          format: iri-reference
          description: File IRI reference
          example: /files/91106968-1abd-4d64-85c1-4e73d96fb997
        '@type':
          type: string
          description: JSON-LD resource type
          default: File
          example: File
        id:
          type: string
          format: uuid
          description: Unique file ID
          example: 91106968-1abd-4d64-85c1-4e73d96fb997
        type:
          type: string
          description: File category, such as an invoice CFDI XML or PDF
          example: invoice.cfdi.xml
        resource:
          type: string
          description: IRI of the resource that produced or owns the file
          example: /invoices/7c45e9c6-8f7f-4d0e-b6e5-65fef6c8c2f9
        mimeType:
          type: string
          description: Media type of the file content
          example: text/xml
        extension:
          type: string
          description: File extension for the stored content
          example: xml
        size:
          type: integer
          description: File size in bytes
          example: 40544
        filename:
          type: string
          description: Suggested filename for the file content
          example: 6f3c5312-2849-4525-86f6-c48a54c64c60.xml
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    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
    updatedAt:
      type: string
      description: Date and time the resource was last updated
      example: '2020-01-01T12:15:00.000Z'
    CollectionLimit:
      type: integer
      default: 20
      minimum: 1
      maximum: 1000
    RpcEntidadeID:
      type: string
      format: uuid
      description: RPC Entidade ID
      example: 99c13810-868f-482e-a6f1-878254248d27
    RpcEntidadeProfile:
      type: object
      description: Basic RPC entidade profile information
      properties:
        '@id':
          type: string
          format: iri-reference
          description: RPC entidade IRI reference
          example: /datasources/mx/rpc/entidades/99c13810-868f-482e-a6f1-878254248d27
        '@type':
          type: string
          default: RpcEntidade
        id:
          $ref: '#/components/schemas/RpcEntidadeID'
        fme:
          $ref: '#/components/schemas/RpcEntidadeFme'
        nombreRazonSocial:
          $ref: '#/components/schemas/RpcEntidadeNombreRazonSocial'
    RpcEntidadeNombreRazonSocial:
      type:
      - string
      - 'null'
      description: Legal name reported by RPC
      example: FOO BAR, S.A. DE C.V.
    CollectionOrder:
      type: string
      enum:
      - asc
      - desc
      example: asc
    CompanyVerificationFoundEntityCapTableEntry:
      type: object
      description: 'A single cap-table holding row for a found entity, scoped to one

        `(capitalType, series)` bucket. A shareholder that holds both Serie A

        fixed and Serie B fixed yields two entries.

        '
      required:
      - id
      - capitalType
      - shares
      - amount
      - bucketPercentage
      properties:
        id:
          type: string
          format: uuid
          example: 73cd5678-3456-7890-bcde-f01234567890
        capitalType:
          type: string
          description: 'Capital classification: `fixed`, `variable`, or `unspecified`.'
          enum:
          - fixed
          - variable
          - unspecified
          example: fixed
        series:
          type:
          - string
          - 'null'
          description: Capital series identifier (`A`, `B`, …) when the source document reports it.
          example: A
        shares:
          type: integer
          description: Number of shares held in this bucket.
          example: 3000
        amount:
          type: string
          description: Monetary value held in this bucket.
          example: '30000.0000'
        valuePerShare:
          type:
          - string
          - 'null'
          description: Face value per share for this bucket, when known.
          example: '10.0000'
        bucketPercentage:
          type: string
          description: 'Share of this `(capitalType, series)` bucket held by this entity.

            All holdings of the same bucket across the report sum to `100` by

            construction.

            '
          example: '60.0000'
    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
    RpcEntidadeFme:
      type:
      - string
      - 'null'
      description: Electronic commercial folio assigned by RPC
      example: N-2000000000
    CompanyVerificationReport:
      type: object
      required:
      - id
      - link
      - rpcEntity
      - extraction
      - files
      - createdAt
      - updatedAt
      properties:
        '@id':
          type: string
          format: iri-reference
          description: Company Verification Report IRI reference
          example: /datasources/mx/company-verification/reports/91ab5678-1234-5678-9abc-def012345678
        '@type':
          type: string
          default: CompanyVerificationReport
        id:
          type: string
          format: uuid
          description: Unique company verification report ID
          example: 91ab5678-1234-5678-9abc-def012345678
        link:
          type: string
          format: iri-reference
          description: Entity associated with the company verification report
          example: /entities/91ab5678-1234-5678-9abc-def012345678
        rpcEntity:
          allOf:
          - $ref: '#/components/schemas/RpcEntidadeProfile'
          description: RPC company profile used for the verification report
        extraction:
          type: string
          format: iri-reference
          description: Extraction that produced the report
          example: /extractions/91106968-1abd-4d64-85c1-4e73d96fb997
        files:
          type: array
          items:
            $ref: '#/components/schemas/File'
          description: Files generated for the company verification report, including PDF and HTML reports when available
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    CompanyVerificationFoundEntityPower:
      type: object
      description: A power of attorney granted to a found entity.
      required:
      - id
      - status
      - grantedAt
      - documentSource
      - documentNumber
      properties:
        id:
          type: string
          format: uuid
          example: 64de4567-4567-8901-cdef-123456789012
        status:
          type: string
          description: Whether the power is still in effect at the report cut-off date.
          enum:
          - current
          - expired
          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-time
          description: Date the power was granted, as recorded in the source document.
          example: '2020-01-15T00:00:00+00:00'
        expirationDate:
          type:
          - string
          - 'null'
          format: date-time
          description: Date the power expires or expired, when known.
          example: '2025-01-15T00:00:00+00:00'
        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'
        documentGrantingState:
          type:
          - string
          - 'null'
          description: Mexican state where the granting document was issued, when known.
          example: CDMX
        referenceExternal:
          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
    createdAt:
      type: string
      description: Date and time the resource was created
      example: '2020-01-01T12:15:00.000Z'
  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
  parameters:
    resourceId:
      name: id
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
    entityId:
      name: entityId
      in: path
      required: true
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      schema:
        type: string
        format: uuid
    collectionLimit:
      name: itemsPerPage
      in: query
      required: false
      description: Number of items per page
      schema:
        $ref: '#/components/schemas/CollectionLimit'
    orderCreatedAt:
      name: order[createdAt]
      in: query
      description: Order by resource creation date
      schema:
        $ref: '#/components/schemas/CollectionOrder'
    collectionCursorNextPageParam:
      name: id[lt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the next page
      schema:
        type: string
    orderUpdatedAt:
      name: order[updatedAt]
      in: query
      description: Order by resource update date
      schema:
        $ref: '#/components/schemas/CollectionOrder'
    companyVerificationReportId:
      name: reportId
      in: path
      required: true
      description: Identifier of the Company Verification report.
      example: 91ab5678-1234-5678-9abc-def012345678
      schema:
        type: string
        format: uuid
    collectionCursorPreviousPageParam:
      name: id[gt]
      in: query
      required: false
      example: 91106968-1abd-4d64-85c1-4e73d96fb997
      description: Collection cursor pointer to the previous page
      schema:
        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