HarborCRM Integration
Work with the HarborCRM REST API to fetch, cross-reference, classify, and produce structured JSON output across events, finance, CRM, trade-shows, and import pipelines.
How to approach any HarborCRM task
Read the answer template the task provides. It defines every required key, allowed enum value, sort order, and field type. The template is the authoritative schema for the output.
Fetch /api/policies first. Policies carry the business rules that drive qualification, opportunity sizing, follow-up offsets, source priorities, and controlled vocabulary. Everything else follows from them.
Pull all relevant API data in parallel. The API has no dependencies between endpoints — fetch event+orders+badges+sponsor_packages together, or tradeshow+exhibitors+meeting_interest together. Then fetch invoices, CRM entities, and campaign members in a second wave once you know which IDs to filter by.
Match entities by ID first, then by normalized email, then by normalized company name. See references/data-model.md for the exact join keys between entities.
Classify records using policy-driven rules, not hardcoded values. Sponsor statuses, badge classifications, lead qualification, CRM actions, and exclusion reasons all flow from policy data combined with entity state.
Return a single JSON object with no surrounding prose. The output must conform exactly to the answer template — no extra keys, no omitted required keys, correct enum values, integer counts, and the exact sorting the template demands.
Common workflows
Post-event reconciliation
Given an event_id and an answer template:
- Fetch the event, its orders, badges, and sponsor packages together.
- Fetch invoices filtered by
event_id.
- Fetch CRM accounts, contacts, opportunities, and campaign members filtered by
event_id where supported.
- Sponsor statuses: Join orders → invoices by account_id. Classify each sponsor as
paid_deferred (fully paid), open_invoice (has invoice with outstanding balance), or proposal_only (order exists, no invoice). Sort by account_name ascending.
- Sponsor revenue: Sum package_amount per status. For open_invoice, also sum open_balance separately.
- Badge classification: Cross-reference badge company_name/email against sponsor account_ids. A badge belongs to a sponsor if its company matches a sponsor account. Classify each badge as
sponsor_attendee, qualified_non_sponsor_lead, or excluded.
- Exclusions: Exclude sponsor attendees, badges with non-business types, contacts from CRM accounts with disqualified status, and badges missing contact names. List each excluded record with company_name, contact_name, and the controlled exclusion reason. Sort by company_name then contact_name ascending.
- Qualified leads: Non-sponsor, non-excluded badges. For each, determine CRM action by checking whether the account and contact already exist. Use the event's lead opportunity amount from policies (not a per-account negotiation).
- CRM action counts: Count accounts_create, accounts_update, contacts_create, contacts_update, campaign_members_create, campaign_members_update across all qualified leads.
- Follow-up dates: Add the policy-defined lead follow-up offset days to the event end date for lead tasks. Use a shorter offset for sponsor finance tasks. Task counts equal the number of qualified leads and the number of sponsors needing finance follow-up (open_invoice + proposal_only).
Trade-show exhibitor prospecting
Given a show_id, campaign identifier, and answer template:
- Fetch the tradeshow, exhibitors, and meeting interest records together.
- Fetch CRM accounts and policies.
- Qualification: Policies define which exhibitor relationship types (OEM, distributor, service_provider, sensor_vendor, research) qualify for the campaign. Exhibitors whose relationship_type is not in the qualifying set are excluded.
- Platform assignment: Each exhibitor has a list of platforms. Map these to the controlled enum allowed by the template (typically AUV, ROV, Underwater Camera). Sort platforms in the enum order specified.
- Priority tiers: Policies define thresholds using meeting_interest scores and demo requests. When an exhibitor has no meeting interest record, default interest_score to 0 and requested_demo to false.
- Ranking: Apply the ranking rules from the task template. Common pattern: demo-requested first, then descending interest score, then broader platform coverage, then company name ascending.
- CRM matching: Check each qualified exhibitor against CRM accounts by company name. Assign
update_existing when a match is found, create_account otherwise.
- Opportunity sizing: Use policy-defined or template-specified amounts by priority tier, not per-exhibitor negotiated values.
- Exclusions: For each non-qualifying exhibitor, record the company_id, company_name, and the controlled exclusion reason (
distributor_only, service_only, sensor_vendor_only, research_only, not_target_market). Sort by company_name ascending.
- Aggregate counts: Qualified total, platform counts per enum value, priority counts per tier, excluded total.
Import batch preparation
Given a batch_id and answer template:
- Fetch the import batch, raw contacts, and suppression list together.
- Fetch CRM accounts, contacts, and policies.
- Deduplication: Group raw contacts by normalized email (lowercase, trimmed). For groups with multiple rows, pick a winner using source priority from policies. Record removed duplicates with the dedup key (format
"email:<normalized_email>"), winner row_id, and removed row_ids.
- Suppression: Remove rows whose normalized email or normalized company name appears in the suppression list.
- Unusable rows: Remove rows with missing contact_name. The removal reason is
missing_contact.
- CRM matching: For each surviving contact, look up existing CRM accounts by normalized company name or email domain. Look up existing CRM contacts by normalized email. Populate existing_account_id (or null) and existing_contact_id (or null).
- CRM actions: Assign
create_account for new companies, update_existing for matched companies, suppress for suppression matches, no_import for unusable rows.
- Clean contacts: Sort by clean_contact_id (which equals the winning source row_id) ascending.
- Removal summary: List all removed rows with row_id and reason. Sort by row_id ascending. Count unusable_removed and suppressed_removed separately.
- Campaign member count: Every surviving clean contact with crm_action
create_account or update_existing counts toward campaign member import.
Campaign member management
When a task requires campaign member create/update/no-action decisions:
- Fetch existing campaign members filtered by
event_id.
- Cross-reference with badge classifications and sponsor registrations.
- No action: Existing campaign members for sponsor attendees or registrants who are already correctly tracked.
- Create: Qualified non-sponsor badge leads not yet in campaign members, plus sponsor attendees who need campaign member records.
- Update: Existing campaign members whose status needs correction.
- No import: Excluded badges (non-business, missing contact, disqualified).
- Target status values:
attended (non-sponsor attendee), attended_sponsor (sponsor attendee), registered_sponsor (sponsor registrant who didn't attend).
- Sort campaign member actions by subject_key ascending.
Entity resolution
When joining records across API endpoints, use these strategies in order:
- By ID: account_id, contact_id, badge_id, company_id — exact match, always preferred.
- By normalized email: Lowercase, trim whitespace. Used for contact-level matching.
- By normalized company name: Lowercase, strip punctuation and common suffixes (Inc, LLC, Ltd, Corp), trim. Use for account-level matching.
- By email domain: Extract domain from email, match to known company domains from CRM accounts.
When multiple CRM accounts match the same normalized company name, prefer the one with matching email domain or the most recently modified.
Classification reference
Every classification value must come from the answer template's allowed enums. These are common across HarborCRM tasks but always verify against the specific template:
Sponsor financial status: paid_deferred, open_invoice, proposal_only
paid_deferred: Invoice exists and paid_amount equals or exceeds package_amount.
open_invoice: Invoice exists with paid_amount less than package_amount.
proposal_only: Sponsor order exists but no invoice has been issued (invoice_id is null).
Badge classification: sponsor_attendee, qualified_non_sponsor_lead, excluded
sponsor_attendee: Badge holder's company matches a sponsor account.
qualified_non_sponsor_lead: Non-sponsor, business badge type, account not disqualified.
excluded: Non-business badge, disqualified CRM account, or missing required fields.
Badge exclusion reasons: sponsor_attendee, non_business_badge, existing_disqualified, missing_contact, inactive_sponsor_record
Trade-show exclusion reasons: distributor_only, service_only, sensor_vendor_only, research_only, not_target_market
CRM actions (accounts/contacts): create_account, update_existing, create_contact, no_import, suppress
Campaign member actions: create, update, no_action, no_import
Campaign member target statuses: attended, attended_sponsor, registered_sponsor, excluded
Platform enums: AUV, ROV, Underwater Camera (always sort in this order)
Priority tiers: A, B, C
Import source names: badge_scan, sponsor_form, partner_upload, webinar_form, exhibitor_form, manual_upload
Normalization rules
Apply these consistently across all workflows:
- Email: Convert to lowercase, trim leading/trailing whitespace. Use empty string
"" when not supplied.
- Phone: Strip all characters except digits (0-9). Use empty string
"" when not supplied. Do not add country code prefixes unless the raw data already includes them.
- Company name for matching: Lowercase, remove punctuation (periods, commas, hyphens), collapse whitespace. Remove common legal suffixes (Inc, LLC, Ltd, Corp, Co, GmbH, Pty Ltd). For display, always use the original casing from the source data.
- Dedup keys: Format as
"email:<normalized_email>" for email-based dedup, "phone:<normalized_phone>" for phone-based.
Sorting conventions
When the answer template specifies a sort order, follow it exactly. These defaults apply when the template is less explicit:
- Account/company names: ascending, case-insensitive alphabetical.
- IDs (account_id, badge_id, row_id, company_id): ascending alphanumeric.
- Ranks: numeric ascending, 1-based and contiguous.
- Platforms within a list: always the enum order
AUV, ROV, Underwater Camera.
- Excluded records: by
company_name ascending, then contact_name ascending.
- Duplicate keys: by key string ascending.
- Removed rows: by row_id ascending.
Numeric and date conventions
- All monetary amounts: integers (whole USD). No decimals, no currency symbols inside values.
- Counts: integers.
- Dates: ISO 8601
YYYY-MM-DD strings.
- Nullable fields: Use JSON
null for absent IDs. Use "" for absent strings.
- invoice_id is
null when no invoice exists (proposal_only sponsors).
Fetch strategy
The HarborCRM API is read-only and stateless. Optimize for parallelism:
- Wave 1: Fetch the primary entity (event/tradeshow/batch) plus all its directly-related collections (orders, badges, sponsor_packages, exhibitors, meeting_interest, raw_contacts, suppression). Also fetch policies.
- Wave 2: Fetch CRM entities filtered by the IDs or event_ids discovered in Wave 1. Also fetch invoices filtered by event_id or account_id.
- No write operations: All endpoints are GET only. The output JSON represents intended CRM actions, not executed ones.
When a filter parameter is available (event_id, account_id, status, owner_region), use it to limit result size.
Error handling
- When a referenced entity ID produces no match in a join, skip that record. If the template provides an exclusion list, include it there with an appropriate reason.
- When an invoice shows zero paid_amount, classify the sponsor as
open_invoice with open_balance equal to the full package_amount.
- When a badge has no associated company, classify it as excluded with reason
non_business_badge or missing_contact depending on what data is absent.
- When a trade-show exhibitor has no meeting_interest record, default
interest_score to 0 and requested_demo to false.
- When multiple CRM records match, prefer the one with matching domain, then the most recently modified, then the lowest ID.
Reference files
- references/api-surface.md — Complete endpoint catalog with query parameters and response shapes.
- references/data-model.md — Entity descriptions, field meanings, and cross-entity join keys.
1---2name: harbor-crm-integration3description: Integrate HarborCRM REST API data for post-event reconciliation, trade-show exhibitor prospecting, contact import batch preparation, campaign member management, and cross-entity CRM workflows. Use whenever a task mentions HarborCRM, event reconciliation, trade-show lead qualification, contact import cleaning, sponsor finance handoff, CRM data merge, badge-based lead handoff, or any multi-entity data integration against the HarborCRM API — even if the user doesn't name it directly.4metadata:5 source: https://skillmd.com/skills/prism-shadow/harbor-crm-integration6---78# HarborCRM Integration910Work with the HarborCRM REST API to fetch, cross-reference, classify, and produce structured JSON output across events, finance, CRM, trade-shows, and import pipelines.1112## How to approach any HarborCRM task13141. **Read the answer template** the task provides. It defines every required key, allowed enum value, sort order, and field type. The template is the authoritative schema for the output.15162. **Fetch `/api/policies` first.** Policies carry the business rules that drive qualification, opportunity sizing, follow-up offsets, source priorities, and controlled vocabulary. Everything else follows from them.17183. **Pull all relevant API data in parallel.** The API has no dependencies between endpoints — fetch event+orders+badges+sponsor_packages together, or tradeshow+exhibitors+meeting_interest together. Then fetch invoices, CRM entities, and campaign members in a second wave once you know which IDs to filter by.19204. **Match entities by ID first, then by normalized email, then by normalized company name.** See [references/data-model.md](references/data-model.md) for the exact join keys between entities.21225. **Classify records using policy-driven rules, not hardcoded values.** Sponsor statuses, badge classifications, lead qualification, CRM actions, and exclusion reasons all flow from policy data combined with entity state.23246. **Return a single JSON object with no surrounding prose.** The output must conform exactly to the answer template — no extra keys, no omitted required keys, correct enum values, integer counts, and the exact sorting the template demands.2526## Common workflows2728### Post-event reconciliation2930Given an event_id and an answer template:3132- Fetch the event, its orders, badges, and sponsor packages together.33- Fetch invoices filtered by `event_id`.34- Fetch CRM accounts, contacts, opportunities, and campaign members filtered by `event_id` where supported.35- **Sponsor statuses**: Join orders → invoices by account_id. Classify each sponsor as `paid_deferred` (fully paid), `open_invoice` (has invoice with outstanding balance), or `proposal_only` (order exists, no invoice). Sort by account_name ascending.36- **Sponsor revenue**: Sum package_amount per status. For open_invoice, also sum open_balance separately.37- **Badge classification**: Cross-reference badge company_name/email against sponsor account_ids. A badge belongs to a sponsor if its company matches a sponsor account. Classify each badge as `sponsor_attendee`, `qualified_non_sponsor_lead`, or `excluded`.38- **Exclusions**: Exclude sponsor attendees, badges with non-business types, contacts from CRM accounts with disqualified status, and badges missing contact names. List each excluded record with company_name, contact_name, and the controlled exclusion reason. Sort by company_name then contact_name ascending.39- **Qualified leads**: Non-sponsor, non-excluded badges. For each, determine CRM action by checking whether the account and contact already exist. Use the event's lead opportunity amount from policies (not a per-account negotiation).40- **CRM action counts**: Count accounts_create, accounts_update, contacts_create, contacts_update, campaign_members_create, campaign_members_update across all qualified leads.41- **Follow-up dates**: Add the policy-defined lead follow-up offset days to the event end date for lead tasks. Use a shorter offset for sponsor finance tasks. Task counts equal the number of qualified leads and the number of sponsors needing finance follow-up (open_invoice + proposal_only).4243### Trade-show exhibitor prospecting4445Given a show_id, campaign identifier, and answer template:4647- Fetch the tradeshow, exhibitors, and meeting interest records together.48- Fetch CRM accounts and policies.49- **Qualification**: Policies define which exhibitor relationship types (OEM, distributor, service_provider, sensor_vendor, research) qualify for the campaign. Exhibitors whose relationship_type is not in the qualifying set are excluded.50- **Platform assignment**: Each exhibitor has a list of platforms. Map these to the controlled enum allowed by the template (typically AUV, ROV, Underwater Camera). Sort platforms in the enum order specified.51- **Priority tiers**: Policies define thresholds using meeting_interest scores and demo requests. When an exhibitor has no meeting interest record, default interest_score to 0 and requested_demo to false.52- **Ranking**: Apply the ranking rules from the task template. Common pattern: demo-requested first, then descending interest score, then broader platform coverage, then company name ascending.53- **CRM matching**: Check each qualified exhibitor against CRM accounts by company name. Assign `update_existing` when a match is found, `create_account` otherwise.54- **Opportunity sizing**: Use policy-defined or template-specified amounts by priority tier, not per-exhibitor negotiated values.55- **Exclusions**: For each non-qualifying exhibitor, record the company_id, company_name, and the controlled exclusion reason (`distributor_only`, `service_only`, `sensor_vendor_only`, `research_only`, `not_target_market`). Sort by company_name ascending.56- **Aggregate counts**: Qualified total, platform counts per enum value, priority counts per tier, excluded total.5758### Import batch preparation5960Given a batch_id and answer template:6162- Fetch the import batch, raw contacts, and suppression list together.63- Fetch CRM accounts, contacts, and policies.64- **Deduplication**: Group raw contacts by normalized email (lowercase, trimmed). For groups with multiple rows, pick a winner using source priority from policies. Record removed duplicates with the dedup key (format `"email:<normalized_email>"`), winner row_id, and removed row_ids.65- **Suppression**: Remove rows whose normalized email or normalized company name appears in the suppression list.66- **Unusable rows**: Remove rows with missing contact_name. The removal reason is `missing_contact`.67- **CRM matching**: For each surviving contact, look up existing CRM accounts by normalized company name or email domain. Look up existing CRM contacts by normalized email. Populate existing_account_id (or null) and existing_contact_id (or null).68- **CRM actions**: Assign `create_account` for new companies, `update_existing` for matched companies, `suppress` for suppression matches, `no_import` for unusable rows.69- **Clean contacts**: Sort by clean_contact_id (which equals the winning source row_id) ascending.70- **Removal summary**: List all removed rows with row_id and reason. Sort by row_id ascending. Count unusable_removed and suppressed_removed separately.71- **Campaign member count**: Every surviving clean contact with crm_action `create_account` or `update_existing` counts toward campaign member import.7273### Campaign member management7475When a task requires campaign member create/update/no-action decisions:7677- Fetch existing campaign members filtered by `event_id`.78- Cross-reference with badge classifications and sponsor registrations.79- **No action**: Existing campaign members for sponsor attendees or registrants who are already correctly tracked.80- **Create**: Qualified non-sponsor badge leads not yet in campaign members, plus sponsor attendees who need campaign member records.81- **Update**: Existing campaign members whose status needs correction.82- **No import**: Excluded badges (non-business, missing contact, disqualified).83- Target status values: `attended` (non-sponsor attendee), `attended_sponsor` (sponsor attendee), `registered_sponsor` (sponsor registrant who didn't attend).84- Sort campaign member actions by subject_key ascending.8586## Entity resolution8788When joining records across API endpoints, use these strategies in order:89901. **By ID**: account_id, contact_id, badge_id, company_id — exact match, always preferred.912. **By normalized email**: Lowercase, trim whitespace. Used for contact-level matching.923. **By normalized company name**: Lowercase, strip punctuation and common suffixes (Inc, LLC, Ltd, Corp), trim. Use for account-level matching.934. **By email domain**: Extract domain from email, match to known company domains from CRM accounts.9495When multiple CRM accounts match the same normalized company name, prefer the one with matching email domain or the most recently modified.9697## Classification reference9899Every classification value must come from the answer template's allowed enums. These are common across HarborCRM tasks but always verify against the specific template:100101**Sponsor financial status**: `paid_deferred`, `open_invoice`, `proposal_only`102- `paid_deferred`: Invoice exists and paid_amount equals or exceeds package_amount.103- `open_invoice`: Invoice exists with paid_amount less than package_amount.104- `proposal_only`: Sponsor order exists but no invoice has been issued (invoice_id is null).105106**Badge classification**: `sponsor_attendee`, `qualified_non_sponsor_lead`, `excluded`107- `sponsor_attendee`: Badge holder's company matches a sponsor account.108- `qualified_non_sponsor_lead`: Non-sponsor, business badge type, account not disqualified.109- `excluded`: Non-business badge, disqualified CRM account, or missing required fields.110111**Badge exclusion reasons**: `sponsor_attendee`, `non_business_badge`, `existing_disqualified`, `missing_contact`, `inactive_sponsor_record`112113**Trade-show exclusion reasons**: `distributor_only`, `service_only`, `sensor_vendor_only`, `research_only`, `not_target_market`114115**CRM actions** (accounts/contacts): `create_account`, `update_existing`, `create_contact`, `no_import`, `suppress`116117**Campaign member actions**: `create`, `update`, `no_action`, `no_import`118119**Campaign member target statuses**: `attended`, `attended_sponsor`, `registered_sponsor`, `excluded`120121**Platform enums**: `AUV`, `ROV`, `Underwater Camera` (always sort in this order)122123**Priority tiers**: `A`, `B`, `C`124125**Import source names**: `badge_scan`, `sponsor_form`, `partner_upload`, `webinar_form`, `exhibitor_form`, `manual_upload`126127## Normalization rules128129Apply these consistently across all workflows:130131- **Email**: Convert to lowercase, trim leading/trailing whitespace. Use empty string `""` when not supplied.132- **Phone**: Strip all characters except digits (0-9). Use empty string `""` when not supplied. Do not add country code prefixes unless the raw data already includes them.133- **Company name for matching**: Lowercase, remove punctuation (periods, commas, hyphens), collapse whitespace. Remove common legal suffixes (Inc, LLC, Ltd, Corp, Co, GmbH, Pty Ltd). For display, always use the original casing from the source data.134- **Dedup keys**: Format as `"email:<normalized_email>"` for email-based dedup, `"phone:<normalized_phone>"` for phone-based.135136## Sorting conventions137138When the answer template specifies a sort order, follow it exactly. These defaults apply when the template is less explicit:139140- Account/company names: ascending, case-insensitive alphabetical.141- IDs (account_id, badge_id, row_id, company_id): ascending alphanumeric.142- Ranks: numeric ascending, 1-based and contiguous.143- Platforms within a list: always the enum order `AUV`, `ROV`, `Underwater Camera`.144- Excluded records: by `company_name` ascending, then `contact_name` ascending.145- Duplicate keys: by key string ascending.146- Removed rows: by row_id ascending.147148## Numeric and date conventions149150- **All monetary amounts**: integers (whole USD). No decimals, no currency symbols inside values.151- **Counts**: integers.152- **Dates**: ISO 8601 `YYYY-MM-DD` strings.153- **Nullable fields**: Use JSON `null` for absent IDs. Use `""` for absent strings.154- **invoice_id** is `null` when no invoice exists (proposal_only sponsors).155156## Fetch strategy157158The HarborCRM API is read-only and stateless. Optimize for parallelism:159160- **Wave 1**: Fetch the primary entity (event/tradeshow/batch) plus all its directly-related collections (orders, badges, sponsor_packages, exhibitors, meeting_interest, raw_contacts, suppression). Also fetch policies.161- **Wave 2**: Fetch CRM entities filtered by the IDs or event_ids discovered in Wave 1. Also fetch invoices filtered by event_id or account_id.162- **No write operations**: All endpoints are GET only. The output JSON represents intended CRM actions, not executed ones.163164When a filter parameter is available (event_id, account_id, status, owner_region), use it to limit result size.165166## Error handling167168- When a referenced entity ID produces no match in a join, skip that record. If the template provides an exclusion list, include it there with an appropriate reason.169- When an invoice shows zero paid_amount, classify the sponsor as `open_invoice` with `open_balance` equal to the full `package_amount`.170- When a badge has no associated company, classify it as excluded with reason `non_business_badge` or `missing_contact` depending on what data is absent.171- When a trade-show exhibitor has no meeting_interest record, default `interest_score` to 0 and `requested_demo` to false.172- When multiple CRM records match, prefer the one with matching domain, then the most recently modified, then the lowest ID.173174## Reference files175176- [references/api-surface.md](references/api-surface.md) — Complete endpoint catalog with query parameters and response shapes.177- [references/data-model.md](references/data-model.md) — Entity descriptions, field meanings, and cross-entity join keys.