| Description | Manage Leads |
| Name | MaintainLeadIn |
| Namespace | http://sap.com/xi/AP/CRM/Global |
| Product | SAP Business ByDesign |
| Process component | Lead Processing |
| Process component namespace | http://sap.com/xi/AP/CRM/Global |
| Deployment unit | Customer Relationship Management |
| Endpoint Activation | By Scoping of Process Component | Operations |
|
| Release Status | Released |
| Technical documentation on the SAP API Business Hub | Manage Leads |
| General web service documentation | A2X Web Services (SOAP) |
An interface to migrate lead data from a source system or file.
The web service interface Manage or Maintain Lead In enables you to connect external applications to your SAP system and to create and edit leads in your system. The web service interface Maintain Lead In is relevant if your company wants to access and manage lead data from external applications.
The web service interface Maintain Lead In offers the operations MaintainBundle and CheckMaintainBundle.
Here is an example of a simple web service request:
<n0:LeadMaintainBundleReq_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00000000000102dcade9bcb0ab000c99</ID> </BasicMessageHeader> <Lead actionCode="01"> <Name>A2X Create Lead with Parties, Text etc.</Name> <QualificationLevelCode>01</QualificationLevelCode> <StartDate>2012-11-26</StartDate> <EndDate>2012-12-31</EndDate> <GroupCode>0023</GroupCode> <OriginTypeCode>004</OriginTypeCode> <Note actionCode="01"> <ContentText>A2X Example for text</ContentText> </Note> <Item actionCode="01"> <ID>10</ID> <Description languageCode="EN">A2X Example for item</Description> <QuantityValue unitCode="ea">1</QuantityValue> </Item> <MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty> <SalesResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </SalesResponsibleEmployeeParty> <ProspectParty> <BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID> </ProspectParty> </Lead> </n0:LeadMaintainBundleReq_sync>
Existence of referenced business data:
The following business data are only referenced and will not be created by the service operations. They must exist in the system already at the time the web service is called:
Business partners and related projections like prospects, employees, etc.
Products, Materials, Services
Campaigns
You can find general information about Web services, their structure and consumption in the Web Services documentation. Please open the Web Services document in a new window.
Possible scenarios include the following:
Create Lead
The MaintainBundle operation is used to create leads.
Update Lead
The MaintainBundle operation is used to update leads.
Delete Lead
The MaintainBundle operation is used to delete leads as well.
Example web service request to create a lead:
<n0:LeadMaintainBundleReq_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00000000000102dcade9bcb0aa001a64</ID> </BasicMessageHeader> <Lead actionCode="01" itemListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID/> <ChangeStateID/> <UUID/> <ID/> <Name>A2X Create Lead</Name> <QualificationLevelCode/> <StartDate>2012-11-26</StartDate> <EndDate>2012-12-31</EndDate> <LifeCycleStatusCode/> <StatusValidSinceDate/> <GroupCode/> <OriginTypeCode>004</OriginTypeCode> <ResultReasonCode/> <CampaignPredecessorReferenceID/> <Note actionCode="01"> <ObjectNodeSenderTechnicalID/> <ContentText>A2X Example for Lead note</ContentText> </Note> <Item actionCode="01"> <ObjectNodeSenderTechnicalID/> <UUID/> <ID>10</ID> <Description languageCode="EN">A2X Example for Lead item</Description> <QuantityValue unitCode="ea">2</QuantityValue> <ProductUUID/> <MaterialInternalID>10000335</MaterialInternalID> <ServiceProductInternalID/> <ProductCategoryInternalID/> </Item> <MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty> <SalesResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </SalesResponsibleEmployeeParty> <ProspectParty partyContactPartyListCompleteTransmissionIndicator="true" actionCode="04"> <BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID> <ContactParty actionCode="04"> <ObjectNodeSenderTechnicalID/> <BusinessPartnerInternalID>MCP9785</BusinessPartnerInternalID> <MainIndicator>true</MainIndicator> </ContactParty> </ProspectParty> </Lead> </n0:LeadMaintainBundleReq_sync>
Example to update a lead:
<n0:LeadMaintainBundleReq_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID/> <UUID/> <ReferenceID/> <ReferenceUUID/> </BasicMessageHeader> <Lead actionCode="02" itemListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID/> <ChangeStateID/> <ID>240</ID> <Name languageCode="EN">A2X Test Lead Ayan</Name> <StartDate>2012-11-26</StartDate> <EndDate>2013-12-30</EndDate> <QualificationLevelCode>02</QualificationLevelCode> <GroupCode>0023</GroupCode> <OriginTypeCode>001</OriginTypeCode> <MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty> <SalesResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </SalesResponsibleEmployeeParty> <ProspectParty> <BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID> </ProspectParty> </Lead> </n0:LeadMaintainBundleReq_sync>
Example to delete a lead:
Show full documentation
Show full documentation
<n0:LeadMaintainBundleReq_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID></ID>
</BasicMessageHeader>
<Lead actionCode="03" itemListCompleteTransmissionIndicator="true">
<ObjectNodeSenderTechnicalID/>
<ChangeStateID/>
<ID>503</ID>
</Lead>
</n0:LeadMaintainBundleReq_sync>
| Description | Maintain leads |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Released |
To create, update, or delete leads.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a lead node element that contains the data to be created or updated. The detailed structure of the node will be explained in the following sub-chapters. The node can occur multiple times in the request message – this means that multiple leads can be created and updated through a single web service request.
The response message type of the operation MaintainBundle contains log items, processing information and a lead-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as ID and UUID.
The Lead node element contains all general lead information such as ID, UUID, name, qualification level code and other data.
The data for this node is related to general data on the Lead UI.
The UUID is a unique identifier of the lead. It will be generated by the web service.
The ID is a unique identifier of the lead. It is generated automatically by the system.
The name describes a lead as it will be shown in the UI.
The QualificationLevelCode specifies a classification of the potential interest of a customer:
| Qualification level code | Description |
|---|---|
| 01 | Cold |
| 02 | Warm |
| 03 | Hot |
If a QualificationLevelCode is set, the LifeCycleStatusCode will automatically set to Qualified in backend.
If a QualificationLevelCode is not specified by the customer on creation or will be removed by the customer on update, the LifeCycleStatusCode will be set back to Open as long as the lead has not reached the status Handed Over, Accepted or Declined. Otherwise removing the QualificationLevelCode will lead to an error.
The attribute shows the start date of a lead. The date is the specification of an exact day in the Gregorian calendar.
If not specified by the consumer, a default value is set to the current date.
Example:
<StartDate>2012-05-25</StartDate>
The attribute shows the end date of a lead. The date is the specification of an exact day in the Gregorian calendar.
If not specified by the consumer, a default value is set according to the entry in the business configuration (default 30 days after start date).
Example:
<EndDate>2002-04-19</EndDate>
The attribute LifeCycleStatusCode indicates the status of a lead.
| LifeCycleStatusCode | Description |
|---|---|
| 1 | Open |
| 2 | Qualified |
| 3 | Handed Over (if 'Lead Processing - With Lead Transfer' is scoped) |
| 4 | Accepted |
| 5 | Declined |
| 6 | Converted |
If not specified by the consumer, a default is set by the web service according to the specified lead attributes:
If the attribute QualificationLevelCode is specified, the web service sets the LifeCycleCode to Qualified.
The status Handed Over can be set only if the 'Lead Processing - With Lead Transfer' is scoped. Otherwise the web service would fail with an error. If the status Handed Over shall be set for an existing lead this lead must have a QualificationLevelCode, a valid SalesResponsibleEmployeeParty and a valid ProspectParty. Otherwise the web service would fail with an error message.
The status Accepted can be set only if lead has a valid QualificationLevelCode, a valid SalesResponsibleEmployeeParty and a valid ProspectParty. If a new lead shall be created with status Accept these attributes must be given. If an existing lead shall be updated with status Accepted the lead must have already these attributes filled or the must be given into the message of the web service.
It is not possible to set the status Accepted or Declined and to be set the ResultReasonCode in one call of the web service. It would fail with an error that the ResultReasonCode is not changeable.
The web service must be called two times:
1. set the status Accepted or Declined
2. set the ResultReasonCode
The attribute GroupCode specifies the assignment of a lead to a specific group.
The GroupCode can contain the following values, depending on business configuration settings:
| GroupCode | Description |
|---|---|
| 0023 | Prospect for Product Sales |
| 0024 | Prospect for Service |
| 0025 | Prospect for Training |
| 0026 | Prospect for Consulting |
If not specified by the consumer, a default is set by the web service.
The attribute OriginTypeCode indicates the origin of a lead.
The OriginTypeCode can contain the following values, depending on business configuration settings:
| OriginTypeCode | Description |
|---|---|
| 001 | Trade Fair |
| 002 | External Partner |
| 003 | Campaign |
| 004 | Telephone Inquiry |
| 005 | Roadshow |
If not specified by the consumer, a default is set by the web service.
The attribute ResultReasonCode specifies the reason of a current lead result.
The ResultReasonCode can contain the following values, depending on business configuration settings:
| ResultReasonCode | Description |
|---|---|
| 002 | Lost Due to Product |
| 003 | Lost Due to Price |
| 004 | Lost Due to Service |
| 005 | Won Due to Product |
| 006 | Won Due to Price |
| 007 | Won Due to Service |
| 008 | Accepted Because of High Revenue Potential |
| 009 | Accepted Because of High Chance of Success |
| 010 | Accepted for Strategic Reasons |
| 011 | Rejected Because of Low Revenue Potential |
| 012 | Rejected Because of Low Chance of Success |
| 013 | Rejected Because of Wrong Target Segment |
If not specified by the consumer, a default is set by the web service.
See also the explanations for the LifeCycleStatusCode
By the CampaignPredecessorReferenceID the lead can be referenced to a campaign that is the direct predecessor of the lead.
This node element allows to add text to a lead.
For every update (using action code 02 or 04) the existing entry will be replaced by the new text.
Example for creating a new note entry:
<Note actionCode="01"> <ContentText>A2X Example for Lead note</ContentText> </Note>
The AttachmentFolder node element can be used to add and remove lead attachments.
Data for this node can be found on the lead UI as attachments. On the user interface, files and links can be created. In the web service request, links and files are differentiated through the CategoryCode:
| Category code | Description |
|---|---|
| 2 | Document |
| 3 | Link |
The different types of attachments are differentiated by the TypeCode:
| Type code | Description |
|---|---|
| 10001 | Standard Attachment |
To create link attachments, document elements must be as follows:
<AttachmentFolder ActionCode="04"> <Document ActionCode="04"> <VisibleIndicator>true</VisibleIndicator> <CategoryCode>3</CategoryCode> <TypeCode>10001</TypeCode> <Name>SAP AG Link</Name> <ExternalLinkWebURI>http://www.sap.com</ExternalLinkWebURI> <AlternativeName>SAP AG URL</AlternativeName> <Description languageCode="EN">A hyperlink to SAP AG</Description> </Document> </AttachmentFolder>
To create file attachments, document elements must be as follows:
| Element | Value |
|---|---|
| VisibleIndicator | true |
| CategoryCode | 2 |
| TypeCode | <none> |
| Name | <Document Title> |
| AlternativeName | <Document Title> |
| Description | <Comment> |
The item node contains all information regarding products, product categories or just descriptions, the prospect of the lead is interested in.
Each item is defined by a combination of ID, Description, QuantityValue, a MaterialID, a ServiceProductID, a ProductStandardID and a ProductCategoryInternalID.
Example for creating a new item:
<Item actionCode="01"> <ID>10</ID> <Description languageCode="EN">A2X Example for Lead item</Description> <QuantityValue unitCode="ea">2</QuantityValue> <MaterialInternalID>10000335</MaterialInternalID> </Item>
When updating an item that already contains a MaterialID, a ServiceProductID or a ProductStandardID, it is important, not to provide the ProductCategoryInternalID, as it is not changeable anymore if the item already has a product ID.
If the ProductCategoryInternalID is provided while update and it differs from the original maintained ProductCategoryInternalID, an error message in the response will be provided that the product category ID cannot be changed as the field is read only.
The node element contains the identification for the party that is responsible on marketing side of the lead.
Only the business partner internal ID can be provided.
Example:
<MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty>
The node element contains the identification for the party that is responsible on sales side for the lead.
Only the business partner internal ID can be provided.
Example:
<MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty>
The node element contains the identification for the prospect party, the contacts of the prospect party and the main indicator flag.
Example:
<ProspectParty partyContactPartyListCompleteTransmissionIndicator="true" actionCode="01"> <BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID> <ContactParty actionCode="01"> <BusinessPartnerInternalID>MCP9785</BusinessPartnerInternalID> <MainIndicator>true</MainIndicator> </ContactParty> <ContactParty actionCode="01"> <BusinessPartnerInternalID>MCPC9785</BusinessPartnerInternalID> </ContactParty>
Update SalesResponsibleEmployeeParty and CampaignPredecessorReferenceID:
<n0:LeadMaintainBundleReq_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00000000000102dcade9bcb0ab000c99</ID> </BasicMessageHeader> <Lead actionCode="02"> <ChangeStateID>20141031052319.0814140</ChangeStateID> <UUID>00163e07-3d62-1ed4-9897-af341f2a21fd</UUID> <SalesResponsibleEmployeeParty> <BusinessPartnerInternalID>MC3788</BusinessPartnerInternalID> </SalesResponsibleEmployeeParty> <CampaignPredecessorReferenceID>81</CampaignPredecessorReferenceID> </Lead> </n0:LeadMaintainBundleReq_sync>
| Description | Check leads |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Released |
To check if leads can be created, updated, or deleted without errors.
The web service request - and response message types for the CheckMaintainBundle operation are the same as those of the Maintain Bundle operation. The explanations given can therefore also be applied to the CheckMaintainBundle operation.