Class: Attio::Resources::Lists Private

Inherits:
Base
  • Object
show all
Defined in:
lib/attio/resources/lists.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

API resource for managing Attio lists and list entries

Lists are custom collections for organizing records in your workspace.

Examples:

Listing all lists

client.lists.list

Adding an entry to a list

client.lists.create_entry(id: "list_id", data: { record_id: "rec_123" })

Since:

  • 1.0.0

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from Attio::Resources::Base

Instance Method Details

#assert_entry(id_or_slug:, matching_attribute:, data:) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Assert (upsert) a list entry.

Creates or updates a list entry based on a matching attribute. This is an upsert operation that will create a new entry if no match is found, or update an existing entry if a match is found based on the specified matching attribute.

Required scopes: list_entry:read-write, list_configuration:read

Examples:

Assert entry with record ID

entry = client.lists.assert_entry(
  id_or_slug: "vip_customers",
  matching_attribute: "record_id",
  data: {
    record_id: "rec_123",
    values: { priority: "high" },
    notes: "Premium customer"
  }
)

Assert entry with custom matching

entry = client.lists.assert_entry(
  id_or_slug: "lead_list",
  matching_attribute: "email",
  data: {
    email: "[email protected]",
    values: { status: "qualified" }
  }
)

Options Hash (data:):

  • :record_id (String) —

    The ID of the record to add to the list

  • :values (Hash) —

    Optional field values for the entry

  • :notes (String) —

    Optional notes for the entry

Raises:

  • (ArgumentError) —

    if parameters are invalid

Since:

  • 1.0.0



178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/attio/resources/lists.rb', line 178

def assert_entry(id_or_slug:, matching_attribute:, data:)
  validate_id!(id_or_slug, "List")
  validate_required_string!(matching_attribute, "Matching attribute")
  validate_list_entry_data!(data)

  request_body = {
    data: data,
    matching_attribute: matching_attribute,
  }

  request(:put, "lists/#{id_or_slug}/entries", request_body)
end

#create(data:) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create a new list.

Creates a new list with the specified configuration. The list can be associated with a parent object type and configured with various options.

Examples:

Create a simple list

list = client.lists.create(
  data: {
    name: "VIP Customers",
    parent_object: "people",
    is_public: true
  }
)

Options Hash (data:):

  • :name (String) —

    The name of the list (required)

  • :parent_object (String) —

    The parent object type for the list

  • :is_public (Boolean) —

    Whether the list is publicly accessible

  • :description (String) —

    Optional description for the list

Raises:

  • (ArgumentError) —

    if data is invalid

Since:

  • 1.0.0



69
70
71
72
 
# File 'lib/attio/resources/lists.rb', line 69

def create(data:)
  validate_list_data!(data)
  request(:post, "lists", { data: data })
end

#create_entry(id:, data:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



29
30
31
32
33
 
# File 'lib/attio/resources/lists.rb', line 29

def create_entry(id:, data:)
  validate_id!(id, "List")
  validate_list_entry_data!(data)
  request(:post, "lists/#{id}/entries", data)
end

#delete_entry(list_id:, entry_id:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



41
42
43
44
45
 
# File 'lib/attio/resources/lists.rb', line 41

def delete_entry(list_id:, entry_id:)
  validate_id!(list_id, "List")
  validate_id!(entry_id, "Entry")
  request(:delete, "lists/#{list_id}/entries/#{entry_id}")
end

#entries(id:, **params) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



24
25
26
27
 
# File 'lib/attio/resources/lists.rb', line 24

def entries(id:, **params)
  validate_id!(id, "List")
  request(:get, "lists/#{id}/entries", params)
end

#get(id:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



19
20
21
22
 
# File 'lib/attio/resources/lists.rb', line 19

def get(id:)
  validate_id!(id, "List")
  request(:get, "lists/#{id}")
end

#get_entry(list_id:, entry_id:) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



35
36
37
38
39
 
# File 'lib/attio/resources/lists.rb', line 35

def get_entry(list_id:, entry_id:)
  validate_id!(list_id, "List")
  validate_id!(entry_id, "Entry")
  request(:get, "lists/#{list_id}/entries/#{entry_id}")
