CRM - API Changes: REST/companyAccounts

❗️

Important changes to rest/companyAccounts tentatively scheduled for April 3, 2023

With the launch of the new Zoey 2023 CRM, there will be some structural database changes made that will impact how data is retrieved from the API. All current endpoints will be supported as-is, but the below changes should be made to support the upgrade.

Important Structural Changes

Billing Address is becoming its own entity

We are adding an entity to the Account called "Bill To". The below changes will outline how we are creating and migrating the data to this new structure. The new entity will make it easier to manage Bill To addresses on an account.

  • Addresses currently marked as "billing and shipping" are being migrated into 2 separate addresses.
  • Account addresses can no longer be both billing and shipping.
  • The new Bill To addresses are global by default (available to all locations, unless flagged to specific locations).
  • The migration will keep existing location restriction so billing addresses without assigned locations will be assigned to a new "Unassigned" location (If "Unassigned" location exists, will use a valid location name with number suffixed like Unassigned_1, Unassigned_2, etc).

Shipping Address & Locations are Merging

Locations and Ship To Addresses will remain separate entities but the below changes will more closely align the two. The Location entity allows labeling a Shipping Address as well as applying specific rules such as allowed methods, and more.

  • A Shipping addresses can no longer be assigned to multiple locations.
  • Shipping addresses assigned to more than 1 location will be split in to multiple addresses during the migration.
  • Shipping addresses not assigned to locations will be assigned to a new "Unassigned" location (similar to Bill To above)

Customer Changes

The "Customer" object is being renamed "Contact" in the web admin and iOS app. For this version of the REST API it will remain "customer" and all endpoints will be supported.

  • A Contact (customer) will only be assigned to an Account (company) - no longer to individual locations.
  • A Contact can be configured to have limited access to one or more Locations with different Roles for each location.
  • Location Role is being removed for customers assigned to both company and location.
  • The concept of "Account Owner" is changing to a new designation of "Main Contact" or "Additional Contact"
  • Main Contacts will be assigned to a Main Contact Role
  • There can be multiple Main Contact Roles and multiple Additional Contact Roles
  • The Account Owner settings are being deprecated - previously assigned role (owner settings) will continue to work (will be displayed as "(Legacy Account Role)"), but can no longer be edited. to edit the role of a main contact customer, a main contact role will need to be assigned.

Account Customer Group will Override Customer's Customer Group

The Customer Group assigned to the Account will override what is assigned to the customer. On the Web Portal, if a Contact (customer) belongs to multiple accounts, they will have an "Account Switcher" at the top of their browser window.

API Changes

BREAKING CHANGES

Customer settings removedmain contact role was created to replace customer settings like customer_email_setting, customer_manage_address_setting" etc...

Deprecated settings will be available for read-only.
Setting them will not be supported (keys will be ignored), consumer should assign main contact roles to main contacts instead.
billing,shipping addresses - No longer supported READ - will return 2 addresses instead of 1
UPDATE - "billing,shipping" will not be supported.
* CREATE - will split 1 address to 2
Bill To Address CREATE - will default to is_global - yes
READ - Consumer will need to check is_global value to see if billing is global or restricted to locations.
Ship To Address - can no longer be assigned to multiple locations READ - will return multiple addresses instead of 1
UPDATE - assigning to >1 location will not be supported.
* CREATE - will not be supported - consumer will need to submit an address per location. **

** Shipping Address and Location merging means there should not be an instance where two different locations have the same shipping address. This was also true in the old data-model but not enforced so we do not believe this will be a major change, simply enforcing a model that makes sense.

NON-BREAKING CHANGES

typetype of account - (0: account, 1: opportunity 2: lead)
will return accounts of all types if not specified
opportunity_statusstatus for the opportunity (new, assigned, working, qualified, disqualified, closing, won, lost)
lead_statusstatus for the lead (new, assigned, working, qualified, disqualified, closing, won, lost)
new_customer_group_id is renamed to customer_group_idBoth keys will be supported, but please upgrade to new name.
is_default_billing key changed to is_default_billing_addressBoth keys will be supported, but please upgrade to new name.
is_default_shipping key changed to is_default_shipping_addressBoth keys will be supported, but please upgrade to new name.
RolesA scope filter will be added (0: roles, 2: main contact roles) - will return both roles and main contact roles if scope is not specified
Customers is_main - new key - specifies if a contact is a main contact (1: yes, 0: no)
is_main_contact key changed to is_default_main - Both keys will be supported, but please upgrade to new name.
Notesnew endpoint/param will be added to get "Notes" a new feature shipping with the Zoey 2023 CRM.

📘

Questions about the changes?

If you have any questions about the API changes above, please Create a Support Request

Be sure to include the full Request and Response for the endpoints you have questions about.