API Quick Start Guide - Bulk Upload

This document is used to transfer larger (> 1,000) subscriber lists to Informz for processing. Processing options are:

  1. AddOrUpdateSubscribers (adds and updates the list)
  2. ReplaceAllSubscribers (swaps out all the subscribers in the list)
  3. RemoveSubscribers (removes subcribers from the list)

The BulkUpload is asynchronous. This means that there is a delay of a few minutes between when the call is received and acknowledged, and when it is full uploaded. Upon the completion of the upload process, an email notification is sent to any email addresses listed in the StatusEmailRecipients node.

The <UploadID>###</UploadID> returned in the response gives the upload ID and can be used to query the success/failure of that upload.

Request

<ActionRequest xmlns="http://partner.informz.net/aapi/2009/08/">
  <Brand id="9999">Test Brand</Brand>
  <User>testuser</User>
  <Password>password</Password>
  <Actions>
    <BulkUpload>
      <UploadDetails>
        <InterestDetails>
          <InterestNames>
            <InterestName>Sample Interest 1</InterestName>
            <InterestName>Sample Interest 2</InterestName>
            <InterestName>Sample Interest 3</InterestName>
          </InterestNames>
          <InterestAction>AddOrUpdateSubscribers</InterestAction>
        </InterestDetails>
        <StatusEmailRecipients>
          <Email>johndoe@example.com</Email>
        </StatusEmailRecipients>
        <ColumnDelimiter>,</ColumnDelimiter>
        <HasFieldsEnclosedInQuotes>1</HasFieldsEnclosedInQuotes>
        <RemovePersonalInfoIfBlank>0</RemovePersonalInfoIfBlank>      </UploadDetails>
      <FieldDefinitions>
        <FieldDefinition>
          <Name>Email</Name>
          <DataType>string</DataType>
          <ColumnIndex>1</ColumnIndex>
          <FieldType>Email</FieldType>
        </FieldDefinition>
        <FieldDefinition>
          <Name>ID</Name>
          <DataType>integer</DataType>
          <ColumnIndex>2</ColumnIndex>
          <FieldType>ID</FieldType>
        </FieldDefinition>
        <FieldDefinition>    
               <Name>FirstName</Name>    
               <DataType>String</DataType>    
               <ColumnIndex>3</ColumnIndex>   
        </FieldDefinition>
      </FieldDefinitions>
      <Data>
    <![CDATA[
      joe@example.com, 1374, Joe
      sally@example.com, 5463, Sally
      tom@example.com, 294, Tom
     alice@example.com, 99375, Alice
    ]]>
      </Data>
    </BulkUpload>
  </Actions>
</ActionRequest>

Details

Node Type Req'd? Unique? Description
<UploadDetails> String True NA Details of the file format used in the BulkUpload
<UploadDetails>     <InterestDetails>          <InterestNames>               <InterestName> String True The interest(s) that all of these subscribers will be assigned to or removed from depending upon the UploadAction used.You can use multiple InterestNames
<UploadDetails>     <InterestDetails><InterestAction> String True NA Choices:  AddOrUpdateSubscribers ReplaceAllSubscribers RemoveSubscribers
<UploadDetails>   <StatusEmailRecipients> String True True The email(s) addresses to send the status message regarding the bulk upload once it is complete. Use <Email/> if you wish to leave it blank
<UploadDetails>   <ColumnDelimiter> String True NA The column delimiter character used in the file
<UploadDetails>   <HasFieldsEnclosedInQuotes> Bit True NA Are values enclosed in quotation marks? This can be applied to any or all incoming columns. Quotations are not required even if element is set to True.
<UploadDetails> <RemovePersonalInfoIfBlank> Bit False NA Should existing personalization values inside Informz be blanked out for personalization values included in this upload. Assumes False or NO will NOT
<UploadDetails>   <ColumnIndex> Integer False True The column where the unique record identifier from the partner application resides.
<FieldDefinitions> NA True NA Details of each field in the incoming file. Not all columns in the incoming file have to be used by Informz. Columns are ignored if they are not identified in the FieldDefinitions.
<FieldDefinition>
<Name>
String True True The corresponding personalization field in Informz. If field does not exist it is created. The name ‘Email’ is reserved to indicate the column that contains the email address. Only one column can be defined as ‘Email’.
<FieldDefinition>   <DataType> String True False Choices: String, Integer, Float, Date
<FieldDefinition>   <DefaultValue> String True False A default value to use if the column is blank
<FieldDefinition>   <ColumnIndex> Integer True False Which column contains the defined value. First column is column 1.
<FieldDefinition>   <FieldType> String True NA If left blank, the default value is PersonalInfo, other possible values are Email, ID, Source, and NewsFormat

Notes

  1. When using ReplaceAll, if no replacement subscribers are included, all subscribers are removed from the interest.
  2. It is presumed that there will not be a header row in the file.
  3. Data in the <Data> tag needs to be "XML-safe." This can be done either by using CDATA sections as shown in the example above or by HTML encoding the text.
  4. Leading and trailing blanks are trimmed from the field.
  5. Field definitions are ignored when using the RemoveSubscribers Interest Action.
  6. The only fields updated are those defined in FieldDefinitions.
  7. If the ColumnDelimiter tag isn't included, the delimiter defaults to a Tab.
  8. Incoming email addresses are converted to all lowercase.
  9. To explicitly include a Tab column delimiter use the format below:
<ColumnDelimiter><![CDATA[    ]]></ColumnDelimiter>

Response

The response to a BulkUpload indicates the success or failure of the action.

<?xml version="1.0" encoding="utf-16"?>
<ActionResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns="http://partner.informz.net/aapi/2009/08/">
  <Brand id="9999">Test Brand</Brand>
  <User>testuser</User>
  <Responses>
    <BulkUpload>
      <UploadID>1426</UploadID>
      <ActionStatus>
        <Status>success</Status>
        <Message xsi:type="xsd:string">Data submitted.</Message>
      </ActionStatus>
    </BulkUpload>
  </Responses>
</ActionResponse>