ACP Specification v1.0.0

Automotive Commerce Protocol — Normative specification defining the JSON envelope format for AI-generated automotive commerce data. This document describes the structure, constraints, and semantics of ACP envelopes. It does not describe the internal methods by which producers generate envelope contents.

Out of Scope

The following topics are explicitly outside the scope of this specification and must not be inferred from the data format definitions herein:

1. AI model training methodology — How producers train, fine-tune, or select models for conversation handling.
2. Lead scoring algorithms — How lead.score and score_factors are calculated. The specification defines the output format only.
3. Intent detection methods — How lead.intents[] are identified and confidence values are derived.
4. Handoff trigger logic — What conditions cause a conversation.handoff to be initiated.
5. CRM internal mapping logic — How receivers map ACP fields to their internal data structures.
6. Dealer workflow design — How dealerships route, assign, or act on received envelopes.
7. Conversation moderation policy — How producers filter, moderate, or restrict conversation content.
8. Voice transcription methods — How audio is converted to text for voice agent types.
9. Envelope construction sequencing — How producers progressively build envelope contents during a conversation.

Normative Language

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in RFC 2119.

Content Type

Producers must set the HTTP Content-Type header to application/acp+json when transmitting envelopes. Receivers must accept application/acp+json and should also accept application/json for interoperability.

Number Precision

Monetary fields (vehicle_price, monthly_payment, trade_in_value, down_payment, estimated_value, payoff_amount) should be expressed as decimal values with exactly two fractional digits (e.g., 29995.00, not 29995 or 29995.999).

Percentage fields (apr, purchase_probability, confidence) should be expressed as decimal values with appropriate precision for the domain.

Receivers must not assume floating-point precision beyond standard IEEE-754 double-precision limits. Producers should not emit monetary values with more than two fractional digits.

Envelope Structure

An ACP envelope is a single JSON document with eight top-level objects. Seven are required for snapshot envelopes. Delta envelopes must contain only acp + events.

{
  "acp": { },           // Protocol metadata — REQUIRED
  "source": { },        // Origin attribution — REQUIRED
  "dealership": { },    // Receiving dealer — REQUIRED
  "lead": { },          // Customer intelligence — REQUIRED
  "transaction": { },   // Deal state — REQUIRED
  "conversation": { },  // Transcript — REQUIRED
  "events": [ ],        // Behavioral stream — REQUIRED
  "ai_analysis": { }    // AI insights — OPTIONAL
}

Producers must not include additional top-level keys beyond these eight. Receivers must ignore unknown top-level keys without error.

Envelope Size Guidance

Producers should limit snapshot envelopes to 1MB uncompressed. If conversation transcripts exceed this limit, producers should truncate conversation.messages to the most recent messages and include a vendor-namespaced archival reference field (e.g., x_vendor.transcript_archive_url) pointing to the complete transcript.

Receivers must not reject envelopes solely based on size, but may return PAYLOAD_TOO_LARGE (HTTP 413) if the envelope exceeds their ingestion capacity. Receivers should document their maximum accepted payload size.

Delta envelopes are typically much smaller than snapshots — often under 10KB — as they contain only the changed fields and new events.

Field Ordering

JSON object key ordering is not semantically meaningful in ACP. Implementations must not depend on the order of keys within any object. Producers may emit keys in any order. Receivers must process envelopes identically regardless of key ordering. Array ordering is significant: events must be chronologically ordered, and vehicle_interests should be ordered by customer preference (most preferred first).

acp — Protocol Metadata REQUIRED

Identifies protocol version, envelope identity, and generation context. Uses additionalProperties: false — producers must not add vendor fields to this object.

{
  "acp": {
    "version": "1.0.0",
    "protocol": "acp",
    "generated_at": "2025-02-13T15:30:00Z",
    "envelope_id": "acp_1739456200_x8k2m9",
    "parent_envelope_id": null
  }
}

source — Origin Attribution REQUIRED

Identifies who generated this envelope, from what channel, and how the customer arrived. Extensible — vendors may add custom fields.

