Class: Hubspot::ContactList

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

Overview

HubSpot Contact lists API

Constant Summary collapse

LISTS_PATH = 
'/crm/v3/lists'
LIST_PATH = 
'/crm/v3/lists/:list_id'
SEARCH_PATH = 
LISTS_PATH + '/search'
CONTACTS_PATH = 
LIST_PATH + '/memberships'
RECENT_CONTACTS_PATH = 
LIST_PATH + '/memberships/join-order'
ADD_CONTACTS_PATH = 
LIST_PATH + '/memberships/add'
REMOVE_CONTACTS_PATH = 
LIST_PATH + '/memberships/remove'
UPDATE_NAME_PATH = 
LIST_PATH + '/update-list-name'
CONTACT_OBJECT_TYPE_ID = 
'0-1'
MANUAL_PROCESSING_TYPE = 
'MANUAL'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(hash) ⇒ ContactList

Returns a new instance of ContactList.



61
62
63
 
# File 'lib/hubspot/contact_list.rb', line 61

def initialize(hash)
  send(:assign_properties, hash.key?('list') ? hash['list'] : hash)
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



59
60
61
 
# File 'lib/hubspot/contact_list.rb', line 59

def id
  @id
end

#legacy_list_id ⇒ Object (readonly)

Returns the value of attribute legacy_list_id.



59
60
61
 
# File 'lib/hubspot/contact_list.rb', line 59

def legacy_list_id
  @legacy_list_id
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



59
60
61
 
# File 'lib/hubspot/contact_list.rb', line 59

def name
  @name
end

#processing_type ⇒ Object (readonly)

Returns the value of attribute processing_type.



59
60
61
 
# File 'lib/hubspot/contact_list.rb', line 59

def processing_type
  @processing_type
end

#properties ⇒ Object (readonly)

Returns the value of attribute properties.



59
60
61
 
# File 'lib/hubspot/contact_list.rb', line 59

def properties
  @properties
end

Class Method Details

.all(opts = {}) ⇒ Object

https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/guide#retrieve-by-searching-list-details



29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/hubspot/contact_list.rb', line 29

def all(opts = {})
  body = opts.delete(:body) || { query: '' }

  Hubspot::PagedCollection.new(opts) do |options, after, limit|
    response = Hubspot::Connection.post_json(
      SEARCH_PATH,
      options.merge('limit' => limit, 'offset' => after, 'offset_param' => 'after', params: {}, body:)
    )

    lists = response['lists'].map { |list| new(list) }
    after = response.dig('paging', 'next', 'after')
    [lists, after, after.present?]
  end
end

.create!(opts = {}) ⇒ Object

https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/guide#create-a-list



19
20
21
22
23
24
25
26
 
# File 'lib/hubspot/contact_list.rb', line 19

def create!(opts = {})
  object_type_id = opts.delete(:object_type_id) { CONTACT_OBJECT_TYPE_ID }
  processing_type = opts.delete(:processing_type) { MANUAL_PROCESSING_TYPE }
  body = opts.merge(objectTypeId: object_type_id, processingType: processing_type)

  response = Hubspot::Connection.post_json(LISTS_PATH, params: {}, body:)
  new(response)
end

.find(ids) ⇒ Object

https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/get-list-listId https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/get-lists#parameter-list-ids



46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/hubspot/contact_list.rb', line 46

def find(ids)
  batch_mode, path, params = case ids
                             when Integer then [false, LIST_PATH, { list_id: ids }]
                             when String then [false, LIST_PATH, { list_id: ids.to_i }]
                             when Array then [true, LISTS_PATH, { listIds: ids.map(&:to_i) }]
                             else raise Hubspot::InvalidParams, 'expecting Integer or Array of Integers parameter'
                             end

  response = Hubspot::Connection.get_json(path, params)
  batch_mode ? response['lists'].map { |l| new(l) } : new(response)
end

Instance Method Details

#add(contact_ids) ⇒ Object

http://developers.hubspot.com/docs/methods/lists/add_contact_to_list



94
95
96
97
98
 
# File 'lib/hubspot/contact_list.rb', line 94

def add(contact_ids)
  contact_ids = [contact_ids].flatten.uniq.compact
  response = Hubspot::Connection.put_json(ADD_CONTACTS_PATH, params: { list_id: id }, body: contact_ids)
  response['recordsIdsAdded']&.sort == contact_ids.sort.map(&:to_s)
end

#contact_ids(opts = {}) ⇒ Object

https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/memberships/get-memberships-by-id



79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/hubspot/contact_list.rb', line 79

def contact_ids(opts = {})
  path = opts.delete(:recent) ? RECENT_CONTACTS_PATH : CONTACTS_PATH
  opts[:list_id] = id
  Hubspot::PagedCollection.new(opts) do |options, after, limit|
    response = Hubspot::Connection.get_json(
      path, options.merge('limit' => limit, 'offset' => after, 'offset_param' => 'after')
    )

    contact_ids = response['results'].pluck('recordId')
    after = response.dig('paging', 'next', 'after')
    [contact_ids, after, after.present?]
  end
end

#destroy! ⇒ Object

http://developers.hubspot.com/docs/methods/lists/delete_list



73
74
75
76
 
# File 'lib/hubspot/contact_list.rb', line 73

def destroy!
  response = Hubspot::Connection.delete_json(LIST_PATH, { list_id: id })
  @destroyed = (response.code == 204)
end

#destroyed? ⇒ Boolean

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/hubspot/contact_list.rb', line 107

def destroyed?
  !!@destroyed
end

#remove(contact_ids) ⇒ Object

http://developers.hubspot.com/docs/methods/lists/remove_contact_from_list



101
102
103
104
105
 
# File 'lib/hubspot/contact_list.rb', line 101

def remove(contact_ids)
  contact_ids = [contact_ids].flatten.uniq.compact
  response = Hubspot::Connection.put_json(REMOVE_CONTACTS_PATH, params: { list_id: id }, body: contact_ids)
  response['recordIdsRemoved']&.sort == contact_ids.sort.map(&:to_s)
end

#update_name!(new_name) ⇒ Object

https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/update-list-name



66
67
68
69
70
 
# File 'lib/hubspot/contact_list.rb', line 66

def update_name!(new_name)
  response = Hubspot::Connection.put_json(UPDATE_NAME_PATH, params: { list_id: id, listName: new_name }, body: {})
  send(:assign_properties, response['updatedList'])
  self
end