class Hubspot::Contact

HubSpot Contacts API

{developers.hubspot.com/docs/methods/contacts/contacts-overview}

TODO: work on all endpoints that can specify contact properties, property mode etc… as params. cf pending specs

Constants

BATCH_CREATE_OR_UPDATE_PATH
CONTACTS_PATH
CONTACT_BATCH_PATH
CREATE_CONTACT_PATH
CREATE_OR_UPDATE_PATH
DESTROY_CONTACT_PATH
GET_CONTACTS_BY_EMAIL_PATH
GET_CONTACTS_BY_UTK_PATH
GET_CONTACT_BY_EMAIL_PATH
GET_CONTACT_BY_ID_PATH
GET_CONTACT_BY_UTK_PATH
MERGE_CONTACT_PATH
QUERY_PATH
RECENTLY_CREATED_PATH
RECENTLY_UPDATED_PATH
UPDATE_CONTACT_PATH

Attributes

is_contact[R]
is_new[R]
list_memberships[R]
properties[R]
vid[R]

Public Class Methods

all(opts={}) click to toggle source

{developers.hubspot.com/docs/methods/contacts/get_contacts} {developers.hubspot.com/docs/methods/contacts/get_recently_updated_contacts} {developers.hubspot.com/docs/methods/contacts/get_recently_created_contacts}

# File lib/hubspot/contact.rb, line 39
def all(opts={})
  recent = opts.delete(:recent) { false }
  recent_created = opts.delete(:recent_created) { false }
  paged = opts.delete(:paged) { false }
  path, opts =
  if recent_created
    [RECENTLY_CREATED_PATH, Hubspot::ContactProperties.add_default_parameters(opts)]
  elsif recent
    [RECENTLY_UPDATED_PATH, Hubspot::ContactProperties.add_default_parameters(opts)]
  else
    [CONTACTS_PATH, opts]
  end

  response = Hubspot::Connection.get_json(path, opts)
  response['contacts'].map! { |c| new(c) }
  paged ? response : response['contacts']
end
create!(email, params={}) click to toggle source

{developers.hubspot.com/docs/methods/contacts/create_contact}

# File lib/hubspot/contact.rb, line 28
def create!(email, params={})
  params_with_email = params.stringify_keys
  params_with_email = params.stringify_keys.merge('email' => email) if email
  post_data = {properties: Hubspot::Utils.hash_to_properties(params_with_email)}
  response = Hubspot::Connection.post_json(CREATE_CONTACT_PATH, params: {}, body: post_data )
  new(response)
end
createOrUpdate(email, params={}) click to toggle source

TODO: create or update a contact PATH /contacts/v1/contact/createOrUpdate/email/:contact_email API endpoint: developers.hubspot.com/docs/methods/contacts/create_or_update

# File lib/hubspot/contact.rb, line 60
def createOrUpdate(email, params={})
  post_data = {properties: Hubspot::Utils.hash_to_properties(params.stringify_keys)}
  response = Hubspot::Connection.post_json(CREATE_OR_UPDATE_PATH, params: { contact_email: email }, body: post_data )
  contact = find_by_id(response['vid'])
  contact.is_new = response['isNew']
  contact
end
create_or_update!(contacts) click to toggle source

NOTE: Performance is best when calls are limited to 100 or fewer contacts {developers.hubspot.com/docs/methods/contacts/batch_create_or_update}

# File lib/hubspot/contact.rb, line 70
def create_or_update!(contacts)
  query = contacts.map do |ch|
    contact_hash = ch.with_indifferent_access
    if contact_hash[:vid]
      contact_param = {
        vid: contact_hash[:vid],
        properties: Hubspot::Utils.hash_to_properties(contact_hash.except(:vid))
      }
    elsif contact_hash[:email]
      contact_param = {
        email: contact_hash[:email],
        properties: Hubspot::Utils.hash_to_properties(contact_hash.except(:email))
      }
    else
      raise Hubspot::InvalidParams, 'expecting vid or email for contact'
    end
    contact_param
  end
  Hubspot::Connection.post_json(BATCH_CREATE_OR_UPDATE_PATH,
                                params: {},
                                body: query)
end
find_by_email(emails) click to toggle source

{developers.hubspot.com/docs/methods/contacts/get_contact_by_email} {developers.hubspot.com/docs/methods/contacts/get_batch_by_email}

