Show full documentation

 Show full documentation

Definition

An interface to query customer master data.

Business Context and Use

The web service interface Query Customer In enables you to connect external applications to your solution and to query and read accounts and their assigned contacts in your system. The web service interface Query Customer In is relevant if your company wants to access and manage business partner data from external applications.

The web service interface Query Customer In offers the operations Find By Identification, Find By Communication Data, and Find By Elements.

Here is an example of a simple web service request, which seeks for all customers with an Email address matching "*customer.com".

<n0:CustomerByCommunicationDataQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
    <CustomerSelectionByCommunicationData>
        <SelectionByEmailURI>
            <InclusionExclusionCode>I</InclusionExclusionCode>
            <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
            <LowerBoundaryEmailURI>*customer.com</LowerBoundaryEmailURI>
        </SelectionByEmailURI>
    </CustomerSelectionByCommunicationData>
    <ProcessingConditions>
      <!--<QueryHitsMaximumNumberValue>10</QueryHitsMaximumNumberValue>-->
        <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>
    </ProcessingConditions>
</n0:CustomerByCommunicationDataQuery_sync>

Here is an excerpt of the response of the request above including one of 10 customer records returned by the query:

<nm:CustomerByCommunicationDataResponse_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global">
    <Customer>
        <ChangeStateID>20100702104427.3216490</ChangeStateID>
        <UUID>00300571-cc0f-02db-b8c6-6cc9735cc23a</UUID>
        <InternalID>MS2400</InternalID>
        ...
        <Organisation>
            <FirstLineName>Customer Company</FirstLineName>
        </Organisation>
        <LegalCompetenceIndicator>true</LegalCompetenceIndicator>
        <DunAndBradstreetNumberID>101002400</DunAndBradstreetNumberID>
        <AddressInformation>
            ...
            <Address>
                <EmailURI>info@customer.com</EmailURI>
                ...
            </Address>
        </AddressInformation>
        <ContactPerson>
            <BusinessPartnerContactUUID>00300571-ce9b-1ded-89de-403b12aa5ec4</BusinessPartnerContactUUID>
            <BusinessPartnerContactInternalID>MSP2400</BusinessPartnerContactInternalID>
            <FormOfAddressCode>0002</FormOfAddressCode>
            <GivenName>Peter M.</GivenName>
            <FamilyName>Greene</FamilyName>
            ...
        </ContactPerson>
        ...
    </Customer>
    ...
    <ProcessingConditions>
        <ReturnedQueryHitsNumberValue>10</ReturnedQueryHitsNumberValue>
        <MoreHitsAvailableIndicator>false</MoreHitsAvailableIndicator>
        <LastReturnedObjectID>00300571CC0F02DBB8C79C6E3F1E8020</LastReturnedObjectID>
    </ProcessingConditions>
</nm:CustomerByCommunicationDataResponse_sync>

Constraints and Integrity Conditions

General Rules for Using this Web Service

Requested Elements

Examples

• All data (complete response):

Expected result:

<Customer>
<full response... />
<Customer>

Request:

<RequestedElements customerTransmissionRequestCode='1'>

or (default is '1')

<RequestedElements />

or just omit it (default is all)

 ... empty ... 

• Return everything except address information:

Expected result:

<Customer>
  <all... except address information node />
</Customer>

Request:

<RequestedElements customerRequestCode='2'>
  <Customer addressInformationTransmissionRequestCode='4' />
</RequestedElements>

• Return customer general data, address information and bank details:

Expected result:

<Customer>
  <InternalID>MCF-0001-SOS</InternalID>
  <…/>
  <AddressInformation>
    <…/>
  </AddressInformation>
  <BankDetails>
    <…/>
  </BankDetails>
</Customer>

Request:

<RequestedElements customerTransmissionRequestCode='2'>
  <Customer addressInformationTransmissionRequestCode='2'
            bankDetailsTransmissionRequestCode='2' />
</RequestedElements>

• Return customer general data, bank details, and all address information nodes:

Expected result:

