Contacts Service

The `ContactsService` is a high-level helper for interacting with `Contact` resources. It provides methods to list, create, update, delete, and link contacts within your Acumatica instance.

Importing Helpers

To effectively use the service, you will need to import the `ContactBuilder` for creating payloads and the `QueryOptions` and `F` factory for filtering.


from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions, CustomField  
from easy_acumatica.models.contact_builder import ContactBuilder

Service Methods

get_contacts(api_version, options=None)

Retrieves a list of contacts. You can provide an optional `QueryOptions` object to filter, expand, select, or paginate the results.


# Find a specific contact by their ContactID
opts = QueryOptions(filter=F.ContactID == 100073)

contact = client.contacts.get_contacts("24.200.001", options=opts)

create_contact(api_version, draft)

Creates a new contact or lead in Acumatica. This method requires a `ContactBuilder` instance to construct the JSON payload for the new record.


# Build the payload for a new contact
draft = (
    ContactBuilder()
    .first_name("Brent")
    .last_name("Edds")
    .email("brent.edds@example.com")
    .contact_class("ENDCUST")
)

# Create the contact
created_contact = client.contacts.create_contact("24.200.001", draft)

update_contact(api_version, filter_, payload)

Updates one or more existing contacts that match the specified `filter_`. You can provide the update payload as either a `ContactBuilder` instance or a raw dictionary.


# Change the email for the contact with ID 100200
update_payload = ContactBuilder().email("new.email@example.com")

updated_contact = client.contacts.update_contact(
    "24.200.001",
    filter_=(F.ContactID == 100200),
    payload=update_payload
)

deactivate_contact(api_version, filter_, active=False)

Performs a "soft-delete" by setting the `Active` status of contacts matching the filter. Set the `active` parameter to `True` to reactivate them.


# Deactivate a specific contact
client.contacts.deactivate_contact(
    "24.200.001",
    filter_=(F.ContactID == 100200),
    active=False
)

delete_contact(api_version, note_id)

Permanently deletes a contact from Acumatica. This action is irreversible and requires the `NoteID` (GUID) of the contact to be deleted.


# The NoteID is a GUID, not the integer ContactID
note_id_to_delete = "123e4567-e89b-12d3-a456-426614174000"

# Permanently delete the contact
client.contacts.delete_contact("24.200.001", note_id=note_id_to_delete)

link_contact_to_customer(api_version, contact_id, business_account, ...)

Associates an existing contact with a customer (Business Account) record. This is a specialized update operation that sets the `BusinessAccount` field on the contact.


# Associate contact 104000 with business account 'ABAKERY'
client.contacts.link_contact_to_customer(
    "24.200.001",
    contact_id=104000,
    business_account="ABAKERY"
)