{"openapi":"3.1.0","info":{"title":"DealShield Public Profiles API","version":"1.0.0","description":"Read-only access to published public business profiles. Private owner contacts and internal source identifiers are never returned."},"servers":[{"url":"https://shield.dealport.com"}],"paths":{"/api/v1/profiles/{slug}":{"get":{"operationId":"getPublicProfile","summary":"Retrieve a published profile by slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published profile","headers":{"Link":{"description":"Canonical and self links","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicProfile"}}}}}},"404":{"description":"Profile not found, unpublished, or removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Read rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profiles/resolve":{"get":{"operationId":"resolvePublicProfile","summary":"Resolve profiles without knowing a slug","description":"Use either domain, or the exact name + city + two-letter state combination. Results are limited to five published profiles.","parameters":[{"name":"domain","in":"query","schema":{"type":"string"},"example":"example.com"},{"name":"name","in":"query","schema":{"type":"string"},"example":"Example Industrial Services"},{"name":"city","in":"query","schema":{"type":"string"},"example":"Tulsa"},{"name":"state","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"example":"OK"}],"responses":{"200":{"description":"Zero to five exact published matches","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["matches"],"properties":{"matches":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ResolutionMatch"}}}}}}}}},"400":{"description":"Invalid or ambiguous resolution query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Read rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/profiles/search":{"get":{"operationId":"searchPublicProfiles","summary":"Search the published business directory","description":"Search by keyword, city, two-letter state, or industry slug. Results are ordered by permanent profile slug, capped at 25, and paginated with an opaque cursor.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":80},"example":"industrial"},{"name":"city","in":"query","schema":{"type":"string","maxLength":100},"example":"Conroe"},{"name":"state","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"example":"TX"},{"name":"industry","in":"query","schema":{"type":"string","pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"example":"industrial-fabrication"},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":24}}],"responses":{"200":{"description":"A bounded page of published directory results","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DirectorySearchResult"}}}}}},"400":{"description":"Invalid search or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Read rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SourceType":{"enum":["public_record","company_website","owner_verified","other_public_source"]},"PublicProfile":{"type":"object","additionalProperties":false,"required":["schemaVersion","slug","name","claimState","location","website","industries","summary","facts","provenance","freshness","links","updatedAt","messaging"],"properties":{"schemaVersion":{"const":1},"slug":{"type":"string"},"name":{"type":"string"},"claimState":{"enum":["unclaimed","claimed"]},"location":{"type":"object","required":["city","state","county","postalCode","country"],"properties":{"city":{"type":"string"},"state":{"type":"string"},"county":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"country":{"const":"US"}}},"website":{"type":"string","format":"uri"},"publicPhone":{"type":["string","null"]},"industries":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"yearsInBusiness":{"type":["integer","null"],"minimum":0},"facts":{"type":"array","items":{"type":"object","required":["key","value","sourceType","sourceLabel","asOf"],"properties":{"key":{"type":"string"},"value":{"type":"string"},"sourceType":{"$ref":"#/components/schemas/SourceType"},"sourceLabel":{"type":"string"},"asOf":{"type":"string"}}}},"provenance":{"type":"array","items":{"type":"object","required":["field","sourceType","observedAt"],"properties":{"field":{"type":"string"},"sourceType":{"$ref":"#/components/schemas/SourceType"},"observedAt":{"type":"string","format":"date-time"}}}},"freshness":{"type":"object","required":["lastObservedAt","sourceTypes"],"properties":{"lastObservedAt":{"type":"string","format":"date-time"},"sourceTypes":{"type":"array","items":{"$ref":"#/components/schemas/SourceType"}}}},"links":{"type":"object","required":["canonical","self","message","claim","correction"],"additionalProperties":{"type":"string","format":"uri"}},"updatedAt":{"type":"string","format":"date-time"},"messaging":{"type":"object","required":["acceptingSubmissions","unclaimedMessagesHeld","categories"],"properties":{"acceptingSubmissions":{"type":"boolean"},"unclaimedMessagesHeld":{"type":"boolean"},"categories":{"type":"array","items":{"enum":["acquisition","vendor","recruiting","other"]}}}}}},"ResolutionMatch":{"type":"object","additionalProperties":false,"required":["name","location","website","canonicalUrl","profileApiUrl"],"properties":{"name":{"type":"string"},"location":{"type":"object","required":["city","state"],"properties":{"city":{"type":"string"},"state":{"type":"string"}}},"website":{"type":"string","format":"uri"},"canonicalUrl":{"type":"string","format":"uri"},"profileApiUrl":{"type":"string","format":"uri"}}},"DirectoryCard":{"type":"object","additionalProperties":false,"required":["schemaVersion","slug","name","claimState","location","industries","summary","links"],"properties":{"schemaVersion":{"const":1},"slug":{"type":"string"},"name":{"type":"string"},"claimState":{"enum":["unclaimed","claimed"]},"location":{"type":"object","additionalProperties":false,"required":["city","state"],"properties":{"city":{"type":"string"},"state":{"type":"string"}}},"industries":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"links":{"type":"object","additionalProperties":false,"required":["canonical","profileApi"],"properties":{"canonical":{"type":"string","format":"uri"},"profileApi":{"type":"string","format":"uri"}}}}},"DirectorySearchResult":{"type":"object","additionalProperties":false,"required":["items","total","limit","hasMore","nextCursor"],"properties":{"items":{"type":"array","maxItems":25,"items":{"$ref":"#/components/schemas/DirectoryCard"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":25},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}},"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"externalDocs":{"description":"DealShield developer guide","url":"https://shield.dealport.com/developers"}}