Public API Documentation

Integrate Stone Project with your systems using the Public API. Create tokens in Settings → API Settings to get started.

Authentication

All requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

API tokens are created in the app at Settings → API Settings. Each token has specific scopes that control which resources can be accessed.

Base URL

https://api.stoneproject.app/api/v1/public

All endpoint paths below are relative to this base URL.

Response Format

All responses follow a consistent JSON format:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Pagination

List endpoints return paginated results. Use per_page (max 100) and page query parameters.

{
  "success": true,
  "data": {
    "items": [ ... ],
    "meta": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 25,
      "total": 60
    }
  }
}

Rate Limiting

The API is rate-limited. The current limits are returned in response headers:

Error Handling

Errors return a success: false response with an error code:

{
  "success": false,
  "message": "Token is invalid or revoked",
  "error_code": "token_invalid"
}

Projects

GET /projects projects.read

List all projects for your company.

GET /projects/{id} projects.read

Get a single project by ID. Client data is included automatically.

POST /projects projects.write

Create a new project.

curl -X POST https://api.stoneproject.app/api/v1/public/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Kitchen Remodel - Smith",
    "client_id": "019c...",
    "priority": "high",
    "estimated_value": 8500
  }'

PUT /projects/{id} projects.write

Update an existing project. Same fields as POST /projects above, all optional — send only what you want to change. Note the method is PUT, not POST: a POST to /projects creates a new project instead of updating one.

The job site street is address. We also accept address_line_1 as an alias for it, since the field beside it is called address_line_2. Any key we do not recognise is ignored and named back to you in the response message, so a typo never passes as a silent success.

curl -X PUT https://api.stoneproject.app/api/v1/public/projects/019c... \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "4501 Cox Rd",
    "address_line_2": "Suite 200",
    "city": "Glen Allen",
    "state": "VA",
    "zip_code": "23060",
    "contact_name": "Faro Vitale",
    "contact_phone": "+1 718 208 3214"
  }'

Response Example

A project object includes:

{
  "success": true,
  "data": {
    "id": "019c...",
    "title": "Kitchen Remodel - Smith",
    "status": "active",
    "stage": "quoted",
    "priority": "high",
    "estimated_value": 8500.00,
    "deadline": "2026-05-15",
    "client": {
      "id": "019c...",
      "name": "John Smith"
    },
    "created_at": "2026-03-10T14:30:00Z",
    "updated_at": "2026-04-01T09:15:00Z"
  }
}

Clients

GET /clients clients.read

List all clients for your company.

GET /clients/{id} clients.read

Get a single client by ID. Includes project count.

POST /clients clients.write

Create a new client.

curl -X POST https://api.stoneproject.app/api/v1/public/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "555-0100",
    "source": "website"
  }'

PUT /clients/{id} clients.write

Update an existing client. All fields are optional.

Response Example

A client object includes:

{
  "success": true,
  "data": {
    "id": "019c...",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "555-0100",
    "account_name": "Smith Design Co.",
    "source": "website",
    "projects_count": 3,
    "created_at": "2026-01-20T10:00:00Z"
  }
}

Quotes

GET /quotes quotes.read

List all quotes for your company.

GET /quotes/{id} quotes.read

Get a single quote by ID. Client and project data are included automatically.

Orders

Closed sales orders — read-only access to finalized deals. An order is created when a quote is accepted and the sale is closed.

GET /orders orders.read

List all orders for your company.

Response Example

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "019e-...",
        "number": "ORD-2026-00042",
        "name": "Kitchen Renovation — Smith",
        "status": "active",
        "payment_status": "partial",
        "currency": "USD",
        "subtotal": 7200.00,
        "tax": 504.00,
        "discount_amount": 0.00,
        "total": 7704.00,
        "amount_paid": 3852.00,
        "balance_due": 3852.00,
        "sale_date": "2026-06-15",
        "payment_due_date": "2026-07-15",
        "payment_terms": "net30",
        "payment_terms_days": 30,
        "deposit_required": true,
        "deposit_percentage": 50,
        "deposit_amount": 3852.00,
        "installments_count": 2,
        "sqft": 48.5,
        "po_number": "PO-98765",
        "salesperson": "Jane Doe",
        "notes": null,
        "project_id": "019c-...",
        "quote_id": "019d-...",
        "lead_name": "John Smith",
        "account_name": "Smith Family",
        "created_at": "2026-06-15T10:00:00Z",
        "updated_at": "2026-06-20T14:00:00Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "last_page": 3,
      "per_page": 10,
      "total": 28
    }
  }
}