<Customer>
  <InternalID>MCF-0001-SOS</InternalID>
  <…/>
  <BankDetails>
    <…/>
  </BankDetails>
  <AddressInformation>
    <…/>
    <Telephone>
      <…/>
    </Telephone>
    <PersonalAddress>
      <…/>
    </PersonalAddress>
  </AddressInformation>
</Customer>

Request:

<RequestedElements customerTransmissionRequestCode='2'>
  <Material bankDetailsTransmissionRequestCode='2'
            addressInformationTransmissionRequestCode='1' />
</RequestedElements>

• Return address information only:

Expected result:

<Customer>
  <InternalID>MCF-0001-SOS</InternalID>
  <AddressInformation>
    <…/>
    <PersonalAddress>
      <…/>
    </PersonalAddress>
    <Telephone>
      <…/>
    </Telephone>
  </AddressInformation>
</Customer>

Request:

<RequestedElements customerTransmissionRequestCode='2'>
  <Material addressInformationTransmissionRequestCode='1' />
</RequestedElements>

More Information

General Information

You can find general information about Web services, their structure and consumption in the Web Services documentation.

Scenarios

The following example scenario can be carried out using requested elements.

E-Commerce Integration

The following example request returns all accounts with an e-mail address ending with "customer.com" including general data, contact person information, and sales arrangements.

<n0:CustomerByCommunicationDataQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
    <CustomerSelectionByCommunicationData>
        <SelectionByEmailURI>
            <InclusionExclusionCode>I</InclusionExclusionCode>
            <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
            <LowerBoundaryEmailURI>*customer.com</LowerBoundaryEmailURI>
        </SelectionByEmailURI>
    </CustomerSelectionByCommunicationData>
    <ProcessingConditions>
        <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>
    </ProcessingConditions>
    <RequestedElements customerTransmissionRequestCode="2">
        <Customer contactPersonTransmissionRequestCode="1" 
                  salesArrangementTransmissionRequestCode="1"             
                  personTransmissionRequestCode="1"  
                  organisationTransmissionRequestCode="1"/>
    </RequestedElements>
</n0:CustomerByCommunicationDataQuery_sync>

The following example requests returns all accounts for which the given employee is responsible.

<n0:CustomerByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
 <CustomerSelectionByElements>
  <SelectionByResponsibleEmployeeUUID>
   <InclusionExclusionCode>I</InclusionExclusionCode>
   <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode>
   <LowerBoundaryUUID>00163e03-390f-1ed2-a391-b1a36530b88f</LowerBoundaryUUID>
  </SelectionByResponsibleEmployeeUUID>
 </CustomerSelectionByElements>
 <ProcessingConditions>
  <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator>
 </ProcessingConditions>
</n0:CustomerByElementsQuery_sync>

 Show full documentation

 Show full documentation

Definition

To find customer data by identification.

Business Context and Use

The request message of the operation FindByIdentification contains the CustomerSelectionByIdentification node that groups all possible selection parameters.

Structure

Request

Customer Selection By Identification

This node groups all selection parameters. The selection parameters are:

Selection Parameter	Remark
SelectionByInternalID	Selection by internal ID (Account ID)
SelectionByUUID	Selection by UUID
SelectionByCategoryCode	Selection by category code:1 Person (Private Account)2 Organization (Corporate Account)
SelectionBusinessCharacterCode	Selection by business character code:Only prospect is available for Customer: BUP002 Prospect
SelectionByBusinessPartnerID	Selection by business partner ID Should be used together with selection by party identifier type code.
SelectionByPartyIdentifierTypeCode	Selection by party identifier type code Valid values for customer: BUP001 Dun & Bradstreet number BUP005 Global Location Number
SelectionByBusinessPartnerName	Selection by business partner name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name
SelectionByBusinessPartnerAdditionalName	Selection by business partner additional name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts):Additional name
SelectionBySortingFormattedName	Selection by sorting formatted name
SelectionByLifeCycleStatusCode	Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete
SelectionBySearchText	Selection by search text (basic search)

Response

