Catalogs

The Catalogs API provides access to system catalogs and reference data, enabling you to retrieve standardized information for use in your applications.

Overview

Use the Catalogs API to:

Access standardized reference data

Retrieve country, state, and currency information

Get tax rate information

Access industry and category classifications

Integrate with standardized data sets

Endpoints

GET /v2/catalogs

List all available catalogs.

Authentication Required: Yes

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "countries",
      "name": "Countries",
      "description": "List of countries with ISO codes",
      "version": "1.0",
      "lastUpdated": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "currencies",
      "name": "Currencies",
      "description": "List of currencies with ISO codes",
      "version": "1.0",
      "lastUpdated": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "mexican-states",
      "name": "Mexican States",
      "description": "List of Mexican states and territories",
      "version": "1.0",
      "lastUpdated": "2024-01-01T00:00:00.000Z"
    }
  ],
  "message": "Catalogs retrieved successfully"
}

GET /v2/catalogs/{catalogId}

Get entries from a specific catalog.

Authentication Required: Yes

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results to return
`offset`	number	Number of results to skip
`search`	string	Search term for filtering

Response

Success Response (200 OK):

{
  "data": [
    {
      "code": "MX",
      "name": "Mexico",
      "isoCode": "MX",
      "currency": "MXN",
      "phoneCode": "+52"
    },
    {
      "code": "US",
      "name": "United States",
      "isoCode": "US",
      "currency": "USD",
      "phoneCode": "+1"
    }
  ],
  "catalog": {
    "id": "countries",
    "name": "Countries",
    "description": "List of countries with ISO codes"
  },
  "message": "Catalog entries retrieved successfully",
  "totalResults": 195,
  "hasMore": true,
  "next": "eyJvZmZzZXQiOjIwfQ=="
}

Available Catalogs

Countries Catalog

Access country information with ISO codes:

Response Structure:

{
  "code": "MX",
  "name": "Mexico",
  "isoCode": "MX",
  "currency": "MXN",
  "phoneCode": "+52",
  "region": "Americas"
}

Currencies Catalog

Access currency information:

Response Structure:

{
  "code": "MXN",
  "name": "Mexican Peso",
  "symbol": "$",
  "decimals": 2,
  "isActive": true
}

Mexican States Catalog

Access Mexican states and territories:

Response Structure:

{
  "code": "CDMX",
  "name": "Ciudad de México",
  "abbreviation": "CDMX",
  "region": "Centro",
  "postalCodePattern": "^[0-9]{5}$"
}

Tax Rates Catalog

Access current tax rates:

Response Structure:

{
  "country": "MX",
  "type": "VAT",
  "rate": 16.0,
  "description": "Impuesto al Valor Agregado",
  "effectiveDate": "2024-01-01T00:00:00.000Z"
}

Industry Categories Catalog

Access industry classification codes:

Response Structure:

{
  "code": "541511",
  "name": "Custom Computer Programming Services",
  "category": "Technology",
  "sector": "Professional Services"
}

Code Examples

List All Catalogs

JavaScript/Node.js:

Get Countries with Search

JavaScript/Node.js:

Python:

Build Dynamic Forms

Use catalog data to populate form dropdowns:

JavaScript Example:

Integration Examples

Client Form Validation

Use catalog data for form validation:

Tax Rate Calculation

Use tax rates catalog for calculations:

Caching Strategies

Implement caching for better performance:

JavaScript Example:

Error Handling

Handle catalog API errors gracefully:

Best Practices

Caching: Cache catalog data to reduce API calls

Fallback Data: Provide fallback data for critical catalogs

Search Optimization: Use search parameters to reduce data transfer

Pagination: Handle pagination for large catalogs

Version Monitoring: Monitor catalog versions for updates

Error Handling: Implement robust error handling for catalog failures

Next Steps

Use catalogs in client forms

Integrate tax rates with invoicing

Build dynamic service categories

Catalogs

Catalogs#

Overview#

Endpoints#

GET /v2/catalogs#

Response#

GET /v2/catalogs/{catalogId}#

Query Parameters#

Response#

Available Catalogs#

Countries Catalog#

Currencies Catalog#

Mexican States Catalog#

Tax Rates Catalog#

Industry Categories Catalog#

Code Examples#

List All Catalogs#

Get Countries with Search#

Build Dynamic Forms#

Integration Examples#

Client Form Validation#

Tax Rate Calculation#

Caching Strategies#

Error Handling#

Best Practices#

Next Steps#

Catalogs

Overview

Endpoints

GET /v2/catalogs

Response

GET /v2/catalogs/{catalogId}

Query Parameters

Response

Available Catalogs

Countries Catalog

Currencies Catalog

Mexican States Catalog

Tax Rates Catalog

Industry Categories Catalog

Code Examples

List All Catalogs

Get Countries with Search

Build Dynamic Forms

Integration Examples

Client Form Validation

Tax Rate Calculation

Caching Strategies

Error Handling

Best Practices

Next Steps