Overview

Skill Level: Beginner

Step-by-step

  1. Syntax of the request and response XML for GetProgramsByContact

    The GetProgramsByContact call is available in Postman.

    Either CONTACT_ID or VISITOR_KEY must be passed to the method to get a valid response. If both are provided, the CONTACT_ID is used to look up the Contact. CONTACT_ID is the same as RECIPIENT_ID in meaning only and information that is used and returned for CONTACT_ID is the same information that is used and returned for RECIPIENT_ID in any other API call. Standard permissions are applied to this API so that only those programs are returned that the authenticated user has access to see.

       Note:

    • If end track is not used in the program, the element will not have a date value
    • If the contact is currently active in the program, the element will not have a date value
    Operation <GetProgramsByContact>        
    Elements LIST_ID Required The source database or query to which the returned Programs are tied    
      INCLUDE_ACTIVE Required Specify to return the Programs that are in Running, Scheduled and Completed state. Valid values are:

    • True
    • False
       
      INCLUDE_INACTIVE Required Specify to return the Programs that are only in inactive state. Valid values are:

    • True
    • False
       
      CONTACT_ID (Recipient_ID) Optional The Contact Id (Recipient_ID) of the Contact in the Watson Campaign Automation database. Pass this parameter to get all programs associated with a specific contact. Note: Either CONTACT_ID (Recipient_ID) or VISITOR_KEY must be passed. If both passed, CONTACT_ID (Recipient_ID) takes precedence.    
      VISITOR_KEY Optional The web tracking visitor key. Pass this parameter to get all programs associated with a specific visitor. Note: Either CONTACT_ID (Recipient_ID) or VISITOR_KEY must be passed. If both passed, CONTACT_ID (Recipient_ID) takes precedence.    
      INCLUDE_HISTORY Optional By default, it returns the information for the contact that is currently active in that program. Include this element if you want to receive the history for contacts been through the program multiple times. Accepted values are:

    • True
    • False

    If this element is not included, then False is assumed. Note: There will be a separate response for each trip through the program.

       
      CREATED_DATE_RANGE Optional  Specify to return Programs that are created within specific date range. This date is based on Program create date.    
      ChildElement  BEGIN_DATE  Specify start of the date range in the format “mm/dd/yyyy”    
        END_DATE  Specify end of the date range in the format “mm/dd/yyyy”     
      APPROVED_FOR_SALES Optional Specify to return programs that are only Approved for Sales. Accepted values are:

    • True
    • False

    If this element is not included, then False is assumed. Note: These are the programs that are available through contact insight.

       
      INCLUDE_TAGS  Optional  Specify to return programs associated to specific tag(s).    
      ChildElement TAG  Specify to return a program associated to a specific tag. Note: This will return any program containing the tag. If you include multiple tags in your API call we will return any program containing at least one of the tags. Multiple tags will be treated as or statements.    
      INCLUDE_TRACK  Optional  If specified, it will return the Program Track information the participant is currently in. Accepted values are:

    • True
    • False

    If this element is not included, then False is assumed.

       
      INCLUDE_STEP Optional If specified, it will return the Program Step information the participant is currently in. Accepted values are:

    • True
    • False

    If this element is not included, then False is assumed.

       
    Example  <Envelope>
          <Body>
               <GetProgramsByContact>
                     <INCLUDE_ACTIVE>True</INCLUDE_ACTIVE>
                     <INCLUDE_INACTIVE>False</INCLUDE_INACTIVE>
                     <VISITOR_KEY>125632414</VISITOR_KEY>
                     <INCLUDE_HISTORY/>
                          <APPROVED_FOR_SALES/>
                          <INCLUDE_TAGS>
                               <TAG>January Campaign</TAG>
                               <TAG>Feb Campaign</TAG>
                          </INCLUDE_TAGS>
                          <INCLUDE_TRACK/>
                          <INCLUDE_STEP/>
                </GetProgramsByContact>
           </Body>
    </Envelope>
           
    Response  <RESULT>         
    Elements SUCCESS True if successful       
      PROGRAMS XML nodes defining each program       
      ChildElement  PROGRAM       
          PROGRAM_ID  Returns the unique ID of the Program   
          STATE  Returns the status of the Program. Current Possible values:

    • Running
    • Scheduled
    • Completed
    • Inactive

    Note: New values could be added in the future

     
          NOT_ACTIVE This element is included in the response IF the contact is not currently active in the program  
          ENTERED_DATE This element represents the date that the contact entered the program in the format “mm/dd/yyyy”.  
          EXITED_DATE  This element represents the date that the contact exited the program in the format “mm/dd/yyyy”.  
          TRACK  XML node defining the Track of a Program  
          Attribute  Type Types of Tracks

    • start – Defines Start Track
    • end – Defines End Track
    • other – Defines other than Start or End Track
          ChildElement  NAME Name of the track 
            ID  ID of the track 
          STEP XML node defining the Step of a Program   
          Attribute Type  Type of a step

    • Email
    • Direct mail
    • Telesales

    Note: New values could be added in the future

          ChildElement  NAME Name of the step
            ID ID of the step 
    Element <Envelope>
         <Body>
               <RESULT>
                    <SUCCESS>TRUE</SUCCESS>
                    <PROGRAMS>
                         <PROGRAM>
                              <PROGRAM_ID>5435</PROGRAM_ID>
                              <STATE>Running</STATE>
                              <ENTERED_DATE>01/01/2012</ENTERED_DATE>
                              <EXITED_DATE/>
                              <TRACKtype=”start”>
                                    <NAME>
                                          <![CDATA[Initialize]]>
                                    </NAME>
                                     <ID>555</ID>
                              </TRACK>
                              <STEP type=”email”>
                                    <NAME>
                                          <![CDATA[Welcome Email]]>
                                    </NAME>
                                    <ID>101</ID>
                              </STEP>
                       </PROGRAM>
                       <PROGRAM>
                             <PROGRAM_ID>5436</PROGRAM_ID>
                             <STATE>Completed</STATE>
                             <NOT_ACTIVE />
                             <ENTERED_DATE>01/01/2012</ENTERED_DATE>
                             <EXITED_DATE>01/31/2012</EXITED_DATE>
                             <TRACKtype=”end”>
                                   <NAME>
                                         <![CDATA[End Track]]>
                                   </NAME>
                                   <ID>557</ID>
                             </TRACK>
                       </PROGRAM>
                       <PROGRAM>
                             <PROGRAM_ID>5437</PROGRAM_ID>
                             <STATE>Running</STATE>
                             <ENTERED_DATE>01/01/2012</ENTERED_DATE>
                             <EXITED_DATE/>
                             <TRACKtype=”other”>
                                   <NAME>
                                         <![CDATA[Third Track]]>
                                   </NAME>
                                   <ID>558</ID>
                               </TRACK>
                               <STEP type=”direct mail”>
                                    <NAME>
                                          <![CDATA[Customer Event]]>
                                    </NAME>
                                    <ID>102</ID>
                               </STEP>
                        </PROGRAM>
                        <PROGRAM>
                             <PROGRAM_ID>5437</PROGRAM_ID>
                             <STATE>Inactive</STATE>
                             <NOT_ACTIVE />
                             <ENTERED_DATE>01/01/2012</ENTERED_DATE>
                             <EXITED_DATE/>
                             <TRACKtype=”other”>
                                   <NAME>
                                         <![CDATA[Track-4]]>
                                   </NAME>
                                   <ID>560</ID>
                              </TRACK>
                              <STEP type=”email”>
                                    <NAME>
                                         <![CDATA[Renewal Email]]>
                                    </NAME>
                                    <ID>107</ID>
                               </STEP>
                        </PROGRAM>
                  </PROGRAMS>
             </RESULT>
        </Body>
    </Envelope>
           
    Error Message Response Example <Envelope>
         <Body>
    List
        </FaultString>
    </Body>undefined</Envelope>undefined<RESULT>
    <SUCCESS>false</SUCCESS>undefined</RESULT>undefined<Fault>
    <Request/>
    <FaultCode/>
    <FaultString>Contact does not exist in the database or Contact     <detail>
              <error>
                  <errorid>133</errorid>
                  <module/>
                  <class>SP.API</class>
                  <method/>
               </error>
         </detail>
    </Fault>
           
               

     

Join The Discussion

Your email address will not be published. Required fields are marked *