Summary
iPaaS.com Customer records can be captured from Acumatica using an Add/Update sync method. This mapping reads the Acumatica Customer's main and primary contact data — customer number, name, email, and company — and builds an iPaaS.com Customer record, carrying the customer's addresses through a child collection. Capture is polling-based, with an on-demand Manual Sync; writing customers back into Acumatica is handled by a separate article.
Customers and Companies
In Acumatica, customers and companies are the same record: the customer business account (the Customers form, screen AR303000). Two collections read that record:
Add/Update Acumatica Customer TO iPaaS.com writes an account as an iPaaS.com Customer.
Add/Update Acumatica Company TO iPaaS.com writes an account as an iPaaS.com Company.
The customer poll and the company poll both return every account changed in Acumatica, so each account reaches both collections. The integration does not decide which accounts are companies: the subscriber does, with the mapping filters of the two collections. The filters should be complementary, so that every account matches exactly one of them.
Base the split on a value that is set on purpose in Acumatica, such as the Customer Class, and not on anything that changes as users work, such as whether the account has contacts. The two collections come with a split on the customer class COMPANY:
Add/Update Acumatica Company TO iPaaS.com: CustomerClass == "COMPANY"
Add/Update Acumatica Customer TO iPaaS.com: RecordType != "Contact" && CustomerClass != "COMPANY"
The Customer collection's filter is evaluated for Acumatica contacts as well, so it can only use values that both customer accounts and contacts have. Acumatica contacts carry the Customer Class of their business account, which makes it the value to split on; a filter on another account value, such as an attribute, makes every contact transfer fail with a filter error. Until accounts are placed in a customer class named COMPANY in Acumatica, every account is transferred as an iPaaS.com Customer and none as a Company. To split on a different value, change both filters together so they stay complementary.
ID Format
Manual Sync ID Format
When manually transferring a customer, supply the exact Acumatica CustomerID. For example, entering 10 captures the customer whose Acumatica CustomerID is 10. The integration resolves the value to the underlying record.
External ID Format
Each captured customer and address is linked back to its Acumatica source so that later transfers resolve to the same iPaaS.com record rather than creating a duplicate.
Deleted Record Support
Removal of a Customer 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
The parent collection captures two custom fields on the iPaaS.com Customer, Acumatica Customer ID and Acumatica Tax Id Number. 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. The child address collection captures one custom field, Acumatica Primary Contact, which records whether the captured address is the Acumatica main (primary) contact. All three custom fields must be configured in iPaaS.com for their values to be retained.
Mapping Collection Status
Status: Enabled
Trigger Events: The integration periodically polls Acumatica for customer accounts that have changed since the last successful poll and sends each one to this collection; the mapping filter decides which of them are captured as Customers. The same poll also reads Acumatica contacts that have changed; this collection's filter skips them, and they are captured by Add/Update Acumatica Contact TO iPaaS.com instead. A subscriber can also run a Manual Sync to capture a specific customer on demand. There are no external webhooks for this collection — Acumatica does not push customer changes to the integration.
Duplicate or Conflicting Mappings
This collection captures Customers from Acumatica into iPaaS.com. The following collections also operate on iPaaS.com Customer records:
Add/Update Acumatica Contact TO iPaaS.com: Captures Acumatica contacts 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. It is documented in Acumatica to iPaaS.com Contact Mapping Documentation.
Add/Update Acumatica Company TO iPaaS.com: Reads the same Acumatica customer accounts and writes them as iPaaS.com Company records (see Customers and Companies above). It is documented in Acumatica to iPaaS.com Company Mapping Documentation.
Add/Update Acumatica Customer FROM iPaaS.com: Writes Customer records from iPaaS.com into Acumatica, in the opposite direction.
Before enabling this inbound collection alongside the outbound "From iPaaS.com" customer collection, 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.
The Collision Handling Method setting is not used for the Acumatica Customer entity; customers are linked by their Acumatica identifier. A customer that is not yet linked is linked to an existing iPaaS.com Customer that has the same email and is not linked to another Acumatica record; that Customer is then updated instead of a second one being created. Customers are never matched by customer number: an iPaaS.com Customer that only has the same customer number is not taken over, and a second Customer with that number is created. An iPaaS.com Customer that already uses the email but is linked to another Acumatica record is not taken over either, and because iPaaS.com requires a unique email on every Customer, the transfer then fails.
Supported Child Collections
Parent Collection: Add/Update Acumatica Customer TO iPaaS.com — builds the iPaaS.com Customer record from the Acumatica main and primary contact data.
Child Collection: Add/Update Acumatica Customer Address TO iPaaS.com — captures the customer's addresses from Acumatica into iPaaS.com as part of the parent transfer. It runs automatically with the parent Customer capture and is not invoked independently.
System Caveats
Acumatica Caveats
API access must be enabled for the Acumatica Customer and Contact endpoints so the integration can expand the main and primary contacts during capture.
Acumatica enforces length and format constraints on fields such as the customer name (50 characters by default). Values that exceed Acumatica's limits are stored truncated and are captured as stored.
An Acumatica contact address is captured only when its core fields (line 1, city, state, postal code, country) are populated together; a partial contact address may not be captured as a complete record.
iPaaS.com Caveats
iPaaS.com expects a valid email format for the captured email address; malformed values are rejected and logged.
The Acumatica address State maps to the iPaaS.com Region field; both represent the state, province, or region of the address.
The Acumatica Primary Contact value is captured into a custom field on the iPaaS.com address; the corresponding custom field must be configured in iPaaS.com for the value to be retained.
Dynamic formula field references use the Acumatica response field names exactly as they appear on the expanded Customer record, and these references are case-sensitive.
Integration-Specific Caveats
Main contact precedence with fallback. Name and email are read from the Acumatica main contact first. When the main contact value is empty, email falls back in order to the primary contact, then the billing contact, then the shipping contact email, and first name falls back to the customer name. The last name has no fallback — when the main contact has no last name, the captured value is empty.
Per-contact capture. Addresses are captured from each populated Acumatica contact slot (main, billing, shipping) and carried into iPaaS.com with the matching primary flags so each address keeps its role.
Read-back linkage. Each captured customer and address is linked to its Acumatica source so repeated transfers update the existing iPaaS.com record rather than creating duplicates.
Matching by email only. A customer that is not yet linked is matched to an existing, unlinked iPaaS.com Customer by the first email found on the main, primary, billing, then shipping contact (what the shipped EmailAddress mapping writes; the match keeps this order even if the mapping is changed), never by customer number. A customer with no email, or whose email no unlinked iPaaS.com Customer has, creates a new Customer.
Setup Requirements
Acumatica Configuration
API access must be enabled for the Acumatica Customer and Contact endpoints.
iPaaS.com Configuration
An active iPaaS.com Customer mapping collection must exist.
Polling must be configured so that changed Acumatica Customers are captured on a recurring cadence; until polling is set up, customers are captured only by a Manual Sync.
The Acumatica Primary Contact custom field must be configured for that designation to be retained.
The Acumatica Customer ID and Acumatica Tax Id Number custom fields must be configured on the iPaaS.com Customer for their values to be retained.
The child collection Add/Update Acumatica Customer Address TO iPaaS.com must be active for addresses to be captured with the 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.
Integration Flow
The integration polls Acumatica for changed customer accounts, or a subscriber runs a Manual Sync with the Acumatica CustomerID. The mapping filter decides whether the account is captured as a Customer.
The Customer is retrieved from Acumatica and its main, primary, billing, and shipping contacts and addresses are expanded.
An iPaaS.com Customer record is built from the mapped fields. Name and email are sourced primarily from the main contact, with fallbacks where the main contact value is absent.
If a Customer with the same external link already exists in iPaaS.com, the existing record is updated; otherwise a new Customer is created.
Each captured customer and address is linked back to its Acumatica source so later transfers resolve to the same iPaaS.com record.
Mappings
Add/Update Acumatica Customer TO iPaaS.com
Mapping Filter
RecordType != "Contact" && CustomerClass != "COMPANY"
Filter Description. The filter splits accounts by customer class: accounts in the customer class COMPANY go to Add/Update Acumatica Company TO iPaaS.com, and every other account is captured here (see Customers and Companies). Until accounts are placed in that class, every account is captured here. Records that came from an Acumatica contact are skipped here and are handled by Add/Update Acumatica Contact TO iPaaS.com, because the integration's customer poll and Manual Sync also deliver Acumatica contacts as iPaaS.com Customer records. The RecordType condition must stay in place so Acumatica contacts are not mapped with customer fields. Because the filter is evaluated for contacts too, it can only use values that contacts also carry, such as CustomerClass.
Description: Captures the parent Customer record from Acumatica's main and primary contact data into iPaaS.com.
Mapping Type | Source Field (Acumatica) | Destination Field (iPaaS.com) | Description |
Field | CustomerID | CustomerNumber | Required. iPaaS.com requires a customer number on every Customer. Shows the Acumatica Customer ID on the iPaaS.com Customer. iPaaS.com links the customer to its Acumatica source through a dedicated external-ID record, which routes every later transfer. CustomerNumber is not used to match an existing iPaaS.com Customer: an unlinked Customer with the same number is not linked, and a second Customer with that number is created. |
Dynamic Formula |
| FirstName | Recommended. Captures the main contact first name; when it is absent, falls back to the customer name so a usable value is still captured. |
Dynamic Formula |
| LastName | Recommended. Captures the main contact last name. The live formula has no fallback — when the main contact has no last name, the captured value is empty. Ensure the Acumatica main contact carries a last name, or validate the empty-value behavior in a staging environment before relying on it in production. |
Dynamic Formula |
| EmailAddress | Required. iPaaS.com requires a valid email address on every Customer. Captures the main contact email; when it is absent, falls back in order to the primary, billing, then shipping contact email so the email is captured regardless of which contact carries it. iPaaS.com expects a valid email format; malformed values are rejected and logged. When all four are absent, the captured value is empty. |
Dynamic Formula |
| Company | Recommended. Captures the main contact company name. There is no fallback; when the main contact has no company name, the captured value is empty. |
Dynamic Formula | See the formulas below the table. | Comment | Optional. The note attached to the Acumatica customer. When the customer has no note, the comment is sent empty. |
Field | CustomerID | Acumatica Customer ID (custom field) | Optional. The Acumatica Customer ID, 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 | See the formulas below the table. | Acumatica Tax Id Number (custom field) | Optional. The Acumatica customer's Tax Registration ID, kept as a custom field. When the customer has no tax registration ID, the value is sent empty. |
The Comment dynamic formula:
return string.IsNullOrEmpty(CustomerResponse?.note?.Value) ? null : CustomerResponse.note.Value;
The Acumatica Tax Id Number dynamic formula:
return string.IsNullOrEmpty(CustomerResponse?.TaxRegistrationID?.Value) ? null : CustomerResponse.TaxRegistrationID.Value;
Add/Update Acumatica Customer Address TO iPaaS.com
This child collection has no mapping filter; every address found on the parent customer's contacts is captured. It runs as part of the parent Customer capture and is never invoked standalone.
Description: Captures each populated Acumatica contact address (main, billing, shipping) into an iPaaS.com address, carrying its primary flags so the address keeps its role.
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 | PostalCode | PostalCode | Recommended. Part of a complete captured address. |
Field | Country | Country | Recommended. The captured value is in the country format Acumatica stores (for example, |
Dynamic Formula |
| FirstName | Recommended. Captures the contact first name; when it is absent, falls back to the contact display name so a usable name value is captured. |
Field | LastName | LastName | Recommended. Contact identity on the captured address. |
Field | CompanyName | Company | Recommended. The business name associated with the address, most relevant for the main contact. |
Field | Phone1 | PhoneNumber | Optional. A contact phone on the captured address. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. Marks the address captured from the Acumatica billing contact as the primary billing address, preserving the role for a later outbound transfer. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. Marks the address captured from the Acumatica shipping contact as the primary shipping address, preserving the role for a later outbound transfer. |
Field | IsPrimaryContact | Acumatica Primary Contact | Recommended. Captures whether the address is the Acumatica main (primary) contact into a custom field. This designation lets a later outbound transfer route the address back to the Acumatica main contact slot. The custom field must be configured in iPaaS.com for the value to be retained. |
Error Handling
Missing CustomerID: The capture fails because the Acumatica Customer has no CustomerID, so iPaaS.com cannot identify the record. Resolution: ensure every Customer in Acumatica has a unique CustomerID before transferring.
Invalid email format: The captured email does not follow a standard format. Resolution: correct the email in Acumatica. The integration rejects invalid emails and logs an error.
String length exceeded: The customer name is longer than the default 50-character limit. Resolution: shorten the name or extend the field length in Acumatica via customization. The captured value reflects what Acumatica stores.
Null contact data: The main contact has no first or last name and no usable fallback is available. Resolution: populate the Acumatica main contact, or rely on the customer-name fallback for the first name.
If the Acumatica web services endpoint is temporarily unavailable during a transfer, the capture fails and an error appears in Dashboard / Integration Monitoring / Error Logs; the customer is re-captured on the next poll or manual sync.
Testing & Validation
Test Scenarios
Capture a new Acumatica Customer with main, billing, and shipping addresses and verify all fields and address roles in iPaaS.com.
Update a contact field on an existing Acumatica Customer and verify the change is captured on the next poll.
Capture a Customer whose main contact has no last name and confirm the captured LastName is empty (no fallback).
Run a Manual Sync using the exact Acumatica CustomerID and confirm the customer is captured.
Capture a Customer with addresses on multiple contact slots and verify each is captured with its primary flags.
Validation Checklist
Every Acumatica Customer produces a non-empty CustomerID.
The first-name and email fallbacks behave as expected.
The last-name field is empty only when the main contact has no last name.
Captured emails are in a valid format.
The Acumatica Primary Contact custom field is configured so the designation is retained.
The Acumatica Customer ID and Acumatica Tax Id Number custom fields are configured on the iPaaS.com Customer.
Additional Notes
This collection is capture-only. Changes made to a Customer in iPaaS.com are not written back to Acumatica through this collection.
Because capture is polling-based, a change in Acumatica is reflected in iPaaS.com on the next poll rather than instantly. Subscribers who need an immediate capture can run a Manual Sync.
The child address collection runs with the parent; it cannot be captured on its own.
Related Documents
Related Mapping Documentation