HarborCRM Integration
Core workflow
Every HarborCRM task follows the same skeleton:
- Fetch the answer template from the task payload and read every field, enum, and sort rule.
- Discover the task's domain anchors (event_id, show_id, batch_id) from the prompt.
- Pull all relevant domain records in parallel where possible:
- Core entity — event, trade show, or import batch metadata.
- Related children — orders/badges/sponsor-packages, exhibitors/meeting-interest, raw-contacts/suppression.
- CRM cross-reference — accounts, contacts, opportunities, campaign members.
- Policies — always fetch
/api/policies; they encode qualification criteria.
- Build an in-memory join graph across domains. Match on ids where available (account_id, event_id, company_id), and fall back to company/contact name matching when normalizing.
- Classify every entity into the controlled enums the template requires.
- Apply all declared sort orders.
- Compute derived numeric totals, counts, and follow-up dates.
- Emit the JSON object matching the template shape and nothing else.
Produce the final JSON on stdout or write it to the path the runner provides. Never include prose outside the JSON payload.
API base URL
The runner supplies the API base URL, typically as <TASK_ENV_BASE_URL> or another explicit variable in the prompt. Every endpoint below is relative to that base.
Endpoint quick reference
For the full endpoint catalog, see references/endpoints.md. Common entry points by domain:
| Domain |
Key endpoints |
| Events |
/api/events, /api/events/{event_id}, /api/events/{event_id}/orders, /api/events/{event_id}/badges, /api/events/{event_id}/sponsor_packages |
| Finance |
/api/finance/invoices?event_id=…, /api/finance/invoices?account_id=… |
| CRM |
/api/crm/accounts, /api/crm/contacts, /api/crm/opportunities, /api/crm/campaign_members |
| Trade shows |
/api/tradeshows, /api/tradeshows/{show_id}, /api/tradeshows/{show_id}/exhibitors, /api/tradeshows/{show_id}/meeting_interest |
| Import batches |
/api/import_batches, /api/import_batches/{batch_id}, /api/import_batches/{batch_id}/raw_contacts, /api/import_batches/{batch_id}/suppression |
| Policies |
/api/policies |
CRM endpoints support filters via query params: ?status=…, ?owner_region=…, ?event_id=…, ?account_id=…. Use them to narrow responses early.
Classification rules
Sponsor status
Determine by comparing the sponsor's invoice paid amount against the package amount (or order total):
- paid_deferred — invoice exists and paid_amount >= package amount.
- open_invoice — invoice exists and paid_amount < package amount. Include open_balance (package_amount - paid_amount).
- proposal_only — no invoice exists.
An inactive or canceled sponsor record is not a sponsor for the current event; classify it under exclusion rather than sponsor_statuses.
Lead qualification
A non-sponsor entity qualifies as a lead when:
- The company is not a sponsor (not in the event's sponsor orders).
- The badge type is business/professional (not press, student, academic, guest, speaker-only when those are flagged as non-business in policies).
- The CRM account is not already marked disqualified (check account status fields or policy rules).
- The contact name and either email or phone are present (no "missing contact").
Exhibitor prospecting qualification
For trade-show tasks, an exhibitor qualifies when:
- It is an OEM/builder of the target product category (per policy rules).
- It is not a distributor-only, service-only, or sensor-vendor-only entity (check exhibitor relationship_type or category fields against policy).
- Platform coverage matches the allowed platform enums in the template.
Exclusion reasons
Use only the exclusion reasons declared in the template's enum. Common reusable reasons:
| Reason |
When to apply |
sponsor_attendee |
Contact belongs to a confirmed sponsor account for this event. |
non_business_badge |
Badge type is press, student, academic, guest, or similar non-business category. |
existing_disqualified |
CRM account status is disqualified, closed, or marked non-target per policy. |
inactive_sponsor_record |
Sponsor order is canceled or status indicates no active participation. |
distributor_only |
Exhibitor's relationship type is distributor and policy excludes distributors. |
service_only |
Exhibitor is a service provider, not a product OEM. |
sensor_vendor_only |
Exhibitor makes only sensors/components, not complete target platforms. |
missing_contact |
Contact name is absent or both email and phone are empty/null. |
duplicate |
Row is a duplicate of another row (use the winning row). |
suppressed |
Contact appears in the suppression list for the batch. |
CRM action classification
| Action |
Condition |
create_account |
Company not found in existing CRM accounts. |
update_existing |
Company found in CRM accounts by account_id or normalized name match. |
create_contact |
Contact not found in existing CRM contacts for the account. |
update_existing (contact) |
Contact found in CRM contacts for the account. |
add_campaign_member |
Lead is qualified and not already a campaign member for the event. |
no_import |
Entity is excluded; do not create any CRM records. |
suppress |
Contact is in the suppression list; mark for suppression. |
no_action |
Already present with correct status; no change needed. |
Normalization rules
Email
Lowercase, trim whitespace, remove display-name prefixes (everything before the last < if angle-bracket syntax is present). If the field is null/empty, use "".
Phone
Strip all non-digit characters. If the result is empty or the field is null, use "". Do not add a leading country code unless the source already includes one.
Company name
Trim whitespace. When matching against CRM accounts, normalize both sides by lowercasing and stripping punctuation/suffixes like Inc., LLC, Ltd., Corp.. Use the highest-confidence match.
Deduplication
When a batch contains duplicate contacts:
- Group by normalized email.
- Within each group, pick the winner: the row with the most complete data (non-empty phone, contact name, and company name). Break ties by earliest
captured_at timestamp.
- The winner becomes the
clean_contact_id and source_row_id. All other rows in the group are removed with reason duplicate.
- Dedup happens before suppression and before CRM matching.
Sorting rules
Apply sorts in the exact order and direction the template specifies. Common patterns:
- Sponsor statuses:
account_name ascending.
- Qualified leads:
account_name / company_name ascending (unless ranked by priority).
- Excluded records:
company_name ascending, then contact_name ascending.
- Badge decisions:
badge_id ascending.
- Campaign member actions:
subject_key ascending.
- Clean contacts:
clean_contact_id ascending.
- Duplicate keys:
key ascending.
- Removed rows:
row_id ascending.
- Ranked leads:
rank ascending (1-based contiguous).
Enum-valued lists (platforms, priority tiers) sort in the order the template declares the enum values.
Follow-up date defaults
When the task asks for follow-up due dates and a specific policy rule is not present:
- Lead follow-up: 21 calendar days after the event end date (or 14 days after the task run date if no event end date is available).
- Sponsor finance follow-up: 17 calendar days after the event end date.
If a policy endpoint provides explicit follow-up offsets, use those instead.
Opportunity amounts
When the task specifies a per-lead opportunity amount, use the event's lead opportunity amount from the event endpoint or opportunities endpoint. When the task specifies tiered amounts (A/B/C), apply the tiering rules exactly as described in the prompt and map them to the declared tiers in the template.
Aggregate counts
Every count field in the template must match the actual number of records in its corresponding list. Cross-check: for every array produced, verify array.length equals the related count field. Platform and priority counts are always non-negative integers summing to the qualified total.
Template conformance
- Never add fields not declared in the answer template.
- Never omit a required top-level or item-level key.
- Never use an enum value outside the template's declared set.
- Match the template's date format (always
YYYY-MM-DD).
- All currency amounts are integers (USD).
Parallel API strategy
Pull data in waves to minimize round-trips while respecting inter-endpoint dependencies:
- Wave 1 (all parallel, no dependencies): Policies, CRM accounts, CRM contacts, events/tradeshows/import-batches, exhibitors.
- Wave 2 (after wave 1, keyed by ids): Event orders, badges, sponsor packages, invoices, opportunities, campaign members, meeting interest, suppression.
- Join and classify in memory after both waves complete.
This two-wave pattern covers every task shape in the HarborCRM domain.
1---2name: harbor-crm-integration-33description: "Build integrated HarborCRM workflows that join event, CRM, finance, trade-show, import-batch, and policy endpoints into reconciled, classified, and structured outputs. Use when the task involves: (1) post-event CRM handoff or reconciliation, (2) trade-show exhibitor prospecting with qualification and tiering, (3) import-batch cleaning, deduplication, and CRM import preparation, (4) cross-domain data joining across HarborCRM API segments, or (5) template-driven JSON output construction with controlled-enum classification and sorting rules."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/harbor-crm-integration-38---910# HarborCRM Integration1112## Core workflow1314Every HarborCRM task follows the same skeleton:15161. Fetch the answer template from the task payload and read every field, enum, and sort rule.172. Discover the task's domain anchors (event_id, show_id, batch_id) from the prompt.183. Pull all relevant domain records in parallel where possible:19 - **Core entity** — event, trade show, or import batch metadata.20 - **Related children** — orders/badges/sponsor-packages, exhibitors/meeting-interest, raw-contacts/suppression.21 - **CRM cross-reference** — accounts, contacts, opportunities, campaign members.22 - **Policies** — always fetch `/api/policies`; they encode qualification criteria.234. Build an in-memory join graph across domains. Match on ids where available (account_id, event_id, company_id), and fall back to company/contact name matching when normalizing.245. Classify every entity into the controlled enums the template requires.256. Apply all declared sort orders.267. Compute derived numeric totals, counts, and follow-up dates.278. Emit the JSON object matching the template shape and nothing else.2829Produce the final JSON on stdout or write it to the path the runner provides. Never include prose outside the JSON payload.3031## API base URL3233The runner supplies the API base URL, typically as `<TASK_ENV_BASE_URL>` or another explicit variable in the prompt. Every endpoint below is relative to that base.3435## Endpoint quick reference3637For the full endpoint catalog, see [references/endpoints.md](references/endpoints.md). Common entry points by domain:3839| Domain | Key endpoints |40|---|---|41| Events | `/api/events`, `/api/events/{event_id}`, `/api/events/{event_id}/orders`, `/api/events/{event_id}/badges`, `/api/events/{event_id}/sponsor_packages` |42| Finance | `/api/finance/invoices?event_id=…`, `/api/finance/invoices?account_id=…` |43| CRM | `/api/crm/accounts`, `/api/crm/contacts`, `/api/crm/opportunities`, `/api/crm/campaign_members` |44| Trade shows | `/api/tradeshows`, `/api/tradeshows/{show_id}`, `/api/tradeshows/{show_id}/exhibitors`, `/api/tradeshows/{show_id}/meeting_interest` |45| Import batches | `/api/import_batches`, `/api/import_batches/{batch_id}`, `/api/import_batches/{batch_id}/raw_contacts`, `/api/import_batches/{batch_id}/suppression` |46| Policies | `/api/policies` |4748CRM endpoints support filters via query params: `?status=…`, `?owner_region=…`, `?event_id=…`, `?account_id=…`. Use them to narrow responses early.4950## Classification rules5152### Sponsor status5354Determine by comparing the sponsor's invoice paid amount against the package amount (or order total):5556- **paid_deferred** — invoice exists and paid_amount >= package amount.57- **open_invoice** — invoice exists and paid_amount < package amount. Include open_balance (package_amount - paid_amount).58- **proposal_only** — no invoice exists.5960An inactive or canceled sponsor record is not a sponsor for the current event; classify it under exclusion rather than sponsor_statuses.6162### Lead qualification6364A non-sponsor entity qualifies as a lead when:6566- The company is not a sponsor (not in the event's sponsor orders).67- The badge type is business/professional (not press, student, academic, guest, speaker-only when those are flagged as non-business in policies).68- The CRM account is not already marked disqualified (check account status fields or policy rules).69- The contact name and either email or phone are present (no "missing contact").7071### Exhibitor prospecting qualification7273For trade-show tasks, an exhibitor qualifies when:7475- It is an OEM/builder of the target product category (per policy rules).76- It is not a distributor-only, service-only, or sensor-vendor-only entity (check exhibitor relationship_type or category fields against policy).77- Platform coverage matches the allowed platform enums in the template.7879### Exclusion reasons8081Use only the exclusion reasons declared in the template's enum. Common reusable reasons:8283| Reason | When to apply |84|---|---|85| `sponsor_attendee` | Contact belongs to a confirmed sponsor account for this event. |86| `non_business_badge` | Badge type is press, student, academic, guest, or similar non-business category. |87| `existing_disqualified` | CRM account status is disqualified, closed, or marked non-target per policy. |88| `inactive_sponsor_record` | Sponsor order is canceled or status indicates no active participation. |89| `distributor_only` | Exhibitor's relationship type is distributor and policy excludes distributors. |90| `service_only` | Exhibitor is a service provider, not a product OEM. |91| `sensor_vendor_only` | Exhibitor makes only sensors/components, not complete target platforms. |92| `missing_contact` | Contact name is absent or both email and phone are empty/null. |93| `duplicate` | Row is a duplicate of another row (use the winning row). |94| `suppressed` | Contact appears in the suppression list for the batch. |9596### CRM action classification9798| Action | Condition |99|---|---|100| `create_account` | Company not found in existing CRM accounts. |101| `update_existing` | Company found in CRM accounts by account_id or normalized name match. |102| `create_contact` | Contact not found in existing CRM contacts for the account. |103| `update_existing` (contact) | Contact found in CRM contacts for the account. |104| `add_campaign_member` | Lead is qualified and not already a campaign member for the event. |105| `no_import` | Entity is excluded; do not create any CRM records. |106| `suppress` | Contact is in the suppression list; mark for suppression. |107| `no_action` | Already present with correct status; no change needed. |108109## Normalization rules110111### Email112113Lowercase, trim whitespace, remove display-name prefixes (everything before the last `<` if angle-bracket syntax is present). If the field is null/empty, use `""`.114115### Phone116117Strip all non-digit characters. If the result is empty or the field is null, use `""`. Do not add a leading country code unless the source already includes one.118119### Company name120121Trim whitespace. When matching against CRM accounts, normalize both sides by lowercasing and stripping punctuation/suffixes like `Inc.`, `LLC`, `Ltd.`, `Corp.`. Use the highest-confidence match.122123## Deduplication124125When a batch contains duplicate contacts:1261271. Group by normalized email.1282. Within each group, pick the winner: the row with the most complete data (non-empty phone, contact name, and company name). Break ties by earliest `captured_at` timestamp.1293. The winner becomes the `clean_contact_id` and `source_row_id`. All other rows in the group are removed with reason `duplicate`.1304. Dedup happens before suppression and before CRM matching.131132## Sorting rules133134Apply sorts in the exact order and direction the template specifies. Common patterns:135136- Sponsor statuses: `account_name` ascending.137- Qualified leads: `account_name` / `company_name` ascending (unless ranked by priority).138- Excluded records: `company_name` ascending, then `contact_name` ascending.139- Badge decisions: `badge_id` ascending.140- Campaign member actions: `subject_key` ascending.141- Clean contacts: `clean_contact_id` ascending.142- Duplicate keys: `key` ascending.143- Removed rows: `row_id` ascending.144- Ranked leads: `rank` ascending (1-based contiguous).145146Enum-valued lists (platforms, priority tiers) sort in the order the template declares the enum values.147148## Follow-up date defaults149150When the task asks for follow-up due dates and a specific policy rule is not present:151152- **Lead follow-up**: 21 calendar days after the event end date (or 14 days after the task run date if no event end date is available).153- **Sponsor finance follow-up**: 17 calendar days after the event end date.154155If a policy endpoint provides explicit follow-up offsets, use those instead.156157## Opportunity amounts158159When the task specifies a per-lead opportunity amount, use the event's lead opportunity amount from the event endpoint or opportunities endpoint. When the task specifies tiered amounts (A/B/C), apply the tiering rules exactly as described in the prompt and map them to the declared tiers in the template.160161## Aggregate counts162163Every count field in the template must match the actual number of records in its corresponding list. Cross-check: for every array produced, verify `array.length` equals the related count field. Platform and priority counts are always non-negative integers summing to the qualified total.164165## Template conformance1661671. Never add fields not declared in the answer template.1682. Never omit a required top-level or item-level key.1693. Never use an enum value outside the template's declared set.1704. Match the template's date format (always `YYYY-MM-DD`).1715. All currency amounts are integers (USD).172173## Parallel API strategy174175Pull data in waves to minimize round-trips while respecting inter-endpoint dependencies:176177- **Wave 1** (all parallel, no dependencies): Policies, CRM accounts, CRM contacts, events/tradeshows/import-batches, exhibitors.178- **Wave 2** (after wave 1, keyed by ids): Event orders, badges, sponsor packages, invoices, opportunities, campaign members, meeting interest, suppression.179- Join and classify in memory after both waves complete.180181This two-wave pattern covers every task shape in the HarborCRM domain.