The response contains the list of found accounts, log items, and processing conditions.

Customer

In this node, all found accounts are contained, including their account data according to the RequestedElements provided in the query request. This includes the ChangeStateID that may be needed for subsequent change requests via web services as well.

For each address of customers and contact persons the address UUID and the most current address snapshot UUID is returned by this service. Note that the address snapshot UUID is not available for customers and contact persons with status In Preparation.

If you want to change or display address data of business partners, use the AddressInformationUUID element.

In all other cases use the current address snapshot UUID (CurrentAddressSnapshotUUID and CurrentWorkplaceAddressSnapshotUUID elements) representing an address snapshot of this business partner address with the currently valid data. This applies particularly to all usages of the address within business processes or business transaction documents, such as sales orders, purchasing orders, outbound deliveries, or invoices.

The address snapshot contains exactly the same data as the business partner address, but it cannot be changed: If the business partner’s address changes, the address snapshot does not change, but a new address snapshot is created for each change of the business partner address instead.

Example: A business partner has an address in Paris. A sales order is created with a ship-to party using the currently valid address snapshot AddressSnapshotUUID_1. Then the business partner address is changed to Marseille. A new address snapshot AddressSnapshotUUID_2 with the address "Marseille" is created. However, the sales order is still referring to the older address snapshot with the address in Paris. This is intended behavior from a business point of view, since, for example, taxes and prices have been determined for Paris. However, if goods ordered now have to be delivered to Marseille instead, then the sales order needs to be updated with the new address referring to AddressSnapshotUUID_2.

Note that for all SAP-delivered business transaction documents, you must use the address snapshot UUID; you cannot use the address UUID.

Change Log:

Release	Change Description	Details
1902	Supporting MultiChannel for Document Output	The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel
1911	Supporting Japan Invoice Summary Data	The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID
2002	Supporting TransformationID for E-Invoicing	The CommunicationArrangement node and the CommunicationChannel node of the response structure were enhanced with the element TransformationID.

 Show full documentation

 Show full documentation

Definition

To find customer data by communication data.

Business Context and Use

The request message of the operation FindByCommunicationData contains the CustomerSelectionByCommunication node that groups all possible selection parameters.

Structure

Request

Customer Selection By Communication Data

This node groups all selection parameters. The selection parameters are as follows:

Selection Parameter	Remark
SelectionByNormalisedTelephoneNumber	Selection by normalized telephone number
SelectionByNormalisedFacsimileNumber	Selection by normalized facsimile number
SelectionByEmailURI	Selection by Email URI. The following Email addresses are considered by this parameter: Account Email addresses, related Contact Persons Email addresses, related Service Performers Email addresses and Employees Workplace Email addresses.
SelectionByInternalID	Selection by internal ID (Account ID)
SelectionByUUID	Selection by UUID
SelectionByCategoryCode	Selection by category code:1 Person (Private Account) 2 Organization (Corporate Account)
SelectionBusinessCharacterCode	Selection by business character code:Only prospect is available for Customer: BUP002 Prospect
SelectionByBusinessPartnerName	Selection by Business Partner Name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name
SelectionByBusinessPartnerAdditionalName	Selection by Business Partner Additional Name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts): Additional Name
SelectionBySortingFormattedName	Selection by sorting formatted name
SelectionByLifeCycleStatusCode	Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete
SelectionBySearchText	Selection by search text (Basic Search)

Response

The response of the Find By Communication Data operation is the same as for the Find By Identification operation.

Change Log

Release	Change Description	Details
1902	Supporting MultiChannel for Document Output	The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel
1911	Supporting Japan Invoice Summary Data	The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID
2005	Supporting Mexico UseOfCFDI field	The Customer node of the response structure was enhanced with the element MXUseofCFDICode

 Show full documentation

 Show full documentation

Definition

To find customer data by elements.

Business Context and Use

The request message of the operation FindByElements contains the CustomerSelectionByElements node that groups all possible selection parameters.

Structure

Request

Customer Selection By Elements

