overlay: 1.0.0
info:
  title: Citizens Branch Locator API enrichment overlay
  version: 1.0.0
  x-generated: '2026-09-05'
  x-method: generated
  x-source: API Evangelist enrichment pass 2026-09-05; every value is read from the harvested contract
    itself or from a Citizens-published page named in the action description.
extends: citizens-financial-group-branch-locator-openapi.yml
actions:
- target: $.info
  description: Record the harvest provenance and the portal page the contract was read from. This API is
    published only on the sandbox portal - it does not appear in the production API catalog.
  update:
    x-apis-io-harvested: '2026-09-05'
    x-apis-io-source: https://sandboxdeveloper.citizensbank.com/product/127/api/106
    x-apis-io-environment: sandbox
    x-apis-io-production-listing: none - Branch Locator is absent from https://developer.citizensbank.com/api
- target: $.paths['/state/{state}/city/{city}'].get
  description: Supply a stable identifier for the state/city lookup; the published contract declares none.
  update:
    tags:
    - Branch Locator
    x-apis-io-operation-id: findBranchesByStateAndCity
    x-apis-io-operation-id-source: assigned by API Evangelist; the published contract declares none
- target: $.paths['/routingnumber/{routingnumber}'].get
  description: Supply a stable identifier for the routing-number lookup; the published contract declares none.
  update:
    tags:
    - Branch Locator
    x-apis-io-operation-id: findBranchesByRoutingNumber
    x-apis-io-operation-id-source: assigned by API Evangelist; the published contract declares none
- target: $.paths['/postalcode/{postalCode}'].get
  description: Tag the one operation Citizens does name.
  update:
    tags:
    - Branch Locator
- target: $
  description: Record the same path-template defect the ATM Locator contract carries, and the error-contract gap.
  update:
    x-published-contract-defects:
    - path: /latitude/\{latitude}/longitude/{longitude}
      defect: A stray backslash escapes the opening brace, so `latitude` is not a valid path template parameter.
      impact: A generated client emits the literal backslash in the request line. The lookup has to be hand-built.
      observed-in: openapi/_original/citizens-branch-locator-v1-sandbox.json
      note: Reported as observed, not corrected - the original contract is never mutated.
    x-error-contract-gap:
      declared-status-codes:
      - '200'
      note: No 4xx or 5xx response is declared on any operation in this contract.
- target: $.securityDefinitions['Partner Id']
  description: Record that this surface uses the locator credential family, not the commercial-banking one.
  update:
    x-credential-family: locator
    x-note: Gated by a Partner-ID header issued to registered vendors, not by the client-credentials + mTLS
      flow used across the commercial-banking and FDX surfaces.
    x-source: authentication/citizens-financial-group-authentication.yml