> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehatchapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AccuLynx v2

> What Hatch's AccuLynx v2 integration is, how it works, and where to begin.

### What does the AccuLynx v2 integration do?

Hatch offers a native integration with AccuLynx that you can activate within the App
Marketplace (located in your Hatch workspace). This integration syncs AccuLynx jobs — along with the contacts,
estimates, calendar appointments, representatives, and job financials attached to them — into Hatch so you can target
them in campaigns, and logs Hatch activity back into AccuLynx as job messages.

AccuLynx v2 combines two delivery paths:

* **Real-time updates** — AccuLynx notifies Hatch when a contact is created or updated, and when a job is
  updated.
* **Scheduled reads** — Hatch reads jobs, estimates, calendar appointments, representatives, users, and job
  financials from AccuLynx every **5 minutes**.

When the integration is first installed, Hatch automatically runs a 90 day back-sync of your AccuLynx data.

The AccuLynx **job** is the center of the model. Every other record Hatch reads is tied back to the job it belongs
to, and to that job's primary contact — that contact's name, phone, and email are what Hatch campaigns reach.

### How do you set up the integration?

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* AccuLynx account with location administrator *or* company administrator privileges
* An AccuLynx API key for the location you want to connect

#### **Setup Steps**

1. In Hatch, open the **App Marketplace**.
2. Under the **CRMs** filter, click the Connect button for **AccuLynx v2**.
3. In the setup window, click **Install**.
4. AccuLynx authenticates with an API key (not OAuth). Paste the API key for the AccuLynx location you are
   connecting.
   1. The necessary API key can be generated in AccuLynx: Account Settings > Add-ons and Integrations > API Keys
5. Enable the objects Hatch will read — **Contacts**, **Jobs**, **Estimates**, **Calendar Appointments**,
   **Representatives**, **Users**, and **Job Financials**.
6. On the **Select Fields** step, confirm the field selections for each object. Required fields are pre-selected for
   you; all remaining AccuLynx fields, **including your custom fields**, must be enabled by checking them off. To
   enable all fields for an object, choose "Select all optional fields."
7. Review your configuration, then click **Create Integration** to finish.
8. Once activated, a 90 day back-sync of your AccuLynx data will automatically initiate.
9. After the back-sync completes, set up your audience and campaign workflow to launch your AccuLynx contacts into a
   campaign.

### When does Hatch sync data to/from AccuLynx?

#### AccuLynx → Hatch

AccuLynx data reaches Hatch three ways:

* **Real time** — when an AccuLynx **contact** is created or updated, or an AccuLynx **job** is updated, AccuLynx
  notifies Hatch and the record is ingested immediately.
* **Every 5 minutes** — Hatch reads **jobs**, **estimates**, **calendar appointments**, **representatives**,
  **users**, and **job financials** that have changed since the last read.
* **On install** — a 90 day back-sync of all object types runs automatically.

#### Hatch → AccuLynx

**Sync Communications**

Hatch events and communications can be synced to AccuLynx based on the configuration options selected on the
integration. When enabled, Hatch logs the activity as a comment in the **Job Messages** of the AccuLynx job the
activity belongs to.

<Note>
  Push communications occur instantaneously. There must be an AccuLynx job opportunity in Hatch at the time of the
  communication event in order for it to succeed — activity that isn't attached to an AccuLynx job is not logged.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### What AccuLynx data is available in Hatch?

#### Selecting Object Resources

Object selection happens during setup. Hatch reads the AccuLynx resources below, and for each one a small set of
required fields is pre-selected (the fields Hatch maps to its standard fields). Every other field AccuLynx returns
for those objects, **including your custom fields**, can be enabled during setup.

<Note>
  AccuLynx object names and Hatch object names differ. An AccuLynx **job** is an `opportunity` in Hatch, and AccuLynx
  **representatives** and **users** are both `employee` records in Hatch. The detail field prefixes below follow the
  AccuLynx names.
</Note>

| AccuLynx Resource       | Detail Prefix     | What it contains                                                       |
| ----------------------- | ----------------- | ---------------------------------------------------------------------- |
| Jobs                    | `job:`            | The AccuLynx job record, plus any custom fields defined on the job     |
| Contacts                | `contact:`        | The AccuLynx contact record, plus any custom contact fields            |
| Estimates               | `estimate:`       | The job's estimates, their sections, and their financials              |
| Calendar Appointments   | `appointment:`    | Appointments on the AccuLynx calendar, tied to their job               |
| Representatives / Users | `representative:` | The people assigned to the job, and AccuLynx users                     |
| Job Financials          | `financial:`      | Job-level financial totals, such as approved job value and balance due |

