{ "openapi": "3.1.0", "info": { "title": "Groundflag Public API", "version": "v1", "description": "REST API for Groundflag companies. Create a token in Settings → API (each token carries scopes). Every request: `Authorization: Bearer `. Responses wrap the payload in `{success, message, data}`. Lists are paginated with `page` and `per_page` (max 100). Rate limit: 60 requests per minute per token. Webhooks are signed: header `X-Groundflag-Signature` (see /docs#webhooks); deliveries retry 5 times with backoff and can be replayed from Settings → Webhooks.", "contact": { "name": "Groundflag support", "email": "support@groundflag.com", "url": "https://groundflag.com" } }, "servers": [ { "url": "https://api.groundflag.com/api/v1/public", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Jobs" }, { "name": "Clients" }, { "name": "Estimates" }, { "name": "Invoices" }, { "name": "Payments" }, { "name": "Sales" }, { "name": "Analytics" }, { "name": "Vendors" }, { "name": "Tasks" }, { "name": "Leads" }, { "name": "Time entries" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Who this token is (connection test)", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/projects": { "get": { "operationId": "listJobs", "summary": "List jobs", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "projects.read", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lead", "design", "quoted", "approved", "template", "production", "installation", "invoice", "completed", "warranty", "cancelled", "lost" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createJob", "summary": "Create a job", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "projects.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/projects/{id}": { "get": { "operationId": "getJob", "summary": "Get a job", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "projects.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateJob", "summary": "Update a job", "tags": [ "Jobs" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "projects.write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/clients": { "get": { "operationId": "listClients", "summary": "List clients", "tags": [ "Clients" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "clients.read", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createClient", "summary": "Create a client", "tags": [ "Clients" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "clients.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/clients/{id}": { "get": { "operationId": "getClient", "summary": "Get a client", "tags": [ "Clients" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "clients.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateClient", "summary": "Update a client", "tags": [ "Clients" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "clients.write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/quotes": { "get": { "operationId": "listEstimates", "summary": "List estimates (proposals)", "tags": [ "Estimates" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "quotes.read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated: draft, sent, accepted, rejected, expired" }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Estimate" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/quotes/{id}": { "get": { "operationId": "getEstimate", "summary": "Get an estimate", "tags": [ "Estimates" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "quotes.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Estimate" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "invoices.read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "due_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "due_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get an invoice", "tags": [ "Invoices" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "invoices.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments": { "get": { "operationId": "listPayments", "summary": "List payments", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "payments.read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "invoice_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get a payment", "tags": [ "Payments" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "payments.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders": { "get": { "operationId": "listOrders", "summary": "List sales (closed orders)", "tags": [ "Sales" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "orders.read", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "quote_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sale_date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "sale_date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get a sale", "tags": [ "Sales" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "orders.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/suppliers": { "get": { "operationId": "listVendors", "summary": "List vendors", "tags": [ "Vendors" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "suppliers.read", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createVendor", "summary": "Create a vendor", "tags": [ "Vendors" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "suppliers.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/suppliers/{id}": { "get": { "operationId": "getVendor", "summary": "Get a vendor", "tags": [ "Vendors" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "suppliers.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateVendor", "summary": "Update a vendor", "tags": [ "Vendors" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "suppliers.write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "deleteVendor", "summary": "Delete a vendor", "tags": [ "Vendors" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "suppliers.write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Empty" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tasks.read", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "in_progress", "completed", "dismissed", "snoozed" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createTask", "summary": "Create a task", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "tasks.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Task" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/leads": { "post": { "operationId": "createLead", "summary": "Create a lead (client + job in the lead stage)", "tags": [ "Leads" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "leads.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Lead" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" }, "409": { "description": "The client is locked" } } } }, "/time-entries": { "get": { "operationId": "listTimeEntries", "summary": "List clock punches", "tags": [ "Time entries" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "time_entries.read", "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Default 25, max 100" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks.manage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "subscribeWebhook", "summary": "Subscribe a URL to events (REST hook)", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks.manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionCreated" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/webhooks/events": { "get": { "operationId": "listWebhookEvents", "summary": "Events you can subscribe to", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks.manage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEventList" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{id}": { "delete": { "operationId": "unsubscribeWebhook", "summary": "Unsubscribe", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "x-required-scope": "webhooks.manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Empty" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/analytics": { "get": { "operationId": "analyticsPack", "summary": "Ready analytics pack (money, field or safety) as JSON or CSV", "tags": ["Analytics"], "security": [{"bearerAuth": []}], "x-required-scope": "reports.read", "parameters": [ {"name": "pack", "in": "query", "required": false, "schema": {"type": "string", "enum": ["money", "field", "safety"]}}, {"name": "project_id", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "period", "in": "query", "required": false, "schema": {"type": "string"}}, {"name": "start_date", "in": "query", "required": false, "schema": {"type": "string", "format": "date"}}, {"name": "end_date", "in": "query", "required": false, "schema": {"type": "string", "format": "date"}}, {"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["csv"]}} ], "responses": { "200": {"description": "OK"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/TooManyRequests"} } } } }, "webhooks": { "event": { "post": { "summary": "Event delivery to your subscribed URL", "description": "Events: quote.created, quote.sent, quote.accepted, quote.rejected, quote.expired, quote.deposit_paid, project.created, project.stage_changed, client.created, client.updated, invoice.paid, payment.received, order.created, order.status_changed, time_entry.clocked_in, time_entry.clocked_out.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token from Settings → API" } }, "responses": { "Unauthorized": { "description": "Missing, invalid, revoked or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The token lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found in this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limit reached; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Envelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true } }, "additionalProperties": true }, "PageMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "Empty": { "nullable": true }, "Error": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": true }, "Me": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "token": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }, "additionalProperties": true }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "stage": { "type": "string" }, "priority": { "type": "string" }, "client_id": { "type": "string", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "estimated_value": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "JobInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "client_id": { "type": "string", "format": "uuid", "nullable": true }, "stage": { "type": "string", "description": "Defaults to lead" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "source": { "type": "string", "nullable": true }, "estimated_value": { "type": "number", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true, "description": "An active member of the company" }, "tags": { "type": "array", "items": { "type": "string" } }, "deadline": { "type": "string", "format": "date", "nullable": true }, "address": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "contact_name": { "type": "string", "nullable": true }, "contact_phone": { "type": "string", "nullable": true }, "purchase_order": { "type": "string", "nullable": true } }, "required": [ "title" ] }, "Client": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "ClientInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "phone2": { "type": "string", "nullable": true }, "cell": { "type": "string", "nullable": true }, "account_name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "address_line_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "contact_type": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true } }, "required": [ "name" ] }, "Estimate": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "nullable": true }, "project_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "currency": { "type": "string", "nullable": true }, "subtotal": { "type": "number" }, "tax": { "type": "number" }, "total": { "type": "number" }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "nullable": true }, "project_id": { "type": "string", "nullable": true }, "client_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "total": { "type": "number" }, "amount_paid": { "type": "number" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "Payment": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_id": { "type": "string", "nullable": true }, "amount": { "type": "number" }, "status": { "type": "string" }, "payment_method": { "type": "string", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string", "nullable": true }, "quote_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "payment_status": { "type": "string", "nullable": true }, "total": { "type": "number" }, "sale_date": { "type": "string", "format": "date", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "Vendor": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "tax_id": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "VendorInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "whatsapp": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "tax_id": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } }, "required": [ "name" ] }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "priority": { "type": "string" }, "status": { "type": "string" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TaskInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 500 }, "description": { "type": "string", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true }, "assigned_to": { "type": "integer", "nullable": true, "description": "Defaults to the company owner" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "due_date": { "type": "string", "format": "date", "nullable": true } }, "required": [ "title" ] }, "LeadInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "description": "Email or phone is required" }, "phone": { "type": "string" }, "message": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip_code": { "type": "string", "nullable": true }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true } }, "required": [ "name" ] }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "description": "The job id" }, "client_id": { "type": "string" }, "title": { "type": "string" }, "stage": { "type": "string" }, "deduplicated": { "type": "boolean", "description": "True when the same person sent the same lead in the last 10 minutes" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TimeEntry": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "integer" }, "user_name": { "type": "string", "nullable": true }, "user_email": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "checked_in", "on_break", "checked_out" ] }, "check_in_at": { "type": "string", "format": "date-time", "nullable": true }, "check_out_at": { "type": "string", "format": "date-time", "nullable": true }, "check_in_address": { "type": "string", "nullable": true }, "check_out_address": { "type": "string", "nullable": true }, "break_minutes": { "type": "integer" }, "total_minutes": { "type": "integer", "nullable": true }, "review_status": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "WebhookSubscriptionInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public https URL" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "An event name from /webhooks/events, or *" } }, "name": { "type": "string", "nullable": true } }, "required": [ "url", "events" ] }, "WebhookSubscription": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "failing", "disabled" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "WebhookSubscriptionCreated": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret, shown once" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "WebhookEventList": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "description": { "type": "string" } } } }, "WebhookPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_ ULID, unique per event" }, "event": { "type": "string" }, "api_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "company_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "previous": { "type": "object", "additionalProperties": true } } } } } }