Summary

iPaaS.com Customer records can be captured from Acumatica Contacts using an Add/Update sync method. An Acumatica contact is the person record that belongs to a business account; this mapping captures the contact's Contact ID, first and last name, email, company name, note and salutation into an iPaaS.com Customer, carries the contact's address through a child collection, and links the Customer to the iPaaS.com Company that represents the contact's business account through a second child collection. When that business account is an Acumatica customer that is not yet in iPaaS.com, the integration sends it to the Company collection first; when that collection's filter does not take the account as a company, the contact is captured without a company relationship. Capture is polling-based, together with Acumatica customers, with an on-demand Manual Sync; this collection only reads from Acumatica and never writes contacts back.

ID Format

Manual Sync ID Format

When manually transferring a contact, enter the Acumatica Contact ID followed by the contact suffix |contact. For example, enter 5|contact for the contact whose Contact ID is 5. A Contact ID entered without the suffix is treated as an Acumatica Customer ID and does not reach this collection.

External ID Format

After a successful transfer, iPaaS.com saves the Contact ID with the contact suffix (for example, 5|contact) as the external ID of the iPaaS.com Customer, on a dedicated external-ID record. This is the primary match: later transfers of the same contact use that link to update the same iPaaS.com Customer rather than create a new one. The suffix keeps contact links separate from the links of Acumatica customers, whose external ID is the plain Customer ID.

The default mappings also copy the bare Contact ID (for example, 5) into the iPaaS.com CustomerNumber field, which gives visibility of the Contact ID on the iPaaS.com Customer. Contacts are not matched by CustomerNumber: a contact that is not yet linked is matched to an existing Customer only by email (see Collision handling under Duplicate or Conflicting Mappings).

Child ID Format

Address: the contact's address is linked with the Contact ID, the contact suffix and an address suffix (for example, 5|contact|address).
Company relationship: the link to the Company is linked with the Contact ID, the contact suffix and the business account code (for example, 5|contact|AACUSTOMER for Contact ID 5 in business account AACUSTOMER).

Deleted Record Support

Removing a contact in Acumatica is not propagated as a delete in iPaaS.com through this collection, and delete mappings are not included in the default templates.

Custom Field Support

This collection maps two iPaaS.com Customer custom fields, Salutation and Acumatica Contact ID. Both custom fields must be configured on the iPaaS.com Customer for their values to be retained. Salutation mirrors the Acumatica contact Title. Acumatica Contact ID keeps the Contact ID: A custom field keeps its value when another integration updates the record without mapping it, while standard fields such as CustomerNumber are replaced by whichever integration writes the record last, so the custom field keeps a dependable copy of the Acumatica value.

On the Acumatica side, contact fields that the integration does not map to a standard field are passed to iPaaS.com as custom field values under their Acumatica field name, and can be mapped from the Custom source.

The child collections Add/Update Acumatica Contact Address TO iPaaS.com and Add/Update Acumatica Contact Relationship TO iPaaS.com do not map any custom fields.

Mapping Collection Status

Status: Enabled

Trigger Events: Acumatica contacts are picked up by the integration's customer poll. Each time the poll runs, it checks Acumatica for customers that changed since the last successful poll and then, straight after, for contacts that changed since the last successful contact poll. Contacts keep their own last-poll time. A subscriber can also run a Manual Sync to capture a specific contact on demand. There are no external webhooks for this collection; Acumatica does not push contact changes to the integration.

Filter: Acumatica contacts and Acumatica customers both arrive in iPaaS.com as Customer records. This collection's filter takes only the contacts; Acumatica customer accounts go to Add/Update Acumatica Customer TO iPaaS.com or Add/Update Acumatica Company TO iPaaS.com, according to the subscriber's split between Customers and Companies. Each contact carries the Customer Class of its business account, so a split based on the customer class is also evaluated correctly for contacts. See Mappings for the filter.

Duplicate or Conflicting Mappings

The following collections also operate on iPaaS.com Customer records:

