---
schema_version: "1"
id: 65acd985201aa2de1463b37b27342b394fd0b1c0bcf1f59399fedb908cf31888
title: Overview
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/guides/TMF666/TMF666use-cases.md
canonical_url: https://developer.salesforce.com/docs/industries/communications/guide/TMF666use-cases.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: dc805a3a0b632053c9fe16ce935200c529ad0addfbb02a289be12b31138da17f
products:
- Communications Cloud TM Forum API
- Industries Integrations
---
# Overview
- The TMF666 API provides a standardized mechanism for billing account management, such as creation, update, retrieval, and deletion of billing accounts.
- Using the TMF666 API you can perform the following operations on billing accounts.
- Retrieve the list of billing accounts from the system
- Get the billing account details
- Create a billing account
- Update an existing billing account
- Delete an existing billing account
In general, you can consider the various [use cases](#use-cases) listed based on the operation you want to perform.
**important:** Starting from the Winter ’27 release, only the Direct Access option is supported for this API.
## Assumptions
It is assumed that you have completed the following.
- [Enabling Access to Industry APIs](https://help.salesforce.com/s/articleView?id=sf.access_industry_api.htm&type=5)
- Ensuring that the required licenses are enabled. See [TMF666 v5 Account Management API](https://developer.salesforce.com/docs/industries/communications/guide/TMF666.md).
**NOTE:**
- For mandatory fields and resource mappings, see [TMF666 v5 Resource Mappings](https://developer.salesforce.com/docs/industries/communications/Resource_mappings/tmf666_resource_mapping.md).
## Use Cases
| I want to | Request Type | Example URL |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve and display details of a particular billing account. | [GET by ID](#get-by-id) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}_
**NOTE:**
For an invalid ID, you receive HTTP 404 error. |
| Based on the provided field values, retrieve and display details of billing accounts. | [GET with Fields](#get-with-fields) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?fields=name_
**NOTE:**
The requested fields are part of the output if they have a value. |
| List all the billing accounts present in the system. | [GET List](#get-list) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount_ |
| List billing accounts present in the system based on the filter applied. | [GET List with Filtering](#get-list-with-filtering) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?name=TMF666 Account_
**NOTE:**
The requested fields are part of the output if they have a value. |
| List billing accounts, limit the number of records to a specified limit, and start the results from the page specified by offset. | [GET List by limit and offset](#get-list-by-limit-and-offset) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?offset=4&pageLimit=1&pageinfo=true_ |
| Create a new billing account by providing the required details. | [POST](#post) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount_
**NOTE:**
A new billing account is created based on the values mentioned for the mandatory fields. |
| Update details of a particular billing account. | [PATCH](#patch) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}_ |
| Delete a billing account. | [DELETE](#delete) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}_
**NOTE:**
DELETE is a soft delete. The account state is set to Inactive. |
## GET by ID
Consider you want to retrieve details of a particular billing account.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}`
### Sample Response
```
{
"id": "15ixx0000004C92AAE",
"href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004C92AAE",
"name": "UpdatedAcct001",
"state": "Active",
"accountType": "Residential",
"lastUpdate": "2026-04-09T05:25:10.000Z",
"billStructure": {
"format": {
"name": "Detailed",
"@type": "BillFormat"
},
"presentationMedia": [
{
"name": "Email",
"@type": "BillPresentationMedia"
}
],
"cycleSpecification": {
"frequency": "Monthly",
"@type": "BillingCycleSpecification"
},
"@type": "BillStructure"
},
"taxExemption": [
{
"certificateNumber": "TAX-EXEMPT-001",
"validFor": {
"startDateTime": "2025-01-01T00:00:00.000Z",
"endDateTime": "2026-12-31T00:00:00.000Z"
},
"reason": "Government",
"@type": "TaxExemption"
}
],
"relatedParty": [
{
"role": "Financially Responsible Party",
"partyOrPartyRole": {
"id": "001xx000003HJdrAAG",
"href": "/services/data/v68.0/sobjects/Account/001xx000003HJdrAAG",
"name": "Acme Corp",
"@type": "PartyRef",
"@referredType": "Organization"
},
"@type": "RelatedPartyRefOrRelatedPartyRoleRef"
}
],
"contact": [
{
"id": "003xx000004WpZwAAK",
"contactName": "John Doe",
"contactType": "Bill To",
"validFor": {
"endDateTime": "2099-12-31T00:00:00.000Z"
},
"contactMedium": [
{
"id": "15ixx0000004C92AAE-cm-1",
"contactType": "billing email",
"preferred": true,
"emailAddress": "billing@acme.com",
"@type": "EmailContactMedium"
},
{
"id": "15ixx0000004C92AAE-cm-2",
"contactType": "billing address",
"preferred": true,
"city": "San Francisco",
"country": "US",
"postCode": "94105",
"stateOrProvince": "CA",
"street1": "123 Main St",
"@type": "GeographicAddressContactMedium"
}
],
"@type": "Contact"
}
],
"@type": "BillingAccount"
}
```
## GET with Fields
Consider you want to retrieve billing accounts and return only these fields in the output.
- id
- name
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?fields=name`
### Sample Response
```
[
{
"@type": "BillingAccount",
"name": "UpdatedAcct001",
"id": "15ixx0000004C92AAE",
"href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004C92AAE"
},
{
"@type": "BillingAccount",
"name": "Home Account",
"id": "15ixx0000004CAeAAM",
"href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004CAeAAM"
}
]
```
## GET List
Consider there are multiple billing accounts in the system and you want to list all of them.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount`
## GET List with Filtering
Consider you want to retrieve billing accounts with applied filter values. Supported filters include `name` and `id`.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?name=TMF666 Account`
## GET List by limit and offset
Consider you want to retrieve a list of billing accounts, limit the number of records, and start the results from the specified offset.
- `offset` is the number of records to skip. Minimum value is 0.
- `pageLimit` is the page size. Minimum value is 1 and maximum value is 2000.
- Pagination is supported for up to 100,000 records (`offset + pageLimit` must be less than or equal to 100,000).
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount?offset=4&pageLimit=1&pageinfo=true`
## POST
Consider you want to create a new billing account. `name` and `relatedParty` are mandatory.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount`
### Sample Request
```
{
"@type": "BillingAccount",
"name": "New Account",
"relatedParty": [
{
"role": "service provider",
"@type": "RelatedPartyRefOrRelatedPartyRoleRef",
"partyOrPartyRole": {
"id": "001xx000003HP8BAAW"
}
}
]
}
```
### Sample Response
```
{
"id": "15ixx0000004N4SAAU",
"href": "/connect/comms/accountmanagement/v5/billingaccount/15ixx0000004N4SAAU",
"name": "New Account",
"state": "Active",
"lastUpdate": "2026-04-26T15:51:29.000Z",
"relatedParty": [
{
"role": "Financially Responsible Party",
"partyOrPartyRole": {
"id": "001xx000003HP8BAAW",
"href": "/services/data/v68.0/sobjects/Account/001xx000003HP8BAAW",
"name": "Test Acme Corp",
"@type": "PartyRef",
"@referredType": "Organization"
},
"@type": "RelatedPartyRefOrRelatedPartyRoleRef"
}
],
"@type": "BillingAccount"
}
```
## PATCH
Consider you want to update details of a particular billing account.
Patchable attributes include `name`, `state`, `accountType`, bill structure fields (`format`, `presentationMedia`, `cycleSpecification.frequency`), and tax exemption fields (`certificateNumber`, start and end dates, and `reason`).
These attributes are not patchable: `id`, `href`, `lastUpdate`, `relatedParty`, `contact`, `contact.contactMedium`, and `defaultPaymentMethod`.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}`
### Sample Request
```
{
"@type": "BillingAccount",
"name": "Billing Account Updated 2.0",
"state": "Active",
"accountType": "Commercial",
"billStructure": {
"@type": "BillStructure",
"presentationMedia": [
{
"@type": "BillPresentationMedia",
"name": "EBill"
}
],
"format": {
"@type": "BillFormat",
"name": "Summary Bill"
},
"cycleSpecification": {
"@type": "BillingCycleSpecification",
"frequency": "Monthly"
}
},
"taxExemption": [
{
"certificateNumber": "TAX-12345",
"reason": "Lower Income Group",
"startDateTime": "2025-01-01T00:00:00.000Z",
"endDateTime": "2027-12-31T00:00:00.000Z"
}
]
}
```
## DELETE
DELETE is a soft delete. The API sets the billing account `state` to Inactive. The record is not physically deleted.
### Sample URL
`{{orgendpoint}}/services/data/{{version}}/connect/comms/accountmanagement/v5/billingAccount/{ID}`
### Sample Request
No request body.
### Sample Response
Status code 204 with no response body.