openapi: 3.0.3
info:
  title: IIN Lookup API
  version: 1.0.0
  description: |
    This API retrieves metadata about credit or debit cards based on the initial digits of the card number (IIN/BIN).
servers:
  - url: https://api.iinapi.com
paths:
  /iin:
    get:
      summary: Retrieve card metadata using IIN/BIN digits
      description: |
        Accepts the first 6 to 11 digits of a credit or debit card number and returns vendor, location, and other metadata.
      parameters:
        - in: query
          name: key
          required: true
          schema:
            type: string
          description: API key for authentication
        - in: query
          name: digits
          required: true
          schema:
            type: string
            pattern: '^\d{6,11}$'
          description: First 6 to 11 digits of the card number
      responses:
        '200':
          description: The command was processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  result:
                    type: object
                    properties:
                      Bin:
                        type: integer
                        example: 324000
                      CardBrand:
                        type: string
                        example: LOCAL BRAND
                      IssuingInstitution:
                        type: string
                        example: BRANCH BANKING AND TRUST COMPANY
                      CardType:
                        type: string
                        example: DEBIT
                      CardCategory:
                        type: string
                        example: BUSINESS
                      IssuingCountry:
                        type: string
                        example: UNITED STATES
                      IssuingCountryCode:
                        type: string
                        example: US
        '400':
          description: Command unknown – the endpoint is not valid.
        '401':
          description: Unauthorized – incorrect key, IP not whitelisted, or account banned.
        '402':
          description: Billing – refused due to a billing issue with the account.
        '405':
          description: Command invalid – incorrect HTTP method for the endpoint.
        '409':
          description: Command malformed – missing or incorrectly formatted parameters.
        '422':
          description: Unprocessable – well-formed request, but a technical issue prevented processing.
        '500':
          description: Internal Server Error – server encountered an internal issue.