AccountTECH — Darwin Cloud Integration1

Version 1.0

This document defines the required data format, delivery methods, and field mappings for third-party vendors providing transactional, agent, and lead-source data to Darwin Cloud. Adhering to these specifications ensures reliable data matching, accounting accuracy, and minimal manual intervention during integration.

This specification covers three primary data flows:

• Transaction data — residential and commercial property transactions, including agents, commissions, ancillary participants, and referrals.
• Agent roster information — for vendor systems that do not implement roster sync.
• Buyer / seller lead-source data — for CRM and lead-tracking systems.

1. Transaction Data

Vendors provide transaction records in a single unified schema unless a separate schema is explicitly agreed upon during intake. Each record represents a single deal attempt on a property — pending, closed, or cancelled — and includes agent identifiers, commissions, property details, closing information, and any associated ancillary participants (title company, mortgage company, home warranty, etc.).

1.1 Transaction Lifecycle: Listing ID vs. Transaction ID

Most vendor systems model the property lifecycle with two distinct identifiers, and Darwin needs both:

• Listing ID — persistent for the life of the listing. It does not change when a deal falls through and the property is re-marketed.
• Transaction ID — created when a deal goes pending / under contract. If that deal falls through, the vendor typically cancels that Transaction ID and creates a new Transaction ID against the same Listing ID when the property re-lists.

If your system works this way, both identifiers are required. Provide the Listing ID on every record so Darwin can correlate multiple deal attempts on the same property.

How Darwin handles this on our end:

Darwin does not have a separate "listing" entity tied to a transaction. Darwin has a single Property record. The mapping works as follows:

• A pending/active transaction maps to a Darwin Property record. The vendor Transaction ID is stored as the external reference (guid 3 on the Links tab) and the Listing ID is retained for audit correlation.
• When a transaction comes through as cancelled on an incremental pull, Darwin cancels (does not delete) the corresponding Property record.
• If the vendor later sends a new Transaction ID against the same Listing ID, Darwin creates a new Property record linked to the new Transaction ID, while both Darwin Property records continue to reference the same vendor Listing ID.

Why we model it this way: We deliberately keep a separate Property record for each deal attempt so the brokerage retains a complete record of every buyer and seller engaged on the property — including the lost revenue when a deal falls through. Cancelled deals must therefore flow to us (not be silently dropped), with the cancellation reason and date, so we can report on them.

1.2 Core Transaction Fields

1.3 DateTime & Timezone Declaration

The DateTime fields above (modified_date, cancellation_date) carry a time component and must have a declared timezone. Complete the following during onboarding:

• Are all DateTime values delivered in UTC (Zulu / GMT)? ☐ Yes ☐ No
• If local time, specify the IANA timezone: ______________________ (e.g., America/New_York, America/Los_Angeles)

AccountTECH normalizes all timestamps to UTC for storage and consistency.

1.3a Transaction Dates (date-only)

The following are date-only fields (format YYYY-MM-DD, no time component). No timezone declaration is required for these.

1.4 Property Address

1.5 Agent Reference (per-side agent array)

Each side of the transaction is an array of agent objects. Use the order field to indicate ranking (1 = primary agent, 2 = secondary, etc.). Each agent carries a commission split that allocates that side's total commission.

Commission split rules:

• As dollar amounts — each agent's amount must sum to the total side commission (e.g., $9,000 + $9,000 = $18,000).
• As percentages — each agent's percentage is a share of that side's total commission and must sum to 100% (e.g., 50% / 50%, or 60% / 40%).
• Indicate which method is used (e.g., split_type = PERCENT | AMOUNT).

1.6 Participants (Ancillary Vendors)

Ancillary parties attached to the property — mortgage company, title company, home warranty, etc. — are delivered as a participants array. Each entry declares its participant_type and may include both the organization and the individual working the transaction.

1.7 Referrals