end

#list(**params) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 1.0.0



15
16
17
 
# File 'lib/attio/resources/lists.rb', line 15

def list(**params)
  request(:get, "lists", params)
end

#query_entries(id_or_slug:, filter: nil, sort: nil, limit: nil, offset: nil) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Query list entries with advanced filtering and sorting.

Provides advanced querying capabilities for list entries, supporting complex filters, sorting, and pagination. This is more powerful than the basic entries method as it supports structured queries.

Examples:

Query with filters

entries = client.lists.query_entries(
  id_or_slug: "vip_customers",
  filter: { created_at: { gte: "2023-01-01" } },
  sort: { created_at: "desc" },
  limit: 50
)

Query all entries without filters

entries = client.lists.query_entries(id_or_slug: "list_123")

Raises:

  • (ArgumentError) —

    if id_or_slug is invalid

Since:

  • 1.0.0



127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/attio/resources/lists.rb', line 127

def query_entries(id_or_slug:, filter: nil, sort: nil, limit: nil, offset: nil)
  validate_id!(id_or_slug, "List")

  query_params = build_query_params({
    filter: filter,
    sort: sort,
    limit: limit,
    offset: offset,
  })

  request(:post, "lists/#{id_or_slug}/entries/query", query_params)
end

#update(id_or_slug:, data:) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Update an existing list.

Updates the configuration of an existing list. You can modify the name, description, visibility, and other list properties.

Examples:

Update list name and visibility

list = client.lists.update(
  id_or_slug: "list_123",
  data: {
    name: "Premium Customers",
    is_public: false
  }
)

Options Hash (data:):

  • :name (String) —

    New name for the list

  • :is_public (Boolean) —

    New visibility setting

  • :description (String) —

    New description for the list

Raises:

  • (ArgumentError) —

    if id_or_slug or data is invalid

Since:

  • 1.0.0



96
97
98
99
100
 
# File 'lib/attio/resources/lists.rb', line 96

def update(id_or_slug:, data:)
  validate_id!(id_or_slug, "List")
  validate_list_data!(data)
  request(:patch, "lists/#{id_or_slug}", { data: data })
end

#update_entry(id_or_slug:, entry_id:, data:) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Update an existing list entry.

Updates the data for an existing list entry. This method requires the entry ID and will update only the provided fields, leaving other fields unchanged.

Examples:

Update entry values

entry = client.lists.update_entry(
  id_or_slug: "vip_customers",
  entry_id: "ent_456",
  data: {
    values: { priority: "medium", last_contacted: "2024-01-15" },
    notes: "Updated contact information"
  }
)

Update only notes

entry = client.lists.update_entry(
  id_or_slug: "lead_list",
  entry_id: "ent_789",
  data: { notes: "Follow up scheduled" }
)

Options Hash (data:):

  • :values (Hash) —

    Field values to update

  • :notes (String) —

    Updated notes for the entry

Raises:

  • (ArgumentError) —

    if parameters are invalid

Since:

  • 1.0.0



222
223
224
225
226
227
228
229
230
 
# File 'lib/attio/resources/lists.rb', line 222

def update_entry(id_or_slug:, entry_id:, data:)
  validate_id!(id_or_slug, "List")
  validate_id!(entry_id, "Entry")
  validate_list_entry_data!(data)

  request_body = { data: data }

  request(:patch, "lists/#{id_or_slug}/entries/#{entry_id}", request_body)
end

#validate_list_data!(data) ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Validates that the list data parameter is present and valid.

Raises:

  • (ArgumentError) —

    if data is nil or not a hash

  • (ArgumentError)

Since:

  • 1.0.0



242
243
244
245
 
# File 'lib/attio/resources/lists.rb', line 242

private def validate_list_data!(data)
  raise ArgumentError, "Data is required" if data.nil?
  raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
end

#validate_list_entry_data!(data) ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:

  • (ArgumentError)

Since:

  • 1.0.0



232
233
234
235
 
# File 'lib/attio/resources/lists.rb', line 232

private def validate_list_entry_data!(data)
  raise ArgumentError, "Data is required" if data.nil?
  raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
end