Contacts

Creating new contacts

To create a new contact you can use the /contacts endpoint. The method is POST.

The following fields are required:

  • firstName
  • lastName
  • workEmailAddress1
  • workMobilePhone1
  • workCountry
  • timezone

High-level request elements

firstName

String

Specifies the first name of the contact.

lastName

String

Specifies the last name of the contact.

title

String

The title of the contact.

status

String

Specifies the validity status of the contact. The status can be either:

  • Active (A)
  • Disabled (D)

companyName

String

Specifies the company name.

jobTitle

String

Specifies the job title at the company.

division

String

Specifies the division in the company to which this contact is associated with.

businessUnit

String

Specifies the business unit in the company that this contact is associated with.

department

String

Specifies the Department in the company that this contact is associated with.

Teams and Roles

String

Specifies the primary and secondary values for each respective variable:

  • teamName1, teamName2
  • role1, role2

Work Place Address

String

Specifies the primary and secondary values for each respective type. Of all these, workEmailAddress1 is the mandatory field:

  • workEmailAddress1, workEmailAddress2
  • workAddress1, workAddress2
  • workSuburb, workState
  • workPostCode, workCountry
  • workPostalAddress1, workPostalAddress2
  • workPostalSuburb, workPostalState
  • workPostalPostCode, workPostalCountry

Work Place Phones

Number

Specifies the primary and secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field:

  • workMobilePhone1, workMobilePhone2
  • workPhoneAreaCode1, workPhone1
  • workPhoneAreaCode2, workPhone2
  • workFaxAreaCode1, workFax1
  • workSetellitePhone, WorkOtherPhone

timezone

String

Specifies the time zone in which the contact lives in. Values are relative to GMT.

Supported values are:

  • Offset from GMT in the format '+/-NN. For example, ‘+10’.
  • Worldwide time zone in the format ‘Country/City’. For example, ‘Australia/Melbourne’.

See the list of worldwide time zones.

Personal Address

String

Specifies the primary and secondary values for each respective type:

  • personalEmailAddress1, personalEmailAddress2
  • personalAddress1, personalAddress2
  • personalSuburb, personalState
  • personalCountry, personalPostCode

Personal Phones

Number

Specifies the primary and secondary values for each respective type:

  • personalPhoneAreaCode1, personalPhone1
  • personalPhoneAreaCode2, personalPhone2
  • personalFaxAreaCode1, personalFax1
  • otherPhoneAreaCode1, otherPhone1
  • otherMobile

Alias Fields

String

  • The other (alias) name and title fields, otherFirstName, otherLastName, otherTitle

Messaging Options

Object

See Format of messaging options.

Other Fields

String

Whispir allows external developers to build a ‘self-subscription’ portal to allow their own contacts to self-register for internal systems. This is only applicable for customers using Whispir’s Contact Portal product.

To support this feature, the following fields are provided:

  • username: Must be unique within the company (users and active contacts).
  • password: Mandatory only in conjunction with the username.
  • secretQuestion: Mandatory (used for password reset).
  • secretAnswer: Mandatory (used for password reset).

Format of messaging options

For each contact, Whispir allows you to define the channels that can be enabled/used for communicating with that contact. Using Messaging options, you can define the preferred/allowed channels and the respective primary, secondary and tertiary contact numbers and/or email addresses to be used. These values are derived from the various personal and work attributes, as specified in the table above.

Available messaging options:

  • SMS
  • email
  • voice

For each messaging option you can specify the following 3 configuration settings:

  • enabled
    • true
    • false
  • primary
    • workMobilePhone1 (Can be any of the valid attributes that has a value in it)
  • secondary
    • optional: workMobilePhone2
  • tertiary
    • optional: personalMobilePhone1
  • JSON
  • XML

Creating new contacts

Users can easily create new contacts by using the following request structure:

{{codeStart}}

POST https://api.<region>.whispir.com/contacts?apikey=[your api key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.contact-v1+json

{

"firstName": "John",

"lastName": "Smith",

"status": "A",

"timezone": "Australia/Melbourne",

"workEmailAddress1": "jsmith@testcompany.com",

"workMobilePhone1": "61423456789",

"workCountry": "Australia",

"messagingoptions": [{

"channel": "sms",

"enabled": "true",

"primary": "WorkMobilePhone1"

},{

"channel": "email",

"enabled": "true",

"primary": "WorkEmailAddress1"

},{

"channel": "voice",

"enabled": "true",

"primary": "WorkMobilePhone1"

}]

}

{{codeEnd}}

The successful response will be a 201 containing the details of the contact created and its associated unique MRI.

{{codeStart}}

{

"id": "CB4558257DD86D09",

"type": "COMPANY",

"firstName": "John",

"lastName": "Smith",

"locations": [

{

"latitude": "0.0",

"longitude": "0.0",

"type": "CurrentLocation"

}

],

"lastModifiedTime": "2019-06-04T17:37:01+10:00",

"status": "A",

"timezone": "+10",

"workEmailAddress1": "jsmith@testcompany.com",

"workMobilePhone1": "61423456789",

"workCountry": "Australia",

"mri": "John_Smith.1143139@Contact.whispir.sg",

"messagingoptions": [

{

"channel": "sms",

"enabled": "true",

"primary": "WorkMobilePhone1"

},

{

"channel": "email",

"enabled": "true",

"primary": "WorkEmailAddress1"

},

{

"channel": "voice",

"enabled": "true",

"primary": "WorkMobilePhone1"

}

],

"link": [

{

"uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",

"rel": "self",

"method": "GET"

},

{

"uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",

"rel": "updateContact",

"method": "PUT",

"type": "application/vnd.whispir.contact-v1+json,application/vnd.whispir.contact-v1+xml"

},

{

"uri": "https://api.<region>.whispir.com/contacts/CB4558257DD86D09?apikey=[your api key]",

"rel": "deleteContact",

"method": "DELETE"

}

]

}

{{codeEnd}}