> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargeblast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Alerts

> Get all the alerts from your Chargeblast account.

<Info>
  The `subprovider` field indicates the alert network — see [Alert Types](/reference/alert-types) for all values. Each alert may also include optional **`attributes`**: a dictionary of string key/value pairs (for example `order_number`, `processor_id`), the same field that appears on [webhook](/api-reference/webhooks/setup#body) payloads.
</Info>

<Note>
  New integrations should use v3; the legacy endpoint is [Fetch Alerts (v2)](/api-reference/alerts/fetch-alerts-v2). Filters use the bracketed `filter[...]` query parameters below, or an equivalent JSON `filter` body (query string wins; `page` / `per` are always query params).
</Note>


## OpenAPI

````yaml get /api/v3/alerts
openapi: 3.0.1
info:
  title: Chargeblast API
  version: 0.1.0
servers:
  - url: https://api.chargeblast.com
security: []
tags:
  - name: Credit Requests
  - name: Sync Data
  - name: Alerts
  - name: Disputes
  - name: Enrollment
paths:
  /api/v3/alerts:
    get:
      tags:
        - Alerts
      summary: Fetch Alerts
      description: >-
        Get all the alerts from your Chargeblast account, filtered by network,
        status, match state or date range. Each company has its own API key, so
        run the export once per key.
      operationId: alerts-v3
      parameters:
        - name: filter[type]
          in: query
          required: false
          description: >-
            Alert networks to include, comma-separated. Possible values: Ethoca,
            CDRN, RDR, Discover, AMEX, JCB, Cancel, TC40, SAFE, PayPal.
            Case-insensitive. An unrecognised value is rejected with a 400
            rather than ignored.
          schema:
            nullable: true
            type: string
        - name: filter[status]
          in: query
          required: false
          description: >-
            Alert reason codes to include, comma-separated. Possible values:
            Resolved, ResolvedPartial, ResolvedCancelled, AccountCancelled,
            CancellationProcessed, UnmatchedGeneral,
            UnmatchedCannotFindTransaction, Duplicate, MIDLost, AlreadyRefunded,
            AlreadyChargeback, Ineligible, TDS, CannotCancel, MatchedWillShip,
            EscalateChargeback, ContactedShipper, WIP, Error, None,
            NotMyDescriptor, Unactioned, TIMEOUT. Case-insensitive. An
            unrecognised value is rejected with a 400 rather than ignored.
          schema:
            nullable: true
            type: string
        - name: filter[isMatched]
          in: query
          required: false
          description: >-
            `true` returns only alerts matched to a transaction, `false` only
            unmatched ones. Mirrors the `isMatched` field on each alert.
          schema:
            type: boolean
            nullable: true
        - name: filter[startDate]
          in: query
          required: false
          description: >-
            Only return alerts created on or after this point. ISO 8601
            date/time (2026-06-01T00:00:00Z) or a date (2026-06-01).
          schema:
            nullable: true
            type: string
        - name: filter[endDate]
          in: query
          required: false
          description: >-
            Only return alerts created on or before this point. ISO 8601
            date/time (2026-06-01T00:00:00Z) or a date (2026-06-01).
          schema:
            nullable: true
            type: string
        - name: page
          required: false
          in: query
          schema:
            format: int64
            nullable: true
            type: integer
          description: The starting page of the request. Default value of 1.
        - name: per
          required: false
          in: query
          schema:
            format: int64
            nullable: true
            type: integer
          description: How many objects to request per page. Default value of 10.
        - name: X-API-Key
          required: true
          in: header
          schema:
            type: string
          description: Your API key. Sent in the `X-API-Key` header.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIAlertsResponse'
components:
  schemas:
    APIAlertsResponse:
      type: object
      required:
        - alerts
        - page
        - per
        - total
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/AlertV3'
        page:
          type: integer
          format: int64
          description: The page returned. The first page is 1.
        per:
          type: integer
          format: int64
          description: Objects per page.
        total:
          type: integer
          format: int64
          description: Total alerts matching the filter.
    AlertV3:
      type: object
      required:
        - alertType
        - creditAppealed
        - isMatched
        - isRefunded
        - subprovider
      properties:
        acquirerAction:
          nullable: true
          type: string
          description: >-
            Actions taken by the acquirer in response to the alert. Only
            relevant for RDR and other acquirer side alerts - either Resolved or
            Declined.
        alertId:
          description: >-
            Unique identifier for the alert within the provider's system. Will
            match the id field.
          nullable: true
          type: string
        alertType:
          allOf:
            - $ref: '#/components/schemas/GetAlertAlertType'
          description: Type of alert, e.g., FRAUD, DISPUTE.
        amount:
          type: number
          nullable: true
          format: double
          description: >-
            Transaction amount for the alert. $139.38 will be represented as
            139.38
        arn:
          description: Acquirer Reference Number, unique identifier for the transaction.
          nullable: true
          type: string
        attributes:
          additionalProperties:
            type: string
          type: object
          nullable: true
          description: >-
            Optional string key-value metadata associated with the alert.
            Included on webhook payloads and when fetching alerts via the API
            when present.
        authCode:
          description: Authorization code for the transaction, if available.
          type: string
          nullable: true
        bin:
          type: string
          nullable: true
          description: Acquiring BIN the alert was raised under.
        binDetails:
          allOf:
            - $ref: '#/components/schemas/BinDetails'
          description: >-
            Issuer/BIN metadata for the alerted card, when a BIN lookup
            succeeded.
        caid:
          type: string
          nullable: true
          description: Card acceptor id (merchant id) the alert was raised under.
        card:
          description: The redacted card number, e.g., 424242****1234.
          type: string
          nullable: true
        cardBrand:
          type: string
          description: The card network (e.g., Visa, Mastercard, Amex).
          nullable: true
        country:
          type: string
          nullable: true
          description: Issuing country of the alerted card.
        createdAt:
          format: date-time
          nullable: true
          type: string
          description: Date and time when the alert was created.
        creditAppealed:
          type: boolean
          description: Indicates if the credit associated with the alert was appealed.
        creditNotes:
          type: string
          description: Additional notes or information regarding the credit status.
          nullable: true
        creditStatus:
          type: string
          nullable: true
          description: Status of the credit (if any) associated with the alert.
        currency:
          nullable: true
          type: string
          description: Currency code in ISO format (e.g., USD, EUR) for the transaction.
        customerEmail:
          nullable: true
          type: string
          description: Customer's email address associated with the alert, if available.
        customerId:
          description: >-
            Unique identifier for the customer associated with the alert, if
            available.
          nullable: true
          type: string
        descriptor:
          description: Billing descriptor shown on the card statement.
          nullable: true
          type: string
        externalOrder:
          description: External charge id related to the alert.
          nullable: true
          type: string
        externalUrl:
          nullable: true
          type: string
          description: URL linking to an external reference for the alert.
        funding:
          type: string
          nullable: true
          description: Card funding type (credit, debit, prepaid).
        id:
          nullable: true
          type: string
          description: Id for the alert.
        invoicedAt:
          description: Date and time when the alert was invoiced.
          format: date-time
          nullable: true
          type: string
        isMatched:
          type: boolean
          description: >-
            Whether the alert was matched to a transaction. When false, the
            charge-level fields (externalOrder, externalUrl, customerId,
            customerEmail, metadata, attributes, mid, processor) are null and
            isRefunded is false.
        isRefunded:
          type: boolean
          description: >-
            Whether the matched transaction had already been refunded at match
            time. Always false for an unmatched alert.
        issuer:
          type: string
          description: Issuer of the card (e.g., bank or financial institution).
          nullable: true
        merchantId:
          description: Identifier for the merchant within the system.
          type: string
          nullable: true
        merchantName:
          type: string
          nullable: true
          description: Merchant name registered with the alert network.
        metadata:
          type: string
          nullable: true
          description: >-
            Metadata carried on the matched transaction, when the processor
            supplied any.
        mid:
          type: string
          nullable: true
          description: Sub-account / MID the matched transaction settled under.
        networkId:
          type: string
          nullable: true
          description: Network transaction id supplied by the card network.
        notes:
          type: string
          nullable: true
          description: Internal notes recorded against the alert.
        origin:
          type: string
          nullable: true
          description: Upstream alert origin, e.g. mastercard, visa, discover.
        processor:
          allOf:
            - $ref: '#/components/schemas/CommonChargeChargePlatform'
          description: Payment processor the matched transaction belongs to.
        provider:
          type: string
          nullable: true
          description: 'Provider associated with the alert. Possible values: ethoca, verifi'
        reasonCode:
          allOf:
            - $ref: '#/components/schemas/AlertReasonCode'
          description: >-
            Reason code associated with the alert, often indicating the nature
            of the dispute.
        resolvedByApi:
          description: Indicates if the alert was resolved via API.
          nullable: true
          type: boolean
        resolvedDate:
          description: Date and time when the alert was resolved.
          format: date-time
          nullable: true
          type: string
        responseAction:
          description: Response action taken in response to the alert.
          nullable: true
          type: string
        site:
          description: Merchant's website or site string associated with the alert.
          type: string
          nullable: true
        subprovider:
          allOf:
            - $ref: '#/components/schemas/DescriptorType'
          description: Specific sub-provider within the provider service.
        transactionDate:
          nullable: true
          format: date-time
          type: string
          description: Date and time when the transaction took place.
    GetAlertAlertType:
      type: string
      description: |-
        • FRAUD → Fraud
        • DISPUTE → Dispute
        • UNKNOWN → Unknown
        • DISPUTE_RDR → RDR
        • CANCEL → Cancel
      enum:
        - FRAUD
        - DISPUTE
        - UNKNOWN
        - DISPUTE_RDR
        - CANCEL
    BinDetails:
      type: object
      properties:
        type:
          nullable: true
          type: string
        prepaid:
          type: boolean
          nullable: true
        brand:
          nullable: true
          type: string
        bank:
          $ref: '#/components/schemas/Bank'
        country:
          $ref: '#/components/schemas/BinCountry'
    CommonChargeChargePlatform:
      type: string
      enum:
        - Stripe
        - Shopify
        - CheckoutChamp
        - Braintree
        - Mamopay
        - Maverick
        - Sticky
        - Unknown
        - API
        - 29Next
        - Square
        - Spreedly
        - Airwallex
        - NMI
        - Auth
        - Primer
        - Payarc
        - PaymentKit
        - Chargebee
        - Phoenix
        - Adyen
        - Recurly
        - Gr4vy
        - Recharge
        - Openpay
        - Finix
        - Worldpay
        - FMJ
        - Coinflow
        - Xecom
        - Vrio
        - Checkout
        - a55
        - Seal
        - GuestyPay
        - Fyntek
        - Paytech
        - SwissCRM
        - Paysight
        - Whop
        - Spark
        - Kurv
        - Everflow
        - IMerchant
        - RocketGate
      description: |-
        • Stripe → Stripe
        • Shopify → Shopify
        • CheckoutChamp → CheckoutChamp
        • Braintree → Braintree
        • Mamopay → Mamopay
        • Maverick → Maverick
        • Sticky → Sticky
        • Unknown → Unknown
        • API → API
        • 29Next → Next
        • Square → Square
        • Spreedly → Spreedly
        • Airwallex → Airwallex
        • NMI → NMI
        • Auth → Auth
        • Primer → Primer
        • Payarc → Payarc
        • PaymentKit → PaymentKit
        • Chargebee → Chargebee
        • Phoenix → Phoenix
        • Adyen → Adyen
        • Recurly → Recurly
        • Gr4vy → Gr4vy
        • Recharge → Recharge
        • Openpay → Openpay
        • Finix → Finix
        • Worldpay → Worldpay
        • FMJ → FMJ
        • Coinflow → Coinflow
        • Xecom → Xecom
        • Vrio → Vrio
        • Checkout → Checkout
        • a55 → a55
        • Seal → Seal
        • GuestyPay → GuestyPay
        • Fyntek → Fyntek
        • Paytech → Paytech
        • SwissCRM → SwissCRM
        • Paysight → Paysight
        • Whop → Whop
        • Spark → Spark
        • Kurv → Kurv
        • Everflow → Everflow
        • IMerchant → IMerchant
        • RocketGate → RocketGate
    AlertReasonCode:
      type: string
      enum:
        - Resolved
        - ResolvedPartial
        - ResolvedCancelled
        - AccountCancelled
        - CancellationProcessed
        - UnmatchedGeneral
        - UnmatchedCannotFindTransaction
        - Duplicate
        - MIDLost
        - AlreadyRefunded
        - AlreadyChargeback
        - Ineligible
        - TDS
        - CannotCancel
        - MatchedWillShip
        - EscalateChargeback
        - ContactedShipper
        - WIP
        - Error
        - None
        - NotMyDescriptor
        - Unactioned
        - ''
    DescriptorType:
      type: string
      enum:
        - Ethoca
        - CDRN
        - RDR
        - Discover
        - AMEX
        - JCB
        - Unknown
        - ''
        - Cancel
        - TC40
        - SAFE
    Bank:
      type: object
      properties:
        name:
          nullable: true
          type: string
        phone:
          nullable: true
          type: string
    BinCountry:
      type: object
      properties:
        alpha2:
          nullable: true
          type: string
        name:
          nullable: true
          type: string

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.