marqeta-diva-api-openapi.yml

openapi: 3.1.0
info:
  title: Marqeta DiVA API
  description: >-
    The Marqeta DiVA (Data Insights, Visualization, and Analytics) API is a
    RESTful interface that provides programmatic access to production data from
    a Marqeta card program. It surfaces the data behind Marqeta's reporting
    and analytics tools, enabling developers to retrieve large datasets in JSON
    or CSV format. The API supports filtering, sorting, aggregation, and
    pagination for customized responses. Use cases include financial
    reconciliation, program balance reporting, transaction analysis, settlement
    data retrieval, cardholder balance monitoring, and card activity analytics.
    Authentication uses HTTP Basic Auth with the application token as the
    username and the access token as the password. Most endpoints require a
    program query parameter identifying your card program.
  version: '2'
  contact:
    name: Marqeta Support
    url: https://www.marqeta.com/company/contact
    email: support@marqeta.com
  termsOfService: https://www.marqeta.com/api-terms
externalDocs:
  description: Marqeta DiVA API Documentation
  url: https://www.marqeta.com/docs/diva-api/introduction
servers:
  - url: https://diva-api.marqeta.com/data/v2
    description: Production Server
tags:
  - name: Cards
    description: >-
      Retrieve card inventory and state data aggregated at card level or
      by time period for reporting on card issuance and usage.
  - name: Chargebacks
    description: >-
      Access chargeback data aggregated by transaction for dispute tracking
      and financial reconciliation.
  - name: Loads
    description: >-
      Retrieve funding load transaction data at a specified aggregation level.
      Covers all load types including ACH, push-to-card, and program transfers.
  - name: Program Balances
    description: >-
      Retrieve program funding balance data for financial reconciliation.
      Includes beginning and ending bank balances, amounts to send, and
      settlement details aggregated over configurable time periods.
  - name: Transactions
    description: >-
      Access transaction data including authorizations, settlements, and
      declines aggregated at day, week, month, or detail level for analysis
      and reconciliation.
  - name: Users
    description: >-
      Access cardholder (user) data and activity aggregated for program
      reporting and analysis.
  - name: Views
    description: >-
      View endpoints provide programmatic access to aggregated platform data
      derived from card program activity. Each view represents a specific
      dataset such as transactions, balances, or card states, aggregated at
      a configurable time level.
security:
  - basicAuth: []
