Import API

Use the Import API to import customer contact information for an outbound campaign. You can import up to 10,000 records in one create request.

Note

  • You can queue up to 30 requests. If the queue has 30 requests and you submit another request, the response is HTTP 503 Service Unavailable with the boundary error condition "Request processing queue is at capacity."

    If you receive this error, wait until a few requests are processed and submit the next request when the queue has less than 30 requests.

    If a particular integration is doing multiple small inserts per second for a campaign and this error appears, it is more efficient to batch up the records into larger imports.

  • Avoid performing a bulk job transaction during a maintainence window.

  • Only administrators can use the Import API. For this reason, Import API user roles are authorized with the Active Directory, and the local cache is updated every 30 minutes (the interval cannot be modified).

URL

https://<server>/unifiedconfig/config/campaign/<id>/import
Note

You must specify the ID for a campaign that was created using the Outbound Campaign API. If you specify the ID for a campaign created using the Outbound Option Campaign tool, the request returns CceDBDataNotFoundException.

Operations

  • create: Imports customer contacts for a specific campaign.

  • delete: Deletes the imported contacts for a specific campaign.

    Note

    The delete operation deletes all imported contacts for the campaign. You cannot delete an individual record.

  • get (template): Returns a sample CSV template for contacts, which is provided by the API, using the URL https://<server>/unifiedconfig/config/campaign/import/template. The response contains the CSV template as a file attachment.

  • get: Retrieves the details of a single import record using the URL https://<server>/unifiedconfig/config/campaign/<campaignId>/import/<id>. The <id> is the ID of the imported contact.

  • get (csv file): Returns a CSV file for the contacts of the campaign, which is provided by the API, using the URL https://<server>/unifiedconfig/config/campaign/<campaignId>/import with header as "Accept" and value as "text/csv". The response contains the Contacts.csv as a file attachment.

  • get (csv file): Returns a CSV file for the contacts of the campaign, which is provided by the API, using the URL https://<server>/unifiedconfig/config/campaign/<campaignId>/import/csv. The response contains the Contacts.csv as a file attachment. In this operation, you do not need to send "Accept" header.

  • list: Retrieves a list of all imported contacts for the campaign.

    • Query parameters

      • Summary list: See list.

Parameters

Response Parameters for get:

  • accountNumber: The customer's account number.

  • callsMade: The number of calls made.

  • callStatus: The call status of the last call placed for this record. Possible values include the following:

    • active (A)

    • callbackRequested (B)

    • closed (C)

    • agentRejected (J)

    • maxAttemptsReached (M)

    • pending (P)

    • retry (R)

    • personalCallbackRequested (S)

    • unknown (U)

    For more information about these values, see the CallStatusZone Values section of the Outbound Option Guide for Unified Contact Center Enterprise at https://www.cisco.com/c/en/us/support/customer-collaboration/unified-contact-center-enterprise/products-user-guide-list.html.

  • callResultOverall: The call result from the last call placed for this record.

  • firstName: The customer's first name.

  • lastName: The customer's last name.

  • importDate: The date and time that the record was imported.

  • phone01 through phone10: A collection of information about the customer's phones. Each phone contains the following parameters:

    • number: The phone number.

    • callResult: The call result from the last call placed for this phone number.

      For more information about possible callResult values, see the CallResult Codes and Values section of the Outbound Option Guide for Unified Contact Center Enterprise at https://www.cisco.com/c/en/us/support/customer-collaboration/unified-contact-center-enterprise/products-user-guide-list.html.

    • dstObserved: Whether DST is observed for this phone's location. True or false.

    • gmtOffset: The number of minutes that the customer's time zone is offset from GMT. When you create import records, you can optionally provide a TimeZoneBias. The TimeZoneBias parameter represents the way information about time zones is stored in the Windows registry. You can use the following formula to convert TimeZoneBias to gmtOffset:

      Code Snippet
      Copy
if timeZoneBias is postive:
    gmtOffset = 1440 - timeZoneBias (where 1440 is the number of minutes in 24 hours)
