Accounts

Accounts represent the constituents of an organization using NeonCRM, and as such are the primary type of record in NeonCRM.

Types of Accounts

There are two types of accounts: individual and company.

Individual Accounts

An individual account is a record representing one person. An individual account contains a name, contact information, login details, and other pieces of data that are properties of the person.

Company Accounts

A company account is a record representing a business or organization. Like individuals, company accounts have fields representing properties of the company. However, a company does not have contact information fields, such as email and phone number. These fields are properties of the company's contacts.

"Company" vs. "Organization"

Company accounts were previously known organization accounts. This naming convention was changed in 2019 to avoid confusion with the organization itself that uses NeonCRM. Note that you may still find references to "organization" accounts in older documentation and certain methods in API v1.

Individual & Company Types

Within the two categories detailed above, accounts can also be categorized into customizable sub-types, known as individual types and company types. This types are configured in Global Settings and can be retrieved through the API.

Account Relationships

There are three types of account relationships in NeonCRM, but only the two most common are exposed to the API:

  1. Company relations
  2. Household relations
  3. Account relations (Not in the API)

Company and household relationships are accompanied by a secondary record, known as the contact record, which help tie the individuals and companies together.

Company Contacts

A company can have multiple linked contacts, one of which must be the primary contact. The primary contact is created when the company account is created and can be changed later. If linked to a company, an individual account will also have a twined  contact record, which sits between the individual and the company records and contains an email address, mailing address, and phone numbers pertinent to the individual’s relationship with the company.

When linking an individual to a company, the contact record is created automatically, so you do not need to create contacts when linking.

Individual-Contact-Company Relationship
Individual-Contact-Company Relationship

Households & Household Contacts

Similar to company accounts, households group together individual accounts that are part of a common household. Like company accounts, households also have contact records that can be standalone or link individuals to the household. However, unlike company accounts, households are not accounts themselves and cannot have custom properties or "own" transactions.

Managing Duplicate Accounts

When pushing data into NeonCRM from your app, it is important to consider duplicates. Duplicate accounts can be a major source of frustration for users and should be avoided.

Account Match & Partial Match Queue v2 only

NeonCRM’s Account Match & Queue will automatically check accounts coming into the database from the NeonCRM API v2 to find existing accounts with the same identity. If the names and email addresses match, the accounts will be automatically merged together by the Account Match feature. If the accounts are very close—say, email and phone match but not name—the accounts will be entered into the Partial Match Queue. Matches in the queue can be merged together by users in the NeonCRM UI under Tools > Duplicate Management.

Learn more about NeonCRM's Account Match & Queue feature.

The Account Match & Queue functionality is only available for accounts created via API v2 in NeonCRM systems where the feature has been enabled. If you are using API v2, include instructions in your documentation to recommend that users enable the feature to avoid creating duplicate accounts. If you are using API v1, check for existing accounts first before creating new accounts.

Handling HTTP 222 Merged Account

If you are working in NeonCRM systems where the Account Match & Queue functionality is enabled, you may occasionally receive the HTTP success status 222 Merged Account in the response to an API v2 request. This status indicates that the account ID you provided in your request has since been merged into another account by the Account Match & Queue feature.

Note that this is a 200-level status. NeonCRM handles the account merge logic, so strictly speaking, no further action is required from your app in order to complete the operation. In fact, your app could continue to use the old account ID for all subsequent requests, and you would continue to receive successful 222 Merged Account responses. However, it is recommended that you update any internal state in your app to use the new account ID provided in the accountId field of the body associated with a 222 response. NeonCRM users are accustomed to referencing account IDs, and if your app displays account IDs to users—even if it is just in the URL path—you should always display the same ID that is displayed in NeonCRM.

Check for Duplicate Accounts

When creating accounts, your app can check for existing accounts in NeonCRM using one of the account retrieval methods. Your duplicate logic should never use name alone as a matching criterion for finding duplicates. Email address is the only field where a single match criterion is recommended.

Here are some good duplicate matching criteria, in order from most ideal to less ideal:

  1. Name + Email
  2. Email
  3. Name + Address

API Reference

API methods related to accounts.