A2P SMS Operational Data Contract: Fields and Semantics

What an operational data contract solves

In A2P SMS traffic—messages sent from an application or system to a person—multiple organizations may record the same message at different times and use different terminology. An operational data contract reduces ambiguity by specifying what each field means, who reports it, and how events relate to one another.

It is not a universal standard and does not guarantee delivery. It is an agreement between parties to exchange and reconcile information. It should distinguish decisions made within the agreement from the requirements of any applicable interface or technical specification. Consult normative references such as SMPP or HTTP directly before attributing specific requirements to them.

• Agree on the schema before integrating or changing the data exchange.
• Document definitions, formats, vocabularies, and responsibilities alongside the fields.
• Treat the interpretation of statuses as an explicit agreement, not an assumed equivalence between systems.

Participants and responsibility boundaries

A chain may include the business originating the traffic, a messaging platform, one or more providers, and a mobile operator. The specific route and the involvement of each entity depend on the agreement and service configuration; do not assume that every case follows the same chain.

For each data item, specify who generates it, who transmits it, who may transform it, and who is responsible for interpreting it. For example, the sender may declare the traffic type, a platform may assign an internal identifier, and a provider may report a status received from another system. These are possible design assignments, not universal responsibilities.

Separating responsibilities helps investigate discrepancies: one party may confirm that it accepted a request without claiming that the network delivered it, while another may report a later result within the limits of its source.

• Assign an owner to each field and each status transition.
• State where each party’s reporting responsibility ends.
• Include a contact and a process for reconciling discrepancies, without assuming that all parties observe the same events.

Minimum fields and their meaning

The minimum dataset depends on its purpose: operations, support, reconciliation, or analysis. Start with the data needed to correlate a request with subsequent events, then add only fields that the parties can produce and use in a well-defined way.

At a minimum, document a message identifier for each system and, where applicable, correlation identifiers between systems. Include the destination in its agreed format; the sender; the declared traffic classification, such as OTP, transactional, or marketing; and the declared route, if known. Do not present a declared route as independent proof of the route actually taken.

It is also useful to include the status, the source of the status, the event timestamp, and any error code. If the destination operator is shared, specify how it was determined and when. Do not fill in an unknown operator by inference. Also define the applicable version of the terms or operational agreement, with its identifier and agreed date or validity period.

• Identifiers: the message identifier in the sending system and available correlation references.
• Context: destination, sender, traffic classification, declared route, and operator when known.
• Event: status, status source, date and time, error code, and version of the applicable terms.
• For each field, specify its type, format, whether it is required, vocabulary, and meaning.

Statuses: acceptance, sending, DLR, and unknown outcome

Do not reduce the entire lifecycle to one generic “status” field. Define the stages the agreement needs to distinguish, such as a request accepted by an interface, a sending attempt reported by a party, a delivery report received, or an outcome that remains unknown. Agree on the exact names and transitions for each integration.

A DLR is a status report received from a particular source. Record who issued or transmitted it and what it means in that context. By itself, do not treat it as independent verification that the message appeared on the handset or was read by the person.

Retain an unknown status when there is not enough information to reach a conclusion. Do not automatically treat the absence of a DLR as a failure, or a favorable reported status as a guarantee of receipt. If two sources disagree, retain both events and document which one each process uses and why.

• Define each status with a description, its source, and the permitted transitions.
• Separate the reported status from a party’s internal assessment of the case.
• Preserve the original events so the sequence can be reconstructed and discrepancies resolved.

Timestamps and event ordering

A timestamp should make clear when an event occurred or was recorded, and in which time zone. Agree on the format, available precision, and whether the date represents the event time, the time the report was received, or the time it was recorded in the system.

Do not infer event order solely from the time they arrive at a platform: events may be received in an order different from the one assigned to them by each party. Retain event identifiers or sequence numbers if available, and record source and receipt timestamps separately when needed for reconciliation.

If a source does not provide a time zone or sufficient precision, state that explicitly. Do not fill in those details as though they had been observed.

• Agree on the date and time format, time zone, and precision.
• Distinguish event time, receipt time, and processing time.
• Define how to order events when timestamps are identical or incomplete.

Data source and level of evidence

The same value may carry different weight depending on who declared it and how it was obtained. Add provenance metadata when it helps interpret a record: the source system, the party transmitting it, the time of observation, and whether it is a declared value, a received event, or an independent observation.

For example, a platform may declare a route, while a status may arrive in a provider’s report. The contract should prevent that distinction from being lost through transformation or aggregation. If there is no independent verification, say so rather than implying otherwise.

Also establish what evidence is accepted for each use: support, reconciliation, or analysis. A value useful for an investigation may not be sufficient to resolve a commercial dispute.

• Record the data’s provenance and the party that communicated it.
• Distinguish direct observation, declaration, and received event.
• Do not turn a transmitted status into a stronger claim than the available source supports.

Nulls, vocabularies, and error codes

An empty field may mean that the value is unknown, was not collected, does not apply, or was not received. The contract should distinguish these cases rather than leaving each system to interpret them differently. If the exchange format cannot represent those distinctions, document a shared convention and its limitations.

Define controlled vocabularies for categories and statuses, and agree on how to handle provider-specific values. Preserve the original code alongside a normalized category if cross-party data comparison is needed. Normalization should not erase the value needed to investigate the event at its source.

Before adding codes, statuses, or senders to an agreed list, specify who can propose them, how they are documented, and when they take effect. Do not reuse an old value with a new meaning.

• Explicitly distinguish unknown, absent, not applicable, and not received.
• Keep the original value and, where agreed, add a normalized value.
• Publish definitions and examples for proprietary codes without presenting them as universal.

Schema versioning and changes

Each exchange should make it possible to identify which schema version and which version of the operational terms applied. Agree on how the version is communicated and how it relates to the traffic period, rather than assuming an interface name alone identifies the rules.

Define a change process in advance: who proposes modifications, who approves them, how they are tested, and when they take effect. A change that adds an optional field may be easier to adopt than one that changes the meaning of a status or makes a field mandatory; classify the impact with the actual consumers in mind.

During a transition, specify which versions may coexist, how records are identified, and how long compatibility is maintained if the parties agree on a period. Avoid changing semantics without changing the version or communicating the change unambiguously.

• Version the schema and record the version of the applicable terms.
• Classify changes by their impact on producers, consumers, and reconciliation processes.
• Agree on approval, testing, effective date, and treatment of earlier versions.