Criteria for adding and editing contact information

The criteria object specifies what contact information to add or edit and for which database. The information can be either a contact or a contact group. For a contact, the actual contact details are contained in one or more keys, with each key representing a specific piece of information. If no database is specified, the information is added to the default database. If the default database does not exist, it is created.

Use the Add method as follows:

  • To add a new contact or contact group, do not set its id property.

  • To edit an existing contact or contact group, retrieve it using GetList, edit the information, and then send it to Add with the id property unchanged. This overwrites the old entry.

The criteria object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional.

Note: All string values in the object are Unicode.

Table: Criteria object properties

Property

Description

Type

Value

criteria.Type

Specifies the type of contact information to add or edit.

string

Possible values:

  • "Contact"

  • "Group"

criteria.Data

Specifies the contact information to add or edit.

If Type is "Contact", this property takes one or more <key> properties. The number of keys depends on how much information is added about the contact.

object

Object with the properties specified below

[criteria.Data.DBUri]

Specifies the contacts database where the information is added or edited.

If this property is not specified, the default database is used.

string

 

[criteria.Data.id]

Specifies the unique identifier of the contact or contact group to add or edit.

Note:

  • If you want to add a new entry to the database, do not specify this property.

  • If you want to edit (replace) an existing entry in the database, specify the ID of that entry.

string

 

criteria.Data.<key>

Each key represents one piece of information about the contact, such as first name, last name, home phone number, or email address. At least one key must be specified for the contact.

For example:

  • Data.FirstName

  • Data.LastName

  • Data.LandPhoneHome

  • Data.EmailHome

For a list of supported keys, see section Supported contact keys.

Note: This property is valid only if Type is "Contact".

object

Object with the properties specified below

criteria.Data.<key>.Label

Specifies a label that describes the key value.

string

 

criteria.Data.<key>.Value

Specifies the value for the key.

If this is an empty string, the property is not included.

string

 

[criteria.Data.<key>.Next]

This is an object that specifies an additional value for the key. This object contains the same properties as a key: Label, Value, and optionally Next, where Next is an object identical to this one, specifying yet another value for the same key.

There is no limit to how many nested values a key can contain.

For example, an EmailHome key with two values (two email addresses) has the following property structure:

  • Data.EmailHome

  • Data.EmailHome.Label

  • Data.EmailHome.Value

  • Data.EmailHome.Next

  • Data.EmailHome.Next.Label

  • Data.EmailHome.Next.Value

The first email address is contained in Data.EmailHome.Value and the second one in Data.EmailHome.Next.Value.

object

Object with the same properties as Data.<key>

criteria.Data.GroupLabel

Specifies the name of the contact group.

If the database does not support group labels, this property is ignored. SIM databases, for example, do not support group labels.

Note: This property is valid only if Type is "Group".

string