openapi: 3.0.2
info:
  description: FED API is designed to create FEDACH and FEDWIRE dictionaries.  The FEDACH dictionary contains receiving depository financial institutions (RDFI’s) which are qualified to receive ACH entries.  The FEDWIRE dictionary contains receiving depository financial institutions (RDFI’s) which are qualified to receive WIRE entries.  This project implements a modern REST HTTP API for FEDACH Dictionary and FEDWIRE Dictionary.
  version: v1
  title: FED API
  contact:
    name: FED API Support
    url: 'https://github.com/moov-io/fed'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: 'http://localhost:8086'
    description: Local development
tags:
  - name: FED
    description: FEDACH Dictionary and FEDWIRE Dictionary
paths:
  /ping:
    get:
      tags:
        - FED
      summary: Ping the FED service to check if running
      operationId: ping
      responses:
        '200':
          description: Service is running properly
  /fed/ach/search:
    get:
      tags:
        - FED
      summary: Search FEDACH names and metadata
      operationId: searchFEDACH
      parameters:
        - $ref: '#/components/parameters/requestId'
        - name: name
          in: query
          schema:
            type: string
            example: Farmers State Bank
          description: FEDACH Financial Institution Name
        - name: routingNumber
          in: query
          schema:
            type: string
            minimum: 2
            maximum: 9
            example: 325183657
          description: FEDACH Routing Number for a Financial Institution
        - name: state
          in: query
          schema:
            type: string
            minimum: 2
            maximum: 2
            example: PA
          description: FEDACH Financial Institution State
        - name: city
          in: query
          schema:
            type: string
            example: 325183657
          description: FEDACH Financial Institution City
        - name: postalCode
          in: query
          schema:
            type: string
            minimum: 5
            maximum: 5
            example: 19753
          description: FEDACH Financial Institution Postal Code
        - name: limit
          in: query
          schema:
            type: integer
            example: 499
          description: Maximum results returned by a search
      responses:
        '200':
          description: FEDACH Participants returned from a search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACHDictionary'
        '400':
          description: Invalid user information, check error(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error, check error(s) and report the issue.
  /fed/wire/search:
    get:
      tags:
        - FED
      summary: Search FEDWIRE names and metadata
      operationId: searchFEDWIRE
      parameters:
        - $ref: '#/components/parameters/requestId'
        - name: name
          in: query
          schema:
            type: string
            example: First Bank
          description: FEDWIRE Financial Institution Name
        - name: routingNumber
          in: query
          schema:
            type: string
            minimum: 2
            maximum: 9
            example: 324172465
          description: FEDWIRE Routing Number for a Financial Institution
        - name: state
          in: query
          schema:
            type: string
            minimum: 2
            maximum: 2
            example: PA
          description: FEDWIRE Financial Institution State
        - name: city
          in: query
          schema:
            type: string
            example: 325183657
          description: FEDWIRE Financial Institution City
        - name: limit
          in: query
          schema:
            type: integer
            example: 499
          description: Maximum results returned by a search
      responses:
        '200':
          description: FEDWIRE Participants returned from a search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WIREDictionary'
        '400':
          description: Invalid user information, check error(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error, check error(s) and report the issue.
components:
  schemas:
    ACHDictionary:
      description: Search results containing ACHDictionary of Participants
      properties:
        ACHParticipants:
          type: array
          items:
            $ref: '#/components/schemas/ACHParticipant'
    ACHParticipant:
      description: ACHParticipant holds a FedACH dir routing record as defined by Fed ACH Format.  https://www.frbservices.org/EPaymentsDirectory/achFormat.html
      properties:
        routingNumber:
          type: string
          minimum: 9
          maximum: 9
          description: The institution's routing number
          example: 231380104
        officeCode:
          type: string
          minimum: 1
          maximum: 1
          description: Main/Head Office or Branch. O=main B=branch
          example: O
        servicingFRBNumber:
          type: string
          minimum: 9
          maximum: 9
          description: Servicing Fed's main office routing number
          example: 101000048
        recordTypeCode:
          type: string
          minimum: 1
          maximum: 1
          description: |-
            The code indicating the ABA number to be used to route or send ACH items to the RDFI
            0 = Institution is a Federal Reserve Bank
            1 = Send items to customer routing number
            2 = Send items to customer using new routing number field
          example: 1
        revised:
          type: string
          maximum: 8
          description: |-
            Date of last revision
            YYYYMMDD
            Blank
          example: YYYYMMDD, or blank
        newRoutingNumber:
          type: string
          minimum: 9
          maximum: 9
          description: Financial Institution's new routing number resulting from a merger or renumber
          example: 122203950
        customerName:
          type: string
          maximum: 36
          description: Financial Institution Name
          example: BANK OF AMERICA, N.A., FEDERAL RESERVE BANK
        achLocation:
          type: object
          description: FEDACH delivery address
          items:
            $ref: '#/components/schemas/ACHLocation'
        phoneNumber:
          type: string
          minimum: 10
          maximum: 10
          description: The Financial Institution's phone number
          example: 8004460135
        statusCode:
          type: string
          minimum: 1
          maximum: 1
          description: |-
            Code is based on the customers receiver code
            1 = Receives Gov/Comm
          example: 1
        viewCode:
          type: string
          minimum: 1
          maximum: 1
          description: |-
            Code is current view
            1 = Current view
          example: 1
    ACHLocation:
      description: ACHLocation is the FEDACH delivery address
      properties:
        address:
          type: string
          maximum: 36
          description: Street Address
          example: PO BOX 27025
        city:
          type: string
          maximum: 20
          description: City
          example: RICHMOND
        state:
          type: string
          minimum: 2
          maximum: 2
          description: State
          example: VA
        postalCode:
          type: string
          minimum: 5
          maximum: 5
          description: Postal Code
          example: 23261
        postalExtension:
          type: string
          minimum: 4
          maximum: 4
          description: Postal Code Extension
          example: 7025
    WIREDictionary:
      description: Search results containing WIREDictionary of Participants
      properties:
        WIREParticipants:
          type: array
          items:
            $ref: '#/components/schemas/WIREParticipant'
    WIREParticipant:
      description: WIREParticipant holds a FedWIRE dir routing record as defined by Fed WIRE Format.  https://frbservices.org/EPaymentsDirectory/fedwireFormat.html
      properties:
        routingNumber:
          type: string
          minimum: 9
          maximum: 9
          description: The institution's routing number
          example: 231380104
        telegraphicName:
          type: string
          maximum: 18
          description: Short name of financial institution
          example: FRB-BOS (FEDERAL RESERVE BANK OF BOSTON)
        customerName:
          type: string
          maximum: 36
          description: Financial Institution Name
          example: FEDERAL RESERVE BANK OF BOSTON
        wireLocation:
          type: object
          description: FEDWIRE Delivery Address
          items:
            $ref: '#/components/schemas/WIRELocation'
        fundsTransferStatus:
          type: string
          minimum: 1
          maximum: 1
          description: |-
            Designates funds transfer status
            Y = Eligible
            N = Ineligible
          example: Y
        fundsSettlementOnlyStatus:
          type: string
          maximum: 1
          description: |-
            Designates funds settlement only status
            S = Settlement-Only or blank
            Blank
          example: S
        bookEntrySecuritiesTransferStatus:
          type: string
          minimum: 1
          maximum: 1
          description: |-
            Designates book entry securities transfer status
            Y = Eligible
            N = Ineligible
          example: N
        date:
          type: string
          maximum: 8
          description: |-
            Date of last revision
            YYYYMMDD
            Blank
          example: YYYYMMDD
    WIRELocation:
      description: WIRELocation is the FEDWIRE delivery address
      properties:
        city:
          type: string
          maximum: 25
          description: City
          example: BOSTON
        state:
          type: string
          minimum: 2
          maximum: 2
          description: State
          example: MA
    Error:
      required:
        - error
      properties:
        error:
          type: string
          description: An error message describing the problem intended for humans.
          example: Validation error(s) present.
  parameters:
    requestId:
      in: header
      name: X-Request-Id
      description: Optional Request ID allows application developer to trace requests through the systems logs
      schema:
        type: string
        example: 94c825ee