MetaMap API — Verifications

naftiko: 1.0.0-alpha2
info:
  label: MetaMap API — Verifications
  description: 'MetaMap API — Verifications. 7 operations covering start, retrieve, update, delete, send-input,
    skip-upload-wait, and PDF download of an identity verification. Self-contained Naftiko capability over the
    MetaMap Verifications business surface.'
  tags:
  - MetaMap
  - Identity Verification
  - KYC
  - Verifications
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    METAMAP_ACCESS_TOKEN: METAMAP_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: metamap-verifications
    baseUri: https://api.prod.metamap.com
    description: MetaMap Verifications business capability. Self-contained, no shared references.
    resources:
    - name: verifications
      path: /v2/verifications
      operations:
      - name: startverification
        method: POST
        description: Start a new user verification or re-verify an existing user with the specified flow.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body containing flowId and optional metadata.
          required: true
      - name: getverification
        method: GET
        path: /v2/verifications/{id}
        description: Retrieve a verification by ID.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
      - name: updatestatus
        method: PUT
        path: /v2/verifications/{verificationId}/status
        description: Update the status of a verification (e.g. accept, reject, review).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: verificationId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: true
      - name: deleteverification
        method: DELETE
        path: /verifications/{verificationId}
        description: Delete a verification.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: verificationId
          in: path
          type: string
          required: true
      - name: sendinput
        method: POST
        path: /v2/identities/{identity}/send-input
        description: Send documents, selfies, videos, or other identifying information for an existing identity.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: identity
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: true
      - name: skipuploadwait
        method: PUT
        path: /v2/verifications/{verification_id}/inputs/document-photo/skip
        description: Skip the wait time when uploading the back of a document.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: verification_id
          in: path
          type: string
          required: true
      - name: downloadpdf
        method: POST
        path: /verification/v1/pdf/download
        description: Download verification results as a PDF.
        servers:
        - https://api.getmati.com
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    authentication:
      type: apikey
      key: Authorization
      value: 'Bearer {{env.METAMAP_ACCESS_TOKEN}}'
      placement: header
  exposes:
  - type: rest
    namespace: metamap-verifications-rest
    port: 8080
    description: REST adapter for MetaMap Verifications. One Spectral-compliant resource per consumed operation.
    resources:
    - path: /v1/verifications
      name: verifications
      description: REST surface for MetaMap verifications.
      operations:
      - method: POST
        name: startverification
        description: Start a verification.
        call: metamap-verifications.startverification
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getverification
        description: Get a verification by ID.
        call: metamap-verifications.getverification
        with:
          id: rest.params.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: metamap-verifications-mcp
    port: 9090
    transport: http
    description: MCP adapter for MetaMap Verifications. One tool per consumed operation.
    tools:
    - name: metamap-start-verification
      description: Start a MetaMap verification with a given flowId.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: metamap-verifications.startverification
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: metamap-get-verification
      description: Retrieve a MetaMap verification by ID.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: metamap-verifications.getverification
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: metamap-update-verification-status
      description: Update the status of a MetaMap verification.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: metamap-verifications.updatestatus
      with:
        verificationId: tools.verificationId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.