This node groups all selection parameters. The selection parameters are as follows:

Selection Parameter	Remark
SelectionByInternalID	Selection by internal ID (Account ID)
SelectionByUUID	Selection by UUID
SelectionByCategoryCode	Selection by category code:1 Person (Private Account); 2 Organization
SelectionByBusinessPartnerRoleCode	Selection by business partner role code:Only prospect is available for Customer: BUP002 Prospect
SelectionByBusinessPartnerName	Selection by business partner name:For Persons (Private Accounts): Last Name For Organizations (Corporate Accounts): Account Name
SelectionByBusinessPartnerAdditionalName	Selection by business partner additional name:For Persons (Private Accounts): First Name For Organizations (Corporate Accounts): Additional Name
SelectionBySortingFormattedName	Selection by sorting formatted name
SelectionByContactPersonWorkplaceEmailURI	Selection by contact person workplace e-mail address
SelectionByLegalCompetenceIndicator	Selection by legal competence indicator specifying whether the customer is legally competent.
SelectionBySelectionByAddressDefaultIndicator	Selection by default address indicator.
SelectionByPostalAdressCityName	Selection by a city in the postal address, for example, "Walldorf"
SelectionByPostalAddressStreetPostalCode	Selection by a postal code in a postal address, for example, "69124" in the case of "Heidelberg"
SelectionByPostalAddressCountryCode	Selection by country code in a postal address, for example, "DE" for "Germany"
SelectionByPostalAddressRegionCode	Selection by region code in a postal address which are specific for countries, for example, with List ID "DE" the value "08" would stand for "Baden-Wuerttemberg"
SelectionByABCClassificationCode	Selection by ABC classification code:A A-Account B B-Account C C-Account
SelectionByIndustrialSectorCode	Selection by industrial sector code
SelectionByContactPersonInternalID	Selection by contact person internal ID
SelectionByContactPersonUUID	Selection by UUID
SelectionByContactPersonFamilyName	Selection by contact person family name
SelectionByContactPersonGivenName	Selection by contact person given name
SelectionByContactPersonSortingFormattedName	Selection by contact person sorting formatted name
SelectionBySalesArrangementSalesOrganisationID	Selection by sales arrangement sales organization ID
SelectionByCreatedSinceDate	Selection of all accounts that were created since the specified date
SelectionByChangedSinceDate	Selection of all accounts that were changed since the specified date. The "changed since" date does not take into account changes of the response nodes ContactPerson, Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, and PaymentData.
SelectionByCreatedSinceDateTime	Selection of all accounts that were created since the specified point in time.
SelectionByLastChangeSinceDateTime	Selection of all accounts that were changed since the specified point in time. The "changed since" date and time do not take into account changes of the response nodes ContactPerson, Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, and PaymentData.
SelectionByCreationDateTime	Selection of all accounts that were created during the specified time range.
SelectionByCreationIdentityID	Selection by the ID of the identity that created the account.
SelectionByLastChangeIdentityID	Selection by the ID of the identity that changed the account data at last.
SelectionByLifeCycleStatusCode	Selection by life cycle status code:1 In Preparation 2 Active 3 Blocked 4 Obsolete
SelectionBySearchText	Selection by search text (Basic Search)
SelectionByResponsibleEmployeeUUID	Selection by employee responsible UUID
SelectionByLastChangeDateTime	Selection of all accounts that were changed during the specified time range.

Response

The response of the FindByElements operation is the same as for the FindByIdentification operation.

Change Log

Release	Change Description	Details
1902	Supporting MultiChannel for Document Output	The Customer node of the response structure was enhanced with node CommunicationArrangementMultiChannel and sub node CommunicationChannel
1908	Selection parameter SelectionByLastChangeDateTime is added	A range specification for last change is now possible
1911	Supporting Japan Invoice Summary Data	The Customer node of the response structure was enhanced with the elements InvoiceSummaryRoleCode and ClosingDatePatternID
2005	Supporting Mexico UseOfCFDI field	The Customer node of the response structure was enhanced with the element MXUseofCFDICode