# Catalogs

<p> This section provides the **Catalogs** endpoints required to retrieve reference and configuration data necessary to construct and validate outbound money transfer transactions within the ViaBlocks platform. <br/> Catalog endpoints expose corridor-specific operational data including supported countries, currencies, delivery methods, payout networks, payout locations, identification document types, industries, remittance purposes, and source-of-funds classifications. <br/> These endpoints are read-only and must be consumed prior to transaction creation to ensure: <br/> <ul> <li>Compliance with country-specific regulatory requirements  </li> <li>Correct validation of amounts, currencies, and payout configurations  </li> <li>Dynamic population of UI selection fields  </li> <li>Alignment with real-time operational rules and payout network constraints  </li> </ul> Partners should not hardcode catalog values and should instead retrieve them programmatically to maintain synchronization with configuration updates, compliance changes, and corridor availability.</p>

## /catalogs/master/location

 - [GET /catalogs/master/location](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1master~1location/get.md): ## Purpose
Searches master location data (city/state/country) using a partial filter value.

Results are normalized to ViaBlocks field naming conventions.

## When to use
Use this endpoint to:
- Support UI search/type-ahead for location entry
- Normalize and validate user-entered location data before transaction creation

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- Input is provided via the filterValue query parameter.
- Results may contain multiple matches for the same city name across different states/countries.

## Common errors
- 400 Validation errors (missing/invalid filterValue)
- 401 Invalid credentials
- 404 No matches found (when applicable)
- 500 Internal error

## /catalogs/master/zipcodes/{idzipcode}

 - [GET /catalogs/master/zipcodes/{idzipcode}](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1master~1zipcodes~1%7Bidzipcode%7D/get.md): ## Purpose
Retrieves ZIP code metadata including city name, state ISO code, and full state name.

## When to use
Use this endpoint to:
- Auto-populate city/state after ZIP entry
- Validate sender address data prior to transaction creation

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- idzipcode is provided as a path parameter.

## Common errors
- 400 Validation errors
- 401 Invalid credentials
- 404 ZIP code not found (when applicable)
- 500 Internal error

## /catalogs/google-maps-api

 - [POST /catalogs/google-maps-api](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1google-maps-api/post.md): ## Purpose
Proxy endpoint for Google Maps operations used for:
- Address autocomplete (suggestions)
- Geocoding (structured address and coordinates)

## When to use
Use this endpoint when you need:
- Type-ahead address suggestions for sender/beneficiary addresses
- Normalized geocoding results including latitude/longitude

## Authentication
Requires x-client-id and x-secret-key headers.

## Request behavior
- event=autocomplete returns an array of suggestion objects
- event=geocode returns an array of geocoding result objects (including geometry)

## Notes
- Response structure depends on the event.
- The response is returned as an array (no wrapper object).

## Common errors
- 400 Validation errors (missing/invalid address or event)
- 401 Invalid credentials
- 500 Internal error

## /catalogs/countries/{idCountry}/currencies

 - [GET /catalogs/countries/{idCountry}/currencies](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1currencies/get.md): ## Purpose
Returns the list of supported currencies for the specified country.

## When to use
Use this endpoint to:
- Populate currency selection options
- Validate corridor currency support before transaction creation

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- idCountry is an ISO3 country code (e.g., USA, MEX, COL).

## Common errors
- 400 Validation errors
- 401 Invalid credentials
- 404 Country not found (when applicable)
- 500 Internal error

## /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts

 - [GET /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1deliver-methods~1%7Biddelivery%7D~1payouts/get.md): ## Purpose
Returns the available payout methods for a destination country and delivery method.

## When to use
Use this endpoint to:
- Populate payout provider lists (banks, networks, wallet providers)
- Retrieve corridor constraints (min/max, fee, exchange rate)
- Validate account formats using the provided accNumberRegex (when present)

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- idCountry is an ISO3 country code.
- idDelivery represents the delivery method (e.g., bank deposit vs cash pickup; see your configured codes).
- The response may include validation helpers like accNumberRegex.

## Common errors
- 400 Validation errors
- 401 Invalid credentials
- 404 Configuration not found (when applicable)
- 500 Internal error

## /catalogs/countries/{idCountry}/identifications

 - [GET /catalogs/countries/{idCountry}/identifications](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1identifications/get.md): ## Purpose
Returns the supported identification document types for the specified country.

## When to use
Use this endpoint to:
- Populate document type selection during onboarding
- Enforce corridor-specific document requirements (expiration date, back side)

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- Response includes flags such as expirationDateRequired and backSideRequired.

## Common errors
- 400 Validation errors
- 401 Invalid credentials
- 404 Country not found (when applicable)
- 500 Internal error

## /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts/{idpayout}/locations

 - [GET /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts/{idpayout}/locations](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1deliver-methods~1%7Biddelivery%7D~1payouts~1%7Bidpayout%7D~1locations/get.md): ## Purpose
Returns the available physical payout locations (branches/agents) for a selected payout method.

## When to use
Use this endpoint to:
- Populate branch/location selection for cash pickup flows
- Display branch details including address, business hours, and pickup instructions

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- Requires idCountry, idDelivery, and idpayout.
- Response may include fields such as WhatToBring and BusinessHours for customer guidance.

## Common errors
- 400 Validation errors
- 401 Invalid credentials
- 404 Locations not found (when applicable)
- 500 Internal error

## /catalogs/industry

 - [GET /catalogs/industry](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1industry/get.md): ## Purpose
Returns the supported industry categories and associated job titles used for onboarding and compliance classification.

## When to use
Use this endpoint to:
- Populate industry/job selection lists
- Standardize occupation classification for KYC/AML and reporting

## Authentication
Requires x-client-id and x-secret-key headers.

## Common errors
- 401 Invalid credentials
- 500 Internal error

## /catalogs/wire-purpose

 - [GET /catalogs/wire-purpose](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1wire-purpose/get.md): ## Purpose
Returns the supported remittance purposes (reason for transfer) used for compliance classification and reporting.

## When to use
Use this endpoint to:
- Populate “purpose of transfer” selections
- Standardize purpose codes for corridor rules and regulatory reporting

## Authentication
Requires x-client-id and x-secret-key headers.

## Common errors
- 401 Invalid credentials
- 500 Internal error

## /catalogs/funds-origin

 - [GET /catalogs/funds-origin](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1funds-origin/get.md): ## Purpose
Returns supported source-of-funds options used for compliance and risk classification.

## When to use
Use this endpoint to:
- Populate “source of funds” selections during onboarding
- Standardize source-of-funds values for compliance workflows and reporting

## Authentication
Requires x-client-id and x-secret-key headers.

## Notes
- Response includes an order field that can be used to sort options in UI.

## Common errors
- 401 Invalid credentials
- 500 Internal error