else if timeZoneBias is negative:
    gmtOffset = -1 * timeZoneBias
else if timeZoneBias is 0
    gmtOffset = timeZoneBias

Parameters for create:

  • fileContent: Required. Comma-separated or pipe-separated list of data embedded within a CDATA section.

  • overwriteData: True or false. If set to true, the existing import data in the database is overwritten by the new import data. If set to false, the new import data is appended to the existing data. Default is false.

    Note

    You cannot modify or remove existing fields or append a new field to existing data.

  • delimiter: Comma (,) or pipe (|). Default is comma (,).

  • header fields: The following header fields are allowed:

    • AccountNumber: Can contain any characters, including internationalized characters, except the delimiter specified in the input XML. Maximum length of 30 bytes.

    • FirstName: Can contain any characters, including internationalized characters, except the delimiter specified in the input XML. Maximum length of 50 characters.

    • LastName: Can contain any characters, including internationalized characters, except the delimiter specified in the input XML. Maximum length of 50 characters.

    • Phone01 through Phone10: Can contain digits 0-9, pound sign (#), and asterisk (*). Maximum length of 20 bytes. At least one Phone field is required.

    • TimeZoneBias: Specifies the offset of the customer's time zone from UTC in minutes. Integer. Range is from –780 to 720 (–13 to 12 hours from UTC).

    • DstObserved: Specifies whether DST is observed for the customer's location. True or false. Default is false.

      Note

      If the TimeZoneBias parameter is provided but the DstObserved parameter is not, DstObserved is set to false. If the DstObserved parameter is provided but not TimeZoneBias, a validation error is returned.

      If TimeZoneBias is not provided, time zone and Daylight Saving Time information is assigned by matching phone numbers to region prefix strings. If a phone number for a contact does not match a configured region prefix, the default time zone for the campaign is used.

      If a customer record contains multiple phone numbers, the value for TimeZoneBias and DstObserved are applied to all of that customer's phone numbers.

      You can use the Time Zone API to look up the values for TimeZoneBias and DstObserved for the target time zone. For more information, see Time Zone API.

Search and Sort

The following table shows the parameters that are searched and the parameters that are sortable.

Search parameters Sort parameters

  • accountNumber

  • firstName

  • lastName

  • accountNumber (default)

  • firstName

  • lastName

See Search and Sort.

Example Get Response

Code Snippet
Copy
<importContact>
    <refURL>/unifiedconfig/config/campaign/5000/import/1</refURL>
    <accountNumber>4019</accountNumber>
    <callsMade>1</callsMade>
    <callStatus>pending</callStatus>
    <callResultOverall>0</callResultOverall>
    <firstName>Mir</firstName>
    <lastName>Ali</lastName>
    <importDate>2016-03-28T01:09:40</importDate>
    <phone01>        
        <callResult>0</callResult>
        <dstObserved>true</dstObserved>
        <gmtOffset>720</gmtOffset>
        <number>9789360001</number>
    </phone01>
    <phone02>      
        <callResult>0</callResult>
        <dstObserved>true</dstObserved>
        <gmtOffset>720</gmtOffset>
        <number>9789360002</number>
    </phone02>
    <phone03>...</phone03>
    <phone04>...</phone04>
    <phone05>...</phone05>
    <phone06>...</phone06>
    <phone07>...</phone07>
    <phone08>...</phone08>
    <phone09>...</phone09>
    <phone10>
        <callResult>0</callResult>
        <dstObserved>true</dstObserved>
        <gmtOffset>330</gmtOffset>
        <number>9789360010</number>
    </phone10>
</importContact>

Example Create Request

Code Snippet
Copy
<import>
    <fileContent>
        <![CDATA[
        AccountNumber,FirstName,LastName,Phone01,Phone02,TimeZoneBias,DstObserved
        6782,Henry,Martin,2225554444,2225556262,720,false
        3456,Michele,Smith,2225559999,2225551234,540,true
        4569,Walker,Evans,2225552000,2225557890,-600,true
        ]]> 
    </fileContent>
    <delimiter>,</delimiter>
</import>