dealership — Receiving Dealer REQUIRED

Identifies the dealership that should receive this envelope. Receivers must use id for routing.

lead — Customer Intelligence REQUIRED

The core customer data object. Producers must include id and status. All other fields are optional but recommended for maximum CRM utility.

lead.contact

lead.vehicle_interests[]

lead.budget

lead.trade_in

lead.intents[]

Each item represents a detected purchase intent. The detection methodology is producer-defined; this specification defines only the output format.

Standard Intent Types

Producers should use standard types where applicable. Vendors may define additional types prefixed with their namespace: "x-vendorname:custom_intent". Receivers must not reject envelopes containing unknown intent types.

lead.score & lead.score_factors[]

transaction — Deal State REQUIRED

Models the commerce lifecycle. Producers must include id, stage, and last_updated.

Transaction Stages

transaction.offer_history[]

Uses additionalProperties: false. Vendors must not add custom fields.

transaction.finance_terms

transaction.appointment

transaction.delivery

conversation — Transcript REQUIRED

Producers must include id and started_at. Including messages is recommended.

conversation.messages[]

Messages must be chronologically ordered. Producers must not alter message content after generation.

conversation.handoff

Records that a handoff was initiated and why. The decision logic for triggering handoffs is producer-defined; this object captures the outcome only.

events — Behavioral Stream REQUIRED

Chronological array of typed behavioral events. Producers must preserve chronological order. Receivers must not reorder events.

Standard Event Types (18)

Producers should use standard types where applicable. Custom event types must be namespaced: "x-vendorname:event_name". Receivers must not reject envelopes containing unknown event types.

ai_analysis — AI Insights OPTIONAL

Producer-generated analysis. Entirely optional and fully extensible. The contents are producer-defined outputs — this specification defines suggested field names but does not mandate how analysis values are computed.

Snapshots & Deltas

ACP envelopes are full state snapshots by default. Receivers must replace stored state entirely — no merge logic is required or expected.

Delta envelopes may be generated to represent partial updates between snapshots. A delta envelope contains only acp + events and references a parent snapshot via parent_envelope_id. When parent_envelope_id is non-null, all other top-level objects must not be present.

This specification does not define when or how frequently producers generate delta envelopes — that is an implementation decision. Producers must send a full snapshot envelope at the conclusion of the interaction, regardless of how many delta envelopes were previously transmitted.

Delta Conflict Resolution

If a delta envelope references a parent_envelope_id that the receiver has not previously ingested, the receiver must reject the envelope with error code UNKNOWN_PARENT_ENVELOPE (HTTP 422). The producer should respond by retransmitting the parent snapshot before retrying the delta.

If deltas arrive out of chronological order (determined by acp.generated_at), receivers should process them in timestamp order. If reordering is not feasible, receivers may reject out-of-order deltas with error code OUT_OF_ORDER_DELTA and request a fresh snapshot.

Producers must not assume delta delivery is guaranteed. The final snapshot at conversation conclusion serves as the authoritative record and must be independently valid without reference to any prior deltas.

Extensibility

ACP uses a two-tier additionalProperties strategy:

When adding custom fields, vendors should prefix with their namespace to avoid collisions: "x-vendorname:field_name". Receivers must ignore unknown fields without error.

Validation

Producers should validate envelopes against the official JSON Schema before transmission. Receivers must validate on receipt and reject non-conformant envelopes with error code INVALID_SCHEMA.

Versioning Policy

ACP follows Semantic Versioning 2.0.0. The version string in acp.version consists of MAJOR.MINOR.PATCH.

The v1.0.0 schema is frozen upon publication. New optional fields may be introduced in minor versions. Required fields must not be added in minor versions — only in major versions.

Backward Compatibility

Forward Compatibility (Receiver Side)

Receivers must be forward-compatible within a major version. This means:

• Receivers must ignore unknown fields without error.
• Receivers must ignore unknown event types without error.
• Receivers must ignore unknown intent types without error.
• Receivers must not reject envelopes containing fields added in a later minor version.

