> For the complete documentation index, see [llms.txt](https://docs.reachplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reachplatform.com/technical/api/product-lifecycle-api-overview.md). # 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. {% hint style="info" %} 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. {% endhint %} ### 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. ```json { "event": "A", "accountId": "ACC123456", "accountStatus": "ACTIVE", "totalActiveLines": 2, "totalPurchasedLines": 2, "impactedLines": [ "LINE-UUID-001" ], "lines": { "LINE-UUID-001": { "firstName": "John", "lastName": "Doe", "emailId": "john.doe@example.com", "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": "jane.smith@example.com", "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. ```json { "accountId": "726236434348", "newAccountId": "546612546466" } ``` **Email update** Call this when the customer updates their email ID. ```json { "accountId": "726236434348", "emailId": "amber.walker@email.com" } ``` **Apply or remove HSI discount** Call this when the brand wants to apply or remove HSI discount eligibility. ```json { "accountId": "726236434348", "isHSIDiscount": true } ``` **Address update** Call this when the customer updates service or billing address. ```json { "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`. ```json { "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 ` | 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 ```http POST /account/update ``` #### Request sample ```json { "accountId": "string", "newAccountId": "string", "emailId": "amber.walker@email.com", "isHSIDiscount": true, "addresses": [ {} ], "custType": "Residential" } ``` ### Related docs * [Product Bundle Integration](/technical/bolt-on-setup/product-bundle-integration.md) {% hint style="info" %} Questions or clarification? Reach out to your respective account manager or email at for help and support. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.reachplatform.com/technical/api/product-lifecycle-api-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.