openapi: 3.2.0
info:
  title: Modulr Cards Bulk Operations API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Cards Bulk Operations
paths:
  /bulk-cards:
    get:
      tags:
      - Cards Bulk Operations
      summary: List active bulk card requests
      description: Retrieve non-terminated (not processed/archived/deleted) bulk card requests for current user
      operationId: getActiveBulkCardRequests
      parameters:
      - name: page
        in: query
        description: Page to retrieve (0 indexed)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          description: Page to retrieve (0 indexed)
          example: 0
          minimum: 0
        example: 0
      - name: size
        in: query
        description: Page size
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          description: Page size
          example: 500
          maximum: 500
          minimum: 1
        example: 500
      responses:
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Forbidden. Incorrect permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkRequestPageResponse'
      security:
      - HMAC: []
      - TOKEN: []
    post:
      tags:
      - Cards Bulk Operations
      summary: Submit bulk cards operations
      description: Send Card details for Create/Update/Cancel/Patch Cards in bulk. Processing part will be asynchronous
      operationId: submitBulkCardOperations
      parameters:
      - name: validateOnly
        in: query
        description: Flag of whether to validate batch entries and not submit for processing. Default false.
        required: true
        style: form
        explode: true
        schema:
          type: boolean
      - name: keepOperations
        in: query
        description: Flag of whether to persist operations for batch request. Can only be true if validateOnly is true, default is false.
        required: true
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/card.BulkCardsOpsRequest'
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsOpsResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Forbidden. Incorrect permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsOpsResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /bulk-cards/upload:
    post:
      tags:
      - Cards Bulk Operations
      summary: Upload CSV file with bulk card operations
      description: Allow clients to upload csv file with create, update and change card status requests
      operationId: uploadBulkCards
      parameters:
      - name: validateOnly
        in: query
        description: Flag of whether to validate batch entries and not submit for processing. Default false.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: keepEntries
        in: query
        description: Flag of whether to persist entries for batch request. Can only be true if validateOnly is true, default is false
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: overrideFile
        in: query
        description: Flag of whether to replace existing file with same name. Default false.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file containing bulk card operations
              required:
              - file
      responses:
        '202':
          description: CSV file accepted and validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsOpsResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Forbidden. Incorrect permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsOpsResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /bulk-cards/{bulkRequestId}:
    get:
      tags:
      - Cards Bulk Operations
      summary: Get bulk cards by id
      description: Get all batch specific information
      operationId: getBulkCardsInfo
      parameters:
      - name: bulkRequestId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsInfoResponse'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Forbidden. Incorrect permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card.BulkCardsInfoResponse'
      security:
      - HMAC: []
      - TOKEN: []
    delete:
      tags:
      - Cards Bulk Operations
      summary: Mark bulk request as deleted
      description: Allows client to mark bulk request as deleted if not already processed, processed with errors or archived
      operationId: deleteBulkRequest
      parameters:
      - name: bulkRequestId
        in: path
        description: Business id of bulk request to mark as deleted
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Bulk request successfully marked as deleted
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card.MessageResponse'
        '403':
          description: Forbidden. Incorrect permissions
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    card.BulkCardsOpsRequest:
      type: object
      properties:
        externalRef:
          type: string
        operations:
          type: array
          items:
            $ref: '#/components/schemas/card.BulkCardsOperation'
          minItems: 1
      required:
      - operations
    card.Error:
      type: object
      properties:
        operationIndex:
          type: integer
          format: int64
        operationId:
          type: string
        field:
          type: string
        description:
          type: string
    card.BulkCardsOperation:
      type: object
      properties:
        id:
          type: string
        operationType:
          type: string
          enum:
          - CREATE
          - UPDATE
          - PATCH
          - CANCEL
        payload: {}
        cardId:
          type: string
        accountId:
          type: string
      required:
      - operationType
      - payload
    card.BulkCardsInfoResponse:
      type: object
      properties:
        id:
          type: string
        source:
          type: string
          enum:
          - API
          - FILE_UPLOAD
        originalName:
          type: string
        submissionTime:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - SUBMITTED
          - VALIDATED
          - VALIDATED_WITH_ERRORS
          - PROCESSING
          - PARTIALLY_PROCESSED_WITH_ERRORS
          - PARTIALLY_PROCESSED
          - PROCESSED
          - ARCHIVED
          - DELETED
        totalOperations:
          type: integer
          format: int64
        successfulOperations:
          type: integer
          format: int64
        failedOperations:
          type: integer
          format: int64
        processedOperations:
          type: integer
          format: int64
        createdBy:
          type: string
        externalRef:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/card.Error'
    card.BulkCardsOpsResponse:
      type: object
      properties:
        bulkRequestId:
          type: string
        submissionTimestamp:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - SUBMITTED
          - VALIDATED
          - VALIDATED_WITH_ERRORS
          - PROCESSING
          - PARTIALLY_PROCESSED_WITH_ERRORS
          - PARTIALLY_PROCESSED
          - PROCESSED
          - ARCHIVED
          - DELETED
    card.BulkRequestPageResponse:
      type: object
      properties:
        content:
          type: array
          description: List of responses on the current page
          items:
            $ref: '#/components/schemas/card.BulkRequestResponse'
        size:
          type: integer
          format: int32
          description: Page size
        totalSize:
          type: integer
          format: int64
          description: Total count
        page:
          type: integer
          format: int32
          description: Current page number, 0 based; i.e first-page = 0, second-page = 1
        totalPages:
          type: integer
          format: int32
          description: Total pages
      required:
      - content
      - page
      - size
      - totalPages
      - totalSize
    card.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    card.BulkRequestResponse:
      type: object
      description: Bulk card request details
      properties:
        id:
          type: string
          description: Bulk request ID
          example: B000000001
        filename:
          type: string
          description: Filename of the uploaded file
          example: example.csv
        createdDate:
          type: string
          format: date-time
          description: Date and time when the bulk request was created
        createdBy:
          type: string
          description: User ID who created the bulk request
          example: U000001
        status:
          type: string
          description: Status of the bulk request
          example: VALIDATED_WITH_ERRORS
        totalOperations:
          type: integer
          format: int64
          description: Total number of operations in the bulk request
          example: 200
        successfulOperations:
          type: integer
          format: int64
          description: Number of successful operations
          example: 194
        failedOperations:
          type: integer
          format: int64
          description: Number of failed operations
          example: 6
        processedOperations:
          type: integer
          format: int64
          description: Number of processed operations
          example: 142
        externalRef:
          type: string
          description: External reference
          example: example ref
      required:
      - createdBy
      - createdDate
      - failedOperations
      - id
      - status
      - successfulOperations
      - totalOperations
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false