Imports

Bulk contact import

The Whispir API exposes the bulk contact import functionality as a two-stage process:

  1. Submit contact data within a CSV, JSON, XML payload using the /resource endpoint. This returns a resource ID.
  2. Create a new import resource by submitting a POST to the /imports endpoint, referencing the resource ID created in Step 1.

These two stages are further explained below.

 

Create a resource specifying the contact information

Applications can upload a valid CSV, XML or JSON resource containing the contact information that will be imported into the Whispir platform. Whispir will return the resource ID, which can be used to import or update contacts within a workspace through the /imports endpoint as described below.

Request structure

Firstly, the application needs to upload a resource. See Creating a resource

The resource that needs to be provided for importing contacts should be in one of the following formats:

  • XML
  • JSON
  • CSV

Once the resource has been imported with the appropriate mime type, the application can reference this resource within the import request.

Import a resource using the /imports endpoint

After receiving a valid resource ID, applications can make a request to the /imports endpoint within a workspace and reference the appropriate resource ID. Whispir will then create an import process that will import the specified data into the workspace.

Once the application has an appropriate resource ID to use within the /imports endpoint, the following request can be used to begin the import process.

  • JSON
  • XML

Sample data file

The following data file could be produced or created from data in your internal system that needs to be imported into Whispir:

{{codeStart}}

{

"contacts" : [{

"firstName": "John",

"lastName": "Smith",

"workEmailAddress1": "john.smith@testcompany.com",

"workMobilePhone1": "61423456789",

"workCountry": "Australia",

"timezone": "+10"

},{

"firstName": "Jane",

"lastName": "Smith",

"workEmailAddress1": "jane.smith@testcompany.com",

"workMobilePhone1": "61498765432",

"workCountry": "Australia",

"timezone": "+10"

}]

}

{{codeEnd}}

The data could alternatively be provided in CSV format:

firstName,lastName,workEmailAddress1,workMobilePhone1,workCountry,timezone
John,Smith,john.smith@testcompany.com,61423456789,Australia,+10
Jane,Smith,jane.smith@testcompany,com,61498765432,Australia,+10

You can then use the /resources endpoint to upload this information as a Resource in Whispir.

 

Import

Doing an import by mapping the respective data columns to contact fields:

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/imports?apikey=<your_api_key>

Authorization: Basic asdf98nf89asdvasd2r398h8sdf

x-api-key: your_api_key

Accept: application/vnd.whispir.import-v1+json

{

"resourceId": "4FBBC384BCE3DAABFE3",

"importType" : "contact",

"importOptions": {

"fieldMapping" : {

"firstName": "firstName",

"lastName": "lastName",

"workMobilePhone1": "workEmailAddress1",

"workCountry": "workCountry",

"timezone": "timezone"

},

"importMode" : "replace"

}

}

{{codeEnd}}

If the request was successful, the response contains the information for the calling application to retrieve information about the import process that has been started.

...
HTTP 1.1 202 Accepted
...

Note: Import processes take place asynchronously. Any contacts will be created once the import process starts, and users will be able to use imported contacts as soon as each one is completed.

High-level request elements

Field

Details

resourceId

Description

  • The resource identifier returned from the POST to /resources. The resource referred to must be a valid CSV, XML or JSON file.

Required

  • Both Tag and Value.

Sample value

  • 4FBBC384BCE3DAABFE3.

importType

Description

This defines the resource that will be created through this import process.

Required

  • Both Tag and Value.

Available values

  • Contact is the only supported importType at this stage.

importOptions

Description

The list of options that are passed to the import engine.

Required

  • Both Tag and Value.

Available values

  • fieldMapping
  • importMode

importMode

Description

The type of contact import that is occurring.

Required

  • Both Tag and Value.

One of three options available:

  • replace
  • duplicate
  • ignore

fieldMapping

Description

  • Mapping the data column in your resource file to the contact field value.

Required

  • Both Tag and Value.

The following are the mandatory fields to be present and also to be mapped from the resource file:

  • firstName
  • lastName
  • workMobilePhone1
  • workCountry
  • timezone

The fieldMapping section is used to map field/value pairs within a resource to the field/value pairs within a Whispir contact profile.

  • fieldMapping elements must use fields that exist within the resource payload. Any incorrect resource field will return a blank value.
  • fieldMapping elements must be valid Whispir Contact fields; that is, ‘firstName’. The complete list of contact fields is defined in Creating new contacts
  • fieldMapping can include custom contact fields previously set up within your organisation’s Contact profile.
  • The minimum requirement must be fulfilled for a contact to be created. This includes firstName, lastName, and one of personalEmailAddress1, workEmailAddress1, workMobilePhone1, personalMobilePhone1, workCountry and timezone.

firstName

Description

  • First name of the contact. The value is used to map the field within the resource.

Required

  • Both Tag and Value.

Sample value

  • name

lastName

Description

  • Last name of the contact. The value is used to map the field within the resource.

Required

  • Both Tag and Value.

Sample value

  • surname

workMobilePhone1

Description

The mobile phone number of the contact. The value is used to map the field within the newly created resource.

Required

  • Both Tag and Value

Sample value

  • Mobile

workCountry

Description

The country field of the contact. The value is used to map to the field within the newly created contact.

Required

  • Both Tag and Value.

Sample value

  • workCountry

timezone

Description

The time.zone field of the contact. The value is used to map to the time zone field within the newly created contact.

Required

  • Both Tag and Value.

Sample value

  • timezone