Contacts

Advanced options

The Whispir API provides some advanced options for performing search and data-related queries on the contact information. These options can be performed by adding relevant query parameters to the URL.

Deleting a contact from all workspaces

By default, the Whispir API only lets you delete a contact from one workspace at a time. However, due to certain business scenarios, there could be a need to delete all references to a given contact from all workspaces in the company. Usually such references are made when there is a contact mapping rule in place (either automated or via the Contact API).

To accommodate such a case, and also avoid calling DELETE /contacts/{id} repeatedly on all workspaces, the Whispir API allows a ‘Delete All’ functionality for contacts.

Warning! The API call involves passing an action=deleteAll parameter in the URL query params. Once this action is triggered, all the contact references in all workspaces for a given contact{id} are deleted asynchronously. There is no way to stop the process once it's triggered. Use the action only when you're definitely sure you want to delete the contact from all workspaces.

The following types of contact can be deleted:

  • Mapped contacts.
  • Copied contacts.
  • Mapped contacts by contact mapping rules.
  • Mapped contacts via SFTP and contact mapping rules.
  • Mapped contacts of a customised company account.
  • JSON
  • XML

Deleting a contact from all workspaces

The following statement allows users to delete a contact from all mapped/copied workspaces using the API. Note that this process is asynchronous and can't be terminated once triggered.

{{codeStart}}

HTTP 1.1 DELETE https://api.<region>.whispir.com/workspaces/A51D76194DDC09CC/contacts/124F6B2D46A5A268?apikey=<your_api_key>&action=deleteAll

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

{{codeEnd}}


Searching with multiple criteria

The API allows you to search for a contact based on any attribute/data element associated with the contact. This is not limited to just one attribute; multiple attributes can be searched at the same time.

URI request elements as query params

fieldname

String

Specifies the field name of the contact object. The field name could be anything as long as it's a valid contact object.

Example:
http://api..whispir.com/contacts?apikey=&firstName=Sam&lastName=gamjee

sortOrder

String

The order in which you require the results to be returned. Either ‘asc’ or ‘desc’.

sortFields

String

The fields that you require the ordering to be performed on. Multiple fields can be provided, separated by a comma.

Example:
http://api..whispir.com/contacts?apikey=&firstName=Sam&sortFields=lastName,jobTitle


  • JSON
  • XML

Searching with multiple search criteria

The following query parameters allow users to search with more than one search criterion on the contact profile:

{{codeStart}}

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&firstName=Sam&lastname=gamjee

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

{{codeEnd}}


Choosing the data elements

When you request contact information, a simple GET request on the /contact API gives you the basic details of the contact.

To get all the details or fields other than the ones given by default, you have to follow the link and do another GET request. This can be easily skipped by asking the API to give you specific fields and data right away in the first GET /contact call itself.

This can be done by passing the required fields in the URL via the fields parameter. You can also use this in conjunction with the search criteria. For example, you could get the mobile phone number and the email address of all contacts with the first name of ‘Sam’.

  • JSON
  • XML

Choosing specific data elements to return

The following query parameters allow users to return specific data fields from the contact profile:

{{codeStart}}

HTTP 1.1 GET https://api.<region>.whispir.com/contacts?apikey=<your_api_key>&fields=workEmailAddress1,workMobilePhone1&firstname=Sam

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"contacts": [{

"id": "DC09CC30243A51D5",

"workEmailAddress1":"sam@gamjee.com",

"workMobilePhone1":"61423456789"

"messagingoptions": [],

"link": [{

"uri": "https://api.<region>.whispir.com/contacts/DC09CC30243A51D5?apikey=<your_key_api>",

"rel": "self",

"method": "GET"

}]

}

{{codeEnd}}