ContactBuilder

This page provides an in-depth guide to constructing Contact payloads using the `ContactBuilder` and `Attribute` helpers. You’ll learn how to assemble complex JSON structures with a fluent API—with no need to memorize Acumatica’s exact field names or nesting.

Importing the Builders

To get started, import the `ContactBuilder` and `Attribute` classes from the `easy_acumatica.models` module.


from easy_acumatica.models.contact_builder import ContactBuilder, Attribute

The `Attribute` Helper Class

The `Attribute` class represents one element of a contact’s `Attributes` array. Use it when adding or updating custom fields on the Contact screen.


# Create a single attribute payload
attr = Attribute(
    attribute_id="INTEREST",
    value="Product Updates"
)

# .to_dict() generates the required JSON structure
# print(attr.to_dict())

ContactBuilder Methods

The `ContactBuilder` provides a wide range of chainable methods to set all properties of a contact record. Below are examples grouped by functionality.

Core Identity Fields


builder = ContactBuilder()
builder.first_name("Jane").last_name("Doe").middle_name("A.")

Contact Details


builder.email("jane.doe@example.com")
       .phone1("+1 555-1234", phone_type="Business 1")
       .job_title("Sales Engineer")

Classification & Ownership


builder.business_account("ABAKERY")
       .contact_class("ENDCUST")
       .workgroup("Sales")
       .owner("jsmith")

Adding Custom Attributes

Use the `.add_attribute()` method to add custom attributes. The builder ensures that each attribute is unique by its ID.


builder.add_attribute("INTEREST", "Webinars")
       .add_attribute("REGION", "EMEA")

Complete Example

Here is a complete example of how to use the `ContactBuilder` to create a new contact with various properties and custom attributes.


contact_payload = (
    ContactBuilder()
    .first_name("Jane")
    .last_name("Doe")
    .email("jane.doe@example.com")
    .contact_class("ENDCUST")
    .business_account("ABAKERY")
    .add_attribute("INTEREST", "Product Updates")
)

# Get the final dictionary, ready for the API
json_body = contact_payload.build()

# Use with the ContactsService
# client.contacts.create_contact("24.200.001", draft=contact_payload)