Product lifecycle API Overview

Lifecycle event flags, sequencing, and ownership for the MAM integration.

Understand the lifecycle events Reach sends to your MAM endpoint.

Overview

This page defines the lifecycle events exchanged between a brand and Reach.

It covers event sequencing, flag meanings, and API ownership.

APIs involved

• Mobile Account Management (MAM) API (brand-owned): Reach notifies the brand when lifecycle events occur.
• Account Update API (Reach-owned): the brand notifies Reach when account attributes change (for example, address, custType, eligibility).

This is a business overview with the core lifecycle payload used by the MAM integration.

If you use IP whitelisting, set it up in both directions:

• Reach → brand: Reach must be able to reach the brand’s MAM endpoint from Reach egress IPs.
• Brand → Reach: the brand must be able to reach Reach’s Account Update API from the brand’s egress IPs.

Lifecycle phases

Bundle-eligible accounts typically move through:

1. Purchase (order placed)
2. Activation (relationship established on first activation event)
3. In-life changes (for example, reconnects)
4. Disconnection (line-level or final account-level)
5. Termination (relationship released after a waiting period)

The relationship between Brand Account ID and Reach group account ID is established on the first A event.

Lifecycle event flags

Reach sends notifications to the brand’s MAM API for each lifecycle event.

Flag	Event	Description and trigger
B	Buy / order placed	Fired for each line at the point of order. Marks the start of the lifecycle sequence.
A	Activation	Fired for each activated line. The first A establishes the relationship between Brand Account ID and Reach group account ID.
D	Line disconnection	Fired when a single line is disconnected. The overall account relationship remains active.
DF	Final disconnection	Fired when the last line in the mobile account is disconnected. Starts the termination waiting window.
R	Reconnection	Fired when any line is reconnected. Resets the termination timer if it occurs within 30 days of DF.
CA	Order cancellation	Order is canceled before shipment. No relationship is established for canceled orders.
T	Termination	Fired 30 days after DF with no subsequent R. Brand marks the mobile account as terminated and releases the account relationship.

Sample MAM payload

Use this payload shape when Reach posts lifecycle updates to the brand endpoint.

{
  "event": "A",
  "accountId": "ACC123456",
  "accountStatus": "ACTIVE",
  "totalActiveLines": 2,
  "totalPurchasedLines": 2,
  "impactedLines": [
    "LINE-UUID-001"
  ],
  "lines": {
    "LINE-UUID-001": {
      "firstName": "John",
      "lastName": "Doe",
      "emailId": "[e-mail]",
      "status": "ACTIVE",
      "reachNumber": "8001112222",
      "reachPlanId": "Smartphone & Tablet 2GB",
      "isPrimary": true,
      "imei": "111111111111111",
      "activationDate": "2023-10-18T13:05:00.164Z",
      "purchaseDate": "2023-10-18T12:21:50.924Z",
      "disconnectionDate": "2023-10-19T13:05:00.164Z",
      "reconnectionDate": "2023-10-20T13:05:00.164Z",
      "simPreference": "PHYSICAL_SIM",
      "isPortIn": true
    },
    "LINE-UUID-002": {
      "firstName": "Jane",
      "lastName": "Smith",
      "emailId": "[e-mail]",
      "status": "ACTIVE",
      "reachPlanId": "Smartphone & Tablet 2GB",
      "isPrimary": true,
      "imei": "222222222222222",
      "purchaseDate": "2023-10-19T12:21:50.924Z",
      "activationDate": "2023-10-19T13:20:00.270Z",
      "simPreference": "ESIM",
      "isPortIn": false
    }
  }
}

Payload notes

• event identifies the lifecycle trigger.
• impactedLines lists the line IDs affected by the event.
• lines is a map keyed by line ID.
• The first A event establishes the brand-to-Reach account relationship.

Agent parameters

Agent parameters are optional.

Add them only for B and A events when applicable for the purchase mode.

