For App Developers

Build on the property record.

The Foundation API lets your software submit property service events, attach documents, and read event history — programmatically, at scale. Your field software, CRM, or dispatching platform can contribute directly to the permanent property record.

View API Reference Request API Access

Base URL

https://api-rc.bluetruss.com

Source: PUBLIC_API_BASE_URL

Authentication

Pass your provider identity via the X-Provider-Id request header. API keys will be issued during early access onboarding.

Format

All request and response bodies are JSON unless uploading a document, which uses multipart/form-data. All timestamps are ISO 8601 with timezone offset.

API Reference — v0.2.1-rc.4

Endpoints

Try It Defaults

Used for all Try It requests on this page.

POST
/events

Submit a new property event

Records a completed service event against a property. The property is resolved automatically from the site address. Returns a unique eventId that can be used to attach documents.

X-Provider-Id = your-provider-id Content-Type = application/json

Request Body

{
  "providerEventId": "WO-10045",
  "eventType": "hvac.service.completed",
  "occurredAt": "2026-07-01T14:30:00-05:00",
  "summary": "Annual HVAC tune-up, replaced filter, checked refrigerant.",
  "site": {
    "addressLine1": "123 Main Street",
    "city": "Nashville",
    "state": "TN",
    "postalCode": "37201"
  },
  "tags": ["hvac", "maintenance"],
  "references": [
    { "type": "workOrder", "value": "WO-10045" }
  ],
  "metadata": {
    "technician": "Jane Doe",
    "unitModel": "Carrier 24ACC636A003"
  }
}

Responses

  • 202 Accepted Event recorded. Body contains eventId and providerEventId. 
    {
  "eventId": "f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b",
  "providerEventId": "WO-10045",
  "status": "accepted"
}
  • 400 Bad Request Validation failed. Body contains field-level error details. 
    {
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Validation failed.",
  "status": 400,
  "errors": {
    "ProviderEventId": ["ProviderEventId is required."],
    "Site.PostalCode": ["Site.PostalCode is required."]
  }
}
  • 409 Conflict An event with this providerEventId already exists. 
    {
  "message": "An event with this ProviderEventId already exists.",
  "providerEventId": "WO-10045",
  "eventId": "f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b"
}
GET
/events/{eventId}

Retrieve an event by Foundation ID

Returns the full event record including site details, metadata, and any attached documents. Only accessible to the provider that submitted the event.

X-Provider-Id = your-provider-id

Responses

  • 200 OK Event found. Body contains full event details and document list. 
    {
  "eventId": "f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b",
  "providerEventId": "WO-10045",
  "eventType": "hvac.service.completed",
  "occurredDate": "2026-07-01T14:30:00-05:00",
  "summary": "Annual HVAC tune-up, replaced filter, checked refrigerant.",
  "site": {
    "addressLine1": "123 Main Street",
    "city": "Nashville",
    "state": "TN",
    "postalCode": "37201"
  },
  "documents": []
}
  • 404 Not Found Event not found or not accessible with the current provider identity. 
    {
  "title": "Event not found.",
  "status": 404,
  "detail": "Event 'f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b' was not found."
}
GET
/events?providerEventId={id}

Retrieve an event by your own ID

Looks up an event using the providerEventId you assigned at submission. Useful for checking whether a work order has already been recorded.

X-Provider-Id = your-provider-id

Responses

  • 200 OK Event found. 
    {
  "eventId": "f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b",
  "providerEventId": "WO-10045",
  "eventType": "hvac.service.completed",
  "occurredDate": "2026-07-01T14:30:00-05:00",
  "summary": "Annual HVAC tune-up, replaced filter, checked refrigerant.",
  "site": {
    "addressLine1": "123 Main Street",
    "city": "Nashville",
    "state": "TN",
    "postalCode": "37201"
  },
  "documents": []
}
  • 400 Bad Request providerEventId query parameter is required. 
    {
  "title": "Validation failed.",
  "status": 400,
  "errors": {
    "providerEventId": ["providerEventId is required."]
  }
}
  • 404 Not Found No event found for this providerEventId. 
    {
  "title": "Event not found.",
  "status": 404,
  "detail": "Event with providerEventId 'WO-10045' was not found."
}
POST
/events/{eventId}/documents

Attach a document to an event

Uploads a file (PDF, image) and attaches it to an existing event. Accepts multipart/form-data with a documentType field and a file field.

X-Provider-Id = your-provider-id Content-Type = multipart/form-data

Request Body

// multipart/form-data
documentType: "Invoice"   // Invoice | Receipt | Photo | Inspection Report | Permit | Warranty
file: <binary>

Responses

  • 202 Accepted Document uploaded and attached. 
    {
  "documentId": "6d67bc57-6092-41e2-a43c-2d70a5efef2c",
  "eventId": "f4ca8a20-8f7b-4e67-9cb1-c07b68f9250b",
  "documentType": "Invoice",
  "status": "accepted"
}
  • 400 Bad Request Validation failed — missing file, unsupported document type, or file is empty.
  • 404 Not Found Parent event not found.
  • 413 Payload Too Large File exceeds the 25 MB limit. 
    {
  "message": "File size exceeds the 25 MB limit."
}
  • 415 Unsupported Media Type MIME type not permitted for the chosen document type. 
    {
  "message": "Unsupported MIME type 'text/plain' for document type 'Invoice'."
}
  • 422 Unprocessable Entity Document limit reached (max 20 per event). 
    {
  "message": "Document limit reached. Maximum 20 documents are allowed per event."
}
GET
/events/{eventId}/documents/{documentId}

Download a document

Returns the raw file content of an attached document with appropriate Content-Type and Content-Disposition headers.

X-Provider-Id = your-provider-id

Responses

  • 200 OK File stream returned. 
    // Binary file stream
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-10045.pdf"
  • 404 Not Found Document or event not found. 
    {
  "message": "Document not found."
}

Reference Data

Supported event types

The eventType field must be one of the recognized values below. The catalog is expanding — contact us if your trade isn't listed.

  • hvac.service.completed HVAC service
  • roof.replaced Roof replacement
  • plumbing.repaired Plumbing repair

Quick Start — cURL

curl -X POST https://api-rc.bluetruss.com/events \
  -H "Content-Type: application/json" \
  -H "X-Provider-Id: your-provider-id" \
  -d '{
    "providerEventId": "WO-10045",
    "eventType": "hvac.service.completed",
    "occurredAt": "2026-07-01T14:30:00-05:00",
    "summary": "Annual HVAC tune-up.",
    "site": {
      "addressLine1": "123 Main Street",
      "city": "Nashville",
      "state": "TN",
      "postalCode": "37201"
    }
  }'

Ready to integrate?

Foundation is in early access. Tell us about your platform and we'll get you set up with credentials and sandbox access.

Request API Access