Class: Hubspot::Contact

Inherits:
Object
  • Object
show all
Defined in:
lib/hubspot/contact.rb

Overview

HubSpot Contacts API

https://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

Constant Summary collapse

CREATE_CONTACT_PATH = 
'/contacts/v1/contact'
BATCH_CREATE_OR_UPDATE_PATH = 
'/contacts/v1/contact/batch/'
GET_CONTACT_BY_EMAIL_PATH = 
'/contacts/v1/contact/email/:contact_email/profile'
GET_CONTACTS_BY_EMAIL_PATH = 
'/contacts/v1/contact/emails/batch'
GET_CONTACT_BY_ID_PATH = 
'/contacts/v1/contact/vid/:contact_id/profile'
CONTACT_BATCH_PATH = 
'/contacts/v1/contact/vids/batch'
GET_CONTACT_BY_UTK_PATH = 
'/contacts/v1/contact/utk/:contact_utk/profile'
GET_CONTACTS_BY_UTK_PATH = 
'/contacts/v1/contact/utks/batch'
UPDATE_CONTACT_PATH = 
'/contacts/v1/contact/vid/:contact_id/profile'
DESTROY_CONTACT_PATH = 
'/contacts/v1/contact/vid/:contact_id'
MERGE_CONTACT_PATH = 
'/contacts/v1/contact/merge-vids/:contact_id'
CONTACTS_PATH = 
'/contacts/v1/lists/all/contacts/all'
RECENTLY_UPDATED_PATH = 
'/contacts/v1/lists/recently_updated/contacts/recent'
RECENTLY_CREATED_PATH = 
'/contacts/v1/lists/all/contacts/recent'
CREATE_OR_UPDATE_PATH = 
'/contacts/v1/contact/createOrUpdate/email/:contact_email'
QUERY_PATH = 
'/contacts/v1/search/query'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(response_hash) ⇒ Contact

Returns a new instance of Contact.



171
172
173
174
175
176
177
 
# 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

Instance Attribute Details

#is_contact ⇒ Object (readonly)

Returns the value of attribute is_contact.



169
170
171
 
# File 'lib/hubspot/contact.rb', line 169

def is_contact
  @is_contact
end

#is_new ⇒ Object

Returns the value of attribute is_new.



168
169
170
 
# File 'lib/hubspot/contact.rb', line 168

def is_new
  @is_new
end

#list_memberships ⇒ Object (readonly)

Returns the value of attribute list_memberships.



169
170
171
 
# File 'lib/hubspot/contact.rb', line 169

def list_memberships
  @list_memberships
end

#properties ⇒ Object (readonly)

Returns the value of attribute properties.



168
169
170
 
# File 'lib/hubspot/contact.rb', line 168

def properties
  @properties
end

#vid ⇒ Object (readonly)

Returns the value of attribute vid.



168
169
170
 
# File 'lib/hubspot/contact.rb', line 168

def vid
  @vid
end

Class Method Details

.all(opts = {}) ⇒ Object

https://developers.hubspot.com/docs/methods/contacts/get_contacts https://developers.hubspot.com/docs/methods/contacts/get_recently_updated_contacts https://developers.hubspot.com/docs/methods/contacts/get_recently_created_contacts



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# 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 = {}) ⇒ Object

https://developers.hubspot.com/docs/methods/contacts/create_contact



28
29
30
31
32
33
34
 
# 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

.create_or_update!(contacts) ⇒ Object

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



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# 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

.createOrUpdate(email, params = {}) ⇒ Object

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



60
61
62
63
64
65
66
 
# 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

.find_by_email(emails) ⇒ Object

https://developers.hubspot.com/docs/methods/contacts/get_contact_by_email https://developers.hubspot.com/docs/methods/contacts/get_batch_by_email



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# 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) ⇒ Object

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

Raises:



96
97
98
99
100
101
102
103
104
105
106
 
# 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) ⇒ Object

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

Raises:



133
134
135
136
137
138
139
140
141
142
143
 
# 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) ⇒ Object

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 https://developers.hubspot.com/docs/methods/contacts/merge-contacts



159
160
161
162
163
164
165
 
# 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

.search(query, options = {}) ⇒ Object

https://developers.hubspot.com/docs/methods/contacts/search_contacts



146
147
148
149
150
151
152
 
# File 'lib/hubspot/contact.rb', line 146

def search(query, options = {})
  count   = options.fetch(:count, 100)
  offset  = options.fetch(:offset, 0)

  response = Hubspot::Connection.get_json(QUERY_PATH, { q: query, count: count, offset: offset })
  response.merge("contacts" => response["contacts"].map { |contact_hash| new(contact_hash) })
end

Instance Method Details

#[](property) ⇒ Object 



179
180
181
 
# File 'lib/hubspot/contact.rb', line 179

def [](property)
  @properties[property]
end

#destroy! ⇒ TrueClass

Archives the contact in hubspot https://developers.hubspot.com/docs/methods/contacts/delete_contact

Returns:

  • (TrueClass) —

    true



209
210
211
212
 
# File 'lib/hubspot/contact.rb', line 209

def destroy!
  Hubspot::Connection.delete_json(DESTROY_CONTACT_PATH, { contact_id: vid })
  @destroyed = true
end

#destroyed? ⇒ Boolean

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/hubspot/contact.rb', line 214

def destroyed?
  !!@destroyed
end

#email ⇒ Object 



183
184
185
 
# File 'lib/hubspot/contact.rb', line 183

def email
  @properties['email']
end

#update!(params) ⇒ Hubspot::Contact

Updates the properties of a contact https://developers.hubspot.com/docs/methods/contacts/update_contact

Parameters:

  • params (Hash) —

    hash of properties to update

Returns:



199
200
201
202
203
204
 
# 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 ⇒ Object 



187
188
189
 
# File 'lib/hubspot/contact.rb', line 187

def utk
  @properties['usertoken']
end