Texture OEM / TPDO Integration Technical Requirements

Version: 1.1 Last Updated: December 2025 Contact: integrations@texturehq.com

---

Executive Summary

Texture provides a unified platform for device connectivity, telemetry ingestion, and real-time control of distributed energy resources (DERs).

This specification defines the technical requirements for:

• OEMs (device manufacturers), and
• TPDOs (Third-Party Demand Orchestrators — any third-party entity that enrolls, aggregates, orchestrates, dispatches, or otherwise exercises operational control over distributed energy resources or customer-sited devices and provides a cloud-based interface for accessing telemetry, control signals, or program participation data, regardless of whether the entity manufactures the devices)

integrating their devices with the Texture platform. This includes both traditional OAuth-based enrollment flows and OEM-initiated enrollment, where manufacturers can proactively register devices and provide customer consent signals at commissioning time.

These requirements are device-type agnostic. Different device classes (batteries, solar inverters, EV chargers, thermostats, etc.) have different telemetry and control surfaces. The canonical field-level schemas for each device type are defined in Texture's API documentation. This spec describes the integration patterns and expectations for accessing and controlling those devices via an OEM or TPDO API.

Integrations must be reliable, secure, and capable of supporting fleet-scale telemetry and dispatch.

---

1. Scope and Device Types

Texture supports multiple device classes, including but not limited to:

• Whole-home and C&I battery systems
• Solar inverters and hybrid inverter systems
• EV charging equipment
• Smart thermostats and HVAC controls
• Other controllable DERs exposed via OEM or TPDO APIs

For any given integration, Texture and the OEM/TPDO will agree on which Texture device models apply (e.g., battery, inverter, thermostat) and map the OEM/TPDO's data to those models.

Field-level schemas for each device class are defined in Texture's API documentation. This spec focuses on transport, freshness, control semantics, and performance—not enumerating every field for every device type.

---

2. Integration Patterns

There are three primary ways devices integrate with Texture:

2.1 Texture-led ("Pull") Integrations

In this pattern, Texture implements the integration:

• Texture reads the OEM/TPDO's API documentation.
• Texture implements polling against the OEM/TPDO API.
• Texture performs device discovery (e.g., list sites → list devices) and creates internal device records.
• Texture translates OEM-specific telemetry and commands into Texture's standard device models.

OEMs/TPDOs typically do not need to build anything new; Texture does the implementation work.

2.2 Partner-led ("Push / Programmatic") Integrations

In this pattern, the OEM/TPDO takes a more active role:

• OEM/TPDO exposes APIs or event streams Texture subscribes to.
• OEM/TPDO assists with device identification and registration.
• OEM/TPDO implements push-first behaviors (e.g., telemetry pushed to Texture).

Partner-led integrations allow faster onboarding when OEMs/TPDOs have well-documented, reliable APIs that meet this spec's requirements.

2.3 Texture-native Integrations

In this pattern, the OEM/TPDO has already pointed their devices and/or API data to Texture:

• Texture already captures all telemetry data directly from devices or the OEM/TPDO's systems.
• The OEM/TPDO only needs to respond to control signals from Texture.
• In some cases, Texture handles control as well, communicating directly with device endpoints on behalf of the OEM/TPDO.

Texture-native integrations provide the tightest coupling and fastest response times for grid services.

Regardless of pattern, OEMs/TPDOs must meet the freshness, reliability, and control expectations defined in this document.

---

3. Authentication & Authorization

Texture requires programmatic access to:

• Read telemetry for authorized devices
• Send control/dispatch requests to those devices

The specific auth mechanism (OAuth2, API key, service account) can vary by OEM/TPDO. What matters is that it is secure, automatable, and appropriately scoped.

We distinguish integrations by who is granting authorization, not by which auth protocol is used.

3.1 End-User Authorized (BYOD)

Used when the end customer (homeowner, business) owns the device and explicitly grants Texture access.

OAuth 2.0 is the preferred authorization method. Texture will never store end-user username/password credentials, as this is inherently insecure. Access must be granted through a delegated authorization flow that provides an explicit grant the end user can revoke.

Requirements:

• OAuth 2.0 Authorization Code flow (or equivalent delegated authorization mechanism).
• End user can grant Texture access to read device information/telemetry and send allowable control commands.
• Access can be revoked by the end user at any time.
• Long-lived access is supported via refresh tokens (≥90 days recommended).
• The OEM/TPDO defines the actual scopes/permissions; Texture will request the minimal set needed to discover devices, read telemetry, and issue control commands.

3.2 Utility or Program-Authorized Access

Used when a utility, CCA, or program administrator is the effective owner/operator of a fleet of devices.

Requirements:

• Programmatic access to telemetry and control for enrolled devices via OAuth2 (client credentials) or API keys/service accounts with clear scoping.
• Ability to onboard devices in bulk (by program, site, account, etc.).
• Ability to revoke or adjust access by program/portfolio.

3.3 Fleet Owner / Third-Party Device Operator (TPDO)

Used when a fleet owner, installer, aggregator, or TPDO manages devices for many end customers.

Requirements:

• Programmatic access via OAuth2 or API key/service account.
• Fleet-level querying of devices and metadata.
• Bulk operations (e.g., "all devices in portfolio X").
• Stable device identifiers (no churn on IDs).

Any TPDO that aggregates multiple OEMs must ensure all devices they expose to Texture meet the freshness, reliability, and control expectations in this spec.

---

4. Telemetry Requirements

Texture requires fresh, structured telemetry for all enrolled devices at a cadence that supports grid operations and program logic.

4.1 Delivery Patterns

Push (Preferred)

OEM/TPDO sends events to Texture when data changes or at specified intervals via:

• Webhooks / HTTP callbacks
• WebSockets / streaming
• MQTT, Kafka, or equivalent

Requirements:

• Data delivered in near real time or on a consistent schedule.
• Retries on transient failure.
• Reasonable backoff and idempotency or deduplication support.

Polling (Fallback)

Texture calls OEM/TPDO APIs on a schedule to fetch telemetry.

Requirements:

• Support polling at 5–15 minute intervals.
• Data returned must reflect current device state, not stale batch-processed data.
• Data freshness must be < 15 minutes.
• API response latency: p95 < 2 seconds.

4.2 Telemetry Expectations

For every device type integrated with Texture, OEMs/TPDOs must provide:

• A stable device identifier and associated metadata.
• Time-stamped telemetry fields that map to Texture's device models.

Examples (illustrative):

• Batteries: state of charge, charge/discharge power, available energy, connection/health status
• Solar inverters: real power output, grid connection state, export/import, per-phase metrics
• Thermostats/HVAC: current temperature, setpoint(s), mode, fan state, system on/off

The authoritative field list per device type is in Texture's API documentation.

---

5. Control & Dispatch Requirements

Control surfaces vary by device type. How control is executed depends on the integration pattern:

Texture-led integrations: Texture translates control requests into OEM/TPDO-specific API calls and hits their endpoints directly to actuate commands.

Partner-led integrations: Texture issues a standardized control signal. The OEM/TPDO transforms it into their own command format and actuates it on the device.

Texture-native integrations: Texture handles everything end-to-end, contacting device endpoints directly for dispatch without requiring OEM/TPDO intervention.

5.1 General Control Requirements

OEMs/TPDOs must:

• Provide documented control endpoints or operations.
• Return clear acknowledgment that a command was accepted or rejected.
• Provide a way to query command status (pending, in-progress, complete, failed).
• Return actionable error information for failed commands.

Control may be synchronous or asynchronous, but the behavior must be documented and consistent.

5.2 Device-Type Specific Control

Command sets differ by device:

• Battery systems: set charge/discharge power or mode, set import/export to/from the grid, set backup reserve
• Solar inverters: limit export, curtailment commands, power factor adjustments
• Thermostats: set setpoints, HVAC mode, fan mode, schedule overrides

For any device class claimed to be controllable via Texture, OEMs/TPDOs must expose a control surface sufficient to implement agreed use cases (demand response, TOU shifting, VPP dispatch).

5.3 Control Safety Requirements

The control surface exposed via API must be designed to be safe and must not allow commands that could cause harm to the device, property, or persons.

Requirements:

• Control commands must operate within manufacturer-specified safe operating limits.
• APIs must reject or constrain commands that could damage equipment (e.g., overcharging a battery beyond rated capacity, running HVAC systems outside safe parameters).
• OEMs/TPDOs are responsible for implementing appropriate safeguards at the device or cloud level to prevent unsafe operations, regardless of what commands are received via API.