# File lib/hubspot/contact.rb, line 110
def find_by_email(emails)
  batch_mode, path, params = case emails
  when String then [false, GET_CONTACT_BY_EMAIL_PATH, { contact_email: emails }]
  when Array then [true, GET_CONTACTS_BY_EMAIL_PATH, { batch_email: emails }]
  else raise Hubspot::InvalidParams, 'expecting String or Array of Strings parameter'
  end

  begin
    response = Hubspot::Connection.get_json(path, params)
    if batch_mode
      response.map{|_, contact| new(contact)}
    else
      new(response)
    end
  rescue => e
    raise e unless e.message =~ /not exist/ # 404 / handle the error and kindly return nil
    nil
  end
end
find_by_id(vids) click to toggle source

NOTE: problem with batch api endpoint {developers.hubspot.com/docs/methods/contacts/get_contact} {developers.hubspot.com/docs/methods/contacts/get_batch_by_vid}

# File lib/hubspot/contact.rb, line 96
def find_by_id(vids)
  batch_mode, path, params = case vids
  when Integer then [false, GET_CONTACT_BY_ID_PATH, { contact_id: vids }]
  when Array then [true, CONTACT_BATCH_PATH, { batch_vid: vids }]
  else raise Hubspot::InvalidParams, 'expecting Integer or Array of Integers parameter'
  end

  response = Hubspot::Connection.get_json(path, params)
  raise Hubspot::ApiError if batch_mode
  new(response)
end
find_by_utk(utks) click to toggle source

NOTE: problem with batch api endpoint {developers.hubspot.com/docs/methods/contacts/get_contact_by_utk} {developers.hubspot.com/docs/methods/contacts/get_batch_by_utk}

# File lib/hubspot/contact.rb, line 133
def find_by_utk(utks)
  batch_mode, path, params = case utks
  when String then [false, GET_CONTACT_BY_UTK_PATH, { contact_utk: utks }]
  when Array then [true, GET_CONTACTS_BY_UTK_PATH, { batch_utk: utks }]
  else raise Hubspot::InvalidParams, 'expecting String or Array of Strings parameter'
  end

  response = Hubspot::Connection.get_json(path, params)
  raise Hubspot::ApiError if batch_mode
  new(response)
end
merge!(primary_contact_vid, secondary_contact_vid) click to toggle source

Merge two contacts Properties of the secondary contact will be applied to the primary contact The main email will be the primary contact's The secondary email still won't be available for new contacts {developers.hubspot.com/docs/methods/contacts/merge-contacts}

# File lib/hubspot/contact.rb, line 159
def merge!(primary_contact_vid, secondary_contact_vid)
  Hubspot::Connection.post_json(
    MERGE_CONTACT_PATH,
    params: { contact_id: primary_contact_vid, no_parse: true },
    body: { vidToMerge: secondary_contact_vid }
  )
end
new(response_hash) click to toggle source
# File lib/hubspot/contact.rb, line 171
def initialize(response_hash)
  props = response_hash['properties'] || {}
  @properties = Hubspot::Utils.properties_to_hash(props)
  @is_contact = response_hash["is-contact"]
  @list_memberships = response_hash["list-memberships"] || []
  @vid = response_hash['vid']
end

Public Instance Methods

[](property) click to toggle source
# File lib/hubspot/contact.rb, line 179
def [](property)
  @properties[property]
end
destroy!() click to toggle source

Archives the contact in hubspot {developers.hubspot.com/docs/methods/contacts/delete_contact} @return [TrueClass] true

# File lib/hubspot/contact.rb, line 209
def destroy!
  Hubspot::Connection.delete_json(DESTROY_CONTACT_PATH, { contact_id: vid })
  @destroyed = true
end
destroyed?() click to toggle source
# File lib/hubspot/contact.rb, line 214
def destroyed?
  !!@destroyed
end
email() click to toggle source
# File lib/hubspot/contact.rb, line 183
def email
  @properties['email']
end
is_new=(val) click to toggle source
# File lib/hubspot/contact.rb, line 191
def is_new=(val)
  @is_new = val
end
update!(params) click to toggle source

Updates the properties of a contact {developers.hubspot.com/docs/methods/contacts/update_contact} @param params [Hash] hash of properties to update @return [Hubspot::Contact] self

# File lib/hubspot/contact.rb, line 199
def update!(params)
  query = {"properties" => Hubspot::Utils.hash_to_properties(params.stringify_keys!)}
  Hubspot::Connection.post_json(UPDATE_CONTACT_PATH, params: { contact_id: vid }, body: query)
  @properties.merge!(params)
  self
end
utk() click to toggle source
# File lib/hubspot/contact.rb, line 187
def utk
  @properties['usertoken']
end