# List cards in Protection Bulletin

Get all Pismo-issued cards in the Protection Bulletin with filtering options.

 **Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Card issuing - Protection Bulletin",
    "version": "2.0.3",
    "description": "Bulletin API endpoints",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/protection-bulletin",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Bulletin",
      "description": "Endpoints to manage cards with the Protection Bulletin"
    }
  ],
  "components": {
    "parameters": {
      "AuthHeader": {
        "in": "header",
        "name": "Authorization",
        "required": true,
        "description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.",
        "schema": {
          "type": "string",
          "example": "Bearer eyJhbGci...IUzUx"
        }
      },
      "BeginDateQuery": {
        "name": "begin_date",
        "in": "query",
        "description": "Beginning date filter, format = `yyyy-mm-dd`",
        "required": true,
        "schema": {
          "type": "string",
          "example": "2025-01-01"
        }
      },
      "EndDateQuery": {
        "name": "end_date",
        "in": "query",
        "description": "End date filter, format = `yyyy-mm-dd`",
        "required": true,
        "schema": {
          "type": "string",
          "example": "2025-01-30"
        }
      },
      "NetworkBrandTypeQuery": {
        "name": "network_brand_type",
        "in": "query",
        "description": "Card network brand.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "ELO",
            "MASTERCARD",
            "VISA"
          ],
          "example": "ELO"
        }
      },
      "PageQuery": {
        "name": "page",
        "in": "query",
        "description": "Page to return. Default is `1`.",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 1,
          "example": 2,
          "minimum": 1
        }
      },
      "PerPageQuery": {
        "name": "per_page",
        "in": "query",
        "description": "Number of items per page to return. Default is `10`.",
        "required": false,
        "schema": {
          "type": "integer",
          "default": 10,
          "example": 20,
          "minimum": 1
        }
      },
      "ProgramIdQuery": {
        "name": "program_id",
        "in": "query",
        "description": "Pismo program ID",
        "required": false,
        "schema": {
          "type": "number",
          "example": 1010
        }
      },
      "StateQuery": {
        "name": "state",
        "in": "query",
        "description": "Is card blocked or not in the network brand? \n\nWhen empty, it means the network did not successfully receive the action.\n",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "",
            "BLOCKED",
            "UNBLOCKED"
          ],
          "example": "BLOCKED"
        }
      },
      "StatusQuery": {
        "name": "status",
        "in": "query",
        "description": "Request processing status.",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "PENDING",
            "SUCCESS",
            "FAILED"
          ],
          "example": "PENDING"
        }
      }
    },
    "schemas": {
      "BulletinResponseListModel": {
        "type": "object",
        "description": "Response model for the Bulletin API list.",
        "properties": {
          "current_page": {
            "$ref": "#/components/schemas/CurrentPage"
          },
          "pages": {
            "$ref": "#/components/schemas/Pages"
          },
          "per_page": {
            "$ref": "#/components/schemas/PerPage"
          },
          "total_items": {
            "$ref": "#/components/schemas/TotalItems"
          },
          "items": {
            "$ref": "#/components/schemas/Items"
          }
        }
      },
      "ErrorDetailMessageModel": {
        "description": "Detailed information about the error.",
        "type": "object",
        "properties": {
          "payload": {
            "type": "array",
            "description": "List of payload-related error details.",
            "items": {
              "$ref": "#/components/schemas/ErrorPayloadMessageModel"
            }
          },
          "header": {
            "type": "array",
            "description": "List of header-related error details.",
            "items": {
              "$ref": "#/components/schemas/ErrorHeaderMessageModel"
            }
          },
          "parameters": {
            "type": "array",
            "description": "List of parameter-related error details.",
            "items": {
              "$ref": "#/components/schemas/ErrorParameterMessageModel"
            }
          }
        }
      },
      "ErrorHeaderMessageModel": {
        "description": "Details about header-related errors.",
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Header name related to the error.",
            "example": "x-field"
          },
          "message": {
            "type": "string",
            "description": "Error message for the header.",
            "example": "Generic error"
          }
        }
      },
      "ErrorMessageModel": {
        "title": "ErrorModel",
        "type": "object",
        "description": "API generic returned error.",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "description": "Error description."
          },
          "http_status_code": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "details": {
            "$ref": "#/components/schemas/ErrorDetailMessageModel"
          }
        }
      },
      "ErrorParameterMessageModel": {
        "description": "Details about parameter-related errors.",
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Parameter name related to the error.",
            "example": "query_parameter"
          },
          "message": {
            "type": "string",
            "description": "Parameter error message"
          }
        }
      },
      "ErrorPayloadMessageModel": {
        "description": "Details about payload-related errors.",
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field name related to the error.",
            "example": "field"
          },
          "message": {
            "type": "string",
            "description": "Error message for the field.",
            "example": "Generic error"
          }
        }
      },
      "CardID": {
        "description": "Pismo card ID.",
        "type": "number",
        "example": 10203040
      },
      "CardTrackNumber": {
        "description": "Pismo card track number.",
        "type": "number",
        "example": 1
      },
      "CreatedAt": {
        "type": "string",
        "description": "Date and time when the Protection Bulletin registration was created. Format = ISO 8601.",
        "format": "yyyy-mm-dd hh:mm:ss",
        "example": "2025-04-22 20:31:50"
      },
      "CurrentPage": {
        "type": "integer",
        "example": 1,
        "description": "Current page."
      },
      "Items": {
        "type": "array",
        "description": "List of Bulletin Cards",
        "items": {
          "type": "object",
          "description": "Response model for the Bulletin API.",
          "properties": {
            "card_id": {
              "$ref": "#/components/schemas/CardID"
            },
            "org_id": {
              "$ref": "#/components/schemas/OrgID"
            },
            "program_id": {
              "$ref": "#/components/schemas/ProgramID"
            },
            "network_brand_type": {
              "$ref": "#/components/schemas/NetworkBrandType"
            },
            "created_at": {
              "$ref": "#/components/schemas/CreatedAt"
            },
            "updated_at": {
              "$ref": "#/components/schemas/UpdatedAt"
            },
            "network_track_number": {
              "$ref": "#/components/schemas/NetworkTrackNumber"
            },
            "state": {
              "$ref": "#/components/schemas/State"
            },
            "status": {
              "$ref": "#/components/schemas/Status"
            },
            "purge_date": {
              "$ref": "#/components/schemas/PurgeDate"
            },
            "was_automatically_purged": {
              "$ref": "#/components/schemas/WasAutomaticallyPurged"
            },
            "card_track_number": {
              "$ref": "#/components/schemas/CardTrackNumber"
            },
            "region_code": {
              "$ref": "#/components/schemas/RegionCode"
            }
          }
        }
      },
      "NetworkBrandType": {
        "type": "string",
        "description": "Card network brand.",
        "enum": [
          "ELO",
          "MASTERCARD",
          "VISA"
        ],
        "example": "ELO"
      },
      "NetworkTrackNumber": {
        "type": "string",
        "description": "Created in the internal system to track the card's event history. This is a combination between the tenant and the truncated random uuid.",
        "example": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c"
      },
      "OrgID": {
        "description": "Pismo organization/tenant ID.",
        "type": "string",
        "example": "TN-123XXX-XXXXXX-XXXXXXX"
      },
      "Pages": {
        "type": "integer",
        "example": 1,
        "description": "Total number of pages."
      },
      "PerPage": {
        "type": "integer",
        "example": 100,
        "description": "Items per page."
      },
      "ProgramID": {
        "description": "Pismo program ID.",
        "type": "number",
        "example": 1010
      },
      "PurgeDate": {
        "type": "string",
        "description": "Date when the card will be removed from the Protection Bulletin in the network brand. Format = yyyy-mm-dd.\n",
        "format": "yyyy-mm-dd",
        "example": "2025-04-22"
      },
      "RegionCode": {
        "type": "array",
        "description": "Region code contains one or more Account Screen Authorization File (ASAF) region codes that define the distribution of a Visa cardholder account number in Card Recovery Bulletin Service files. **REQUIRED** for Visa. \n  `0` - No Bulletin / V.I.P. Only (cannot be combined with other region codes)\n  `A` - All Asia-Pacific region countries\n  `B` - All  Central Europe, Middle East, and Africa (CEMEA) region countries.\n  `C` - All Visa Canada\n  `D` - National Card Recovery Bulletin\n  `E` - All European countries\n  `F` - All Latin America and Caribbean (LAC) region countries \n\nRegion codes can be in any order, except no other region code can be specified in combination with region code 0.\n\nVisa documentation: VisaNet Authorization-Only Online Messages – Technical Specifications - Table 215: Field 127E.2 Account Screen Authorization File (ASAF) Region Codes\n",
        "items": {
          "type": "string",
          "enum": [
            "0",
            "A",
            "B",
            "C",
            "D",
            "E",
            "F"
          ]
        }
      },
      "State": {
        "type": "string",
        "description": "Is card blocked or not in the network brand? When the state is empty, it means the network brand did not successfully receive any action.\n",
        "enum": [
          "",
          "BLOCKED",
          "UNBLOCKED"
        ],
        "example": "BLOCKED"
      },
      "Status": {
        "type": "string",
        "description": "Request processing status.",
        "enum": [
          "PENDING",
          "SUCCESS",
          "FAILED"
        ],
        "example": "PENDING"
      },
      "TotalItems": {
        "type": "integer",
        "example": 10,
        "description": "Total number of items in page."
      },
      "UpdatedAt": {
        "type": "string",
        "description": "Date and time when the Protection Bulletin was updated. Format = ISO 8601.\n",
        "format": "yyyy-mm-dd hh:mm:ss",
        "example": "2025-04-22 20:31:50"
      },
      "WasAutomaticallyPurged": {
        "type": "boolean",
        "description": "Was card removed from the network brand on the purge date?\n",
        "example": true
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error.\n",
        "bearerFormat": "JWT"
      }
    },
    "responses": {
      "401": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessageModel"
            },
            "examples": {
              "Missing or invalid Authorization header": {
                "value": {
                  "code": "EBLT0005",
                  "message": "Missing or invalid Authorization header",
                  "http_status_code": 401
                }
              },
              "Invalid Authorization header, missing account-id": {
                "value": {
                  "code": "EBLT0006",
                  "message": "Invalid Authorization header, missing account-id",
                  "http_status_code": 401
                }
              },
              "Invalid Authorization header, missing tenant": {
                "value": {
                  "code": "EBLT0007",
                  "message": "Invalid Authorization header, missing tenant",
                  "http_status_code": 401
                }
              }
            }
          }
        }
      },
      "500": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessageModel"
            },
            "examples": {
              "Something went wrong when try to process a request in another service": {
                "value": {
                  "code": "EBLT9998",
                  "message": "Something went wrong when try to process a request in Programs API using ID: 123",
                  "http_status_code": 500
                }
              },
              "Something went wrong, please try again later": {
                "value": {
                  "code": "EBLT9999",
                  "message": "Something went wrong, please try again later",
                  "http_status_code": 500
                }
              }
            }
          }
        }
      },
      "504": {
        "description": "Gateway Timeout",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessageModel"
            },
            "examples": {
              "Request timeout": {
                "value": {
                  "code": "EBLT0001",
                  "message": "Request timeout",
                  "http_status_code": 504
                }
              }
            }
          }
        }
      },
      "200ListBulletin": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BulletinResponseListModel"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/bulletin": {
      "get": {
        "summary": "List cards in Protection Bulletin",
        "operationId": "list-v1-bulletin",
        "description": "Get all Pismo-issued cards in the Protection Bulletin with filtering options.\n\n **Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.\n",
        "tags": [
          "Bulletin"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthHeader"
          },
          {
            "$ref": "#/components/parameters/BeginDateQuery"
          },
          {
            "$ref": "#/components/parameters/EndDateQuery"
          },
          {
            "$ref": "#/components/parameters/PerPageQuery"
          },
          {
            "$ref": "#/components/parameters/PageQuery"
          },
          {
            "$ref": "#/components/parameters/ProgramIdQuery"
          },
          {
            "$ref": "#/components/parameters/NetworkBrandTypeQuery"
          },
          {
            "$ref": "#/components/parameters/StatusQuery"
          },
          {
            "$ref": "#/components/parameters/StateQuery"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200ListBulletin"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "504": {
            "$ref": "#/components/responses/504"
          }
        }
      }
    }
  }
}
```