#### Available Resource Fields

Every field AccuLynx returns for these resources lands in the matching opportunity's details, under the prefix listed
above. Custom fields are included. Nested values are joined with a colon (`estimate:financials:totalPrice`), and
repeated values are numbered starting at 1 (`contact:phoneNumbers:1:number`). By default a field is treated as
**text**.

The fields listed below are the exception: Hatch recognizes them as **dates, numbers, or true/false values**, so you
can build audience rules on them using date ranges and numeric comparisons rather than text matching. Any AccuLynx
field that isn't on this list — including all of your custom fields — is still available, as text.

| Resource       | Field Name                                             | Data Type |
| -------------- | ------------------------------------------------------ | --------- |
| Job            | `job:contacts:1:isPrimary`                             | Boolean   |
| Job            | `job:createdDate`                                      | Date      |
| Job            | `job:locationAddress:country:id`                       | Number    |
| Job            | `job:locationAddress:state:id`                         | Number    |
| Job            | `job:milestoneDate`                                    | Date      |
| Job            | `job:modifiedDate`                                     | Date      |
| Contact        | `contact:billingAddress:country:id`                    | Number    |
| Contact        | `contact:billingAddress:state:id`                      | Number    |
| Contact        | `contact:mailingAddress:country:id`                    | Number    |
| Contact        | `contact:mailingAddress:state:id`                      | Number    |
| Contact        | `contact:phoneNumbers:1:primary`                       | Boolean   |
| Contact        | `contact:phoneNumbers:1:smsOptOut`                     | Boolean   |
| Estimate       | `estimate:createdBy:role:id`                           | Number    |
| Estimate       | `estimate:createdDate`                                 | Date      |
| Estimate       | `estimate:financials:overheadRate`                     | Number    |
| Estimate       | `estimate:financials:overheadTotal`                    | Number    |
| Estimate       | `estimate:financials:profitRate`                       | Number    |
| Estimate       | `estimate:financials:profitTotal`                      | Number    |
| Estimate       | `estimate:financials:taxRate`                          | Number    |
| Estimate       | `estimate:financials:taxTotal`                         | Number    |
| Estimate       | `estimate:financials:totalCost`                        | Number    |
| Estimate       | `estimate:financials:totalPrice`                       | Number    |
| Estimate       | `estimate:isPrimary`                                   | Boolean   |
| Estimate       | `estimate:modifiedBy:role:id`                          | Number    |
| Estimate       | `estimate:modifiedDate`                                | Date      |
| Estimate       | `estimate:profitMarginRate`                            | Number    |
| Estimate       | `estimate:profitMarginTotal`                           | Number    |
| Estimate       | `estimate:sections:1:createdDate`                      | Date      |
| Estimate       | `estimate:sections:1:modifiedDate`                     | Date      |
| Estimate       | `estimate:sections:1:profitMarginRate`                 | Number    |
| Estimate       | `estimate:sections:1:profitMarginTotal`                | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:overheadRate`   | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:overheadTotal`  | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:profitRate`     | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:profitTotal`    | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:taxRate`        | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:taxTotal`       | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:totalCost`      | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:totalPrice`     | Number    |
| Appointment    | `appointment:allDay`                                   | Boolean   |
| Appointment    | `appointment:end`                                      | Date      |
| Appointment    | `appointment:start`                                    | Date      |
| Representative | `representative:role:id`                               | Number    |
| Financial      | `financial:approvedJobValue`                           | Number    |
| Financial      | `financial:balanceDue`                                 | Number    |
| Financial      | `financial:worksheetSectionTotals:changeOrderTotal`    | Number    |
| Financial      | `financial:worksheetSectionTotals:discountTotal`       | Number    |
| Financial      | `financial:worksheetSectionTotals:insuranceClaimTotal` | Number    |
| Financial      | `financial:worksheetSectionTotals:supplementTotal`     | Number    |
| Financial      | `financial:worksheetSectionTotals:upgradeTotal`        | Number    |
| Financial      | `financial:worksheetSectionTotals:workNotDoingTotal`   | Number    |
| Financial      | `financial:worksheetSectionTotals:worksheetTotal`      | Number    |

