Module: Virtuous::Client::Contact

Included in:
Virtuous::Client
Defined in:
lib/virtuous/client/contact.rb

Overview

Contact data

{
  contact_type: [String],
  reference_source: [String],
  reference_id: [String],
  name: [String],
  informal_name: [String],
  description: [String],
  website: [String],
  marital_status: [String],
  anniversary_month: [Integer],
  anniversary_day: [Integer],
  anniversary_year: [Integer],
  origin_segment_id: [Integer],
  is_private: [Boolean],
  is_archived: [Boolean],
  contact_addresses: [
    {
      label: [String],
      address1: [String],
      address2: [String],
      city: [String],
      state_code: [String],
      postal: [String],
      country_code: [String],
      is_primary: [Boolean],
      latitude: [Float],
      longitude: [Float]
    }
  ],
  contact_individuals: [
    {
      first_name: [String],
      last_name: [String],
      prefix: [String],
      middle_name: [String],
      suffix: [String],
      birth_month: [Integer],
      birth_day: [Integer],
      birth_year: [Integer],
      approximate_age: [Integer],
      gender: [String],
      passion: [String],
      is_primary: [Boolean],
      is_secondary: [Boolean],
      is_deceased: [Boolean],
      contact_methods: [
        {
          type: [String],
          value: [String],
          is_opted_in: [Boolean],
          is_primary: [Boolean]
        }
      ],
      custom_fields: [Hash]
    }
  ],
  custom_fields: [Hash],
  custom_collections: [
    {
      name: [String],
      fields: [
        {
          name: [String],
          value: [String]
        }
      ]
    }
  ]
}

Instance Method Summary collapse

Instance Method Details

#create_contact(data) ⇒ Hash

Creates a contact.

Examples:

client.create_contact(
  contact_type: 'Organization', name: 'Org name',
  contact_individuals: [
    { first_name: 'John', last_name: 'Doe' }
  ]
)

Parameters:

  • data (Hash) —

    A hash containing the contact details. Refer to the Contact data section above to see the available attributes.

Returns:

  • (Hash) —

    The contact that has been created.



196
197
198
 
# File 'lib/virtuous/client/contact.rb', line 196

def create_contact(data)
  parse(post('api/Contact', format(data)))
end

#find_contact_by_email(email) ⇒ Hash

Fetches a contact record by email.

Examples:

client.find_contact_by_email('[email protected]')

Parameters:

  • email (String) —

    The email of the contact.

Returns:

  • (Hash) —

    The contact information in a hash.



86
87
88
 
# File 'lib/virtuous/client/contact.rb', line 86

def find_contact_by_email(email)
  parse(get('api/Contact/Find', { email: email }))
end

#get_contact(id) ⇒ Hash

Fetches a contact record by id.

Examples:

client.get_contact(1)

Parameters:

  • id (Integer) —

    The id of the contact.

Returns:

  • (Hash) —

    The contact information in a hash.



99
100
101
 
# File 'lib/virtuous/client/contact.rb', line 99

def get_contact(id)
  parse(get("api/Contact/#{id}"))
end

#import_contact(data) ⇒ Object

Creates a contact. This will use the virtuous import tool to match the new contact with existing ones. If the contact record exists already but there is new information the record will be flagged for review.

Transactions are posted to the API and are set to a holding state. At midnight, transactions are bundled into imports based on the source they were posted with. The organization reviews the imported transactions, and then clicks run.

Required fields

  • contact_type: "Household", "Organization", "Foundation" or a custom type.
  • contact_name: required if Organization or Foundation.
  • first_name
  • last_name

Suggested fields

  • reference_source: the system it came from.
  • reference_id: the ID in the original system.
  • email
  • phone
  • address

Full list of accepted fields

{
  reference_source: [String],
  reference_id: [String],
  contact_type: [String],
  name: [String],
  title: [String],
  first_name: [String],
  middle_name: [String],
  last_name: [String],
  suffix: [String],
  email_type: [String],
  email: [String],
  phone_type: [String],
  phone: [String],
  address1: [String],
  address2: [String],
  city: [String],
  state: [String],
  postal: [String],
  country: [String],
  event_id: [Integer],
  event_name: [String],
  invited: [Boolean],
  rsvp: [Boolean],
  rsvp_response: [Boolean],
  attended: [Boolean],
  tags: [String],
  origin_segment_code: [String],
  email_lists: [String[]],
  custom_fields: [Hash],
  volunteer_attendances: [
    {
      volunteer_opportunity_id: [Integer],
      volunteer_opportunity_name: [String],
      date: [String],
      hours: [String]
    }
  ]
}

Examples:

client.import_contact(
  contact_type: 'Organization', name: 'Org name',
  first_name: 'John', last_name: 'Doe'
)

Parameters:

  • data (Hash) —

    A hash containing the contact details.



176
177
178
 
# File 'lib/virtuous/client/contact.rb', line 176

def import_contact(data)
  post('api/Contact/Transaction', format(data))
end

#update_contact(id, data) ⇒ Hash

Note:

Excluding a property will remove it's value from the object.

Updates a contact.

If you're only updating a single property, the entire model is still required.

Examples:

client.update_contact(1, contact_type: 'Organization', name: 'New name')

Parameters:

  • id (Integer) —

    The id of the contact to update.

  • data (Hash) —

    A hash containing the contact details. Refer to the Contact data section above to see the available attributes.

Returns:

  • (Hash) —

    The contact that has been updated.



215
216
217
 
# File 'lib/virtuous/client/contact.rb', line 215

def update_contact(id, data)
  parse(put("api/Contact/#{id}", format(data)))
end