{"openapi":"3.1.0","info":{"title":"StoreInspect API","version":"1.0.0","description":"Database-backed Shopify store and contact intelligence API. V1 access requires a paid StoreInspect plan."},"servers":[{"url":"https://storeinspect.com/api/v1"}],"tags":[{"name":"usage","x-displayName":"Usage","x-group":"Usage","description":"API access state, request quotas, search-row quota, and shared contact-credit usage."},{"name":"taxonomy","x-displayName":"Taxonomy","x-group":"Taxonomy","description":"Filter values, labels, and metadata used by store and contact search requests."},{"name":"stores","x-displayName":"Stores","x-group":"Stores","description":"Store lookup, store search, and batch domain enrichment for Shopify accounts."},{"name":"contacts","x-displayName":"Contacts","x-group":"Contacts","description":"Contact preview search and credit-based contact reveal workflows."}],"paths":{"/usage":{"get":{"tags":["usage"],"operationId":"getUsage","x-route-path":"/api/v1/usage","summary":"Get usage","description":"Returns API access state, request quota, search-row quota, and shared contact-credit usage for the authenticated account.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Usage for the authenticated account."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."}}}},"/taxonomy":{"get":{"tags":["taxonomy"],"operationId":"getTaxonomy","x-route-path":"/api/v1/taxonomy","summary":"List taxonomy","description":"Returns valid filter values and display labels for store search, contact search, and enrichment workflows.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Taxonomy values for filters and display names."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."}}}},"/stores/{domain}":{"get":{"tags":["stores"],"operationId":"getStore","x-route-path":"/api/v1/stores/{domain}","summary":"Get store","description":"Enriches one known Shopify store domain from the StoreInspect database. V1 does not live-scan uncached domains.","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Store domain to look up. URLs are normalized to their hostname."}],"responses":{"200":{"description":"Store intelligence for a domain already present in the StoreInspect database."},"400":{"description":"Invalid domain input."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."},"404":{"description":"No known store exists for the domain."}}}},"/stores/search":{"post":{"tags":["stores"],"operationId":"searchStores","x-route-path":"/api/v1/stores/search","summary":"Search stores","description":"Searches Shopify stores by focused ICP filters with stable sorting, cursor pagination, broad-search guardrails, and monthly search-row quotas.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreSearchRequest"}}}},"responses":{"200":{"description":"A cursor-paginated list of stores matching the supplied filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreListResponse"}}}},"400":{"description":"Invalid filters, limit, or cursor."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."}}}},"/stores/enrich":{"post":{"tags":["stores"],"operationId":"enrichStores","x-route-path":"/api/v1/stores/enrich","summary":"Enrich stores","description":"Batch enriches a small set of known Shopify store domains already present in the StoreInspect database.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreEnrichRequest"}}}},"responses":{"200":{"description":"Found and not-found rows for a small set of domains already present in the StoreInspect database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreEnrichResponse"}}}},"400":{"description":"Invalid domains or unsupported reveal mode."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."}}}},"/contacts/search":{"post":{"tags":["contacts"],"operationId":"searchContacts","x-route-path":"/api/v1/contacts/search","summary":"Search contacts","description":"Searches preview-safe contact records at Shopify stores using role, seniority, location, technology, and store ICP filters.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}}}},"responses":{"200":{"description":"A cursor-paginated list of contact previews matching the supplied filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPreviewListResponse"}}}},"400":{"description":"Invalid filters, limit, or cursor."},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account does not have API access."}}}},"/contacts/reveal":{"post":{"tags":["contacts"],"operationId":"revealContacts","x-route-path":"/api/v1/contacts/reveal","summary":"Reveal contacts","description":"Reveals full contact identity and contact channels with shared contact credits and optional idempotency protection.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional key used to safely retry a contact reveal request without spending credits twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRevealRequest"}}}},"responses":{"200":{"description":"Full contact data for contacts revealed with shared contact credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactRevealResponse"}}}},"400":{"description":"Invalid contact IDs."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Not enough contact credits."},"403":{"description":"The account does not have API access."},"404":{"description":"No revealable contacts were found."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"StoreInspect API key"}},"schemas":{"StoreSearchRequest":{"type":"object","additionalProperties":false,"properties":{"filters":{"$ref":"#/components/schemas/StoreSearchFilters"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":["string","null"],"pattern":"^cur_[A-Za-z0-9_-]+$","default":null}},"required":["filters"]},"StoreSearchFilters":{"type":"object","additionalProperties":false,"properties":{"categories":{"type":"array","items":{"type":"string"},"maxItems":50},"countries":{"type":"array","items":{"type":"string"},"maxItems":50},"traffic_tiers":{"type":"array","items":{"type":"string"},"maxItems":50},"revenue_tiers":{"type":"array","items":{"type":"string"},"maxItems":50},"shopify_plus":{"type":"boolean"},"apps":{"$ref":"#/components/schemas/StoreTechnologyFilter"},"pixels":{"$ref":"#/components/schemas/StoreTechnologyFilter"},"themes":{"type":"object","additionalProperties":false,"properties":{"types":{"type":"array","items":{"type":"string","enum":["free","paid","custom"]},"maxItems":50}}},"meta_ads":{"type":"object","additionalProperties":false,"properties":{"active_ads_min":{"type":"integer","minimum":0,"maximum":100000}}},"contacts":{"type":"object","additionalProperties":false,"properties":{"has_revealable_contacts":{"type":"boolean"},"roles_any":{"type":"array","items":{"type":"string"},"maxItems":50}}}}},"StoreTechnologyFilter":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"array","items":{"type":"string"},"maxItems":50},"none":{"type":"array","items":{"type":"string"},"maxItems":50}}},"StoreListResponse":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Store"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["object","data","has_more","next_cursor","request_id"]},"StoreEnrichRequest":{"type":"object","additionalProperties":false,"properties":{"domains":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"},"description":"Store domains or URLs to enrich. Inputs are normalized to hostnames."},"include":{"type":"array","items":{"type":"string","enum":["store","technologies","contact_previews"]},"default":["store","technologies"]},"contact_roles":{"type":"array","items":{"type":"string"},"maxItems":50},"max_contacts_per_store":{"type":"integer","minimum":1,"maximum":10,"default":1},"reveal_contacts":{"type":"boolean","default":false,"description":"Must be false in V1 synchronous enrichment. Use /api/v1/contacts/reveal to reveal contacts."}},"required":["domains"]},"StoreEnrichResponse":{"type":"object","properties":{"object":{"type":"string","const":"store_enrichment_result"},"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreEnrichResult"}},"found":{"type":"integer","minimum":0},"not_found":{"type":"integer","minimum":0},"request_id":{"type":"string"}},"required":["object","data","found","not_found","request_id"]},"StoreEnrichResult":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["found","not_found"]},"store":{"oneOf":[{"$ref":"#/components/schemas/Store"},{"type":"null"}]},"contact_previews":{"type":"array","items":{"$ref":"#/components/schemas/ContactPreview"}}},"required":["domain","status","store"]},"Store":{"type":"object","properties":{"id":{"type":"string","pattern":"^st_[A-Za-z]+_[A-Za-z]{16}$"},"object":{"type":"string","const":"store"},"domain":{"type":"string"},"name":{"type":"string"},"category":{"type":["string","null"]},"country":{"type":["string","null"]},"traffic_tier":{"type":["string","null"]},"revenue_tier":{"type":["string","null"]},"shopify_plus":{"type":"boolean"},"lead_fit_score":{"type":["number","null"]},"technologies":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"string"}},"pixels":{"type":"array","items":{"type":"string"}},"theme":{"type":"object","properties":{"name":{"type":["string","null"]},"type":{"type":["string","null"]}}}}},"contacts_summary":{"type":"object","properties":{"total":{"type":"integer"},"has_revealable_contacts":{"type":"boolean"},"verified_email_count":{"type":"integer"},"roles":{"type":"array","items":{"type":"string"}}}}}},"ContactSearchRequest":{"type":"object","additionalProperties":false,"properties":{"person":{"$ref":"#/components/schemas/ContactPersonFilters"},"store":{"$ref":"#/components/schemas/ContactStoreFilters"},"max_contacts_per_store":{"type":"integer","minimum":1,"maximum":10,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":["string","null"],"pattern":"^cur_[A-Za-z0-9_-]+$","default":null}}},"ContactPersonFilters":{"type":"object","additionalProperties":false,"properties":{"roles_any":{"type":"array","items":{"type":"string"},"maxItems":50},"seniority_any":{"type":"array","items":{"type":"string"},"maxItems":50},"has_verified_email":{"type":"boolean"},"has_phone":{"type":"boolean"},"has_linkedin":{"type":"boolean"}}},"ContactStoreFilters":{"type":"object","additionalProperties":false,"properties":{"categories":{"type":"array","items":{"type":"string"},"maxItems":50},"countries":{"type":"array","items":{"type":"string"},"maxItems":50},"traffic_tiers":{"type":"array","items":{"type":"string"},"maxItems":50},"revenue_tiers":{"type":"array","items":{"type":"string"},"maxItems":50},"shopify_plus":{"type":"boolean"},"apps":{"$ref":"#/components/schemas/StoreTechnologyFilter"},"pixels":{"$ref":"#/components/schemas/StoreTechnologyFilter"},"themes":{"type":"object","additionalProperties":false,"properties":{"types":{"type":"array","items":{"type":"string","enum":["free","paid","custom"]},"maxItems":50}}},"meta_ads":{"type":"object","additionalProperties":false,"properties":{"active_ads_min":{"type":"integer","minimum":0,"maximum":100000}}}}},"ContactPreviewListResponse":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactPreview"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"request_id":{"type":"string"}},"required":["object","data","has_more","next_cursor","request_id"]},"ContactPreview":{"type":"object","properties":{"id":{"type":"string","pattern":"^ct_[A-Za-z]+_[A-Za-z]{16}$"},"object":{"type":"string","const":"contact_preview"},"first_name":{"type":["string","null"]},"last_name_obfuscated":{"type":["string","null"]},"role":{"type":["string","null"]},"seniority":{"type":"string","enum":["executive","decision_maker","other"]},"title":{"type":["string","null"]},"has_verified_email":{"type":"boolean"},"has_phone":{"type":"boolean"},"has_linkedin":{"type":"boolean"},"revealed":{"type":"boolean"},"store":{"type":"object","properties":{"id":{"type":"string","pattern":"^st_[A-Za-z]+_[A-Za-z]{16}$"},"domain":{"type":"string"},"name":{"type":"string"},"category":{"type":["string","null"]},"traffic_tier":{"type":["string","null"]},"technologies":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"string"}},"pixels":{"type":"array","items":{"type":"string"}}}}}}}},"ContactRevealRequest":{"type":"object","additionalProperties":false,"properties":{"contact_ids":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^ct_[A-Za-z]+_[A-Za-z]{16}$"}}},"required":["contact_ids"]},"ContactRevealResponse":{"type":"object","properties":{"object":{"type":"string","const":"contact_reveal_result"},"credits":{"type":"object","properties":{"spent":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0}},"required":["spent","remaining"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"request_id":{"type":"string"}},"required":["object","credits","data","request_id"]},"Contact":{"type":"object","properties":{"id":{"type":"string","pattern":"^ct_[A-Za-z]+_[A-Za-z]{16}$"},"object":{"type":"string","const":"contact"},"full_name":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"title":{"type":["string","null"]},"role":{"type":["string","null"]},"seniority":{"type":"string","enum":["executive","decision_maker","other"]},"linkedin_url":{"type":["string","null"]},"reveal_status":{"type":"string","enum":["newly_revealed","already_revealed"]},"charged":{"type":"boolean"},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"is_primary":{"type":"boolean"}}}},"phones":{"type":"array","items":{"type":"object","properties":{"phone":{"type":"string"},"type":{"type":"string"},"is_primary":{"type":"boolean"}}}},"store":{"type":"object","properties":{"id":{"type":"string","pattern":"^st_[A-Za-z]+_[A-Za-z]{16}$"},"domain":{"type":"string"},"name":{"type":"string"}}},"revealed_at":{"type":"string","format":"date-time"}}}}}}