{
  "openapi": "3.1.0",
  "info": {
    "title": "DealerData API",
    "version": "1.1.0",
    "description": "Verified contacts and store data for US and Canadian car dealerships. Docs: https://usedealerdata.com/docs/api"
  },
  "servers": [
    {
      "url": "https://api.usedealerdata.com/functions/v1/api/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "dd_live_ API key"
      }
    }
  },
  "paths": {
    "/contacts": {
      "get": {
        "summary": "Search contacts (free)",
        "description": "Dealership staff matching the filters, best ranked first. Emails are masked and phones hidden until unlocked; the row id is what you pass to /unlock. Each page counts toward the daily search allowance.",
        "operationId": "get_contacts",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Job role keys. Values: owner_dealer_principal, gm, gsm, sales_manager, used_car_manager, fi_manager, internet_sales, bdc_manager, marketing, fixed_ops_director, service_manager, parts_manager, fleet_manager, sales_staff, service_staff, accounting, hr, it, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "seniority",
            "in": "query",
            "required": false,
            "description": "Seniority. Values: owner, executive, director, manager, staff. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Job title contains this phrase (case insensitive), e.g. \"internet director\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title_any",
            "in": "query",
            "required": false,
            "description": "Comma or | separated titles. A contact matches when its title holds every word of any one entry, in any order, e.g. \"internet director|digital manager\". Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country codes. Values: US, CA. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "State or province codes, e.g. TX,FL,ON. Values: two-letter US state or Canadian province codes. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Exact city names (case insensitive), e.g. Houston,Dallas. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any. Values: OEM names as listed by GET /filters. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Store type. Values: franchise, independent, group, powersports_rv, specialty. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Dealer group name contains this, e.g. AutoNation.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Store headcount band. Values: 1-19, 20-49, 50-99, 100-249, 250+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revenue",
            "in": "query",
            "required": false,
            "description": "Store revenue band (USD). Values: <1M, 1-5M, 5-10M, 10-25M, 25-50M, 50M+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mail_provider",
            "in": "query",
            "required": false,
            "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like). Values: google, microsoft, gateway, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dealer_id",
            "in": "query",
            "required": false,
            "description": "Only contacts at these dealer ids. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Look up these record ids directly (max 1,000). Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_tier",
            "in": "query",
            "required": false,
            "description": "Email check result. Values: verified, unverified. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_email",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a verified work email.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_phone",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a mobile or direct line.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_linkedin",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a LinkedIn profile.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "moved",
            "in": "query",
            "required": false,
            "description": "true: only people recently found in a new seat at another store.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "verified_within_days",
            "in": "query",
            "required": false,
            "description": "Email verified within this many days.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3650
            }
          },
          {
            "name": "max_per_dealer",
            "in": "query",
            "required": false,
            "description": "At most this many contacts per store (highest ranked first).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for offset paging. Default 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Rows per page. Default 25, max 50 (500 on admin accounts).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page. Faster and stable for long pulls; overrides page.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/contacts/search": {
      "post": {
        "summary": "Search contacts with a JSON body",
        "description": "Same as GET /contacts, with the filters in a JSON body. Lists can be arrays or comma separated strings. Use it for long id or domain lists.",
        "operationId": "post_contacts_search",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
                    "type": "string"
                  },
                  "role": {
                    "description": "Job role keys.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "seniority": {
                    "description": "Seniority.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "title": {
                    "description": "Job title contains this phrase (case insensitive), e.g. \"internet director\".",
                    "type": "string"
                  },
                  "title_any": {
                    "description": "Comma or | separated titles. A contact matches when its title holds every word of any one entry, in any order, e.g. \"internet director|digital manager\".",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "country": {
                    "description": "Country codes.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "state": {
                    "description": "State or province codes, e.g. TX,FL,ON.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "city": {
                    "description": "Exact city names (case insensitive), e.g. Houston,Dallas.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "brand": {
                    "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "type": {
                    "description": "Store type.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "group": {
                    "description": "Dealer group name contains this, e.g. AutoNation.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Store headcount band.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "revenue": {
                    "description": "Store revenue band (USD).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "mail_provider": {
                    "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "domain": {
                    "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "dealer_id": {
                    "description": "Only contacts at these dealer ids.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "ids": {
                    "description": "Look up these record ids directly (max 1,000).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "email_tier": {
                    "description": "Email check result.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "has_email": {
                    "description": "true: only contacts with a verified work email.",
                    "type": "boolean"
                  },
                  "has_phone": {
                    "description": "true: only contacts with a mobile or direct line.",
                    "type": "boolean"
                  },
                  "has_linkedin": {
                    "description": "true: only contacts with a LinkedIn profile.",
                    "type": "boolean"
                  },
                  "moved": {
                    "description": "true: only people recently found in a new seat at another store.",
                    "type": "boolean"
                  },
                  "verified_within_days": {
                    "description": "Email verified within this many days.",
                    "type": "integer"
                  },
                  "max_per_dealer": {
                    "description": "At most this many contacts per store (highest ranked first).",
                    "type": "integer"
                  },
                  "page": {
                    "description": "Page number for offset paging. Default 1.",
                    "type": "integer"
                  },
                  "page_size": {
                    "description": "Rows per page. Default 25, max 50 (500 on admin accounts).",
                    "type": "integer"
                  },
                  "cursor": {
                    "description": "next_cursor from the previous page. Faster and stable for long pulls; overrides page.",
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/contacts/count": {
      "get": {
        "summary": "Count contacts (free)",
        "description": "Exact number of contacts matching the filters, to size a list before pulling it. Does not use the daily search allowance. Also accepts POST with a JSON body.",
        "operationId": "get_contacts_count",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Job role keys. Values: owner_dealer_principal, gm, gsm, sales_manager, used_car_manager, fi_manager, internet_sales, bdc_manager, marketing, fixed_ops_director, service_manager, parts_manager, fleet_manager, sales_staff, service_staff, accounting, hr, it, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "seniority",
            "in": "query",
            "required": false,
            "description": "Seniority. Values: owner, executive, director, manager, staff. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "Job title contains this phrase (case insensitive), e.g. \"internet director\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title_any",
            "in": "query",
            "required": false,
            "description": "Comma or | separated titles. A contact matches when its title holds every word of any one entry, in any order, e.g. \"internet director|digital manager\". Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country codes. Values: US, CA. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "State or province codes, e.g. TX,FL,ON. Values: two-letter US state or Canadian province codes. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Exact city names (case insensitive), e.g. Houston,Dallas. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any. Values: OEM names as listed by GET /filters. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Store type. Values: franchise, independent, group, powersports_rv, specialty. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Dealer group name contains this, e.g. AutoNation.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Store headcount band. Values: 1-19, 20-49, 50-99, 100-249, 250+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revenue",
            "in": "query",
            "required": false,
            "description": "Store revenue band (USD). Values: <1M, 1-5M, 5-10M, 10-25M, 25-50M, 50M+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mail_provider",
            "in": "query",
            "required": false,
            "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like). Values: google, microsoft, gateway, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dealer_id",
            "in": "query",
            "required": false,
            "description": "Only contacts at these dealer ids. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Look up these record ids directly (max 1,000). Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_tier",
            "in": "query",
            "required": false,
            "description": "Email check result. Values: verified, unverified. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_email",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a verified work email.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_phone",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a mobile or direct line.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_linkedin",
            "in": "query",
            "required": false,
            "description": "true: only contacts with a LinkedIn profile.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "moved",
            "in": "query",
            "required": false,
            "description": "true: only people recently found in a new seat at another store.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "verified_within_days",
            "in": "query",
            "required": false,
            "description": "Email verified within this many days.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3650
            }
          },
          {
            "name": "max_per_dealer",
            "in": "query",
            "required": false,
            "description": "At most this many contacts per store (highest ranked first).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ]
      },
      "post": {
        "summary": "Count contacts (free)",
        "description": "Exact number of contacts matching the filters, to size a list before pulling it. Does not use the daily search allowance. Also accepts POST with a JSON body.",
        "operationId": "get_contacts_count_post",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
                    "type": "string"
                  },
                  "role": {
                    "description": "Job role keys.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "seniority": {
                    "description": "Seniority.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "title": {
                    "description": "Job title contains this phrase (case insensitive), e.g. \"internet director\".",
                    "type": "string"
                  },
                  "title_any": {
                    "description": "Comma or | separated titles. A contact matches when its title holds every word of any one entry, in any order, e.g. \"internet director|digital manager\".",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "country": {
                    "description": "Country codes.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "state": {
                    "description": "State or province codes, e.g. TX,FL,ON.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "city": {
                    "description": "Exact city names (case insensitive), e.g. Houston,Dallas.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "brand": {
                    "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "type": {
                    "description": "Store type.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "group": {
                    "description": "Dealer group name contains this, e.g. AutoNation.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Store headcount band.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "revenue": {
                    "description": "Store revenue band (USD).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "mail_provider": {
                    "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "domain": {
                    "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "dealer_id": {
                    "description": "Only contacts at these dealer ids.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "ids": {
                    "description": "Look up these record ids directly (max 1,000).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "email_tier": {
                    "description": "Email check result.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "has_email": {
                    "description": "true: only contacts with a verified work email.",
                    "type": "boolean"
                  },
                  "has_phone": {
                    "description": "true: only contacts with a mobile or direct line.",
                    "type": "boolean"
                  },
                  "has_linkedin": {
                    "description": "true: only contacts with a LinkedIn profile.",
                    "type": "boolean"
                  },
                  "moved": {
                    "description": "true: only people recently found in a new seat at another store.",
                    "type": "boolean"
                  },
                  "verified_within_days": {
                    "description": "Email verified within this many days.",
                    "type": "integer"
                  },
                  "max_per_dealer": {
                    "description": "At most this many contacts per store (highest ranked first).",
                    "type": "integer"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/contacts/{id}": {
      "get": {
        "summary": "One contact",
        "description": "A single contact by id, showing whatever this account has unlocked. 404 if the id does not exist.",
        "operationId": "get_contacts_id_",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/dealers": {
      "get": {
        "summary": "Search dealerships (free)",
        "description": "US and Canadian rooftops with OEMs, type, dealer group, size and revenue bands. Domain, phone, street, postal code, LinkedIn, headcount and revenue show once the store is unlocked.",
        "operationId": "get_dealers",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country codes. Values: US, CA. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "State or province codes, e.g. TX,FL,ON. Values: two-letter US state or Canadian province codes. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Exact city names (case insensitive), e.g. Houston,Dallas. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any. Values: OEM names as listed by GET /filters. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Store type. Values: franchise, independent, group, powersports_rv, specialty. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Dealer group name contains this, e.g. AutoNation.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Store headcount band. Values: 1-19, 20-49, 50-99, 100-249, 250+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revenue",
            "in": "query",
            "required": false,
            "description": "Store revenue band (USD). Values: <1M, 1-5M, 5-10M, 10-25M, 25-50M, 50M+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mail_provider",
            "in": "query",
            "required": false,
            "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like). Values: google, microsoft, gateway, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Look up these record ids directly (max 1,000). Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_headcount",
            "in": "query",
            "required": false,
            "description": "Stores with at least this many staff.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "min_contacts",
            "in": "query",
            "required": false,
            "description": "Stores with at least this many contacts on file.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for offset paging. Default 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Rows per page. Default 25, max 50 (500 on admin accounts).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "next_cursor from the previous page. Faster and stable for long pulls; overrides page.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/dealers/search": {
      "post": {
        "summary": "Search dealerships with a JSON body",
        "description": "Same as GET /dealers, with the filters in a JSON body.",
        "operationId": "post_dealers_search",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
                    "type": "string"
                  },
                  "country": {
                    "description": "Country codes.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "state": {
                    "description": "State or province codes, e.g. TX,FL,ON.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "city": {
                    "description": "Exact city names (case insensitive), e.g. Houston,Dallas.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "brand": {
                    "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "type": {
                    "description": "Store type.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "group": {
                    "description": "Dealer group name contains this, e.g. AutoNation.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Store headcount band.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "revenue": {
                    "description": "Store revenue band (USD).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "mail_provider": {
                    "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "domain": {
                    "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "ids": {
                    "description": "Look up these record ids directly (max 1,000).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "min_headcount": {
                    "description": "Stores with at least this many staff.",
                    "type": "integer"
                  },
                  "min_contacts": {
                    "description": "Stores with at least this many contacts on file.",
                    "type": "integer"
                  },
                  "page": {
                    "description": "Page number for offset paging. Default 1.",
                    "type": "integer"
                  },
                  "page_size": {
                    "description": "Rows per page. Default 25, max 50 (500 on admin accounts).",
                    "type": "integer"
                  },
                  "cursor": {
                    "description": "next_cursor from the previous page. Faster and stable for long pulls; overrides page.",
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dealers/count": {
      "get": {
        "summary": "Count dealerships (free)",
        "description": "Exact number of stores matching the filters. Also accepts POST with a JSON body.",
        "operationId": "get_dealers_count",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country codes. Values: US, CA. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "State or province codes, e.g. TX,FL,ON. Values: two-letter US state or Canadian province codes. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Exact city names (case insensitive), e.g. Houston,Dallas. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "required": false,
            "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any. Values: OEM names as listed by GET /filters. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Store type. Values: franchise, independent, group, powersports_rv, specialty. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Dealer group name contains this, e.g. AutoNation.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Store headcount band. Values: 1-19, 20-49, 50-99, 100-249, 250+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revenue",
            "in": "query",
            "required": false,
            "description": "Store revenue band (USD). Values: <1M, 1-5M, 5-10M, 10-25M, 25-50M, 50M+. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mail_provider",
            "in": "query",
            "required": false,
            "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like). Values: google, microsoft, gateway, other. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped. Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Look up these record ids directly (max 1,000). Comma separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_headcount",
            "in": "query",
            "required": false,
            "description": "Stores with at least this many staff.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "min_contacts",
            "in": "query",
            "required": false,
            "description": "Stores with at least this many contacts on file.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          }
        ]
      },
      "post": {
        "summary": "Count dealerships (free)",
        "description": "Exact number of stores matching the filters. Also accepts POST with a JSON body.",
        "operationId": "get_dealers_count_post",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "description": "Free text. Contacts: title, full name or dealership name contains it. Dealers: name or city contains it.",
                    "type": "string"
                  },
                  "country": {
                    "description": "Country codes.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "state": {
                    "description": "State or province codes, e.g. TX,FL,ON.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "city": {
                    "description": "Exact city names (case insensitive), e.g. Houston,Dallas.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "brand": {
                    "description": "OEMs the store sells, e.g. Ford,Toyota. Matches any.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "type": {
                    "description": "Store type.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "group": {
                    "description": "Dealer group name contains this, e.g. AutoNation.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Store headcount band.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "revenue": {
                    "description": "Store revenue band (USD).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "mail_provider": {
                    "description": "Who hosts the store's email. gateway = behind a security gateway (Mimecast, Proofpoint and the like).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "domain": {
                    "description": "Store website domains, e.g. boydauto.com. https://, www. and paths are stripped.",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "ids": {
                    "description": "Look up these record ids directly (max 1,000).",
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "string"
                      }
                    ]
                  },
                  "min_headcount": {
                    "description": "Stores with at least this many staff.",
                    "type": "integer"
                  },
                  "min_contacts": {
                    "description": "Stores with at least this many contacts on file.",
                    "type": "integer"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/dealers/{id}": {
      "get": {
        "summary": "One dealership",
        "description": "A single store by id. 404 if the id does not exist.",
        "operationId": "get_dealers_id_",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/filters": {
      "get": {
        "summary": "Valid filter values with counts",
        "description": "Every role, seniority, state, OEM, store type, size and revenue band and mail provider, with live counts, plus the top dealer groups and the credit price of each unlock. Read this before building filters.",
        "operationId": "get_filters",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        }
      }
    },
    "/unlock": {
      "post": {
        "summary": "Unlock records (spends credits)",
        "description": "Reveals records for this account. Already unlocked ids are free. Ids that do not qualify for the kind (for example contact_email on a contact without a verified email) are skipped, not charged, and listed in skipped with the reason. Max 100 ids per call (1,000 on admin accounts).",
        "operationId": "post_unlock",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind",
                  "ids"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "contact_email",
                      "contact_profile",
                      "contact_phone",
                      "dealer"
                    ]
                  },
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "return_rows": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/account": {
      "get": {
        "summary": "Credit balance and prices",
        "description": "The account email, credit balance and the credit price of each unlock kind.",
        "operationId": "get_account",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        }
      }
    },
    "/export/contacts": {
      "get": {
        "summary": "Every unlocked contact",
        "description": "All contacts this account has unlocked (email, profile or phone), with store details, in one response with total. 20 exports per hour.",
        "operationId": "get_export_contacts",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        }
      }
    },
    "/export/dealers": {
      "get": {
        "summary": "Every unlocked dealership",
        "description": "All stores this account has unlocked, with full details, in one response with total. 20 exports per hour.",
        "operationId": "get_export_dealers",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad filter or value"
          },
          "401": {
            "description": "Invalid API key"
          },
          "429": {
            "description": "Rate or daily limit"
          }
        }
      }
    }
  }
}