Out-of-office referrals — a company that provided the buyer or seller and is paid out of the commission. Multiple referrals are supported per transaction. For each, declare how the referral is calculated: most often a percentage of GCI, occasionally a fixed dollar amount.

1.8 Contact Information (Buyer / Seller)

2. Agent Roster Data (non-roster-sync vendors)

If a vendor does not implement roster sync but maintains agent rosters, provide either a periodic full roster export or incremental roster updates. This allows Darwin to maintain external-ID links and activate/deactivate agents.

2.1 Agent Roster Schema

Delivery cadence:

• Full export — all active and inactive agents; monthly or quarterly.
• Incremental export — only agents with status or contact changes since the last pull; daily or weekly; must include modified_date.

3. Buyer / Seller Lead-Source Data

For vendors providing lead-source information (CRM systems, referral-source tracking, etc.), submit records to populate Darwin's purchasing table. These capture the source of the buyer or seller, whether the lead was office- or agent-generated, and the person's contact information.

3.1 Lead-Source Schema

4. Code Value API Lookups

To match reliably, vendors should use the Darwin Code Value API to retrieve the actual enumeration values the client uses in our system, and return both the ID and the string value on every coded field. This avoids brittle string matching and prevents data-entry drift.

4.1 Endpoint

GET /api/v2/code-values?category={category}

Example response:

{
  "data": [
    { "id": "12345", "code": "SFR",   "description": "Single Family Residential", "active": true },
    { "id": "12346", "code": "CONDO", "description": "Condominium",              "active": true }
  ]
}

4.2 Categories to Look Up

• property_type — SFR, CONDO, TOWNHOUSE, COMM, etc.
• transaction_type — SALE, LEASE, EXCHANGE, SHORT_SALE, etc.
• status — PENDING, UNDER_CONTRACT, ACTIVE, CLOSED, CANCELLED, etc. (so we know which state the property is in).
• cancellation_reason — FINANCING_FAILED, INSPECTION_ISSUE, APPRAISAL_ISSUE, BUYER_WITHDREW, etc.
• accounting_code — brokerage-specific accounting classifications (vary by client).
• participant_type — TITLE_COMPANY, MORTGAGE_COMPANY, MORTGAGE_BROKER, HOME_WARRANTY, etc.
• lead_source — REFERRAL, INTERNET, DIRECT_MAIL, REPEAT_CLIENT, RELOCATION, etc.

4.3 Recommended Practice

1. Call the Code Value API during onboarding to retrieve all valid codes per category.
2. Cache the values locally and refresh periodically (weekly or monthly).
3. On every coded field, send both the Darwin ID and the string value (e.g., property_type_id: "12345", property_type: "SFR").
4. For any value with no Darwin match, send your native value and we will map it manually during intake.

5. Data Delivery

5.1 Transport & Direction

• REST API only. Darwin integrates exclusively over a REST API exposed by the vendor.
• Pull only. Darwin pulls data from the vendor's API. Vendors do not push data into Darwin.

5.2 Pull Modes

The vendor API must support both of the following:

• Full pull — returns all records. Used for initial onboarding and periodic reconciliation.
• Incremental pull — returns only records changed since a supplied timestamp (modified_date ≥ last_pull). Cancelled transactions MUST be included so Darwin can cancel the corresponding property record rather than orphaning it.

5.3 Single-Record Retrieval

In addition to bulk pulls, the API must support retrieving a single record by a stable identifier (GUID or vendor ID) — e.g., one property/transaction at a time. This lets Darwin re-pull an individual record that was missed in a previous pull without re-running a full sync.

Open items to confirm during onboarding

• Timezone declaration for DateTime fields (UTC vs. local — Section 1.3).
• Per participant type: company, individual, or both (Section 1.6).
• Whether your system separates Listing ID and Transaction ID (Section 1.1).
• company_id / office_id routing when the client runs multiple companies in Darwin (Section 1.2).