---

6. Historical Metrics

Historical data supports reconciliation, settlement, program analytics, and reporting.

Requirements:

• OEMs/TPDOs must expose endpoints or reports where Texture can retrieve historical telemetry for enrolled devices.
• Up to 90 days of history is required where available (newly installed devices may have less).
• Granularity: 5-minute, 15-minute, or hourly depending on device type and integration.
• Historical endpoints must support pagination or batching.
• Query performance: p95 ≤ 10 seconds for reasonable date ranges.

---

7. Performance, Reliability, and Rate Limits

7.1 Availability

Requirements:

• 99.5%+ uptime for production APIs.
• 48 hours advance notice for planned maintenance where feasible.
• Status page or equivalent channel for outage communication (strongly recommended).

7.2 Rate Limits

Rate limits must support fleet-scale workloads:

• Telemetry polling for all enrolled devices at 5–15 minute intervals.
• Control bursts during DR/VPP events.
• Historical export for portfolios without throttling into unusability.

Rate limits must be:

• Documented per endpoint category (telemetry / control / historical / metadata).
• Scaled to portfolio size or adjustable via coordination with Texture.

7.3 Performance Targets

Category	Required p95 Latency
Telemetry requests	< 2 seconds
Control acknowledgments	< 3 seconds
Historical queries	< 10 seconds

---

8. Documentation & Developer Experience

OEMs/TPDOs must provide:

• API reference (REST or GraphQL), preferably with OpenAPI/Swagger schema.
• Authentication guide.
• Examples for common telemetry and control flows.
• Clear description of device discovery (how Texture finds devices for a given customer/program).
• Documentation of rate limits.
• Versioning and changelog policy.

A sandbox or test environment is strongly recommended.

---

9. Security & Privacy

Transport & Access Control

• All APIs served over HTTPS with modern TLS.
• API keys, client secrets, and tokens must be rotatable without downtime.
• Production APIs require authentication (no anonymous endpoints for device data/control).

Data Handling & Privacy

• OEMs/TPDOs must comply with applicable privacy regulations (e.g., GDPR, CCPA where relevant).
• Documented process for de-provisioning access for a device or account.
• Documented process for handling data deletion requests.

---

10. Device Identification & Mapping

Regardless of integration pattern, Texture requires stable device identification.

Requirements:

• Each device has a stable unique ID that does not change over time.
• OEMs/TPDOs provide sufficient metadata to:
  • Identify device type (battery, inverter, thermostat, etc.)
  • Associate device to a customer/site/account
  • Map to Texture's internal models

---

11. OEM-Initiated Enrollment

This section defines the requirements for OEM-initiated enrollment, an integration pattern where OEMs proactively notify Texture when devices are deployed and customers have opted in to grid programs. This enables automatic device discovery without requiring end-user-initiated OAuth flows.

For API endpoints, payload schemas, and implementation details, see Texture's API documentation.

11.1 Overview

OEM-initiated enrollment allows device manufacturers and TPDOs to:

• Notify Texture when a new device is commissioned
• Provide customer consent signals directly
• Enable automatic utility/program matching
• Streamline enrollment for utility grid services programs

This pattern is additive to existing OAuth-based enrollment flows. OEMs may support both patterns simultaneously.

11.2 Enrollment Data Requirements

When an OEM initiates enrollment, the following categories of data must be provided. See Texture's API documentation for the specific payload schema and field definitions.

Device Information (Required):

• Stable unique device identifier (must not change over time)
• Serial number
• Device model and manufacturer
• Device type (battery, inverter, EV charger, thermostat, etc.)
• Commission date
• Device capabilities (controllable, telemetry support, supported commands)

Site/Location Information (Required):

• Full street address (street, city, state, postal code, country)

Texture will automatically geocode the address to determine geographic coordinates and timezone.

Customer Information (Required):

• OEM's customer reference identifier
• Utility account number (if known)

Consent Information (Required):

• Opt-in status (boolean)
• Consent timestamp
• Source of consent (e.g., device app, web portal, installer app, purchase flow)
• Version of terms/conditions accepted
• Scope of consent (which program types the customer authorized)

