Fence Declaration monitoring API

openapi: 3.2.0
info:
  title: Fence Partner Integration Declaration monitoring API
  version: '2.0'
  description: Machine-readable contract for the Fence API operations documented for integration partners. Access requires credentials provisioned by Fence during onboarding. Deal-specific asset fields are agreed separately and remain explicitly extensible in this contract. The current public API uses the /v2 major-version path. Compatible additive changes may be introduced within a major version; a change that breaks a documented integration requires a new major version. No operation in this description is currently announced for deprecation.
  contact:
    name: Fence
    url: https://fence.finance/contact/
    email: hello@fence.finance
servers:
- url: https://dev-api.fence.finance
  description: Sandbox API for integration testing. Requires sandbox credentials provisioned by Fence.
- url: https://api.fence.finance
  description: Production API. Requires production credentials provisioned by Fence.
security:
- OAuth2ClientCredentials: []
tags:
- name: Declaration monitoring
  description: Monitor declaration runs and per-asset results.
paths:
  /v2/declarations:
    get:
      tags:
      - Declaration monitoring
      operationId: listDeclarationRuns
      summary: List declaration runs
      description: List declaration runs visible to the authenticated client, optionally filtered by deal or portfolio declaration.
      parameters:
      - $ref: '#/components/parameters/OptionalDealId'
      - $ref: '#/components/parameters/OptionalPortfolioDeclarationId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Paginated declaration runs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDeclarationRuns'
        '401':
          description: A valid bearer access token is required.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: The client is not authorized for this deal or action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '422':
          description: The request did not satisfy validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
  /v2/declarations/{declaration_id}:
    parameters:
    - $ref: '#/components/parameters/DeclarationId'
    get:
      tags:
      - Declaration monitoring
      operationId: getDeclarationRun
      summary: Get a declaration run
      description: Retrieve the current state and timestamps for one declaration run.
      responses:
        '200':
          description: Declaration run details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclarationRun'
        '401':
          description: A valid bearer access token is required.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: The client is not authorized for this deal or action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '404':
          description: The requested deal or resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '422':
          description: The request did not satisfy validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
  /v2/declarations/{declaration_id}/assets:
    parameters:
    - $ref: '#/components/parameters/DeclarationId'
    get:
      tags:
      - Declaration monitoring
      operationId: listDeclarationRunAssets
      summary: List declaration asset results
      description: List per-asset processing results for a declaration run with optional eligibility filters.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - name: external_asset_ids
        in: query
        required: false
        description: External asset identifiers to include.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: is_eligible
        in: query
        required: false
        description: Filter by the final eligibility result.
        schema:
          type: boolean
      - name: is_declarable
        in: query
        required: false
        description: Filter by the final declarability result.
        schema:
          type: boolean
      responses:
        '200':
          description: Paginated declaration asset results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDeclarationRunAssets'
        '401':
          description: A valid bearer access token is required.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: The client is not authorized for this deal or action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '404':
          description: The requested deal or resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '422':
          description: The request did not satisfy validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
  /v2/declarations/{declaration_id}/assets/{portfolio_declaration_asset_id}:
    parameters:
    - $ref: '#/components/parameters/DeclarationId'
    - $ref: '#/components/parameters/PortfolioDeclarationAssetId'
    get:
      tags:
      - Declaration monitoring
      operationId: getDeclarationRunAsset
      summary: Get one declaration asset result
      description: Retrieve all processing-step results for one asset in a declaration run.
      responses:
        '200':
          description: Declaration asset processing results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclarationRunAsset'
        '401':
          description: A valid bearer access token is required.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: The client is not authorized for this deal or action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '404':
          description: The requested deal or resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '422':
          description: The request did not satisfy validation rules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
components:
  schemas:
    DeclarationAssetResultStatus:
      type: string
      enum:
      - successful
      - unsuccessful
      - failed
    DeclarationRunStatus:
      type: string
      enum:
      - queued
      - processing
      - completed
      - completed_with_errors
      - failed
    DeclarationAssetStepResult:
      type: object
      additionalProperties: false
      required:
      - id
      - step_name
      - status
      - details
      properties:
        id:
          type: string
          format: uuid
        step_name:
          type: string
        status:
          $ref: '#/components/schemas/DeclarationAssetResultStatus'
        details:
          oneOf:
          - type: object
            additionalProperties: true
          - type: 'null'
    DealSpecificProperties:
      type: object
      description: Fields vary by deal and are defined in the integration-specific schema provided during onboarding.
      additionalProperties: true
    ValidationIssue:
      type: object
      additionalProperties: true
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
        msg:
          type: string
        type:
          type: string
    PaginatedDeclarationRunAssets:
      type: object
      additionalProperties: false
      required:
      - data
      - total
      - page
      - size
      - pages
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeclarationRunAsset'
        total:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        size:
          type: integer
          minimum: 1
        pages:
          type: integer
          minimum: 0
    DeclarationRun:
      type: object
      additionalProperties: false
      required:
      - id
      - portfolio_declaration_id
      - dry_run
      - status
      properties:
        id:
          type: string
          format: uuid
        portfolio_declaration_id:
          type: string
          format: uuid
        dry_run:
          type: boolean
        status:
          $ref: '#/components/schemas/DeclarationRunStatus'
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    PaginatedDeclarationRuns:
      type: object
      additionalProperties: false
      required:
      - data
      - total
      - page
      - size
      - pages
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeclarationRun'
        total:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        size:
          type: integer
          minimum: 1
        pages:
          type: integer
          minimum: 0
    DeclarationRunAsset:
      type: object
      additionalProperties: false
      required:
      - asset_id
      - external_asset_id
      - contract_external_id
      - properties
      - results
      properties:
        asset_id:
          type: string
          format: uuid
        external_asset_id:
          type: string
        contract_external_id:
          type:
          - string
          - 'null'
        properties:
          oneOf:
          - $ref: '#/components/schemas/DealSpecificProperties'
          - type: 'null'
        is_eligible:
          type:
          - boolean
          - 'null'
        is_declarable:
          type:
          - boolean
          - 'null'
        results:
          type: array
          items:
            $ref: '#/components/schemas/DeclarationAssetStepResult'
    HttpError:
      type: object
      additionalProperties: true
      required:
      - detail
      properties:
        detail:
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/ValidationIssue'
          - type: object
            additionalProperties: true
  parameters:
    PortfolioDeclarationAssetId:
      name: portfolio_declaration_asset_id
      in: path
      required: true
      description: Asset identifier within a portfolio declaration.
      schema:
        type: string
        format: uuid
    Page:
      name: page
      in: query
      required: false
      description: One-indexed result page.
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSize:
      name: page_size
      in: query
      required: false
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    OptionalDealId:
      name: deal_id
      in: query
      required: false
      description: Return declaration runs for one accessible deal.
      schema:
        type: string
        format: uuid
    OptionalPortfolioDeclarationId:
      name: portfolio_declaration_id
      in: query
      required: false
      description: Return runs for one portfolio declaration.
      schema:
        type: string
        format: uuid
    DeclarationId:
      name: declaration_id
      in: path
      required: true
      description: Declaration run identifier returned by a declare operation.
      schema:
        type: string
        format: uuid
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials grant for server-to-server integrations. Fence provisions credentials separately for each environment.
      flows:
        clientCredentials:
          tokenUrl: /v1/login/access-token
          scopes: {}
externalDocs:
  description: Fence API Client Integration Guide
  url: https://docs.fence.finance/