Get started
Getting Started Guide:
1. Account & Permissions
The SitePro API is permission-scoped. The sites and equipment returned by every endpoint are limited to what your account has been granted access to. If a site does not appear in GET /v1/sites, your account does not have access to it.
| Role | Sites visible | Equipment visible | Transactions visible |
|---|---|---|---|
| API User | Assigned sites only | Equipment at assigned sites | Transactions at assigned sites |
| API Parent Admin | All sites under parent account | All equipment under parent account | All transactions under parent account |
Tip: Getting empty responses? The most common cause is a missing or incorrect permission assignment. Contact your System administrator to verify your account has the API role and the correct site access.
2. Authentication
POST /token is the only unauthenticated endpoint in the API. Submit your credentials to receive a JWT Bearer token. Include this token in the Authorization header on every subsequent request.
3. Data Model
Every object in the SitePro API is scoped to a site. Understanding this hierarchy before making calls will prevent confusion when chaining requests together.
- Site - A physical location you have access to. Identified by an integer id. Every downstream call requires a siteId.
- Equipment - Physical/virtual devices for a site. Pumps, Meters, Sensors, Tanks, and external source readings. Each has its own list endpoint and returns equipment IDs used for log queries and live data.
- Logs - Time-series telemetry data for a piece of equipment over a date range. Returned as arrays of aggregated readings (avg / min / max) at the requested interval. Raw logs are currently available for Sensors, with the other equipment types (Pumps, Meters, and Tanks) raw logs coming soon.
- Transactions - Ticket records for fluid hauling events at a site. Separate from equipment telemetry. Can include images referenced by UUID.
Note: SitePro follows a tiered system architecture of Sites -> Equipment -> Logs, so it is best to start by retrieving SiteIDs, using those SiteIDs to retrieve EquipmentIDs, which can then be used to retrieve log data, live data, configuration set points, etc
4. List Sites
Returns all sites that an account has access to. The id values in this response are required for all equipment and transaction calls.
5. List Equipment at a Site
Use a siteId from the previous step to get a list of the equipment for that site. Each of the four equipment types has its own list endpoint. The id returned for each piece of equipment is what you will use to pull logs.
| Equipment type | Endpoint | Key response fields |
|---|---|---|
| Pumps | GET /v1/edge/user/pumps?siteIds={siteId} | id, name, active |
| Meters | GET /v1/edge/user/meters?siteIds={siteId} | id, name, pipelineId |
| Sensors | GET /v1/edge/user/sensors?siteIds={siteId} | id, name, active |
| Tanks | GET /v1/edge/user/tanks?siteIds={siteId} | id, name, active |
6. Pull Equipment Logs
All log endpoints follow the same pattern: POST a request body with an array of equipment IDs, a UTC date range, and an interval. The interval controls how readings are grouped and returned.
| Interval value | Description |
|---|---|
| HourData | One record per hour |
| DayData | One record per day |
Examples:
Fetches groomed pump logs for one meter in a time range and interval. The request body uses pumpIds (integer array, max 1) along with a UTC date range and interval.
Fetches groomed meter logs for one meter in a time range and interval. The request body uses meterIds (integer array, max 1) along with a UTC date range and interval.
Sensors support two log endpoints: summary logs (groomed, interval-based) and raw logs (individual timestamped readings). Use summary logs for dashboards and trend analysis. Use raw logs when you need the full resolution of every recorded reading.
Returns the last known reading for every sensor at a given site. Unlike the sensor log endpoints - which return historical data aggregated over a time range and interval - this endpoint gives you a point-in-time snapshot of current conditions across all sensors at once. No date range or interval is required.
This is the recommended endpoint for dashboards, alerting integrations, or any use case where you need to know what sensors are reading right now.
Fetches groomed tank logs for one tank in a time range and interval. Tank responses separate fluid levels and volumes by layer - total, oil, and water - making it straightforward to track tank composition over time.
7. Transactions & Tickets
Transactions are ticket records for fluid disposal and other hauling events. Each transaction captures source site, destination site, hauler details, volumes, and review status. Transactions can also carry image UUIDs for attached photos - see Section 8. The request can be modified to include only results for transactions modified after a specified date.
The change log endpoint gives you a full audit trail of edits made to any transaction: who changed what, when, and what the previous value was.
8. Images
Transactions may contain imageUUIDs and a ticketImage UUID in their response. Pass those UUIDs to the images endpoint to retrieve the actual image data.
Error Handling
All error responses return a JSON body with details on what went wrong. The table below covers the status codes you will encounter across all endpoints.
| Status | Meaning | What to do |
|---|---|---|
| 200 | Success | Parse the response body as JSON |
| 400 | Validation error | Check your request body - missing required fields, invalid date format, or out-of-range values |
| 401 | Unauthorized | Token is missing, expired, or malformed. Re-authenticate via POST /token and retry |
| 403 | Forbidden | Your account does not have access to the requested resource. Check permissions with your administrator |
| 404 | Not found | The site ID or equipment ID does not exist or is not accessible to your account |
| 500 | Server error | Retry with exponential backoff. If it persists, contact SitePro support |
End-to-End Example
The following sequence walks through a complete integration: authenticate, discover a site, list pumps, pull logs for January, retrieve transactions for the same period, and collect any attached images.
Step 1 - Authenticate
POST /token with your credentials. Store the access_token.
Step 2 - List sites
GET /v1/sites. Store the id of the site you want to work with.
Step 3 - List equipment
GET /v1/edge/user/pumps?siteIds={siteId}. Store the id of the pump you want to monitor.
Repeat for meters, sensors, or tanks as needed.
Step 4 - Pull Logs
POST /v1/pumps/logs/load with your pump id, date range, and interval.
Step 5 - Pull transactions (if any)
POST /v1/transactions/logs/load with your siteId and the same date range.
Step 6 - Retrieve images (if any)
Collect imageUUIDs from transaction responses.
POST /v1/images/tickets with the collected UUIDs.