Program Eligibility (Optional):

• Known eligible program identifiers
• Utility account verification status
• Installer identifier
• Sales channel

Request Authentication:

• All enrollment requests must be authenticated and signed
• OEMs will receive credentials during integration setup
• Requests must include idempotency keys to prevent duplicate enrollments

11.3 Service-Territory Matching

Upon receiving an enrollment request, Texture performs automatic service-territory matching to associate the device with the appropriate utility, CCA, or program.

Matching Process:

1. Geocoding: Texture geocodes the provided address to determine geographic coordinates.

2. Geographic lookup: Texture uses the geocoded coordinates to determine the electric utility service territory and cross-references with utility service territory boundaries.

3. Utility identification: Texture identifies the investor-owned utility (IOU), municipal utility, co-op, or CCA serving the location.

4. Program matching: Texture checks active programs in the identified territory against the device's type and capabilities.

5. Site creation: Texture creates or updates an internal site record linking device → site → utility → program(s).

Matching Outcomes:

Outcome	Description	Next Steps
Matched	Utility and program(s) identified	Device proceeds to eligible state
Partial match	Utility identified, no active programs	Device enters discovered state
Ambiguous	Multiple possible utilities (e.g., territory boundary)	Manual review required
No match	Location outside supported territories	Enrollment rejected with reason
Invalid location	Address cannot be geocoded or is malformed	Enrollment rejected, correction required

Handling Ambiguous Matches:

When territory matching is ambiguous, Texture will:

• Accept the request as pending review
• Flag the enrollment for manual resolution
• Optionally request additional metadata from the OEM
• Notify the OEM of resolution within 48 business hours

11.4 Enrollment State Model

Devices progress through a defined lifecycle of enrollment states.

State Definitions:

State	Description
Discovered	Device registered, not yet eligible for programs
Eligible	Device matched to territory, awaiting opt-in or program assignment
Opted-in	Customer consent received and validated
Pending verification	Additional verification required (utility account, address, etc.)
Enrolled	Device fully enrolled in one or more programs
Active	Device actively participating in grid services
Suspended	Temporarily suspended (connectivity, compliance, etc.)
Opted-out	Customer revoked consent
Revoked	Enrollment terminated (decommission, ownership change, etc.)

State Transitions:

Transition	Trigger	OEM Action Required
Discovered → Eligible	Territory match successful	None
Eligible → Opted-in	Consent validated	Provide consent
Opted-in → Enrolled	Program assignment complete	None
Enrolled → Active	Device begins participation	Ensure connectivity
Active → Suspended	Connectivity loss, compliance issue	Resolve issue
Active → Opted-out	Customer revokes consent	Send revocation event
Any → Revoked	Decommission, ownership change	Send revocation event

11.5 Consent Requirements

OEM-provided consent must meet the following requirements to be considered valid.

Required Consent Data:

• Opt-in status (must be true for enrollment)
• Consent timestamp (must be within last 90 days)
• Consent source (where consent was captured)
• Consent version (version of terms/conditions accepted)
• Consent scope (which program types were authorized)

Consent Validity Rules:

• Freshness: Consent timestamp must be within 90 days of enrollment request. Stale consent (>90 days) requires re-consent.
• Specificity: Consent scope must include at least one valid program type.
• Non-repudiation: OEM must retain original consent records for minimum 7 years.
• Revocability: Customer must be able to revoke consent at any time.

Anti-Replay Requirements:

• Each enrollment request must use a unique request identifier
• Consent timestamps must not be in the future
• Consent must have been captured before the enrollment request was submitted
• Requests with stale signatures will be rejected

OEM Certification Requirements:

By submitting an enrollment request, the OEM certifies that:

1. The consent was obtained directly from the device owner or authorized representative.
2. The consent was informed (customer understood what they were agreeing to).
3. The consent was voluntary (not coerced or bundled deceptively).
4. The OEM has records to substantiate the consent if audited.
5. The OEM will honor revocation requests within 24 hours.

Consent Audit Trail:

OEMs must maintain and provide upon request:

• Timestamp of consent capture
• Method of consent capture (screenshot, log, signed form)
• IP address and user agent (if digital)
• Version of terms/disclosures presented
• Any modifications or re-consents

