--- schema_version: "1" id: 0d7c6e2080c295702436e68d3055b48007749208765c5103b25d217ad2243066 title: TMF629 v4 Customer Management collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/industries-integrations/comms/references/generated-api-specs/tmf629.md canonical_url: https://developer.salesforce.com/docs/industries/communications/references/tmf629 source_site: developer.salesforce.com content_type: documentation content_hash: ae2a6cba26104f94a436a4163152ad24677186f91026f87cffaa8afef4b9bc78 products: - Communications Cloud TM Forum API - Industries Integrations --- TMF629 v4 Customer Management # TMF629 v4 Customer Management The customer management API (TMF 629) provides a standardised mechanism for customer and customer account management, such as creation, update, retrieval and deletion of customers. **Version:** v1 Protocols: https. ## Operations ### GET Get Customers `GET /customer` Retrieves a list of Customer entities. Attribute selection is enabled for first-level attributes. #### Parameters * `fields` (query, string) Specifies the comma-separated properties to be included in the response. supported fields are name, id. * `offset` (query, integer) Specifies the requested index for the start of the resources to be included in the response. * `pageLimit` (query, integer) Specifies the requested number of the resources to be included in the response. * `id` (query, string) Unique identifier for Customers * `name` (query, string) term by which the Customer is known and distinguished from other Customers * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Version` (header, string, required) Specifies the version to use with the URL path. version should be greater than or equal to v58.0 * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. #### Responses * **200** successfully retrieved the customer list Media type: `application/json`. Schema: `array of customer_get`. Array of `customer_get`. _Example_ ``` [ { "account": [ { "description": "US, UK, Eastern Europe, Japan, and SE Asia.", "href": "/services/data/v60.0/sobjects/account/001xx000003GYdPAAE", "id": "001xx000003GYdPAAE", "name": "Grand Hotels", "referredType": "Billing Account" } ], "agreement": [ { "href": "/services/data/v60.0/sobjects/contract/800xx000000bna5AAA", "id": "800xx000000bna5AAA", "name": "Contract Of Legal Issue" } ], "engagedParty": { "href": "/services/data/v60.0/sobjects/contact/003xx000004WhECAA0", "id": "003xx000004WhECAA0", "name": "Rose Gonzalez", "role": "Individual" }, "href": "/connect/comms/openapi/customermanagement/customer/001xx000003GYdLAAX", "id": "001xx000003GYdLAAX", "name": "Pyramid Construction Inc." }, { "account": [ { "description": "Chain of hotels and resorts across the US, UK, Eastern Europe, Japan, and SE Asia.", "href": "/services/data/v60.0/sobjects/account/001xx000003GYdPAAW", "id": "001xx000003GYdPAAW", "name": "Grand Hotels & Resorts Ltd", "referredType": "Billing Account" } ], "agreement": [ { "href": "/services/data/v60.0/sobjects/contract/800xx000000bna5AAA", "id": "800xx000000bna5AAA", "name": "Contract Of Legal Issue" } ], "engagedParty": { "href": "/services/data/v60.0/sobjects/contact/003xx000004WhECAA0", "id": "003xx000004WhECAA0", "name": "Rose Gonzalez", "role": "Individual" }, "href": "/connect/comms/openapi/customermanagement/customer/001xx000003GYdLAAW", "id": "001xx000003GYdLAAW", "name": "Edge Communications" } ] ``` * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: RECORD_NOT_FOUND reason: The specified Customer ID doesn’t exist. Provide a valid Customer ID and try again. ``` ### POST Create Customer `POST /customer` Creates a Customer entity. #### Parameters * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Version` (header, string, required) Specifies the version to use with the URL path. version should be greater than or equal to v58.0 * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. #### Request body Media type: `application/json`. Schema: `customer_create`. Specifies the Customer to be created. _Example_ ``` { "name": "Kevin Harper", "engagedParty": { "name": "Sean Forbes" }, "account": [ { "id": "001xx000003GaYhAAK", "name": "Salesforce India" } ], "contactMedium": [ { "mediumType": "Phone", "characteristic": { "phoneNumber": "(555) 555-1234" } }, { "mediumType": "Fax", "characteristic": { "faxNumber": "(555) 123-4567" } }, { "mediumType": "Email", "characteristic": { "emailAddress": "kevin.jarper@salesforce.com" } } ] } ``` #### Responses * **201** Created the Customer resource. Media type: `application/json`. Schema: `customer_create`. _Example_ ``` { "id": "001xx000003GaYiAAK", "href": "/connect/comms/customermanagement/v4/customer/001xx000003GaYiAAK", "type": "Customer", "name": "Kevin Harper", "account": [ { "id": "001xx000003GaX5AAK", "href": "/services/data/v60.0/sobjects/account/001xx000003GaX5AAK", "name": "Salesforce India", "referredType": "Business Account" } ], "engagedParty": { "id": "003xx000004WhvlAAC", "href": "/services/data/v60.0/sobjects/contact/003xx000004WhvlAAC", "name": "Sean Forbes", "role": "Individual" }, "contactMedium": [ { "mediumType": "Email", "characteristic": { "contactType": "Email", "emailAddress": "ttesting25@salesforce.com" } }, { "mediumType": "Fax", "characteristic": { "contactType": "Fax", "faxNumber": "(555) 321-4567" } }, { "mediumType": "Phone", "characteristic": { "contactType": "Phone", "phoneNumber": "(555) 666-2234" } } ] } ``` * **400** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: BAD_REQUEST reason: Specify a valid name and engagedParty. ``` ### GET Retrieve a Customer `GET /customer/{id}` Retrieves a Customer entity by id. Attribute selection is enabled for first-level attributes. #### Parameters * `id` (path, string, required) * `fields` (query, string) Specifies the comma-separated properties to be included in the response. supported fields are name, id. * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Version` (header, string, required) Specifies the version to use with the URL path. version should be greater than or equal to v58.0 * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. #### Responses * **200** Success Media type: `application/json`. Schema: `customer_get`. _Example_ ``` { "account": [ { "description": "Chain of hotels and resorts across the US, UK, Eastern Europe, Japan, and SE Asia.", "href": "/services/data/v60.0/sobjects/account/001xx000003GYdPAAW", "id": "001xx000003GYdPAAW", "name": "Grand Hotels & Resorts Ltd", "referredType": "Billing Account" } ], "agreement": [ { "href": "/services/data/v60.0/sobjects/contract/800xx000000bna5AAA", "id": "800xx000000bna5AAA", "name": "Contract Of Legal Issue" } ], "engagedParty": { "href": "/services/data/v60.0/sobjects/contact/003xx000004WhECAA0", "id": "003xx000004WhECAA0", "name": "Rose Gonzalez", "role": "Individual" }, "href": "/connect/comms/openapi/customermanagement/customer/001xx000003GYdLAAW", "id": "001xx000003GYdLAAW", "name": "Edge Communications" } ``` * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: RECORD_NOT_FOUND reason: The specified Customer ID doesn’t exist. Provide a valid Customer ID and try again. ``` ### PATCH Update Customer `PATCH /customer/{id}` This operation allows partial updates of a Customer entity by id. #### Parameters * `id` (path, string, required) * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Version` (header, string, required) Specifies the version to use with the URL path. version should be greater than or equal to v58.0 * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. #### Request body Media type: `application/json`. Schema: `customer_update`. Specifies the Customer to be updated. _Example_ ``` { "name": "Kevin Harper Updated", "account": [ { "id": "001xx000003GaYhAAK", "name": "Salesforce UK" } ] } ``` #### Responses * **200** Updated the Customer. Media type: `application/json`. Schema: `customer_update`. _Example_ ``` { "id": "001xx000003GaYiAAK", "href": "/connect/comms/customermanagement/v4/customer/001xx000003GaYiAAK", "type": "Customer", "name": "Edge Communications1 patch", "account": [ { "id": "001xx000003GaX5AAK", "href": "/services/data/v60.0/sobjects/account/001xx000003GaX5AAK", "name": "Salesforce India", "referredType": "Business Account" } ], "engagedParty": { "id": "003xx000004WhvlAAC", "href": "/services/data/v60.0/sobjects/contact/003xx000004WhvlAAC", "name": "Sean Forbes", "role": "Individual" }, "contactMedium": [ { "mediumType": "Email", "characteristic": { "contactType": "Email", "emailAddress": "ttesting25@salesforce.com" } }, { "mediumType": "Fax", "characteristic": { "contactType": "Fax", "faxNumber": "(555) 321-4567" } }, { "mediumType": "Phone", "characteristic": { "contactType": "Phone", "phoneNumber": "(555) 666-2234" } } ] } ``` * **400** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: BAD_REQUEST reason: Specify a valid value for mediumType and characteristic. ``` ### DELETE Delete Customer `DELETE /customer/{id}` This operation allows deletion of a Customer by id. #### Parameters * `id` (path, string, required) * `Authorization` (header, string, required) Specifies the bearer token to use for the authentication of request. * `Version` (header, string, required) Specifies the version to use with the URL path. version should be greater than or equal to v58.0 * `Domain-Name` (header, string, required) Specifies the domain name to use with the URL path received from the userinfo API. #### Responses * **204** * **404** Resource not found. Media type: `application/json`. Schema: `Error`. _Example_ ``` code: RECORD_NOT_FOUND reason: The specified customer ID doesn’t exist. Provide a valid customer ID and try again. ``` ## Schemas ### customer\_get * `id` (_string_) Unique identifier for Customers * `name` (_string_) term by which the Customer is known and distinguished from other Customers * `@type` (_string_) The @type attribute provides a way to represent the actual class type of an entity. * `href` (_string_) Url used to reference the customer * `agreement` (_array of object_) A list of agreement references (AgreementRef \[\*\]),such as a service level agreement or a customer price agreement. Includes all fields of `AgreementRef`. * `account` (_array of object_) A account may be a party account or a financial account Includes all fields of `AccountRef`. * `contactMedium` (_array of object_) A list of contact mediums (ContactMedium \[\*\]). Indicates the contact medium that could be used to contact the party. Includes all fields of `ContactMedium`. * `engagedParty` (_object_) an organization or an individual - that is engaged as a customer. Includes all fields of `EngagedPartyRef`. ### Error Shown when an API throws an error, typically with an HTTP error response code (3xx, 4xx, or 5xx). * `code` (_string_, required) Specifies the application-relevant detail defined in the API or a common list. * `reason` (_string_, required) Describes the reason for the error, which can be shown to a client user. ### customer\_create * `name` (_string_, required) term by which the Customer is known and distinguished from other Customers * `account` (_array of object_) A account may be a party account or a financial account Includes all fields of `AccountRefPostandPatch`. * `contactMedium` (_array of object_) A list of contact mediums (ContactMedium \[\*\]). Indicates the contact medium that could be used to contact the party. Includes all fields of `ContactMedium`. * `engagedParty` (_object_, required) an organization or an individual - that is engaged as a customer. Includes all fields of `EngagedPartyRefPost`. ### customer\_update * `name` (_string_) term by which the Customer is known and distinguished from other Customers * `account` (_array of object_) A account may be a party account or a financial account Includes all fields of `AccountRefPostandPatch`. * `contactMedium` (_array of object_) A list of contact mediums (ContactMedium \[\*\]). Indicates the contact medium that could be used to contact the party. Includes all fields of `ContactMediumPatch`. * `engagedParty` (_object_) an organization or an individual - that is engaged as a customer. Includes all fields of `EngagedPartyRefPatch`. ### AgreementRef * `id` (_string_) A string. Unique identifier of a related entity. * `href` (_string_) A string. Reference of the related entity. * `name` (_string_) A string. Name of the agreement. ### AccountRef * `id` (_string_) A string. Reference of the account. Id of an existing account. * `description` (_string_) A string. Detailed description of the account. * `href` (_string_) A string. Reference of the account. * `name` (_string_) A string. Name of the account. Name of an existing account. * `referredType` (_string_) A string. type fo the account ### ContactMedium * `characteristic` (_object_, required) A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this contact medium. Includes all fields of `MediumCharacteristic`. * `mediumType` (_string_, required) A string. Type of the contact medium, such as email address, telephone number, postal address. Supported values are Email, Phone, Fax ### EngagedPartyRef * `href` (_string_) A string. Reference of the related entity. * `id` (_string_) A string. Unique identifier of a related entity. * `name` (_string_) A string. Name of the agreement. * `role` (_string_) A string. Role played by the related party. ### AccountRefPostandPatch * `id` (_string_, required) A string. Reference of the account. Id of an existing account. * `name` (_string_, required) A string. Name of the account. Name of an existing account. ### EngagedPartyRefPost * `id` (_string_) A string. Unique identifier of a related entity. * `name` (_string_, required) A string. Name of the agreement. ### ContactMediumPatch * `characteristic` (_object_) A medium characteristic (MediumCharacteristic). Any additional characteristic(s) of this contact medium. Includes all fields of `MediumCharacteristicPatch`. * `mediumType` (_string_) A string. Type of the contact medium, such as email address, telephone number, postal address. Supported values are Email, Phone, Fax ### EngagedPartyRefPatch * `id` (_string_) A string. Unique identifier of a related entity. * `name` (_string_) A string. Name of the agreement. ### MediumCharacteristic * `contactType` (_string_) A string. The type of contact, for example phone number such as mobile, fixed home, fixed office. postal address such as shipping installation. Supported values are Email, Phone, Fax * `emailAddress` (_string_) A string. Full email address in standard format. This Email Address should be unique. * `faxNumber` (_string_) A string. The fax number of the contact. * `phoneNumber` (_string_) A string. The primary phone number of the contact. ### MediumCharacteristicPatch * `emailAddress` (_string_) A string. Full email address in standard format. This Email Address should be unique. * `faxNumber` (_string_) A string. The fax number of the contact. * `phoneNumber` (_string_) A string. The primary phone number of the contact.