CarpetGuys API – Vendor Onboarding Guide

Welcome! This document explains how to access the CarpetGuys Leads API, authenticate, and handle the data it returns.

Step 1 – Get Your API Key

• Your company has been assigned a unique API key by CarpetGuys.
• This key is required to access the API.
• Treat it like a password — do not share it publicly.

Step 2 – Base URL

All requests go to this endpoint:

https://www.carpetguys.com/apis/saved-queries/hubspot.php

Step 3 – Authentication

You must include your API key in each request. Two supported methods:

Option A: Query String

https://www.carpetguys.com/apis/saved-queries/hubspot.php?api_key=YOUR_API_KEY

Option B: HTTP Header

Send your API key using the X-API-KEY header.

Example using curl:

curl -H "X-API-KEY: YOUR_API_KEY" \
"https://www.carpetguys.com/apis/saved-queries/hubspot.php"

Step 4 – Example Response

[
  {
    "type": "GRAND TOTAL",
    "custid": "",
    "name": "",
    "Contract": 45230.50
  },
  {
    "type": "Customer",
    "custid": "12345",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "555-1234",
    "status": "Closed Won",
    "leadresults": "Installed",
    "intiated": "2025-09-24 14:23:10",
    "first_contact": "2025-09-10",
    "lifetime_spend": 90320.00,
    "contacts": 4,
    "Contract": 12000.00
  },
  ...
]

• The first row is the Grand Total, showing the sum of contracts.
• Following rows are customer records with detailed lead information.

Step 5 – Error Responses

If something goes wrong, the API returns a JSON error object:

• Missing or Invalid API Key → 401 Unauthorized

  
  {"error": "Unauthorized: Invalid or missing API key"}
  
  
  

• Blacklisted IP → 403 Forbidden

  
  {"error": "Forbidden: Your IP is blocked."}
  
  
  

• Database or Query Error → 500 Internal Error

  
  {"error": "Query failed", "details": [...]}
  
  
  

Step 6 – Using the Data

• Data is returned in JSON format.

• You can consume this data into:

  • Excel/Google Sheets (via JSON connectors).
  • BI Tools (Power BI, Looker Studio, Tableau).
  • Custom Integrations in your systems.

Security Notes

• API keys are tied to your account.
• Keys may be rotated at any time — you will be notified if this happens.
• Requests from suspicious IPs may be blocked.
• Logs are kept of all failed attempts for auditing.

Quick Checklist for Vendors

• Do you have your API key from CarpetGuys?
• Are you passing the key via query string or header?
• Are you connecting from a non-blocked IP?
• Can you parse JSON data?

Postman Instructions

1. Download the file CarpetGuys-Leads-API.postman_collection.json.
2. Open Postman.
3. Click Import → File and select the file.
4. The collection will appear in your sidebar.
5. Set the API_KEY variable:
6. Click on the collection name → Variables.
7. Replace your_api_key_here with your assigned API key.
8. Run either:
   • Get Leads (Query String Auth), or
   • Get Leads (Header Auth).
   You should see JSON data in the response window.

Copy and Paste for Postman

		{
  "info": {
    "name": "CarpetGuys Leads API",
    "_postman_id": "c7c33c8b-1234-5678-90ab-carp-guys-api",
    "description": "Postman collection for accessing CarpetGuys Leads API with API Key authentication.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Leads (Query String Auth)",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "https://www.carpetguys.com/apis/saved-queries/hs.php?api_key={{API_KEY}}",
          "protocol": "https",
          "host": ["www", "carpetguys", "com"],
          "path": ["apis", "saved-queries", "hs.php"],
          "query": [
            {
              "key": "api_key",
              "value": "{{API_KEY}}"
            }
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Leads (Header Auth)",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "X-API-KEY",
            "value": "{{API_KEY}}",
            "type": "text"
          }
        ],
        "url": {
          "raw": "https://www.carpetguys.com/apis/saved-queries/hs.php",
          "protocol": "https",
          "host": ["www", "carpetguys", "com"],
          "path": ["apis", "saved-queries", "hs.php"]
        }
      },
      "response": []
    }
  ],
  "variable": [
    {
      "key": "API_KEY",
      "value": "your_api_key_here"
    }
  ]
}