Marqeta Loads API

openapi: 3.2.0
info:
  title: Marqeta DiVA Loads 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.
  version: '2'
  contact:
    name: Marqeta Support
    url: https://www.marqeta.com/company/contact
    email: support@marqeta.com
  termsOfService: https://www.marqeta.com/api-terms
servers:
- url: https://diva-api.marqeta.com/data/v2
  description: Production Server
security:
- basicAuth: []
tags:
- 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.
paths:
  /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'
components:
  parameters:
    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
    offset:
      name: offset
      in: query
      description: Zero-based offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    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
    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
    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
    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
  responses:
    Unauthorized:
      description: Unauthorized. The provided application token and access token credentials are invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request. One or more required query parameters are missing or contain invalid values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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.
    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.
    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.
  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.
externalDocs:
  description: Marqeta DiVA API Documentation
  url: https://www.marqeta.com/docs/diva-api/introduction