Add/Update Acumatica Customer TO iPaaS.com: Captures Acumatica customers as iPaaS.com Customers. It shares the iPaaS.com Customer type with this collection; the two filters split the records so each record is processed by exactly one of them. Its filter is also evaluated for contacts, so it can only use values that contacts carry too, such as CustomerClass. It is documented in Acumatica to iPaaS.com Customer Mapping Documentation.
Add/Update Acumatica Customer FROM iPaaS.com: Writes iPaaS.com Customers into Acumatica as Acumatica customers. It is documented in iPaaS.com to Acumatica Customer Mapping Documentation.

Before enabling this collection alongside the outbound "From iPaaS.com" customer collections, review and customize your mapping collection filters to prevent circular updates between the two systems, where a capture into iPaaS.com triggers a write back into Acumatica that re-triggers the capture. Decide which system is the source of truth for contact records and filter the other direction accordingly.

Collision handling: the Collision Handling Method setting is not supported for this collection. Duplicate handling for contacts is automatic and built into the integration:

A contact that is already linked to an iPaaS.com Customer always updates that Customer.
A contact that is not yet linked is compared with the iPaaS.com Customer that has the same email. Because iPaaS.com requires a unique email on every Customer, at most one Customer can match. When that Customer is not linked to another Acumatica record, the contact is linked to it and that Customer is updated instead of a second record being created. When it is already linked to another Acumatica record, it is not taken over (see Known Limitations).
A contact with no email cannot be transferred, because iPaaS.com requires an email address on every Customer; add an email to the contact in Acumatica and run the transfer again.
Whenever the contact is linked to an iPaaS.com Customer, on its first transfer or a later one, its address and Company relationship that are not yet linked are matched against the ones already on that Customer, so they are updated instead of added a second time.

Supported Child Collections

Parent Collection: Add/Update Acumatica Contact TO iPaaS.com: builds the iPaaS.com Customer record from the Acumatica contact.
Child Collection: Add/Update Acumatica Contact Address TO iPaaS.com: captures the contact's single address as an iPaaS.com Customer Address, as both the primary billing and the primary shipping address.
Child Collection: Add/Update Acumatica Contact Relationship TO iPaaS.com: links the iPaaS.com Customer to the iPaaS.com Company that represents the contact's business account.

Both child collections run automatically with the parent contact transfer and are not invoked independently. To capture an address or a relationship, transfer its parent contact.

System Caveats

Acumatica Caveats

Contact must exist: a Manual Sync for a Contact ID that Acumatica does not return fails with ACUM-NFND-1010. Check the Contact ID and that the contact exists in Acumatica, then run the transfer again with the contact suffix.
Inactive contacts: the poll does not check the contact's Active flag, so inactive contacts that change in Acumatica are captured too. Subscribers who do not want them can add a condition to this collection's filter.
One address and one business account per contact: an Acumatica contact carries a single address and belongs to one business account, so each contact produces at most one iPaaS.com address and one Company relationship.
Address captured only when present: an address is captured only when the contact has at least an address line 1, a city or a postal code. A contact with none of these gets no address in iPaaS.com, and no empty address is created.

iPaaS.com Caveats

Company collection must be active: the Company-first step uses Add/Update Acumatica Company TO iPaaS.com. If that collection is not active in the subscription, no Company is created for the contacts' business accounts: the contacts are transferred as Customers without a company relationship, and a warning is written to the integration log for each transfer.
Custom fields: the Salutation and Acumatica Contact ID custom fields must be configured on the iPaaS.com Customer for their values to be retained.
Email required and unique: iPaaS.com requires an email address on every Customer and does not allow two Customers with the same email. A contact with no email, or with an email already used by an iPaaS.com Customer linked to another Acumatica record, is rejected (see Known Limitations).
The Acumatica address State maps to the iPaaS.com Region field; both represent the state, province or region of the address.
Dynamic formula field references use the Acumatica field names exactly and are case-sensitive.

Integration-Specific Caveats

Contact details on the address: the name, company name and phone number on the captured address come from the contact itself. Company on the address is the company name shown on the contact, the same value the parent collection writes to the Customer Company field.
Designed relationship values: every relationship is captured with Type set to Company and IsPrimary set to true, because an Acumatica contact belongs to one business account and that account's Company is always the contact's primary company.
Read-back linkage: each captured contact, address and relationship is linked to its Acumatica source so repeated transfers update the existing iPaaS.com records rather than creating duplicates.

Setup Requirements

