Arcadia Discovered Statements API

openapi: 3.2.0
info:
  description: Plug API
  title: Plug Discovered Statements API
  version: 2.0.0
servers:
- url: https://api.arcadia.com
security:
- OAuth2: []
tags:
- name: Discovered Statements
paths:
  /plug/discoveredStatements:
    get:
      description: 'Get a list of discovered statements in the Arcadia system. This endpoint is pageable.


        This endpoint supports Sandbox Mode.'
      operationId: list-discovered-statements
      parameters:
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are:

          - `accountIds`

          - `accountNumbers`

          - `businessUnitsIntersection.id`

          - `businessUnitsIntersection.name`

          - `businessUnitsUnion.id`

          - `businessUnitsUnion.name`

          - `correlationIds`

          - `createdAt`

          - `credentialIds`

          - `dataIngestionMethod`

          - `dueDate`

          - `hasValidAccountStatus`

          - `id`

          - `invoiceNumber`

          - `periodEndDate`

          - `periodStartDate`

          - `provider.id`

          - `provider.name`

          - `statementDate`

          - `statementId`

          - `statementType`

          - `status`'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: A global search query string. See [this page](ref:searching#global-search) for more information.
        in: query
        name: globalSearch
        required: false
        schema:
          type: string
      - description: Business Unit IDs to filter Discovered Statements by.
        in: query
        name: businessUnitIds
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicDiscoveredStatementResource'
          description: OK
      summary: List Discovered Statements
      tags:
      - Discovered Statements
      servers:
      - url: https://api.arcadia.com
      - url: https://sandbox.api.arcadia.com
  /plug/discoveredStatements/{discoveredStatementId}:
    get:
      description: 'Retrieve a single discovered statement record.


        This endpoint supports Sandbox Mode.'
      operationId: retrieve-discovered-statement
      parameters:
      - in: path
        name: discoveredStatementId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDiscoveredStatementResource'
          description: OK
      summary: Retrieve Discovered Statement
      tags:
      - Discovered Statements
      servers:
      - url: https://api.arcadia.com
      - url: https://sandbox.api.arcadia.com
  /plug/discoveredStatements/{discoveredStatementId}/source:
    get:
      description: Download the source file for a discovered statement.
      operationId: download-discovered-statement-source
      parameters:
      - in: path
        name: discoveredStatementId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          description: OK
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlugErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlugErrorResponse'
          description: Internal Server Error
      summary: Download Discovered Statement Source
      tags:
      - Discovered Statements
  /plug/discoveredStatements/{discoveredStatementId}/versions:
    get:
      description: 'List all versions of a specific Discovered Statement.


        This endpoint supports Sandbox Mode.'
      operationId: list-discovered-statement-versions
      parameters:
      - in: path
        name: discoveredStatementId
        required: true
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPublicDiscoveredStatementResource'
          description: OK
      summary: List Discovered Statement Versions
      tags:
      - Discovered Statements
      servers:
      - url: https://api.arcadia.com
      - url: https://sandbox.api.arcadia.com
  /plug/discoveredStatements/{discoveredStatementId}/versions/{discoveredStatementVersionId}:
    get:
      description: 'Retrieve a specific version of a Discovered Statement.


        This endpoint supports Sandbox Mode.'
      operationId: retrieve-a-discovered-statement-version
      parameters:
      - in: path
        name: discoveredStatementId
        required: true
        schema:
          type: string
      - in: path
        name: discoveredStatementVersionId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDiscoveredStatementResource'
          description: OK
      summary: Retrieve a Discovered Statement Version
      tags:
      - Discovered Statements
      servers:
      - url: https://api.arcadia.com
      - url: https://sandbox.api.arcadia.com
