Class: Attio::Person

Inherits:
TypedRecord show all
Defined in:
lib/attio/resources/person.rb

Overview

Represents a person record in Attio Provides convenient methods for working with people and their attributes

Constant Summary

Constants inherited from APIResource

APIResource::SKIP_KEYS

Instance Attribute Summary

Attributes inherited from Internal::Record

#attio_object_id, #object_api_slug

Attributes inherited from APIResource

#created_at, #id, #metadata

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from TypedRecord

all, delete, #destroy, find, find_by, #initialize, list, object_type, retrieve, #save, update

Methods inherited from Internal::Record

#add_to_list, #destroy, #initialize, #inspect, list, #lists, #resource_path, resource_path, retrieve, #save, #to_h, update

Methods inherited from APIResource

#==, #[], #[]=, api_operations, attr_attio, #changed, #changed?, #changed_attributes, #changes, #destroy, #each, execute_request, #fetch, #hash, id_param_name, #initialize, #inspect, #key?, #keys, #persisted?, prepare_params_for_create, prepare_params_for_update, #reset_changes!, resource_name, resource_path, #resource_path, #revert!, #save, #to_h, #to_json, #update_attributes, #update_from, validate_id!, #values

Constructor Details

This class inherits a constructor from Attio::TypedRecord

Class Method Details

.create(first_name: nil, last_name: nil, full_name: nil, email: nil, phone: nil, job_title: nil, company: nil, values: {}, **opts) ⇒ Object

Create a person with a simplified interface

Parameters:

  • attributes (Hash) —

    Person attributes



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/attio/resources/person.rb', line 198

def create(first_name: nil, last_name: nil, full_name: nil, email: nil, phone: nil,
  job_title: nil, company: nil, values: {}, **opts)
  # Build the values hash
  values[:name] ||= []
  if first_name || last_name || full_name
    name_data = {}

    # If only full_name is provided, try to parse it
    if full_name && !first_name && !last_name
      parts = full_name.split(" ")
      if parts.length >= 2
        name_data[:first_name] = parts.first
        name_data[:last_name] = parts[1..].join(" ")
      else
        name_data[:first_name] = full_name
      end
      name_data[:full_name] = full_name
    else
      name_data[:first_name] = first_name if first_name
      name_data[:last_name] = last_name if last_name
      name_data[:full_name] = full_name || [first_name, last_name].compact.join(" ")
    end

    values[:name] = [name_data]
  end

  values[:email_addresses] = [email] if email && !values[:email_addresses]

  if phone && !values[:phone_numbers]
    values[:phone_numbers] = [{
      original_phone_number: phone,
      country_code: opts.delete(:country_code) || "US"
    }]
  end

  values[:job_title] = job_title if job_title && !values[:job_title]

  if company && !values[:company]
    company_ref = if company.is_a?(Company)
      company_id = company.id.is_a?(Hash) ? company.id["record_id"] : company.id
      {
        target_object: "companies",
        target_record_id: company_id
      }
    elsif company.is_a?(String)
      {
        target_object: "companies",
        target_record_id: company
      }
    end
    values[:company] = [company_ref] if company_ref
  end

  super(values: values, **opts)
end

.search(query, **opts) ⇒ Object

Search people by query

Parameters:

  • query (String) —

    Query to search for



256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/attio/resources/person.rb', line 256

def search(query, **opts)
  # Search across name fields
  list(**opts.merge(
    filter: {
      "$or": [
        {name: {first_name: {"$contains": query}}},
        {name: {last_name: {"$contains": query}}},
        {name: {full_name: {"$contains": query}}}
      ]
    }
  ))
end

Instance Method Details

#add_email(email) ⇒ Object

Add an email address

Parameters:

  • email (String) —

    The email address to add



117
118
119
120
121
122
123
124
125
 
# File 'lib/attio/resources/person.rb', line 117

def add_email(email)
  emails = self[:email_addresses] || []
  # Ensure it's an array
  emails = [emails] unless emails.is_a?(Array)

  # Add the email if it's not already present
  emails << email unless emails.include?(email)
  self[:email_addresses] = emails
end

#add_phone(number, country_code: "US") ⇒ Object

Add a phone number