GET /orders/{id} orders.read

Get a single order by ID. The line_items array is included only on this detail response (not on the list). Internal cost, commission, and margin keys are stripped from each line item.

Invoices

GET /invoices invoices.read

List all invoices for your company.

GET /invoices/{id} invoices.read

Get a single invoice by ID. Client, project, and payments are included automatically.

Payments

GET /payments payments.read

List all payments for your company.

GET /payments/{id} payments.read

Get a single payment by ID. Invoice summary is included automatically.

Pieces / Inventory

Manage your company's stone pieces and remnants — the core of Stone Project.

List Pieces

List your company's pieces with optional filters. Requires the pieces.read scope. To browse public remnants across the whole marketplace (other companies' listings), use the Search endpoint instead.

Response Example

{
  "data": [
    {
      "id": "019d-...",
      "title": "White Carrara Remnant",
      "description": "Beautiful remnant piece, polished finish",
      "status": "available",
      "dimensions": {
        "length_cm": 120,
        "width_cm": 60,
        "thickness_cm": 3,
        "area_sqft": 7.75
      },
      "price": 350.00,
      "price_type": "fixed",
      "color": "White",
      "finish": "polished",
      "origin": "Italy",
      "stone_type": { "id": "...", "name": "Marble" },
      "category": { "id": "...", "name": "Remnants" },
      "images": [
        { "id": 1, "url": "https://...", "thumbnail_url": "https://..." }
      ],
      "company": { "id": "...", "name": "Stone Works LLC" },
      "views_count": 42,
      "created_at": "2026-03-15T10:30:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 98 }
}

Get Piece

Get a single piece by ID. Includes all details, images, company info, and related stone type/category.

Create Piece

Create a new piece in your inventory. If coordinates are not provided, the company's location is used.

Update Piece

Update an existing piece. All fields are optional — only send the fields you want to change.

Delete Piece

Soft-delete a piece. It can be restored later via the app.

Upload Piece Images

Upload images to a piece. Send as multipart/form-data.

Update Piece Status

Change the status of a piece.

Suppliers

Manage your stone and material suppliers.

List Suppliers

List all suppliers for your company.

Response Example

{
  "success": true,
  "data": [
    {
      "id": "019d-...",
      "name": "Premium Stone Supply",
      "email": "[email protected]",
      "phone": "+1 555-0123",
      "city": "Miami",
      "state": "FL",
      "country": "US",
      "is_active": true,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
}

Get Supplier

Get a single supplier by ID.

Create Supplier

Create a new supplier.

Update Supplier

Update an existing supplier. All fields are optional.

Delete Supplier

Delete a supplier.

Tasks

List tasks, newest first. Filters: project_id, status (pending, in_progress, completed, dismissed, snoozed).

Create a task. title is required; optional description, project_id (a project of this company), assigned_to (an active member; defaults to the owner), priority (low, medium, high, urgent) and due_date (defaults to today).

Leads

Create a lead: the client (matched by email, then phone, so the same person stays one client) and a project in the lead stage, exactly like a website form does. name and email or phone are required; optional message, address fields and utm_source/utm_medium/utm_campaign. The same lead sent twice within 10 minutes returns the first one with deduplicated: true.

Time entries

Clock punches, newest first: who, check-in and check-out, break and total minutes, review status. Filters: user_id, from, to (dates). GPS and photos are never exposed.

Webhook subscriptions

REST hooks for Zapier, Make and your own code: subscribe a URL when your automation turns on, unsubscribe when it turns off. Deliveries are the same signed, retried webhooks described below.

Body: url (public https), events (array of event names, or ["*"]), optional name. The response carries the signing secret once.

Search

Search the Remnant Finder marketplace for pieces across all companies.

Search Pieces

Full-text search across public pieces. Supports filters, geo search, and sorting.

Stone Types

Reference data for stone types (Marble, Granite, Quartz, etc.). Read-only.

List Stone Types

Returns all available stone types. Requires a valid API token (Bearer); no specific scope needed. Each item also includes slug and icon.

Response Example

{
  "data": [
    { "id": "019a-...", "name": "Marble" },
    { "id": "019a-...", "name": "Granite" },
    { "id": "019a-...", "name": "Quartz" },
    { "id": "019a-...", "name": "Quartzite" },
    { "id": "019a-...", "name": "Porcelain" }
  ]
}

Categories

Piece categories (Slabs, Remnants, Countertops, etc.). Read-only.

List Categories

Returns all active categories, ordered by display order. Requires a valid API token (Bearer); no specific scope needed. Each item includes id, name, slug, icon.

Colors

System and custom colors used for pieces.

List Colors

Returns system colors plus your company's custom colors.

Create Color

Create a custom color for your company.

Origins

Stone origin countries and regions.

List Origins

Returns system origins plus your company's custom origins.

Create Origin

Create a custom origin for your company.

Available Scopes

Each API token is created with specific scopes that control access:

Read-only reference data (stone types, categories, colors, origins) and the marketplace Search require only a valid token — no specific scope.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account. Configure webhook URLs in Settings → API Settings → Webhooks.

Subscribe one or more HTTPS endpoints to the events your integration cares about. Each delivery is signed (HMAC-SHA256) so you can verify it came from us — see Verifying the signature below.

Available Events

Subscribe to * to receive every event.

Webhook Payload

Every delivery is a JSON POST with a stable envelope. data is the public representation of the entity (the same shape as the matching GET endpoint). previous is present only on change events and holds the prior values of the changed fields.

{
  "id": "evt_01J9Z4Q1ABC...",
  "event": "quote.accepted",
  "api_version": "v1",
  "created_at": "2026-06-26T14:30:00+00:00",
  "company_id": "019c...",
  "data": {
    "id": "019d...",
    "number": "Q-2026-00012",
    "project_id": "019c...",
    "status": "accepted",
    "total": 8500.00,
    "accepted_at": "2026-06-26T14:30:00+00:00"
  },
  "previous": { "status": "sent" }
}

The id (evt_…) is unique per event — use it to make your handler idempotent, since a delivery may be retried. Delivery order is best-effort, not guaranteed.

Verifying the signature

Each request carries these headers:

The signature is HMAC-SHA256 of the string "{t}.{raw_request_body}", keyed with your endpoint's signing secret (shown only once, when you create or rotate the endpoint). Verify it against the raw request body (before any JSON parsing), and reject timestamps outside a tolerance window (e.g. 5 minutes) to prevent replay attacks.

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_REMNANTFINDER_SIGNATURE']; // "t=...,v1=..."
parse_str(strtr($header, ',', '&'), $p);

$expected = hash_hmac('sha256', $p['t'] . '.' . $payload, $YOUR_SIGNING_SECRET);

if (! hash_equals($expected, $p['v1']) || abs(time() - (int) $p['t']) > 300) {
    http_response_code(400);
    exit; // reject: bad signature or stale timestamp
}
// trusted — respond 2xx quickly to acknowledge receipt

Delivery & retries

• Only HTTPS endpoints are accepted, and the target must resolve to a public address.
• A delivery is successful on any 2xx response. Respond within a few seconds.
• Failed deliveries are retried up to 5 times with exponential backoff (~1m → 5m → 30m → 2h → 5h).
• After repeated consecutive failures the endpoint is automatically disabled and the account owner is notified. Re-enable it from Settings → API Settings → Webhooks, where you can also browse the delivery log and replay individual deliveries.
• Send test posts a delivery whose event is ping and whose data is a real sample — your most recent record for the first event the endpoint subscribes to, serialized exactly like the live payload. Point your automation platform's field mapping at that request instead of creating a throwaway record just to get an example.