paths:
  /views:
    get:
      operationId: listViews
      summary: List available views
      description: >-
        Returns a list of all available view endpoints for the DiVA API.
        Each view provides access to a specific type of program data
        aggregated at a defined level. Use this endpoint to discover
        which datasets are available for your program.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/program'
      responses:
        '200':
          description: A list of available view endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewsListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/programbalances/{time_agg}:
    get:
      operationId: getProgramBalances
      summary: Retrieve program funding balances
      description: >-
        Returns program funding balance data aggregated over the specified
        time period. Use this endpoint for financial reconciliation to
        retrieve beginning bank balance, amount to send, and ending bank
        balance. Supports daily, weekly, and monthly aggregation levels.
        An example request for daily balances:
        /views/programbalances/day?program=my_program&fields=beginning_bank_balance,amount_to_send,ending_bank_balance
      tags:
        - Program Balances
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Program balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted program balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/programbalancessettlement/{time_agg}:
    get:
      operationId: getProgramBalancesSettlement
      summary: Retrieve program settlement balances
      description: >-
        Returns program settlement balance data aggregated over the specified
        time period. Settlement balances reflect funds settled between Marqeta
        and the card networks. Use this alongside the programbalances view for
        full financial reconciliation.
      tags:
        - Program Balances
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Settlement balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted settlement balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/authorizations/{time_agg}:
    get:
      operationId: getAuthorizations
      summary: Retrieve authorization transaction data
      description: >-
        Returns authorization transaction data aggregated over the specified
        time period. Includes approved and declined authorizations with
        response codes, merchant details, and transaction amounts. Use the
        detail aggregation level to retrieve individual authorization records.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Authorization data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted authorization data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/settlements/{time_agg}:
    get:
      operationId: getSettlements
      summary: Retrieve settlement transaction data
      description: >-
        Returns settlement transaction data at a specified aggregation level.
        Settlement data reflects finalized transactions after card network
        clearing. Use this endpoint to reconcile cleared transactions against
        your financial records.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Settlement transaction data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted settlement data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/cards/{time_agg}:
    get:
      operationId: getCards
      summary: Retrieve card state and history data
      description: >-
        Returns card state and history data aggregated at card level or
        by time period. Use this endpoint to report on card issuance volume,
        card state distribution, and card activity across your program.
      tags:
        - Cards
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Card data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted card data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/cards/detail:
    get:
      operationId: getCardsDetail
      summary: Retrieve detailed card information
      description: >-
        Returns detailed information for each card in your program,
        including the full card lifecycle history, current state, expiration,
        and associated user. Use this endpoint for granular card-level
        reporting and auditing.
      tags:
        - Cards
      parameters:
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Detailed card records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardsDetailResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted detailed card data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/users/{time_agg}:
    get:
      operationId: getUsers
      summary: Retrieve user activity data
      description: >-
        Returns cardholder (user) data aggregated over the specified time
        period. Includes registration counts, KYC status distributions,
        and account status summaries for program reporting.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: User data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted user data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/users/detail:
    get:
      operationId: getUsersDetail
      summary: Retrieve detailed user information
      description: >-
        Returns detailed information for each cardholder in your program,
        including current account status, KYC verification status, associated
        cards, and GPA balance summary.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Detailed user records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersDetailResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted detailed user data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/loads/{time_agg}:
    get:
      operationId: getLoads
      summary: Retrieve funding load data
      description: >-
        Returns funding load transaction data at a specified aggregation level.
        When using the detail aggregation level, each row represents a single
        funding load transaction. Supports daily, weekly, monthly, and detail
        levels. Covers ACH loads, push-to-card loads, and program transfers.
      tags:
        - Loads
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Load transaction data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadsResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted load data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/chargebacks/{time_agg}:
    get:
      operationId: getChargebacks
      summary: Retrieve chargeback data
      description: >-
        Returns chargeback data aggregated by transaction or time period.
        Includes dispute status, amounts, reason codes, and resolution
        details for tracking chargeback activity and financial exposure.
      tags:
        - Chargebacks
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Chargeback data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebacksResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted chargeback data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /views/activitybalances/{time_agg}:
    get:
      operationId: getActivityBalances
      summary: Retrieve activity balance data
      description: >-
        Returns cardholder activity balance data aggregated over the specified
        time period. Provides a summary of GPA balance changes driven by
        card transactions, loads, and transfers for program financial reporting.
      tags:
        - Program Balances
      parameters:
        - $ref: '#/components/parameters/time_agg'
        - $ref: '#/components/parameters/program'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/start_date'
        - $ref: '#/components/parameters/end_date'
        - $ref: '#/components/parameters/format'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Activity balance data for the specified time period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityBalancesResponse'
            text/csv:
              schema:
                type: string
                description: CSV-formatted activity balance data.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication. Use your application token as the username
        and your access token as the password. Contact your Marqeta
        representative to obtain DiVA API credentials.
  parameters:
    program:
      name: program
      in: query
      required: true
      description: >-
        The name of your Marqeta card program. This parameter is required
        for most DiVA API endpoints to scope the data to your program.
      schema:
        type: string
    time_agg:
      name: time_agg
      in: path
      required: true
      description: >-
        Aggregation time level for the data. Use 'day' for daily rollups,
        'week' for weekly rollups, 'month' for monthly rollups, or 'detail'
        for individual record-level data.
      schema:
        type: string
        enum: [day, week, month, detail]
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of fields to include in the response. If not
        specified, all available fields are returned.
      schema:
        type: string
    start_date:
      name: start_date
      in: query
      description: >-
        Start date for filtering data (format YYYY-MM-DD). Returns records
        on or after this date.
      schema:
        type: string
        format: date
    end_date:
      name: end_date
      in: query
      description: >-
        End date for filtering data (format YYYY-MM-DD). Returns records
        on or before this date.
      schema:
        type: string
        format: date
    format:
      name: format
      in: query
      description: >-
        Response format. Use 'json' for JSON responses or 'csv' for
        comma-separated bulk file format. Defaults to json.
      schema:
        type: string
        enum: [json, csv]
        default: json
    limit:
      name: limit
      in: query
      description: Maximum number of records to return per request.
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
    offset:
      name: offset
      in: query
      description: Zero-based offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  responses:
    BadRequest:
      description: >-
        Bad request. One or more required query parameters are missing or
        contain invalid values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Unauthorized. The provided application token and access token
        credentials are invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response returned by the Marqeta DiVA API.
      properties:
        error_code:
          type: string
          description: Machine-readable error code.
        error_message:
          type: string
          description: Human-readable error description.
    DivaResponseMeta:
      type: object
      description: Metadata included in DiVA API paginated responses.
      properties:
        total_count:
          type: integer
          description: Total number of records matching the query.
        limit:
          type: integer
          description: Maximum records returned per page.
        offset:
          type: integer
          description: Current page offset.
        has_more:
          type: boolean
          description: Whether additional pages of data are available.
    ViewsListResponse:
      type: object
      description: Response containing the list of available DiVA API view endpoints.
      properties:
        views:
          type: array
          description: Array of available view endpoint descriptors.
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the view endpoint.
              path:
                type: string
                description: URL path for the view endpoint.
              description:
                type: string
                description: Description of the data provided by this view.
              time_aggregations:
                type: array
                description: Supported time aggregation levels for this view.
                items:
                  type: string
    ProgramBalancesResponse:
      type: object
      description: Program funding balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of program balance records.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Date of the balance record.
              program:
                type: string
                description: Program identifier.
              beginning_bank_balance:
                type: number
                description: Opening bank balance for the period.
              ending_bank_balance:
                type: number
                description: Closing bank balance for the period.
              amount_to_send:
                type: number
                description: Net amount to send to or receive from the bank.
              currency_code:
                type: string
                description: ISO 4217 currency code for the balance figures.
    SettlementBalancesResponse:
      type: object
      description: Program settlement balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of settlement balance records.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Settlement date.
              program:
                type: string
                description: Program identifier.
              settlement_amount:
                type: number
                description: Total amount settled during this period.
              network:
                type: string
                description: Card network (e.g., VISA, MASTERCARD).
              currency_code:
                type: string
                description: ISO 4217 currency code.
    AuthorizationsResponse:
      type: object
      description: Authorization transaction data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of authorization records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Transaction date or aggregation period.
              program:
                type: string
                description: Program identifier.
              authorization_count:
                type: integer
                description: Number of authorization events in the period.
              approved_count:
                type: integer
                description: Number of approved authorizations.
              declined_count:
                type: integer
                description: Number of declined authorizations.
              total_amount:
                type: number
                description: Total transaction amount for the period.
              approved_amount:
                type: number
                description: Total approved transaction amount.
              currency_code:
                type: string
                description: ISO 4217 currency code.
    SettlementsResponse:
      type: object
      description: Settlement transaction data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of settlement records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Settlement date or aggregation period.
              program:
                type: string
                description: Program identifier.
              settlement_count:
                type: integer
                description: Number of settled transactions.
              total_amount:
                type: number
                description: Total settled amount for the period.
              currency_code:
                type: string
                description: ISO 4217 currency code.
    CardsResponse:
      type: object
      description: Card data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of card data records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Aggregation period date.
              program:
                type: string
                description: Program identifier.
              active_card_count:
                type: integer
                description: Number of active cards at end of period.
              issued_card_count:
                type: integer
                description: Number of cards issued during the period.
              terminated_card_count:
                type: integer
                description: Number of cards terminated during the period.
    CardsDetailResponse:
      type: object
      description: Detailed card records response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of detailed card records.
          items:
            type: object
            properties:
              card_token:
                type: string
                description: Unique identifier of the card.
              last_four:
                type: string
                description: Last four digits of the card PAN.
              state:
                type: string
                description: Current card state.
              user_token:
                type: string
                description: Token of the cardholder.
              card_product_token:
                type: string
                description: Token of the card product.
              created_time:
                type: string
                format: date-time
                description: ISO 8601 card creation timestamp.
              expiration:
                type: string
                description: Card expiration date (MMYY format).
    UsersResponse:
      type: object
      description: User activity data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of user activity records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Aggregation period date.
              program:
                type: string
                description: Program identifier.
              new_user_count:
                type: integer
                description: Number of new users registered during the period.
              active_user_count:
                type: integer
                description: Number of active users at end of period.
              kyc_passed_count:
                type: integer
                description: Number of users who passed KYC during the period.
    UsersDetailResponse:
      type: object
      description: Detailed user records response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of detailed user records.
          items:
            type: object
            properties:
              user_token:
                type: string
                description: Unique identifier of the user.
              status:
                type: string
                description: Current account status.
              kyc_required:
                type: string
                description: KYC requirement status.
              created_time:
                type: string
                format: date-time
                description: ISO 8601 user creation timestamp.
              gpa_balance:
                type: number
                description: Current GPA available balance.
              card_count:
                type: integer
                description: Number of cards associated with the user.
    LoadsResponse:
      type: object
      description: Funding load transaction data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of load transaction records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Load date or aggregation period.
              program:
                type: string
                description: Program identifier.
              load_count:
                type: integer
                description: Number of load transactions in the period.
              total_load_amount:
                type: number
                description: Total amount loaded during the period.
              load_type:
                type: string
                description: Type of funding load (ACH, push-to-card, transfer).
              currency_code:
                type: string
                description: ISO 4217 currency code.
    ChargebacksResponse:
      type: object
      description: Chargeback data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of chargeback records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Chargeback date or aggregation period.
              program:
                type: string
                description: Program identifier.
              chargeback_count:
                type: integer
                description: Number of chargebacks in the period.
              total_chargeback_amount:
                type: number
                description: Total chargeback amount.
              reason_code:
                type: string
                description: Chargeback reason code from the card network.
              status:
                type: string
                description: Current status of the chargeback.
    ActivityBalancesResponse:
      type: object
      description: Activity balance data response.
      properties:
        meta:
          $ref: '#/components/schemas/DivaResponseMeta'
        data:
          type: array
          description: Array of activity balance records.
          items:
            type: object
            properties:
              date:
                type: string
                description: Activity date or aggregation period.
              program:
                type: string
                description: Program identifier.
              beginning_balance:
                type: number
                description: Total GPA beginning balance for all cardholders.
              ending_balance:
                type: number
                description: Total GPA ending balance for all cardholders.
              load_amount:
                type: number
                description: Total funds loaded during the period.
              spend_amount:
                type: number
                description: Total funds spent during the period.
              currency_code:
                type: string
                description: ISO 4217 currency code.