---
schema_version: "1"
id: 841dcb626356070e791d8c38eecf19d352a5f84278569994b70f88841cff1f08
title: Use Cases for Agreement
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/guides/TMF651/use-cases-for-agreement.md
canonical_url: https://developer.salesforce.com/docs/industries/communications/guide/use-cases-for-agreement.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: d6094b064c40009d573fac8f22ee6432148da52a1048d4ddc95145b9058ae1cc
products:
- Communications Cloud TM Forum API
- Industries Integrations
---
# Use Cases for Agreement
| I want to | Request Type | Example URL |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve and display details of a agreement instance. | [GET by ID for Agreement](#get-by-id-for-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement/{id-of-the-resouce-to-be-retrieved}
_
**NOTE:**
For invalid customer ID, you will receive HTTP 404 error. |
| Based on the provided field values, retrieve and display details of agreement instance. | [GET with Fields for Agreement](#get-with-fields-for-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement?fields=name_
**NOTE:**
The requested fields will be part of output, if they have value. |
| List all the agreement instances present in the system. | [GET List of Agreements](#get-list-of-agreements) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/aagreement_ |
| List agreement instances present in the system based on the filter applied. | [GET List with Filtering for Agreement](#get-list-with-filtering-for-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement?name=testing_
**NOTE:**
The requested fields will be part of output, if they have value. |
| List agreement instances, limit the number of agreement instances to a maximum of specified limit, and
starts the results display from page specified by offset. | [GET with Pagination for Agreement](#get-with-pagination-for-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement?pageLimit=2&offset=5_
|
| Create a new agreement instance by providing the required details. | [POST an Agreement](#post-an-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement
_
**NOTE:**
A new agreement instances gets created based on the values mentioned for the mandatory fields. |
| Update details of particular agreement instance. | [PATCH an Agreement](#patch-an-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement/{ID}_ |
| Delete an agreement instance. | [DELETE an Agreement](#delete-an-agreement) | _{{orgendpoint}}/services/data/{{version}}/connect/comms/agreementmanagement/v4/agreement/{ID}_ |
## GET by ID for Agreement
Consider you want to retrieve details of a particular agreement instance.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA`
### Sample Response
```
200 OK
{
"id": "800xx000000bp41AAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA",
"name": "features",
"agreementType": "SampleContractType",
"description": "new statement",
"documentNumber": "00000156",
"status": "Draft",
"@type": "Agreement",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
],
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementSpecification": {
"id": "2dtxx0000000001AAA",
"href": "/connect/comms/AGREEMENTMANAGEMENT/v4/AGREEMENT/2dtxx0000000001AAA",
"name": "Test Document 2",
"referredType": "Document Template"
},
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2SAAQ",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2SAAQ",
"name": "GenWatt Diesel 200kW",
"referredType": "ProductOffering"
},
{
"id": "01txx0000006i2iAAA",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2iAAA",
"name": "Installation: Industrial - Medium",
"referredType": "ProductOffering"
}
],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
]
}
```
## GET with Fields for Agreement
Consider you want to retrieve details of an agreement with requested attributes (id, href are always included).
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement?fields=name`
### Sample Response
```
[
{
"@type": "Agreement",
"name": "testing",
"id": "800xx000000bni9AAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bni9AAA"
},
{
"@type": "Agreement",
"name": "testing",
"id": "800xx000000bnjlAAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bnjlAAA"
}
]
```
## GET List of Agreements
Consider there are agreement instances in the system and you want to list all of them.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement`
### Sample Response
```
200 OK
[
{
"documentNumber": "00000154",
"@type": "Agreement",
"description": "new statement",
"name": "features",
"status": "Draft",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"id": "800xx000000bp2PAAQ",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp2PAAQ",
"agreementType": "SampleContractType",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementItem": [
{
"productOffering": [],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
],
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
]
},
{
"agreementType": "SampleContractType",
"documentNumber": "00000156",
"@type": "Agreement",
"description": "new statement",
"name": "features",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"id": "800xx000000bp41AAA",
"status": "Draft",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementSpecification": {
"id": "2dtxx0000000001AAA",
"href": "/connect/comms/AGREEMENTMANAGEMENT/v4/AGREEMENT/2dtxx0000000001AAA",
"name": "Test Document 2",
"referredType": "Document Template"
},
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2SAAQ",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2SAAQ",
"name": "GenWatt Diesel 200kW",
"referredType": "ProductOffering"
},
{
"id": "01txx0000006i2iAAA",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2iAAA",
"name": "Installation: Industrial - Medium",
"referredType": "ProductOffering"
}
],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
],
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
]
}
]
```
## GET List with Filtering for Agreement
Consider you want to retrieve all the agreement instances in the system with applied filter values.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement?name=testing`
### Sample Response
Response displays records filtered by `testing` for field `name`.
```
[
{
"agreementType": "SampleContractType",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [...],
"documentNumber": "00000141",
"@type": "Agreement",
"description": "Sample description",
"name": "testing",
"completionDate": "Wed Sep 19 00:00:00 GMT 2018",
"id": "800xx000000boj3AAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000boj3AAA",
"agreementItem": [
{
"productOffering": [...],
"termOrCondition": [...]
}
],
"engagedParty": [...],
"status": "Draft"
},
{
"agreementType": "SampleContractType",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [...],
"documentNumber": "00000142",
"@type": "Agreement",
"agreementSpecification": {.},
"description": "Sample description",
"name": "testing",
"completionDate": "Wed Sep 19 00:00:00 GMT 2018",
"id": "800xx000000bokfAAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bokfAAA",
"agreementItem": [
{
"productOffering": [...],
"termOrCondition": [...]
}
],
"engagedParty": [.],
"status": "Draft"
}
]
```
## GET with Pagination for Agreement
Consider you want to
- Retrieve a list of agreement instances
- Limit the number of results to a maximum of specified limit
- Start the results display from page specified by offset
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement?pageLimit=2&offset=5`
**NOTE:** The above pagination query displays maximum 2 records from 5th record onwards (skips first 4 records).
### Sample Response
```
200 OK
[
{
"documentNumber": "00000154",
"@type": "Agreement",
"description": "new statement",
"name": "features",
"status": "Draft",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"id": "800xx000000bp2PAAQ",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp2PAAQ",
"agreementType": "SampleContractType",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementItem": [
{
"productOffering": [],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
],
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
]
},
{
"agreementType": "SampleContractType",
"documentNumber": "00000156",
"@type": "Agreement",
"description": "new statement",
"name": "features",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"id": "800xx000000bp41AAA",
"status": "Draft",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementSpecification": {
"id": "2dtxx0000000001AAA",
"href": "/connect/comms/AGREEMENTMANAGEMENT/v4/AGREEMENT/2dtxx0000000001AAA",
"name": "Test Document 2",
"referredType": "Document Template"
},
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2SAAQ",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2SAAQ",
"name": "GenWatt Diesel 200kW",
"referredType": "ProductOffering"
},
{
"id": "01txx0000006i2iAAA",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2iAAA",
"name": "Installation: Industrial - Medium",
"referredType": "ProductOffering"
}
],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
],
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
]
}
]
```
## POST an Agreement
Consider you want to create a new agreement instance.
**Prerequisites**
These are the prerequisites for the POST operation.
- The `agreementType` attribute must be the name of `ContractType`. Perform the following steps to create `ContractType`.
- Create a `RecordType` on Contract entity.
- Create a `ContractType` by associating it with `RecordType` created previously.
- These are mandatory fields.
- name
- agreementType
- agreementPeriod(startDateTime)
- engagedParty
- agreementItem (productOffering + termOrCondition)
- Fields `engagedParty` and `productOffering` are validated for Id-Name pair
- Fields `associatedAgreement` and `agreementSpecification` are only validated for Salesforce ID. The name can be passed but it is ignored.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement`
### Sample Request
```
{
"name" : "features",
"description" : "new statement",
"agreementType" : "SampleContractType",
"agreementTerm" : "6",
"agreementPeriod": {
"startDateTime": "2018-04-20T00:00"
},
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"name": "Edge Communications"
}
],
"associatedAgreement":
[
{
"id" : "800xx000000bnlNAAQ",
"name": "full contract"
}
],
"agreementSpecification":
{
"id" : "2dtxx0000000001AAA",
"name": "Test Document 2"
}
,
"agreementItem":
[
{
"productOffering": [
{
"id": "01txx0000006i2SAAQ",
"name": "GenWatt Diesel 200kW"
},
{
"id": "01txx0000006i2iAAA",
"name": "Installation: Industrial - Medium"
}
],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "2018-04-25T00:00",
"endDateTime": "2018-11-20T00:00"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "2018-04-25T00:00",
"endDateTime": "2018-11-20T00:00"
}
}
]
}
]
}
```
### Sample Response
```
{
"id": "800xx000000bp41AAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA",
"name": "features",
"agreementType": "SampleContractType",
"description": "new statement",
"documentNumber": "00000156",
"status": "Draft",
"@type": "Agreement",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"engagedParty": [
{
"id": "001xx000003GYiBAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiBAAW",
"name": "Edge Communications",
"role": "Customer - Direct",
"referredType": "Account"
}
],
"associatedAgreement": [
{
"id": "800xx000000bnlNAAQ",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnlNAAQ",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementSpecification": {
"id": "2dtxx0000000001AAA",
"href": "/connect/comms/AGREEMENTMANAGEMENT/v4/AGREEMENT/2dtxx0000000001AAA",
"name": "Test Document 2",
"referredType": "Document Template"
},
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2SAAQ",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2SAAQ",
"name": "GenWatt Diesel 200kW",
"referredType": "ProductOffering"
},
{
"id": "01txx0000006i2iAAA",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2iAAA",
"name": "Installation: Industrial - Medium",
"referredType": "ProductOffering"
}
],
"termOrCondition": [
{
"description": "condition 1",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
},
{
"description": "condition 2",
"id": "2",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Tue Nov 20 00:00:00 GMT 2018"
}
}
]
}
]
}
```
## PATCH an Agreement
Consider you want to update details of a particular agreement instance.
**NOTE:**
- Following are patchable attributes.
- description
- engagedParty
- associatedAgreement
- agreementSpecification
- agreementItem
- Fields `associatedAgreement` and `agreementSpecification` are only validated for Salesforce ID. The name can be passed but it is ignored.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v4/agreement/2dtxx00000000eLAAQ`
### Sample Request
Request body will have fields that need to be updated.
```
{
"description" : "Sample description - updated",
"engagedParty": [
{
"id": "001xx000003GYiGAAW",
"name": "United Oil & Gas Corp."
}
],
"associatedAgreement":
[
{
"id" : "800xx000000bnmzAAA",
"name": "full contract 2"
}
],
"agreementSpecification":
{
"id" : "2dtxx000000001dAAA",
"name": "Test Document 3"
}
,
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2TAAQ",
"name": "GenWatt Diesel 10kW"
}
],
"termOrCondition": [
{
"description": "updated termOrCondition",
"id": "1",
"validFor": {
"startDateTime": "2018-04-25T00:00",
"endDateTime": "2019-11-20T00:00"
}
}
]
}
]
}
```
### Sample Response
```
{
"id": "800xx000000bp41AAA",
"href": "/connect/comms/agreementmanagement/v4/agreement/800xx000000bp41AAA",
"name": "features",
"agreementType": "SampleContractType",
"description": "Sample description - updated",
"documentNumber": "00000156",
"status": "Draft",
"@type": "Agreement",
"completionDate": "Fri Oct 19 00:00:00 GMT 2018",
"agreementPeriod": {
"startDateTime": "Fri Apr 20 00:00:00 GMT 2018"
},
"engagedParty": [
{
"id": "001xx000003GYiGAAW",
"href": "/services/data/v60.0/sobjects/Account/001xx000003GYiGAAW",
"name": "United Oil & Gas Corp.",
"role": "Customer - Direct",
"referredType": "Account"
}
],
"associatedAgreement": [
{
"id": "800xx000000bnmzAAA",
"href": "/services/data/v60.0/sobjects/Contract/800xx000000bnmzAAA",
"name": "full contract 1",
"referredType": "Parent Contract"
}
],
"agreementSpecification": {
"id": "2dtxx000000001dAAA",
"href": "/connect/comms/AGREEMENTMANAGEMENT/v4/AGREEMENT/2dtxx000000001dAAA",
"name": "Test Document 3",
"referredType": "Document Template"
},
"agreementItem": [
{
"productOffering": [
{
"id": "01txx0000006i2TAAQ",
"href": "/services/data/v60.0/sobjects/Product2/01txx0000006i2TAAQ",
"name": "GenWatt Diesel 10kW",
"referredType": "ProductOffering"
}
],
"termOrCondition": [
{
"description": "updated termOrCondition",
"id": "1",
"validFor": {
"startDateTime": "Wed Apr 25 00:00:00 GMT 2018",
"endDateTime": "Wed Nov 20 00:00:00 GMT 2019"
}
}
]
}
]
}
```
## DELETE an Agreement
Consider you want to delete details of a particular agreement instance.
### Sample URL
`https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/data/v62.0/connect/comms/agreementmanagement/v5/agreement/2dtxx00000000eLAAQ`
### Sample Request
No request body.
### Sample Response
Status code 204 with no response body