--- schema_version: "1" id: b94e0a21953d276430f27b0f9778372488e678560a0778ba7c132f7931e15797 title: TMF629 v4 Customer Management - Outbound Notification collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/guides/TMF629/TMF629_notification.md canonical_url: https://developer.salesforce.com/docs/industries/communications/guide/TMF629_notification.html source_site: developer.salesforce.com content_type: documentation content_hash: fb4da93e3e7f022259833631364e00cbafa70c5df365a58046417a5aaf9b4c45 products: - Communications Cloud TM Forum API - Industries Integrations --- # TMF629 v4 Customer Management - Outbound Notification Use TMF629 Outbound Notification API for customer and customer account management, such as creation, update, and retrieval of customers. Outbound notifications can be configured to be triggered for change events on the parent entity (Account) as well as for relevant sub-resources, see [Supported Sub-Resources for TMF Outbound Notifications](#supported-sub-resources-for-tmf-outbound-notifications) for the list of supported sub-resources in scope. - `/api/notification/customerCreateEvent` - `/api/notification/customerAttributeValueChangeEvent` - `/api/notification/customerStateChangeEvent` (status field) The user must configure the notification framework to detect CDC events and invoke the relevant TMF Open API implementations that generate the event payloads and forward them to the target systems configured within the API. **note:** This API has been tested with an external system using TMF-aligned customizations. It may not include all optional fields and may not work out-of-the-box with your system. Customizations will likely be required. We recommend a thorough evaluation to ensure it meets your specific needs. ## Available In This API is available in the managed package. ## Prerequisites - MuleSoft License required: MuleSoft Direct for Communications Cloud (add-on for Communications Cloud) or MuleSoft Anypoint Base Subscription. - Communications cloud license required: Communications Cloud Growth. ## Assumptions - The notification uses a fire-and-forget approach. Salesforce does not process or store the response in any objects. MuleSoft logs and tracks all received notifications. - In alignment with TMF v4 standards for event notifications, the system sends the same payload, which includes the full customer resource and the supported related sub-resources, for all events. - Access to the target system is authenticated using the OAuth 2.0 Client Credentials grant type. - In case of failure when invoking the target system endpoint, the request is retried up to three times, with a two second interval between attempts. - TMF629 v4 Inbound API response may include optional fields. According to TMF specifications, if the outbound Event Notification payload contains unsupported optional parameters, the downstream system may reject it with a 4xx error. To avoid this, tailor the payload to include only the optional fields supported by the client. - Salesforce and MuleSoft do not have a centralized event hub configured by default. Customers are responsible for setting up their own event hub to manage subscribers. Outbound notifications are generated and sent directly to a single, client-defined target endpoint. - The Allow users to relate a contact to multiple accounts feature enables a single contact to be associated with multiple accounts through the `AccountContactRelation` object in Salesforce. Since this feature is disabled by default, the `contactToMultipleAccountsEnabled` query parameter must only be set to `true` when the feature is enabled, and only during the creation of integration definitions. ![Contact Multiple Accounts](https://developer.salesforce.com/media/contact_multiple_acc.png "Contact Multiple Accounts") The following table summarizes the change events supported for the Account entity, along with the required configurations to trigger them through the Notification Framework. **important:** When configuring Object Integration Definitions, ensure you use the exact `RelatedFieldName` values provided in the table below. | TMF Resource | SalesforceEntity | Scenario
| changeEventType Supported | Notification Event Path | RelatedFieldName | | ------------ | ---------------- | --------------------------------------------------- | ------------------------- | ----------------------------------------------------- | ----------------------- | | Customer | Account | Creation of an Account record | Create | `/api/notification/customerCreateEvent` | "RelatedFieldName":"Id" | | | | Updates to attributes of an existing Account record | Update | `/api/notification/customerAttributeValueChangeEvent` | "RelatedFieldName":"Id" | **note:** - The core entity does not include a status field, and this API is designed to work only with the core model—not with the managed package. Consequently, the inbound API does not return a status value, and status changes do not trigger notifications by default. - To enable status-based notifications, you can create a custom field to track status and subscribe to its changes using the Salesforce Notification Framework. However, while this approach allows notifications to be triggered, the updated status field value will not be included in the notification payload. ## Sample Outbound Notification Request This is a sample payload sent to the target system endpoint for the event Type: `CustomerCreateEvent`. **note:** The event notification payload is same for all three events (`CustomerCreateEvent`, `CustomerAttributeValueChangeEvent`, `CustomerStateChangeEvent`). The `eventType` value will differ between the three events. ``` { "id": "d35161e0-e2ec-11ef-8c9a-02bec51f016d", "eventId": "string", "eventTime": "2025-02-07T06:04:20.966Z", "eventType": "CustomerCreateEvent", "correlationId": "0001ade9-3f74-0b99-dbc4-42e73424b774-1", "timeOccurred": "2025-02-07T06:04:20.966Z", "event": { "customer": { "account": [ { "description": "Chain of hotels and resorts across the US, UK, Eastern Europe, Japan, and SE Asia.", "id": "001xx000003GYdPAAW", "name": "Grand Hotels & Resorts Ltd", "referredType": "Billing Account" } ], "agreement": [ { "id": "800xx000000bna5AAA", "name": "Contract Of Legal Issue" } ], "engagedParty": { "id": "003xx000004WhECAA0", "name": "Rose Gonzalez", "role": "Individual" }, "contactMedium": [ { "mediumType": "Email", "characteristic": { "contactType": "Email", "emailAddress": "kevin.harper@salesforce.com" } }, { "mediumType": "Fax", "characteristic": { "contactType": "Fax", "faxNumber": "(555) 123-4567" } }, { "mediumType": "Phone", "characteristic": { "contactType": "Phone", "phoneNumber": "(555) 555-1234" } } ], "id": "001xx000003GYdLAAW", "name": "Edge Communications" } } } ``` ## Outbound Event Notifications Field Mappings | TMF Field | TMF Type | Is it Mandatory ? | Supported | Mappings | | -------------- | -------- | ----------------- | --------- | ------------------------------------------------------------------------------------------ | | id | string | No | TRUE | Mule correlation Id | | eventId | string | No | TRUE | inputPayload.eventId | | eventTime | string | No | TRUE | inputPayload.commitTimestamp as UTC | | eventType | string | No | TRUE | `CustomerCreateEvent` or `CustomerAttributeValueChangeEvent` or `CustomerStateChangeEvent` | | correlationId | string | No | TRUE | inputPayload.correlationId | | timeOccurred | string | No | TRUE | inputPayload.commitTimestamp as UTC | | event.customer | object | Yes | TRUE | TMF629v4 Inbound response payload | ## Supported Sub-Resources for TMF Outbound Notifications This section outlines the sub-resources within TMF629 for which outbound notifications can be configured for create, update, and delete operations. **note:** - Refer to [Assumptions](#assumptions) section for essential configuration guidelines and design assumptions required to enable TMF outbound notifications on these sub-resources. - Outbound notifications on the Contact and Contact Medium sub-resources are currently excluded, as these are already addressed by TMF 632. - When the parent account association of an account is modified, notifications are triggered only from the child account where the association or disassociation occurs. This is achieved by configuring Object Integration Definition mappings to monitor changes to the `Account.ParentId` field on the child account. Since the Account entity does not maintain direct references to its child accounts, notifications can only be configured at the child account level and cannot be triggered from the parent account when these associations change. For each sub-resource listed below, use the RelatedFieldName specified in the table to configure the Object Integration Definition mappings. This ensures the Salesforce Notification Framework triggers notifications accurately for the corresponding change events. **TMF Sub-resource: EngagedParty Salesforce entity: AccountContactRelationship[ACR]/Contact** | TMF Resource | SalesforceEntity
| Scenario | changeEventType Supported | Notification Event Path | RelatedFieldName | | ------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------- | ----------------------------------------------------- | ---------------- | | EngagedParty | AccountContactRelationship [when the contactToMultipleAccountsEnabled = true] | Association of a new Contact with an existing Account | Create | `/api/notification/customerAttributeValueChangeEvent` | AccountId | | | | Disassociation of a contact from an account | Delete | `/api/notification/customerAttributeValueChangeEvent` | AccountId | | | Contact[when the contactToMultipleAccountsEnabled = false] | Updates to Account associated with a Contact | Updates | `/api/notification/customerAttributeValueChangeEvent` | AccountId | | | | Association of an Account with a Contact | Create | `/api/notification/customerAttributeValueChangeEvent` | AccountId | ### Sample Notification framework Payload Request Below is a sample payload that is received from the notification framework when a new Account is associated with a Contact and the query parameter `ContactToMultipleAccountsEnabled = true`. ``` [ { "entityId": "07kLT000000CDeDYAW", "entityName": "AccountContactRelation", "eventId": "000006e5-4f71-6ead-7c8f-6c9e81a573d9_1", "commitTimestamp": 1750834235000, "commitNumber": 1750834235317805057, "correlationId": "000006e5-4f71-6ead-7c8f-6c9e81a573d9", "changedFields": { "LastModifiedDate": "Wed Jun 25 06:50:35 GMT 2025", "AccountId": "001LT00000bu04rYAA", "CreatedById": "005LT000006GmRpYAK", "IsActive": "true", "CreatedDate": "Wed Jun 25 06:50:35 GMT 2025", "ContactId": "003LT000002tUnYYAU", "IsDirect": "false", "CurrencyIsoCode": "USD", "LastModifiedById": "005LT000006GmRpYAK" }, "changeEventType": "Create", "enrichedFields": { "AccountId": "001LT00000bu04rYAA" } } ] ``` Below is a sample payload that is received from the notification framework when a new Account is associated with a Contact and the query parameter `ContactToMultipleAccountsEnabled = false`. ``` { "entityId": "003LT0000038MODYA2", "entityName": "Contact", "eventId": "0000077d-ce77-8a12-2b87-5cb092fc43f3_1", "commitTimestamp": 1750756823000, "commitNumber": 1750756824119255041, "correlationId": "0000077d-ce77-8a12-2b87-5cb092fc43f3", "changedFields": { "AccountId": "001LT00000l1F1xYAE" }, "changeEventType": "Update", "enrichedFields": { "AccountId": "001LT00000l1F1xYAE" } } ``` **TMF Sub-resource: AgreementRef Salesforce entity: Contract** **note:** - The Notification Framework must be configured to trigger `CustomerAttributeValueChangeEvent` events only for changes to the `Contract.AccountId` attribute. All other attribute-level changes on the Contract are handled through TMF651. - The creation of new contracts and updates to existing contracts trigger notifications through both TMF651 and TMF629. | TMF Resource | Salesforce Entity | Scenario | changeEventType Supported | Notification Event Path | RelatedFieldName | | ------------ | ----------------- | ---------------------------------------------------- | ------------------------- | ----------------------------------------------------- | ---------------- | | AgreementRef | Contract | When a Contact is associated with an Account | Create | `/api/notification/CustomerAttributeValueChangeEvent` | AccountId | | | | When an existing Contract is deleted from an Account | Delete | `/api/notification/CustomerAttributeValueChangeEvent` | AccountId | | | | Updates to the Contract entity | Update | `/api/notification/CustomerAttributeValueChangeEvent` | AccountId | ### Sample Notification framework Payload Request Below is a sample payload sent by the notification framework when a Contract is associated with an account. ``` { "entityId": "800LT00000Bjv8fYAB", "entityName": "Contract", "eventId": "0000077d-ce77-8a12-2b87-5cb092fc43f3_1", "commitTimestamp": 1750756823000, "commitNumber": 1750756824119255041, "correlationId": "0000077d-ce77-8a12-2b87-5cb092fc43f3", "changedFields": { "AccountId": "001LT00000l1F1xYAE" }, "changeEventType": "Update", "enrichedFields": { "AccountId": "001LT00000l1F1xYAE" } } ```