Acumatica Configuration

No Acumatica customization is needed. Contacts, and the customers transferred as Companies, are read through the standard Acumatica web service endpoint (Default) at the version set in the Version setting of the iPaaS.com subscription.

iPaaS.com Configuration

Polling must be configured for the integration so that changed contacts are captured on a recurring cadence; until polling is set up, contacts are captured only by a Manual Sync.
The collection Add/Update Acumatica Company TO iPaaS.com must be active so the Company-first step can create the contact's Company.
The child collections Add/Update Acumatica Contact Address TO iPaaS.com and Add/Update Acumatica Contact Relationship TO iPaaS.com must be active for the address and the Company relationship to be captured with the contact.
The Salutation and Acumatica Contact ID custom fields must be configured on the iPaaS.com Customer.

Authentication & Security

The integration authenticates to the Acumatica instance with OAuth 2.0; the Acumatica company it works in is set by the Connected Application's Client Id. The full authentication walkthrough is covered in the Acumatica Connections and Settings and Acumatica Installation Instructions articles; this document does not repeat it.

Prerequisite Handling

The contact's Company is transferred automatically as a prerequisite. Subscribers do not pre-synchronize Companies for their contacts; the integration handles it as part of the contact transfer, and a failed Company transfer blocks the contact.

Business account is a customer not yet in iPaaS.com: when the contact has a business account and that account is not yet linked to an iPaaS.com Company, the integration reads the account from Acumatica as a customer and sends it to Add/Update Acumatica Company TO iPaaS.com first (that collection's filter and duplicate checks apply). This happens once: later transfers of contacts from the same business account reuse the existing Company and do not send it again.
Business account is not taken as a company: when the Company collection's filter skips the account (for example, an account the subscriber keeps as an iPaaS.com Customer), no Company is created. The contact is transferred as a Customer with no Company relationship, and a warning is written to the integration log.
Company transfer fails with an error: the contact is not transferred and the error ACUM-EXTN-1005 appears in Dashboard / Integration Monitoring / Error Logs, followed by the reason the Company transfer failed when one is available. Correct the cause on the Company (for example, by reviewing the Add/Update Acumatica Company TO iPaaS.com collection) and run the contact transfer again.
Contact with no business account: no Company is transferred and no relationship is captured. The contact is transferred as a Customer, and no error is raised.
Business account that is not a customer (for example, a vendor account), or that cannot be read from Acumatica for any other reason: the integration does not create a Company for it. The contact is transferred as a Customer with no Company relationship, a warning is written to the integration log, and no error is raised. To exclude these contacts, see Mapping Filter.

The Company created this way is documented in Acumatica to iPaaS.com Company Mapping Documentation.

Integration Flow

The integration's customer poll picks up contacts that changed in Acumatica since the last contact poll, or a subscriber runs a Manual Sync with the Contact ID and the contact suffix (for example, 5|contact).
The contact is retrieved from Acumatica by its Contact ID, together with its address and its business account. The collection filter routes it to this collection.
When the contact's business account is not yet linked to an iPaaS.com Company and is an Acumatica customer, the integration sends that customer to the Company collection first (see Prerequisite Handling). When the Company collection's filter skips it, the contact continues without a company relationship; if the Company transfer fails with an error, the contact transfer stops with ACUM-EXTN-1005.
When the contact is not yet linked to an iPaaS.com Customer, the integration looks for the existing, unlinked iPaaS.com Customer with the same email and links the contact to it instead of creating a second record. Whenever the contact is linked to an iPaaS.com Customer, its address and Company relationship that are not yet linked are matched to the ones already on that Customer.
The iPaaS.com Customer is added or updated from the mapped fields. A contact that is already linked by its external ID, or that was linked by email in step 4, updates that Customer; otherwise a new Customer is created. iPaaS.com rejects the contact when it has no email or when its email is already used by another Customer.
The child collections capture the contact's address and its relationship to the Company under the iPaaS.com Customer, and each captured record is linked back to its Acumatica source so later transfers resolve to the same iPaaS.com records.

Mappings

Add/Update Acumatica Contact TO iPaaS.com

iPaaS.com data type: Customer

Mapping Filter

RecordType == "Contact"

Filter Description. Only records that came from an Acumatica Contact are processed by this collection. Records that came from an Acumatica customer are skipped here and are handled by Add/Update Acumatica Customer TO iPaaS.com or Add/Update Acumatica Company TO iPaaS.com, according to the subscriber's split between Customers and Companies. The contact's CustomerClass (the customer class of its business account; empty when the contact has no customer account) can be used in this filter too, for example RecordType == "Contact" && CustomerClass == "COMPANY" to capture only the contacts of companies. Subscribers can add conditions to this filter to capture only some contacts, but the RecordType condition must stay in place. Without it, Acumatica customers would also be processed by this collection and mapped with contact fields.

Contacts of a business account that is not a customer (for example, a vendor account) are transferred as iPaaS.com Customers with no Company relationship. Subscribers who do not want them in iPaaS.com can exclude them with the contact class: assign those contacts a contact class in Acumatica, for example VENDOR, and add a condition on ContactClass to this filter. The same approach excludes any other group of contacts that shares a contact class. With the example class, the filter is:

RecordType == "Contact" && ContactClass != "VENDOR"

Description: Captures the Acumatica contact into the iPaaS.com Customer record.

Mapping Type	Source Field (Acumatica)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`ContactID`	CustomerNumber	Recommended. Copies the Acumatica ContactID (the number only, without the contact suffix; for example, 5). It shows the Contact ID on the iPaaS.com Customer; the link back to Acumatica is the external ID saved after the first transfer, and contacts are not matched by CustomerNumber.
Dynamic Formula	`FirstName`	FirstName	Recommended. Copies the contact's first name. There is no fallback; when the contact has no first name, the captured value is empty.
Dynamic Formula	`LastName`	LastName	Recommended. Copies the contact's last name. There is no fallback; when the contact has no last name, the captured value is empty.
Field	Email	EmailAddress	Required. iPaaS.com requires a valid, unique email address on every Customer. A contact with no email cannot be transferred; add an email to the contact in Acumatica. The email is also what the integration uses to find the existing, unlinked iPaaS.com Customer on the contact's first transfer. A contact whose email is already used by a Customer linked to another Acumatica record cannot be transferred (see Known Limitations).
Field	CompanyName	Company	Recommended. The company name shown on the contact (for a contact of a customer account, the account's name). When the contact has no company name, the value is empty. The link to the contact's Company is set by the relationship child collection, not by this field.
Field	NoteText	Comment	Optional. The note attached to the Acumatica contact. When the contact has no note, the comment is sent empty.
Field	ContactID	Acumatica Contact ID (custom field)	Optional. The Acumatica ContactID, kept as a custom field. A custom field keeps its value when another integration updates the record without mapping it, while standard fields such as CustomerNumber are replaced by whichever integration writes the record last, so the custom field keeps a dependable copy of the Acumatica value.
Dynamic Formula	`Title`	Salutation (custom field)	Optional. Captures the contact's Title (the salutation, for example Mr.). The value mirrors the Acumatica Title: a contact with no Title writes an empty Salutation, and clearing the Title in Acumatica clears it on the next transfer. The custom field must be configured on the iPaaS.com Customer.

Add/Update Acumatica Contact Address TO iPaaS.com

iPaaS.com data type: Customer Address

This child collection has no mapping filter; the address of every contact processed by the parent collection is captured when the contact has an address. It runs as part of the parent contact transfer and is never invoked standalone.

Description: Captures the contact's single Acumatica address into an iPaaS.com Customer Address, marked as both the primary billing and the primary shipping address.

Mapping Type	Source Field (Acumatica)	Destination Field (iPaaS.com)	Description
Field	AddressLine1	Address1	Recommended. The primary street line of the captured address.
Field	AddressLine2	Address2	Optional. Suite, unit or additional street detail.
Field	City	City	Recommended. Part of a complete captured address.
Field	State	Region	Recommended. The Acumatica field is named State but it represents the state, province or region, which iPaaS.com stores as Region.
Field	Country	Country	Recommended. The captured value is in the country format Acumatica stores (for example, US). Important for proper address formatting downstream.
Field	PostalCode	PostalCode	Recommended. Part of a complete captured address.
Field	FirstName	FirstName	Recommended. The contact's first name, for contact identity on the captured address. There is no fallback; when the contact has no first name, the value is empty.
Field	LastName	LastName	Recommended. The contact's last name, for contact identity on the captured address.
Field	CompanyName	Company	Optional. The company name text shown on the contact, the same value the parent collection writes to the Customer Company field. When the contact has no company name, the value is empty.
Field	Phone1	PhoneNumber	Optional. The contact's main phone number, carried on the captured address. When the contact has no Phone 1, the value is empty.
Field	IsPrimaryBilling	IsPrimaryBilling	Recommended. Always true for a contact's address, because it is the contact's only address. Also one of the values compared when the integration looks for an identical address already on an existing iPaaS.com Customer.
Field	IsPrimaryShipping	IsPrimaryShipping	Recommended. Always true for a contact's address, because it is the contact's only address. Also one of the values compared when the integration looks for an identical address already on an existing iPaaS.com Customer.

An address is treated as identical to one already on the iPaaS.com Customer when its address lines, city, region, country, postal code and primary billing and shipping flags all match.

Add/Update Acumatica Contact Relationship TO iPaaS.com

iPaaS.com data type: Customer Relationship

This child collection has no mapping filter; a relationship is captured for every contact processed by the parent collection whose business account is an Acumatica customer that is, or becomes, an iPaaS.com Company. A contact whose account the Company collection's filter does not take as a company is captured without a relationship. It runs as part of the parent contact transfer and is never invoked standalone.

Description: Links the iPaaS.com Customer created from the contact to the iPaaS.com Company that represents the contact's business account.

Mapping Type	Source Field (Acumatica)	Destination Field (iPaaS.com)	Description
Dynamic Formula	See the formula below the table.	RelatedToId	Recommended. Looks up the iPaaS.com Company linked to the contact's BusinessAccount code (for example, AACUSTOMER) and returns its iPaaS.com id; without it the relationship does not point at a Company. When no Company is linked to that business account, the formula returns no value. In normal operation the parent collection has already transferred the Company first, which requires Add/Update Acumatica Company TO iPaaS.com to be active.
Static	`Company`	Type	Recommended. Set to Company by design, recording the relationship as the contact's link to a Company. This collection only ever captures the contact's link to its business account, so the value does not need to change.
Static	`True`	IsPrimary	Recommended. Set to true by design. An Acumatica contact belongs to one business account, so that account's Company is always the contact's primary company in iPaaS.com; keep this value so downstream processes can identify the contact's main company.

The RelatedToId dynamic formula:

var companyId = await GetSpaceportIdAsync(BusinessAccount, "Company", SpaceportSystemId);
if(companyId != null)
return companyId;
return null;

Error Handling

Errors appear in Dashboard / Integration Monitoring / Error Logs. The full list of messages is in Acumatica Error Messages.

Related company could not be transferred first (ACUM-EXTN-1005): The contact's business account is an Acumatica customer that is not yet in iPaaS.com, and its transfer as a Company failed with an error, so the contact is not transferred. An account that the Company collection's filter skips is not an error: the contact is captured without a company relationship. The message is followed by the reason the Company transfer failed when one is available. Resolution: make sure Add/Update Acumatica Company TO iPaaS.com is active, correct the cause on the Company, then run the contact transfer again.
Contact could not be located (ACUM-NFND-1010): Acumatica returned no contact for the Contact ID entered in a Manual Sync. Resolution: check the Contact ID and that the contact exists in Acumatica, then run the transfer again with the contact suffix (for example, 5|contact).
Existing customer could not be linked (ACUM-BIZL-1004): The contact matched an existing iPaaS.com Customer by email, but iPaaS.com did not confirm the link. The message warns that duplicate customer records may result. Resolution: review the matching iPaaS.com Customer and run the contact transfer again.
Existing customer address could not be linked (ACUM-BIZL-1005): The contact's address matched an address already on the iPaaS.com Customer, but iPaaS.com did not confirm the link. Resolution: review the Customer's addresses for duplicates and run the contact transfer again.
Existing customer relationship could not be linked (ACUM-BIZL-1006): The contact's Company relationship matched a relationship already on the iPaaS.com Customer, but iPaaS.com did not confirm the link. Resolution: review the Customer's relationships for duplicates and run the contact transfer again.

iPaaS.com also rejects a contact that has no email (an email address is required on every Customer) or whose email is already used by another iPaaS.com Customer (the email must be unique). Resolution: add an email to the contact in Acumatica, or give the contact its own email, then run the transfer again.

If the Acumatica web service endpoint is temporarily unavailable during a transfer, the capture fails and an error appears in Dashboard / Integration Monitoring / Error Logs; the contact is captured again on the next poll in which it has changed, or by a Manual Sync.

The following situations are handled without an error: a contact with no business account, or with a business account that is not a customer or cannot be read from Acumatica, is transferred with no Company relationship (a warning is written to the integration log in the second case).

Testing & Validation

Test Scenarios

Run a Manual Sync for a contact whose business account is an Acumatica customer not yet in iPaaS.com (for example, 5|contact) and verify that the Company is created first, then the Customer, its address and its relationship to the Company.
Transfer a second contact from the same business account and verify that it is linked to the existing Company and that no second Company is created.
Change a contact field (for example, the last name) in Acumatica and verify that the change is captured on the next poll and updates the same iPaaS.com Customer.
Transfer a contact with no business account and verify that the Customer is created with no Company relationship and no error.
Transfer a contact whose business account is a vendor and verify that the Customer is created with no Company relationship and no error.
Transfer an unlinked contact whose email matches an unlinked iPaaS.com Customer and verify that the contact is linked to that Customer instead of creating a duplicate.
Transfer a contact with no email and verify that it is rejected; add an email in Acumatica and verify that the transfer then succeeds.

Validation Checklist

No custom Acumatica web service endpoint is required; the subscription's Version setting matches an endpoint version available in Acumatica.
Only contacts are processed by this collection, and Acumatica customers are processed by Add/Update Acumatica Customer TO iPaaS.com.
CustomerNumber carries the bare Contact ID and the Customer is linked by the Contact ID with the contact suffix.
Every contact to be transferred has its own email in Acumatica.
The Company field carries the company name shown on the contact.
The address is captured as both the primary billing and the primary shipping address.
The relationship has Type Company, IsPrimary true, and points at the Company of the contact's business account.
The Salutation and Acumatica Contact ID custom fields are configured so their values are retained.

Additional Notes

This collection is capture-only. It never creates or changes a contact, address or business account in Acumatica, and changes made to the Customer in iPaaS.com are not written back to Acumatica through this collection.
Acumatica customers are captured by Add/Update Acumatica Customer TO iPaaS.com, not by this collection.
This collection creates the contact's Company only when it is missing from iPaaS.com. Later changes to the company in Acumatica are sent by a manual transfer in Add/Update Acumatica Company TO iPaaS.com.
The child address and relationship collections run with the parent; they cannot be captured on their own.

Known Limitations

At the time this documentation was written:

Each contact needs its own email. iPaaS.com requires a unique email on every Customer. A contact whose email already belongs to an iPaaS.com Customer linked to another Acumatica record is not linked to that Customer, and because the email is already in use, the contact cannot be transferred; iPaaS.com reports that the email must be unique. Contacts that share an email (for example, a shared mailbox) transfer only once. Give each Acumatica contact its own email before transferring it.
Polling latency. A change to a contact in Acumatica reaches iPaaS.com on the next poll rather than instantly. Subscribers who need an immediate capture can run a Manual Sync.
Starting point for contacts. On a subscription that already polled customers before contacts were added, the contact poll starts from the last customer poll time instead of reading every contact. Contacts that have not changed since then are captured only when they next change in Acumatica or by a Manual Sync.
Empty Salutation. A contact with no Title writes an empty Salutation. Subscribers should validate in a staging environment whether an empty value overwrites a salutation already stored on the iPaaS.com Customer before relying on it in production.
Changing a contact's business account. A contact moved to another business account in Acumatica receives a relationship to the new Company on its next transfer. Subscribers who move contacts between accounts should validate in a staging environment how the relationship to the previous Company is handled.
Deleted contacts. Removing a contact in Acumatica, or clearing its address, is not propagated as a delete in iPaaS.com.

For integration-wide limitations, see Acumatica Known Limitations.

Acumatica to iPaaS.com Contact Mapping Documentation