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
Public Class Methods
{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
{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
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
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
{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
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
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 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
# 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
{developers.hubspot.com/docs/methods/contacts/search_contacts}
# 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
Public Instance Methods
# File lib/hubspot/contact.rb, line 179 def [](property) @properties[property] end
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
# File lib/hubspot/contact.rb, line 214 def destroyed? !!@destroyed end
# File lib/hubspot/contact.rb, line 183 def email @properties['email'] end
# File lib/hubspot/contact.rb, line 191 def is_new=(val) @is_new = val end
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
# File lib/hubspot/contact.rb, line 187 def utk @properties['usertoken'] end