Backward Compatibility (Producer Side)

Producers targeting a specific version must produce envelopes valid against that version's schema. Producers may include fields from a later minor version, but must not depend on receivers understanding them.

Deprecation Policy

• Fields must not be removed in minor versions. Removal requires a major version increment.
• Deprecated fields must be documented for at least one full minor version cycle before removal.
• Migration guides must accompany any major version release.

Version Negotiation

Producers should include the X-ACP-Version HTTP header. Receivers should check acp.version and respond with VERSION_MISMATCH if the major version is unsupported.

Conformance Requirements

A system is ACP-conformant if it meets one or both of the following profiles:

ACP Producer Conformance

A conformant producer must:

1. Produce envelopes that validate against the official JSON Schema for the declared version.
2. Include all required fields in snapshot envelopes.
3. Generate globally unique envelope_id values matching pattern ^acp_.
4. Preserve chronological order in events arrays.
5. Send a full snapshot envelope at the conclusion of an interaction if delta envelopes were transmitted.
6. Set Content-Type: application/acp+json when transmitting envelopes.

ACP Receiver Conformance

A conformant receiver must:

1. Accept application/acp+json content type.
2. Validate received envelopes against the JSON Schema.
3. Deduplicate by envelope_id, returning success (not error) for duplicates.
4. Distinguish snapshot vs delta envelopes via parent_envelope_id.
5. Replace stored state on snapshot receipt (not merge).
6. Ignore unknown fields, event types, and intent types without error.
7. Respond with standardized error codes (see Error Codes).

Security Considerations

Personally Identifiable Information (PII)

ACP envelopes may contain PII including names, email addresses, phone numbers, physical addresses, and conversation transcripts. Implementations must handle PII in accordance with applicable regulations (CCPA, GDPR, TCPA, state privacy laws). Producers should document what PII categories their envelopes contain.

Encryption in Transit

ACP envelopes must be transmitted over TLS 1.2 or higher. Unencrypted HTTP transmission is a conformance violation. Producers and receivers should enforce HTTPS-only endpoints.

Authentication & Access Control

Receivers must authenticate the source of incoming envelopes. Bearer tokens, mutual TLS, or API key authentication are all acceptable. Receivers should verify that the source.provider value matches the authenticated identity. Unauthorized sources must be rejected with UNAUTHORIZED_SOURCE.

Replay Attack Prevention

The envelope_id field serves as an idempotency key. Receivers must track processed envelope IDs and reject replayed envelopes. Receivers should also validate generated_at timestamps — envelopes more than 24 hours old should be flagged for review. This prevents captured envelopes from being re-submitted by malicious actors.

Envelope Integrity

Producers should include an X-ACP-Signature HTTP header containing an HMAC-SHA256 signature of the envelope body. Receivers should verify this signature when present. A future version of this specification may make envelope signing required.

Data Minimization

Producers should include only data relevant to the receiving dealership's legitimate business purpose. Conversation transcripts should not include system prompts, internal reasoning traces, or model configuration details. Producers must not include data from other customers' conversations in an envelope.

Rate Limiting

Receivers should implement rate limiting to mitigate denial-of-service attacks and resource exhaustion from misconfigured producers. Receivers must respond with RATE_LIMITED (HTTP 429) and include a Retry-After header indicating the number of seconds before the producer may retry.

Producers must respect 429 responses and implement exponential backoff with jitter. A producer that continues to transmit after receiving a 429 response may be permanently blocked by the receiver.

Error Codes

Receivers must use the following standardized error codes in HTTP responses. Error responses must include a JSON body conforming to the canonical error structure:

{
  "error": {
    "code": "INVALID_SCHEMA",
    "message": "Envelope does not conform to ACP v1.0.0 schema",
    "details": [
      {
        "field": "lead.score",
        "issue": "Value 150 exceeds maximum of 100"
      }
    ]
  }
}

The error.code field must match one of the codes below. The error.message field should be a human-readable explanation. The error.details array is optional and may contain field-level validation errors or contextual information.