{ "openapi": "3.1.0", "info": { "title": "cc_api V1 API", "version": "1.0.0", "description": "Version 1 of the cc_api public-facing REST API. All endpoints are JSON, authenticated via the X-Api-Key header, and policy-scoped per user role." }, "servers": [ { "url": "https://{host}/v1", "variables": { "host": { "default": "api.example.com" } } } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Leads" }, { "name": "LeadActivities" }, { "name": "CompanyRetailers" }, { "name": "CompanyRetailerLocations" }, { "name": "Products" }, { "name": "StoreLocator" } ], "paths": { "/leads": { "get": { "tags": [ "Leads" ], "summary": "List leads", "operationId": "listLeads", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/OptsPage" }, { "$ref": "#/components/parameters/OptsPerPage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Leads" ], "summary": "Create a lead", "operationId": "createLead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead" ], "properties": { "lead": { "$ref": "#/components/schemas/LeadInput" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/leads/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Leads" ], "summary": "Show a lead", "operationId": "showLead", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Leads" ], "summary": "Update a lead", "operationId": "updateLead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "$ref": "#/components/schemas/LeadInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "put": { "tags": [ "Leads" ], "summary": "Update a lead (replace)", "operationId": "replaceLead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "$ref": "#/components/schemas/LeadInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Leads" ], "summary": "Delete a lead", "operationId": "deleteLead", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/lead_activities": { "get": { "tags": [ "LeadActivities" ], "summary": "List lead activities", "operationId": "listLeadActivities", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/OptsPage" }, { "$ref": "#/components/parameters/OptsPerPage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_activities": { "type": "array", "items": { "$ref": "#/components/schemas/LeadActivity" } }, "meta": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "LeadActivities" ], "summary": "Create a lead activity", "operationId": "createLeadActivity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead_activity" ], "properties": { "lead_activity": { "$ref": "#/components/schemas/LeadActivityInput" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadActivity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/lead_activities/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "LeadActivities" ], "summary": "Show a lead activity", "operationId": "showLeadActivity", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadActivity" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "LeadActivities" ], "summary": "Update a lead activity", "operationId": "updateLeadActivity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_activity": { "$ref": "#/components/schemas/LeadActivityInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadActivity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "put": { "tags": [ "LeadActivities" ], "summary": "Update a lead activity (replace)", "operationId": "replaceLeadActivity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_activity": { "$ref": "#/components/schemas/LeadActivityInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadActivity" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "LeadActivities" ], "summary": "Delete a lead activity", "operationId": "deleteLeadActivity", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/company_retailers": { "get": { "tags": [ "CompanyRetailers" ], "summary": "List company retailers", "operationId": "listCompanyRetailers", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/Include" }, { "$ref": "#/components/parameters/OptsPage" }, { "$ref": "#/components/parameters/OptsPerPage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailers": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyRetailer" } }, "meta": { "$ref": "#/components/schemas/SearchMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "CompanyRetailers" ], "summary": "Create a company retailer", "operationId": "createCompanyRetailer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_retailer" ], "properties": { "company_retailer": { "$ref": "#/components/schemas/CompanyRetailerInput" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/company_retailers/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "CompanyRetailers" ], "summary": "Show a company retailer", "operationId": "showCompanyRetailer", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "CompanyRetailers" ], "summary": "Update a company retailer", "operationId": "updateCompanyRetailer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer": { "$ref": "#/components/schemas/CompanyRetailerInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "put": { "tags": [ "CompanyRetailers" ], "summary": "Update a company retailer (replace)", "operationId": "replaceCompanyRetailer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer": { "$ref": "#/components/schemas/CompanyRetailerInput" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "CompanyRetailers" ], "summary": "Delete a company retailer", "operationId": "deleteCompanyRetailer", "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/company_retailer_locations": { "get": { "tags": [ "CompanyRetailerLocations" ], "summary": "List company retailer locations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/OptsPage" }, { "$ref": "#/components/parameters/OptsPerPage" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer_locations": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyRetailerLocation" } }, "meta": { "$ref": "#/components/schemas/SearchMeta" } }, "required": [ "company_retailer_locations", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "CompanyRetailerLocations" ], "summary": "Create a company retailer location", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer_location": { "$ref": "#/components/schemas/CompanyRetailerLocationInput" }, "physical_address": { "$ref": "#/components/schemas/LocationInput" }, "general_email": { "$ref": "#/components/schemas/EmailInput" }, "general_phone_number": { "$ref": "#/components/schemas/PhoneNumberInput" }, "delivery_areas": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryAreaInput" } }, "retailer_location_hours": { "type": "array", "items": { "$ref": "#/components/schemas/RetailerLocationHourInput" } } }, "required": [ "company_retailer_location" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailerLocation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/company_retailer_locations/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "CompanyRetailerLocations" ], "summary": "Show a company retailer location", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailerLocation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "CompanyRetailerLocations" ], "summary": "Update a company retailer location", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer_location": { "$ref": "#/components/schemas/CompanyRetailerLocationInput" }, "physical_address": { "$ref": "#/components/schemas/LocationInput" }, "general_email": { "$ref": "#/components/schemas/EmailInput" }, "general_phone_number": { "$ref": "#/components/schemas/PhoneNumberInput" }, "delivery_areas": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryAreaInput" } }, "retailer_location_hours": { "type": "array", "items": { "$ref": "#/components/schemas/RetailerLocationHourInput" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyRetailerLocation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "CompanyRetailerLocations" ], "summary": "Destroy a company retailer location", "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List products", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/OptsPage" }, { "$ref": "#/components/parameters/OptsPerPage" }, { "$ref": "#/components/parameters/Include" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/SearchMeta" } }, "required": [ "products", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Products" ], "summary": "Create a product", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductInput" } }, "required": [ "product" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/products/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Products" ], "summary": "Show a product", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductInput" } }, "required": [ "product" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Products" ], "summary": "Destroy a product", "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/store_locator": { "get": { "tags": [ "StoreLocator" ], "summary": "Public store locator search (point or bounding box)", "description": "Public endpoint \u2014 no X-Api-Key required. Identify the Company via the X-Cc-Id header or cc_id query parameter.", "security": [], "parameters": [ { "name": "cc_id", "in": "query", "required": false, "description": "Company UUID. Required if the X-Cc-Id header is not supplied.", "schema": { "type": "string", "format": "uuid" } }, { "name": "latitude", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Point search: latitude." }, { "name": "longitude", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Point search: longitude." }, { "name": "radius", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Point search: distance string (e.g. \"50mi\", \"25km\"). Defaults to \"1000mi\"." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 15 } }, { "name": "top_left_latitude", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Bounding box search." }, { "name": "top_left_longitude", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "bottom_right_latitude", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "bottom_right_longitude", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "store_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "province", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "stocked_product_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "available_product_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "stocked_product_external_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "available_product_external_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "stocked_product_skus", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "available_product_skus", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "stocked_product_collection_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "available_product_collection_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": true }, { "name": "X-Cc-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID. Required if the cc_id query parameter is not supplied." } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/StoreLocatorResult" } }, "meta": { "$ref": "#/components/schemas/StoreLocatorMeta" } }, "required": [ "results", "meta" ] } } } }, "400": { "description": "Invalid search parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid search parameters" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/store_locator/{id}": { "get": { "tags": [ "StoreLocator" ], "summary": "Show a single store locator location", "description": "Public endpoint \u2014 no X-Api-Key required. Returns one CompanyRetailerLocation rendered with the same rich payload as the locator search results (address, email, phone number, hours, and stocked / available products). Not policy-scoped: any caller who knows the id can read it. Neither the X-Cc-Id header nor the cc_id query parameter is required.", "operationId": "showStoreLocatorLocation", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "CompanyRetailerLocation UUID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_retailer_location": { "$ref": "#/components/schemas/StoreLocatorResult" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "User API key. May optionally be prefixed with an identifier and a colon; the substring after the last ':' is treated as the key." } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Query": { "name": "q", "in": "query", "required": false, "description": "Searchkick full-text query. Defaults to '*' (match all).", "schema": { "type": "string" } }, "Include": { "name": "include", "in": "query", "required": false, "description": "Comma-separated association include list. Defaults to '*'.", "schema": { "type": "string" } }, "OptsPage": { "name": "opts[page]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, "OptsPerPage": { "name": "opts[per_page]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 50 } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "Forbidden": { "description": "Authenticated but not authorized by policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized", "status": 403 } } } }, "NotFound": { "description": "Resource not found (or outside the caller's policy scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 404, "error": "Not Found", "message": "Couldn't find Lead with 'id'=00000000-0000-0000-0000-000000000000" } } } }, "BadRequest": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "error": "Bad Request", "message": "Invalid JSON: ..." } } } }, "ValidationError": { "description": "The entity could not be processed. Returned for validation failures, missing required root parameter, unknown STI type, unpermitted parameters, or destroy callback halts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "validation": { "summary": "Validation failure", "value": { "status": 422, "error": "Unprocessable Entity", "message": "Validation failed: Name can't be blank", "errors": { "name": [ "can't be blank" ] }, "details": [ { "field": "name", "code": "blank", "message": "can't be blank", "full_message": "Name can't be blank" } ] } }, "parameterMissing": { "summary": "Required root parameter missing", "value": { "status": 422, "error": "Unprocessable Entity", "message": "param is missing or the value is empty: lead", "errors": { "lead": [ "is missing" ] }, "details": [ { "field": "lead", "code": "missing", "message": "is missing", "full_message": "Lead is missing" } ] } }, "subclassNotFound": { "summary": "Unknown STI type", "value": { "status": 422, "error": "Unprocessable Entity", "message": "The single-table inheritance mechanism failed to locate the subclass: 'LeadActivity::Bogus'.", "errors": { "type": [ "is not a valid subclass" ] }, "details": [ { "field": "type", "code": "invalid", "message": "is not a valid subclass", "full_message": "Type is not a valid subclass" } ] } } } } } } }, "schemas": { "Error": { "type": "object", "description": "Generic error envelope used for 4xx responses that are not 422.", "properties": { "status": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] }, "ErrorDetail": { "type": "object", "description": "A single error in a 422 response.", "properties": { "field": { "type": "string", "description": "The attribute or top-level parameter that the error applies to. May be 'base' for record-level errors." }, "code": { "type": "string", "description": "Stable, programmatic error code. Common values: 'blank', 'taken', 'invalid', 'too_short', 'too_long', 'missing', 'unpermitted'." }, "message": { "type": "string", "description": "Short human-readable error message, e.g. \"can't be blank\"." }, "full_message": { "type": "string", "description": "Fully-qualified human-readable message including the field name, e.g. \"Name can't be blank\"." } }, "required": [ "field", "code", "message", "full_message" ] }, "ValidationError": { "type": "object", "description": "422 response envelope. Returned when a request entity cannot be processed, including ActiveRecord validation failures, missing required root parameter, unknown STI type, unpermitted parameters, and destroy callback halts.", "properties": { "status": { "type": "integer", "examples": [ 422 ] }, "error": { "type": "string", "examples": [ "Unprocessable Entity" ] }, "message": { "type": "string" }, "errors": { "type": "object", "description": "Map of field name to array of error messages. Retained for backward compatibility with prior API clients.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "required": [ "status", "error", "message", "errors", "details" ] }, "SearchMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "aggs": { "type": "object", "additionalProperties": true } } }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": "string" }, "country_code": { "type": "string" }, "formatted": { "type": "string" } } }, "PhoneNumberInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": "string" }, "country_code": { "type": "string" }, "_destroy": { "type": "boolean" } } }, "Email": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" } } }, "EmailInput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "_destroy": { "type": "boolean" } } }, "Location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "address_name": { "type": "string", "nullable": true }, "street_line_one": { "type": "string", "nullable": true }, "street_line_two": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } }, "LocationInput": { "type": "object", "properties": { "address_name": { "type": "string" }, "street_line_one": { "type": "string" }, "street_line_two": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" } } }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "assignee": { "type": "object", "additionalProperties": true, "nullable": true }, "location": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true } } }, "LeadInput": { "type": "object", "description": "On create, the owner is automatically set to the caller's company or retailer; supplying owner_id/owner_type is ignored. Top-level keys 'phone_numbers', 'emails', 'location', and 'lead_activities' are rewritten to their *_attributes form server-side.", "properties": { "name": { "type": "string" }, "owner_id": { "type": "string", "format": "uuid" }, "owner_type": { "type": "string" }, "assignee_id": { "type": "string", "format": "uuid" }, "assignee_type": { "type": "string" }, "source_id": { "type": "string", "format": "uuid" }, "source_type": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailInput" } }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberInput" } }, "location": { "$ref": "#/components/schemas/LocationInput" }, "lead_activities": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "source_id": { "type": "string", "format": "uuid" }, "source_type": { "type": "string" }, "body": { "type": "string" } } } } } }, "LeadActivity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "STI subclass.", "examples": [ "LeadActivity::InboundCall", "LeadActivity::OutboundCall", "LeadActivity::OutboundEmail", "LeadActivity::Voicemail", "LeadActivity::Note", "LeadActivity::SampleRequest", "LeadActivity::QuoteRequest", "LeadActivity::Referral", "LeadActivity::Purchase", "LeadActivity::Assignment", "LeadActivity::StatusChange" ] }, "lead": { "$ref": "#/components/schemas/Lead" } } }, "LeadActivityInput": { "type": "object", "required": [ "lead_id" ], "properties": { "lead_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": "string", "format": "uuid" }, "crm_id": { "type": "string" }, "crm_provider": { "type": "string" }, "crm_data_cache": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } } }, "CompanyRetailer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "sending_leads": { "type": "boolean" }, "receiving_leads": { "type": "boolean" }, "is_cc": { "type": "boolean" }, "territory_id": { "type": "string", "format": "uuid", "nullable": true }, "retailer_locations_count": { "type": "integer" }, "type": { "type": "string", "nullable": true }, "retailer": { "type": "object", "additionalProperties": true, "nullable": true }, "company": { "type": "object", "additionalProperties": true, "nullable": true }, "territory": { "type": "object", "additionalProperties": true, "nullable": true }, "physical_address": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true } } }, "CompanyRetailerInput": { "type": "object", "description": "The top-level 'physical_address' key is rewritten to 'physical_address_attributes' server-side.", "properties": { "retailer_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "territory_id": { "type": "string", "format": "uuid" }, "sending_leads": { "type": "boolean" }, "receiving_leads": { "type": "boolean" }, "physical_address": { "type": "object", "properties": { "addressable_id": { "type": "string", "format": "uuid" }, "addressable_scope": { "type": "string" }, "address_name": { "type": "string" }, "street_line_one": { "type": "string" }, "street_line_two": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" } } } } }, "CompanyRetailerLocation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true, "description": "Falls back to retailer_location.name when blank." }, "sending_leads": { "type": "boolean" }, "receiving_leads": { "type": "boolean" }, "delivery_radius": { "type": "number", "nullable": true }, "website": { "type": "string", "nullable": true }, "record_calls": { "type": "boolean" }, "mask_emails": { "type": "boolean" }, "place_id": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" }, "company_retailer_id": { "type": "string", "format": "uuid" }, "retailer_location_id": { "type": "string", "format": "uuid", "nullable": true }, "territory_id": { "type": "string", "format": "uuid", "nullable": true }, "company_store_type_id": { "type": "string", "format": "uuid", "nullable": true }, "physical_address": { "allOf": [ { "$ref": "#/components/schemas/Location" } ], "nullable": true }, "general_email": { "allOf": [ { "$ref": "#/components/schemas/Email" } ], "nullable": true }, "general_phone_number": { "allOf": [ { "$ref": "#/components/schemas/PhoneNumber" } ], "nullable": true } } }, "CompanyRetailerLocationInput": { "type": "object", "description": "Writable attributes for a CompanyRetailerLocation. Role-based policies further restrict which keys are accepted.", "properties": { "name": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "company_retailer_id": { "type": "string", "format": "uuid" }, "retailer_location_id": { "type": "string", "format": "uuid" }, "mask_emails": { "type": "boolean" }, "keep_data": { "type": "boolean" }, "place_id": { "type": "string" }, "sending_leads": { "type": "boolean" }, "website": { "type": "string" }, "company_store_type_id": { "type": "string", "format": "uuid" }, "record_calls": { "type": "boolean" }, "territory_id": { "type": "string", "format": "uuid" } }, "required": [ "company_id", "company_retailer_id" ] }, "DeliveryAreaInput": { "type": "object", "description": "A delivery area attached to a CompanyRetailerLocation. Sent under the top-level `delivery_areas` key, which the controller rewrites to `delivery_areas_attributes`.", "properties": { "id": { "type": "string", "format": "uuid" }, "_destroy": { "type": "boolean" }, "name": { "type": "string" }, "delivery_radius": { "type": "number" }, "delivery_area_type": { "type": "string" }, "delivery_area_data": {} } }, "RetailerLocationHourInput": { "type": "object", "description": "A weekday hours row for a CompanyRetailerLocation. Sent under the top-level `retailer_location_hours` key.", "properties": { "id": { "type": "string", "format": "uuid" }, "open": { "type": "boolean" }, "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "open_at_hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "open_at_minute": { "type": "integer", "minimum": 0, "maximum": 59 }, "close_at_hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "close_at_minute": { "type": "integer", "minimum": 0, "maximum": 59 } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "collection_id": { "type": "string", "format": "uuid", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "company_id": { "type": "string", "format": "uuid" } } }, "ProductInput": { "type": "object", "description": "Writable attributes for a Product. `sku` is unique within `company_id`.", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "company_id": { "type": "string", "format": "uuid" }, "category": { "type": "string" }, "url": { "type": "string" }, "collection_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" } }, "required": [ "sku", "name", "company_id" ] }, "StoreLocatorMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "aggs": { "type": "object", "additionalProperties": true, "description": "Searchkick aggregation buckets for city, province, country and store_type." } } }, "StoreLocatorAddress": { "allOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "object", "properties": { "string": { "type": "string", "description": "Formatted geocoder address string." } } } ] }, "StoreLocatorHour": { "type": "object", "properties": { "day": { "type": "integer", "minimum": 0, "maximum": 6 }, "open": { "type": "boolean" }, "open_at_hour": { "type": "integer" }, "open_at_minute": { "type": "integer" }, "close_at_hour": { "type": "integer" }, "close_at_minute": { "type": "integer" }, "utc_offset_minute": { "type": "integer", "nullable": true }, "open_at": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } }, "StoreLocatorProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "CompanyRetailerLocationProduct id." }, "product_id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "collection_id": { "type": "string", "format": "uuid", "nullable": true }, "stocked": { "type": "boolean" }, "available": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "StoreLocatorResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "full_name": { "type": "string" }, "retailer_name": { "type": "string", "nullable": true }, "store_type": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "place_id": { "type": "string", "nullable": true }, "address": { "allOf": [ { "$ref": "#/components/schemas/StoreLocatorAddress" } ], "nullable": true }, "email": { "allOf": [ { "$ref": "#/components/schemas/Email" } ], "nullable": true }, "phone_number": { "allOf": [ { "$ref": "#/components/schemas/PhoneNumber" } ], "nullable": true }, "retailer_location_hours": { "type": "array", "items": { "$ref": "#/components/schemas/StoreLocatorHour" } }, "retailer_location_products": { "type": "array", "items": { "$ref": "#/components/schemas/StoreLocatorProduct" } } } } } } }