#### Standard Field Mapping

Hatch standard fields are mapped from AccuLynx detail fields as detailed below. Each AccuLynx record Hatch reads
carries the contact information of the job it belongs to, so every record is reachable by a campaign.

**Job Opportunity**

<Note>
  The base object of this opportunity model is the AccuLynx **Job**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the AccuLynx **Job** record.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                    |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| **External ID**                                                | `job:id`                                                 |
| **External Contact ID**                                        | `contact:id` *(the job's primary contact)*               |
| **External Created At**                                        | `job:createdDate`                                        |
| **External Updated At** *(used for Hatch opportunity sorting)* | `job:modifiedDate`                                       |
| **First Name**                                                 | `contact:firstName` *(the job's primary contact)*        |
| **Last Name**                                                  | `contact:lastName` *(the job's primary contact)*         |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*    |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)* |
| **Status**                                                     | `job:currentMilestone`                                   |

**Contact Opportunity**

<Note>
  The base object of this opportunity model is the AccuLynx **Contact**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the AccuLynx **Contact** record.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                    |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| **External ID**                                                | `contact:id`                                             |
| **External Contact ID**                                        | `contact:id`                                             |
| **External Created At**                                        | the time Hatch first received the contact                |
| **External Updated At** *(used for Hatch opportunity sorting)* | the time Hatch last received the contact                 |
| **First Name**                                                 | `contact:firstName`                                      |
| **Last Name**                                                  | `contact:lastName`                                       |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*    |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)* |
| **Status**                                                     | *not set — AccuLynx keeps status on the job*             |

**Estimate, Appointment, Representative, and Financial Opportunities**

<Note>
  The base object of these opportunity models is the AccuLynx **Estimate**, **Calendar Appointment**,
  **Representative**, or **Job Financial** record. AccuLynx links each of these to a job rather than directly to a
  person, so Hatch fills the contact fields from that job's primary contact.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **External ID**                                                | the AccuLynx ID of the record itself (`estimate:id`, `appointment:id`, `representative:id`, or the financial record's ID) |
| **External Contact ID**                                        | `contact:id` *(the primary contact of the job the record belongs to)*                                                     |
| **External Created At**                                        | the time Hatch first received the record                                                                                  |
| **External Updated At** *(used for Hatch opportunity sorting)* | the time Hatch last received the record                                                                                   |
| **First Name**                                                 | `contact:firstName` *(the job's primary contact)*                                                                         |
| **Last Name**                                                  | `contact:lastName` *(the job's primary contact)*                                                                          |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*                                                                     |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)*                                                                  |
| **Status**                                                     | *not set — AccuLynx keeps status on the job*                                                                              |

<Note>
  A contact can hold several phone numbers in AccuLynx, so Hatch picks one using this order of preference: primary
  Mobile, then any Mobile, then primary Home, then primary Work, then primary Unspecified, then any Unspecified.
</Note>

### FAQ

<AccordionGroup>
  <Accordion title="How often does my AccuLynx information sync with Hatch?">
    Contact creates and updates, and job updates, are pushed to Hatch in real time by AccuLynx. On top of that, Hatch
    reads jobs, estimates, calendar appointments, representatives, users, and job financials every 5 minutes so nothing
    is missed.
  </Accordion>

  <Accordion title="Do I need to enable each object in order to sync data?">
    Yes. Objects are enabled during setup, and only the objects you enable — with the fields you select for each —
    are read from AccuLynx. Jobs and contacts are what produce the opportunities you target in campaigns; the remaining
    objects add estimate, appointment, representative, and financial detail you can build audience rules on.
  </Accordion>

  <Accordion title="Are my custom AccuLynx fields available in Hatch?">
    Yes. Every field AccuLynx returns for the objects you enable is available, including custom fields, as long as
    you check the field off during setup. Custom fields come through as text.
  </Accordion>

  <Accordion title="I have multiple AccuLynx locations — how should I connect them?">
    AccuLynx issues a separate API key per location, and a Hatch integration accepts a single API key. Create a
    separate Hatch department for each AccuLynx location and install AccuLynx v2 in each one. That mirrors how AccuLynx
    keeps contact data separate between locations.
  </Accordion>

  <Accordion title="I'm currently using the original AccuLynx integration, can I move to AccuLynx v2?">
    Not yet. Migration from AccuLynx v1 to AccuLynx v2 will be at a later date.
  </Accordion>
</AccordionGroup>