Field summary

Field	Required	Description
accountId	Yes	Unique customer identifier on the brand side, such as account_id or account_number.
accountStatus	Yes	One of INACTIVE, ACTIVATION_IN_PROGRESS, ACTIVE, SUSPENDED, DISCONNECTED, HOTLINED, REJECTED, DISABLED, ACTIVATION_FAILED, PORTING_IN_PROGRESS, PORTING_FAILED, PORT_CANCELLED, INTRA_PORTING_IN_PROGRESS, TERMINATED.
totalActiveLines	Yes	Total number of active lines in the account.
totalPurchasedLines	Yes	Total number of purchased lines in the account.
impactedLines	Yes	List of impacted lines for the event.
event	Yes	Event type. One of B, A, D, DF, R, CA, T.
eventTimestamp	Yes	UTC datetime. Example: 2023-09-13T12:14:15Z.
lines	Yes	Map of line ID to line details.

Line object

Field	Required	Description
firstName	Yes	Customer first name.
lastName	Yes	Customer last name.
emailId	Yes	Customer email address.
reachNumber	No	MDN assigned to the customer.
status	Yes	Current line status.
reachPlanId	Yes	Retail plan ID of the customer.
isPrimary	Yes	Indicates whether the customer is primary.
imei	No	Customer IMEI on network.
activationDate	No	UTC datetime. Example: 2023-09-13T12:14:15Z.
purchaseDate	Yes	UTC datetime. Example: 2023-09-13T12:14:15Z.
disconnectionDate	No	UTC datetime. Example: 2023-09-13T12:14:15Z.
reconnectionDate	No	UTC datetime. Example: 2023-09-13T12:14:15Z.
simPreference	Yes	One of PHYSICAL_SIM or ESIM.
isPortIn	Yes	Indicates whether the customer is a port-in customer.

Account Update API

The brand can call this API to inform Reach about customer updates from the brand side.

Common use cases

Account transfer

Call this when the customer's account ID changes.

{
  "accountId": "726236434348",
  "newAccountId": "546612546466"
}

Email update

Call this when the customer updates their email ID.

{
  "accountId": "726236434348",
  "emailId": "[e-mail]"
}

Apply or remove HSI discount

Call this when the brand wants to apply or remove HSI discount eligibility.

{
  "accountId": "726236434348",
  "isHSIDiscount": true
}

Address update

Call this when the customer updates service or billing address.

{
  "accountId": "726236434348",
  "addresses": [
    {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": "string",
      "name": "string",
      "phone": "string",
      "state": "string",
      "type": "service",
      "zip": "string"
    },
    {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": "string",
      "name": "string",
      "phone": "string",
      "state": "string",
      "type": "billing",
      "zip": "string"
    }
  ]
}

Customer type update

Call this when the brand wants to update custType.

{
  "accountId": "726236434348",
  "custType": "Residential / Employees / CommercialSMB"
}

Request body schema

Content type: application/json

Field	Required	Type	Description
accountId	Yes	string	Customer account ID on the brand side.
newAccountId	No	string	Supply only if the account ID changes.
emailId	No	string <email>	Supply only if email needs to be updated.
isHSIDiscount	Yes, when updating discount eligibility	boolean	true if the customer is eligible for discount. false if the customer is not eligible.
addresses	No	array	Array of ServiceAddress or BillingAddress objects. Maximum 2 items.
custType	No	string	One of Residential, Employees, or CommercialSMB. Supply only if customer type changes.

Response

• 200 — On successful execution, the API returns SUCCESS status.

Endpoint

POST /account/update

Request sample

{
  "accountId": "string",
  "newAccountId": "string",
  "emailId": "[e-mail]",
  "isHSIDiscount": true,
  "addresses": [
    {}
  ],
  "custType": "Residential"
}

Related docs

• Product Bundle Integration

Questions or clarification? Reach out to your respective account manager or email at [e-mail] for help and support.