Core resources and platform areas

The published OpenAPI reference started with the resource groups most external systems need: companies, contacts, deals, rooms, communications, and webhooks. The platform API is broader than that first schema slice. Use this page as the product map, then use Complete API surface for every mounted endpoint.

Area	Common paths	What agents can do
CRM accounts	/companies, /companies/{id}, /companies/{id}/identifiers, /companies/{id}/notes, /companies/{id}/dossier	Create, update, enrich, inspect, and annotate tenant company records, including multiple websites and email domains.
Contacts	/contacts, /contacts/{id}, /contacts/{id}/notes, /contacts/{id}/deals	Create, update, enrich, inspect, and relate people to companies and deals.
Deals	/deals, /deals/pipeline, /deals/{id}, /deals/{id}/stage	Manage opportunities, pipeline views, stage transitions, and lineage.
Activities and saved views	/activities, /saved-views, /audit-logs	Record timeline events, persist filtered views, and inspect audit history.
Rooms	/rooms, /rooms/{id}, /rooms/{id}/items, /rooms/public/{token}	Manage client rooms, room items, public room access, room events, and comments.
Communications	/communications, /calls, /call-recordings, /call-templates, /outreach, /campaigns	Log, schedule, search, attach, and manage customer communications and outbound campaigns.
Delivery	/projects, /tasks, /project-templates, /my-work, /quotes, /work-orders, /invoices	Manage project delivery, task work, templates, operational documents, and personal work queues.
Imports and jobs	/import, /pm-import, /jobs, /jobs/batch	Upload files, preview mappings, execute imports, track async jobs, and stream batch progress.
AI and agent settings	/agent, /agent/actions, /settings/api-access, /settings/agents, /settings/models	Discover capabilities, manage agent tokens, propose or approve risky actions, and configure model providers.
Signing and webhooks	/signing, /webhooks, /signing/webhooks/opensign, /webhooks/payments	Manage signing templates/documents, subscribe to tenant events, and receive signed provider callbacks.
Support and notifications	/support, /notifications, /comments, /reactions	Create support tickets, manage notification state, and interact with collaboration threads.
Platform operations	/admin	Internal operator surface for tenants, users, billing, support, settings, ops, and system pages. Do not expose to customer agents unless they are acting as platform admins.

Canonical company relationships

Use the CRM data model as the canonical relationship guide for clients, company identifiers, contact associations, project links, competitor links, global search, and merge behavior.

DealMeld uses companies as the canonical organization record. A client is a company with client fields such as client_id and client_status; /api/clients exposes the delivery-oriented view of those same company records. Client responses include client_name as an alias for the canonical company name and client_number as an alias for client_id. POST /api/companies and PATCH /api/companies/{id} also accept client_number or client_id when an import or agent already knows the external client number for a company that is also a client. Those same company write endpoints accept notes as optional timeline note content; DealMeld stores it in company_notes, not on the companies row. Contacts, notes, deals, rooms, projects, and competitor intelligence should link back to company records whenever the relationship is known.

Companies can have multiple normalized identifiers:

• website identifiers represent public web properties and portals.
• email_domain identifiers represent company-owned domains used for client matching and contact association.
• companies.website and companies.domain remain the primary compatibility fields. The API synchronizes those fields into identifiers, websites, and email_domains arrays on company and client responses.
• Use GET /api/companies/{id}/identifiers, POST /api/companies/{id}/identifiers, PATCH /api/companies/{id}/identifiers/{identifierId}, and DELETE /api/companies/{id}/identifiers/{identifierId} to manage the full set.
• Use GET /api/companies/{id}/notes, POST /api/companies/{id}/notes, and DELETE /api/companies/{id}/notes/{noteId} for explicit note management after the company exists.

Use POST /api/clients when an agent needs to create or link a client. Send client_name and either domain or website. DealMeld normalizes the company-owned domain and rejects personal email domains. Matching runs in this order: exact company identifier or legacy companies.domain / companies.website, then high-confidence normalized legal-name match, then high-confidence domain-brand match such as talyardbrewing.com to Talyard Brewing. If exactly one company matches, DealMeld links that company, fills empty company fields, assigns or reactivates the client number, and associates matching domain contacts through contact_companies without overwriting existing primary company relationships. If more than one active company matches or scores close enough to be ambiguous, the API returns 409 CONFLICT with candidate company IDs so an agent can ask a human or clean up identifiers before retrying.

Use POST /api/companies/{companyId}/merge to merge a duplicate company into a chosen primary company. The path company is the primary. Send duplicate_company_id; DealMeld preserves the primary values, fills empty primary fields from the duplicate, moves company identifiers, contacts, notes, deals, projects, communications, competitors, custom fields, pulse records, signing records, and activity history, then soft-deletes the duplicate. Duplicate client_id, website, and domain values are released before reparenting so same-company duplicates with overlapping identifiers can still merge cleanly. Use POST /api/contacts/{contactId}/merge the same way for duplicate contacts; it moves emails, phones, profiles, tags, company associations, notes, deals, projects, campaigns, communications, signing records, custom fields, and activity history into the primary contact.

The app exposes the same workflow from company and contact detail pages. Click Merge, search for the duplicate, choose whether the current record or selected match should remain primary, then confirm. Company merge search covers name, website, domain, and client number; contact merge search covers name, email, phone, title, and role. A known record UUID can still be pasted as a fallback.

For project automation, create projects with the client company_id, and only link deals or primary contacts that belong to that same company. POST /api/projects also accepts contacts and partners arrays so agents can create the project and its project-contact and project-partner relationships in one call.

For competitive intelligence, POST /api/competitors and PUT /api/competitors/{id} accept company_id. If omitted during create, DealMeld links the competitor to an active company in the same tenant only when there is exactly one case-insensitive same-name match. Competitor list, detail, and battlecard responses include a company summary when linked.

Use the API Reference for request and response schemas where the OpenAPI slice already covers a route. Use the source-backed Complete API surface when a capability is not yet in the schema reference.

Deal records preserve value as the headline pipeline amount and add contract structure fields for won-deal financial handoff: contract_model, billing_frequency, pricing_basis, revenue_recognition, value_basis, has_overages, includes_pass_through_costs, and optional unit/term fields. Closed-won deal responses include _contractStructureWarning when required handoff fields are missing, while existing deals without structure metadata remain readable and editable.

Mutation behavior

Write endpoints require the matching create, update, or delete permission. Tenant write rate limits also apply to POST, PATCH, PUT, and DELETE requests.

When a route supports idempotency, send an idempotency key from the caller so retries do not duplicate work.

Idempotency-Key: <caller generated key>