Parameters:

  • number (String) —

    The phone number

  • country_code (String) (defaults to: "US") —

    The country code (e.g., "US")



139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/attio/resources/person.rb', line 139

def add_phone(number, country_code: "US")
  phones = self[:phone_numbers] || []
  phones = [phones] unless phones.is_a?(Array)

  phone_data = {
    original_phone_number: number,
    country_code: country_code
  }

  phones << phone_data
  self[:phone_numbers] = phones
end

#company=(company) ⇒ Object

Associate with a company

Parameters:

  • company (Company, String) —

    A Company instance or company ID



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/attio/resources/person.rb', line 169

def company=(company)
  if company.is_a?(Company)
    # Extract ID properly from company instance
    company_id = company.id.is_a?(Hash) ? company.id["record_id"] : company.id
    self[:company] = [{
      target_object: "companies",
      target_record_id: company_id
    }]
  elsif company.is_a?(String)
    self[:company] = [{
      target_object: "companies",
      target_record_id: company
    }]
  elsif company.nil?
    self[:company] = nil
  else
    raise ArgumentError, "Company must be a Company instance or ID string"
  end
end

#email ⇒ String?

Get the primary email address

Returns:

  • (String, nil) —

    The primary email or nil if not set



129
130
131
132
133
134
 
# File 'lib/attio/resources/person.rb', line 129

def email
  emails = self[:email_addresses]
  return nil unless emails

  extract_primary_value(emails, "email_address")
end

#first_name ⇒ String?

Get the person's first name

Returns:

  • (String, nil) —

    The first name or nil if not set



55
56
57
 
# File 'lib/attio/resources/person.rb', line 55

def first_name
  extract_name_field("first_name")
end

#full_name ⇒ String?

Get the person's full name

Returns:

  • (String, nil) —

    The full name or nil if not set



49
50
51
 
# File 'lib/attio/resources/person.rb', line 49

def full_name
  extract_name_field("full_name")
end

#job_title=(title) ⇒ Object

Set the job title

Parameters:

  • title (String) —

    The job title



163
164
165
 
# File 'lib/attio/resources/person.rb', line 163

def job_title=(title)
  self[:job_title] = title
end

#last_name ⇒ String?

Get the person's last name

Returns:

  • (String, nil) —

    The last name or nil if not set



61
62
63
 
# File 'lib/attio/resources/person.rb', line 61

def last_name
  extract_name_field("last_name")
end

#name=(name_value) ⇒ Object

Set the person's name using a hash or string

Parameters:

  • name_value (Hash, String) —

    Either a hash with first/last/middle/full keys or a full name string



36
37
38
39
40
41
42
43
44
45
 
# File 'lib/attio/resources/person.rb', line 36

def name=(name_value)
  case name_value
  when Hash
    set_name(**name_value)
  when String
    set_name(full: name_value)
  else
    raise ArgumentError, "Name must be a Hash or String"
  end
end

#phone ⇒ String?

Get the primary phone number

Returns:

  • (String, nil) —

    The primary phone number or nil if not set



154
155
156
157
158
159
 
# File 'lib/attio/resources/person.rb', line 154

def phone
  phones = self[:phone_numbers]
  return nil unless phones

  extract_primary_value(phones, "original_phone_number")
end

#set_name(first: nil, last: nil, middle: nil, full: nil) ⇒ Object

Set the person's name using a more intuitive interface

Parameters:

  • first (String) (defaults to: nil) —

    First name

  • last (String) (defaults to: nil) —

    Last name

  • middle (String) (defaults to: nil) —

    Middle name (optional)

  • full (String) (defaults to: nil) —

    Full name (optional, will be generated if not provided)



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/attio/resources/person.rb', line 16

def set_name(first: nil, last: nil, middle: nil, full: nil)
  name_data = {}
  name_data[:first_name] = first if first
  name_data[:last_name] = last if last
  name_data[:middle_name] = middle if middle

  # Generate full name if not provided
  if full
    name_data[:full_name] = full
  elsif first || last
    parts = [first, middle, last].compact
    name_data[:full_name] = parts.join(" ") unless parts.empty?
  end

  # Attio expects name as an array with a single hash
  self[:name] = [name_data] unless name_data.empty?
end