components:
  schemas:
    PlugErrorResponse:
      type: object
      properties:
        errors:
          type: array
          description: Contains an array of error objects.
          items:
            $ref: '#/components/schemas/PlugError'
      required:
      - errors
    PagedPublicDiscoveredStatementResource:
      type: object
      properties:
        discoveredStatements:
          type: array
          description: An array of discovered statement objects.
          items:
            $ref: '#/components/schemas/PublicDiscoveredStatementResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
      required:
      - discoveredStatements
      - page
    PlugError:
      type: object
      properties:
        details:
          type: object
          additionalProperties: true
          description: A map of additional details about the error.
          properties:
            errorId:
              type: string
          required:
          - errorId
        message:
          type: string
          description: Human readable text that elaborates on the error.
        param:
          type: string
          description: The parameter that caused the error, if applicable.
        type:
          type: string
          description: The type of error based on Arcadia's classification for errors.
          enum:
          - conflict
          - internalServerError
          - invalidParameter
          - notFound
          - tooManyRequests
          - forbidden
          - methodNotAllowed
      required:
      - details
      - message
      - param
      - type
    PublicDiscoveredStatementResource:
      type: object
      description: An array of discovered statement objects.
      properties:
        accountIds:
          type: array
          description: List of account IDs associated with the discovered statement.
          items:
            type: string
            description: List of account IDs associated with the discovered statement.
        accountNumbers:
          type: array
          description: An array of account identifiers provided by the commodity provider (often times the bill publisher).
          items:
            type: string
            description: An array of account identifiers provided by the commodity provider (often times the bill publisher).
        businessUnitsIntersection:
          type: array
          description: Intersection of Business Units across Accounts linked to this Discovered Statement.
          items:
            $ref: '#/components/schemas/PublicBusinessUnitResource'
        businessUnitsUnion:
          type: array
          description: Union of Business Units from Accounts linked to this Discovered Statement.
          items:
            $ref: '#/components/schemas/PublicBusinessUnitResource'
        correlationIds:
          type: array
          description: A list of correlationIds cascaded from all directly associated Credentials and Files.
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: A timestamp indicating when the entity was created.
        credentialIds:
          type: array
          description: List of credential IDs associated with the discovered statement.
          items:
            type: string
            description: List of credential IDs associated with the discovered statement.
        dataIngestionMethod:
          type:
          - string
          - 'null'
          description: Identifies the data ingestion method that created this Statement.
          enum:
          - BILL_UPLOAD
          - UTILITY_WEBSITE_ACCESS
        dueDate:
          type:
          - string
          - 'null'
          format: date
          description: The due date for payment associated with the account.
        id:
          type: string
          description: A unique identifier for the entity.
        invoiceNumber:
          type:
          - string
          - 'null'
          description: The unique identifier or number assigned to a specific invoice.
        isLatestVersion:
          type: boolean
          description: Indicates whether the Statement is the most recent versionId of the Statement.
        periodEndDate:
          type:
          - string
          - 'null'
          format: date
          description: The end date of the measuring period.
        periodStartDate:
          type:
          - string
          - 'null'
          format: date
          description: The start date of the measuring period.
        provider:
          $ref: '#/components/schemas/PublicProviderResource'
        sourceType:
          type:
          - string
          - 'null'
          description: The format of the data extraction source we used.
          enum:
          - TAG_NAME
          - UNCLASSIFIED
          - HTML
          - CSS
          - PNG
          - JPG
          - GIF
          - TIFF
          - SVG
          - WEBP
          - ICO
          - PDF
          - JSON
          - CSV
          - XML
          - XLS
          - XLSX
          - TXT
          - ZIP
          - MSOTF
          - OTF
          - SFNT
          - TTF
          - WOFF
          - WOFF2
          - FONT_WOFF
          - FONT_WOFF2
          - FONT_XWOFF
          - FONT_TTF
          - FONT_SFNT
          - URJA_NODE_LIST
          - URJA_NAV_HISTORY
          - INSERT_BILL
          - EDI
          - X12
          - EDIFACT
          - TRADACOMS
          - WOOT
        statementDate:
          type:
          - string
          - 'null'
          format: date
          description: The date of the discovered statement.
        statementId:
          type:
          - string
          - 'null'
          description: The unique identifier of a statement.
        statementType:
          type:
          - string
          - 'null'
          description: Describes the source document.
          enum:
          - BILL
          - NOTICE
          - ADJUSTMENT
          - PREPAID
        status:
          type: string
          description: Status of the discovered statement.
          enum:
          - EXTRACTION_PASSED_QUALITY_CHECKS
          - EXTRACTION_FAILED_QUALITY_CHECKS
        versionId:
          type: string
          description: A unique identifier for the version of the Discovered Statement entity at a given moment in time.
      required:
      - accountIds
      - accountNumbers
      - businessUnitsIntersection
      - businessUnitsUnion
      - correlationIds
      - createdAt
      - credentialIds
      - dataIngestionMethod
      - dueDate
      - id
      - invoiceNumber
      - isLatestVersion
      - periodEndDate
      - periodStartDate
      - provider
      - sourceType
      - statementDate
      - statementId
      - statementType
      - status
      - versionId
    PublicProviderResource:
      type:
      - object
      - 'null'
      description: The entity providing service and issuing bills (informally known as a utility).
      properties:
        country:
          type:
          - string
          - 'null'
          description: The country associated with the billing address.
        id:
          type: string
          description: A unique identifier for the entity.
        intervalServiceTypes:
          type: array
          description: List of interval service types supported by this provider (e.g., ['electric', 'gas'])
          items:
            type: string
            description: List of interval service types supported by this provider (e.g., ['electric', 'gas'])
            enum:
            - ELECTRIC
            - GAS
          uniqueItems: true
        isIntervalDataSupported:
          type:
          - boolean
          - 'null'
          description: Indicates whether the provider supports interval data
        isIntervalFileUploadSupported:
          type:
          - boolean
          - 'null'
          description: Indicates whether the provider supports interval file upload
        isRealTimeCredentialValidationSupported:
          type: boolean
          description: Indicates whether the provider supports credential validation
        name:
          type:
          - string
          - 'null'
          description: The name of the utility service provider.
      required:
      - country
      - id
      - intervalServiceTypes
      - isIntervalDataSupported
      - isIntervalFileUploadSupported
      - isRealTimeCredentialValidationSupported
      - name
    PublicBusinessUnitResource:
      type: object
      description: A business unit assignment.
      properties:
        id:
          type: string
          description: Business unit identifier.
          readOnly: true
        name:
          type:
          - string
          - 'null'
          description: Display name when visible to the caller.
      required:
      - id
      - name
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        number:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
      description: Specifies which page of results to return; this is 0-indexed
  parameters:
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2024-02-21'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2024-02-21'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: This API uses OAuth2 with the client credentials flow using the ['Create an Access Token'](ref:create-access-token) endpoint. API keys can be retrieved from the [Dashboard](https://dashboard.arcadia.com/).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /oauth2/token
x-provenance:
  method: harvested
  publisher: Arcadia
  source: https://docs.arcadia.com/openapi/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)