11.6 Revocation and Change Events

OEMs must notify Texture of material changes to enrollment status. See Texture's API documentation for endpoint details and payload schemas.

Required Event Notifications:

Event	When to Send	Required Information
Consent revoked	Customer opts out	Device ID, revocation timestamp, revocation source
Device decommissioned	Device removed from service	Device ID, decommission timestamp, reason
Device relocated	Device moved to new location	Device ID, old site info, new site info, relocation date
Ownership transferred	Device ownership changed	Device ID, previous owner, new owner, transfer date
Consent expired	Consent period ended	Device ID, expiry timestamp
Connectivity lost	Device offline >72 hours	Device ID, last seen timestamp

Processing Expectations:

Event	Texture Processing Time
Consent revoked	Immediate (within 1 minute)
Device decommissioned	Within 15 minutes
Device relocated	Within 1 hour (triggers re-matching)
Ownership transferred	Within 24 hours (requires verification)

Event Delivery Requirements:

• Events must be delivered via authenticated API calls
• OEMs must handle delivery retries for transient failures
• Events must include unique identifiers for idempotency
• Events may arrive out of order; Texture uses timestamps for sequencing

11.7 Error Handling

Texture will return appropriate error responses for enrollment and event failures. OEMs must handle these errors appropriately.

Error Categories:

Category	Description	OEM Response
Validation errors	Payload missing required fields or invalid data	Fix payload and retry
Authentication errors	Invalid or expired credentials	Re-authenticate
Authorization errors	OEM not authorized for operation	Contact Texture support
Territory errors	Location outside supported areas or ambiguous	Verify location data or await manual review
Consent errors	Consent invalid, expired, or insufficient scope	Obtain fresh consent
Conflict errors	Duplicate enrollment or state conflict	Check existing enrollment status
Rate limit errors	Too many requests	Retry with backoff
Server errors	Texture system issues	Retry with exponential backoff

See Texture's API documentation for specific error codes and response formats.

11.8 Backward Compatibility

OEM-initiated enrollment is additive to existing enrollment models.

Coexistence with OAuth Enrollment:

Enrollment Method	Use Case	Supported
End-user OAuth	User-initiated device linking	Yes
OEM-initiated	OEM notifies at commissioning	Yes
Hybrid	OEM enrolls, user confirms via OAuth	Yes

Key Principles:

1. Non-exclusive: Devices may be enrolled via either method. If a device is enrolled via OEM-initiated flow and the user later completes OAuth, the enrollments merge (OAuth consent supplements OEM consent).

2. Consent stacking: OAuth consent and OEM-provided consent are additive. Either is sufficient for enrollment; both provide stronger audit trail.

3. No disruption: Existing OAuth integrations continue to work unchanged. OEM-initiated enrollment is an additional pathway.

4. OEM choice: OEMs may implement one or both enrollment methods based on their product flow.

Handling Duplicate Enrollments:

If a device is enrolled via both methods:

• Texture maintains a single canonical enrollment record
• Both consent sources are recorded in the audit trail
• The most recent consent timestamp governs consent validity
• Revocation via either method triggers full revocation

Migration Path:

OEMs with existing OAuth integrations can adopt OEM-initiated enrollment incrementally:

1. Implement enrollment API integration
2. Enable for new device deployments
3. Optionally backfill existing devices with consent re-capture
4. OAuth flow remains available as fallback

11.9 Implementation Checklist

OEMs implementing OEM-initiated enrollment must:

• Contact integrations@texturehq.com to begin the integration process
• Register for OEM credentials (client ID, client secret, signing keys)
• Review API documentation for enrollment endpoints and schemas
• Implement enrollment API integration
• Implement event notification for revocations and changes
• Capture and store customer consent with required fields
• Handle all error responses appropriately
• Test in Texture sandbox environment
• Complete certification review with Texture team

---

12. Certification Process

OEMs/TPDOs seeking integration with Texture should contact integrations@texturehq.com to begin the process. The Texture team will work with you to:

• Review your API documentation and capabilities.
• Validate telemetry and control requirements against this spec.
• Test the integration in a staging environment.
• Certify the integration for production use.

---

Appendix A — Reference Links

• Texture Documentation
• Texture API Reference (OpenAPI)