Enable a CRM (admin)
Only an organization Admin (or the Metal team) can create, update, or delete a CRM integration. Members without the Admin role cannot change integration settings. Requests made with an organization API key toPOST, PUT, or DELETE /v1/integrations return 403 Forbidden.
1
Open Integrations
Go to Settings → Integrations and find your CRM.
2
Enable and authorize
Click into the CRM and follow its setup. Some CRMs need credentials. For example, DealCloud asks for a Client ID, API Key, and Base Url before you click Connect.
Base Url requirements
The Base Url decides which host receives your CRM credentials, so Metal checks it before saving. The Base Url must:- Start with
https://and not end with/. - Use the default port. A port other than
443is rejected. - Have no query string (
?…), fragment (#…), or embedded credentials (user:password@).
For self-hosted CRMs such as Dynamo, the host must be a public, fully qualified hostname that resolves to a public address. IP addresses and internal names (for example
crm.local or crm.internal) are rejected.
invalid integration base URL: host "crm.example.com" is not a recognised DEALCLOUD domain.
Troubleshooting: If an existing integration starts failing with a configuration error, its saved Base Url may not be on the vendor’s domain. Ask an Admin to update the Base Url in Settings → Integrations to a URL that meets the requirements above.
403 Forbidden. In the app, CRM Mappings is a Metal-team surface, so ask your Metal contact to change a mapping. See Admin-only endpoints.
Connect your account (user)
Where a CRM supports per-user sign-in, connect your account at Settings → Connections once an admin has enabled it. Salesforce is a firm-level integration. After Salesforce is enabled, org admins can connect it from Settings → Connections → Salesforce. Users who already connected Salesforce also see it there so they can manage or disconnect their connection.Setting up a CRM is part of onboarding — the Setup checklist includes an Integrate CRM step. See Onboarding your workspace.
Affinity lists
Metal imports Affinity records from the lists configured for your integration.- Company lists: One Affinity integration can sync companies from more than one company list. Each list keeps its own field mappings and filters. Each imported company gets that list’s tag.
- Person lists: Metal imports people from configured Affinity person lists. Each person is tagged with the list name. To link a person to their company, the person list must map a company-typed field to
CompanyExternalID; without that mapping Metal stores the company name instead of its ID. A person whose company isn’t on a synced company list is imported without the company link. Mapped fields can include relationship-intelligence values, such as the last-contact date.
Investor Relations records from DealCloud
When your DealCloud connection includes the corresponding object mappings, Metal can also sync these records into Investor Relations:- Funds
- Limited Partners
- Fundraising Processes
Write edits back to your CRM
CRM writeback sends a change you make in Metal to the matching field in DealCloud or Salesforce. Metal saves the edit first. The CRM update is asynchronous and does not block the Metal save. Writeback is opt-in. Metal enables it for your organization; it is not on by default. Affinity and Dynamo sync into Metal. They do not receive writeback.If mapped CRM fields are read-only, or you do not see a sync badge after an edit, writeback is not enabled or the field has no working write path. Ask your Metal admin or contact support@metal.ai.
When an edit writes back
All of these must be true:- Writeback is enabled for your organization.
- The record already exists in DealCloud or Salesforce and is linked in Metal.
- You edited the field in Metal (for example on the record page or in a list).
- The field is mapped in your CRM configuration.
What you can change
On a CRM-linked record, Metal labels who owns each field:
Deal financials imported from the CRM (for example revenue or EBITDA) stay read-only. There is no writeback path for those fields today.
The most complete writeback coverage is on deals. When the field is mapped, typical deal writes include status and stage, name, notes, size, priority, and dates. They also include target company, source company, source contact, owners, deal advisors, IOI / LOI / final bid dates and amounts, and mapped custom deal fields.
Companies, people, and activities can also write mapped fields back when writeback is enabled. Coverage is narrower than deals and depends on your mappings. For people, mapped writes include address, contact type, and the person’s company link. On DealCloud, they also include taxonomy (industries, sectors, and subsectors). Each taxonomy value must be linked to a matching DealCloud entry. If any value is not linked, Metal sends none of that field’s values and the field shows Sync failed. You can also clear a person’s company, and Metal sends the clear to the CRM. For activities, this includes notes edits when notes are mapped. See Edit activity notes. Investor Relations records that sync from DealCloud remain read-only for mapped fundraising fields until an outbound path is enabled for your organization.
DealCloud User fields can be written from Metal user fields when the mapping pairs them. Mapping a User field to any other kind of Metal value is not supported, and Metal does not write it.
Multi-select custom picklists in DealCloud sync every selected choice once this mapping is set up for your organization. Import brings in all selected choices, and writeback sends all selected choices back.
Create activities in DealCloud
Metal can create activities in DealCloud, including notes, once their people, companies, and deals are linked. When your organization has more than one destination for new activities, pick one with Create in on the new activity page. Creating an activity writes a new record to your CRM directly. It does not go through the mapped-field writeback above.After you save
After you save, each mapped field shows a sync badge — for example Syncing, Synced, Dry-run, Sync failed, or Action needed. Sync failed includes a Retry button after you fix the value or CRM error. A Dry-run badge means Metal validated the write without sending it; when your organization has turned off CRM dry-run, use Push to CRM on that lane to send it. Action needed marks a blocked lane: the badge shows the reason, with no Retry button, because the app does not yet offer a resolution form for blocked lanes.Use CRM picklist labels in lists
In a writeback-enabled list, you can type the CRM’s own picklist label into a deal or person cell. For example, enter a contact type label exactly as it is configured in your CRM. Metal stores the matching canonical value and keeps the CRM label for writeback. Metal rejects a label that does not match any configured value, and the cell is not saved. Type pickers on CRM-linked records also show your CRM’s labels for mapped enum fields. Company type is picked in the company’s Settings tab. Deal type, person contact type, and activity type are picked in their edit dialogs, and record pages and list cells show the stored label. When you pick an option, Metal saves that exact selection. Saving other changes does not change an enum field you did not touch.Clearing values
Clearing a CRM-linked field is not the same as leaving it blank. Empty values are not sent as clears. Clearing the company on a CRM-sourced deal is rejected. See Working with deals.People created in Metal
When your organization creates Contacts in DealCloud, a person you add in Metal, or that chat adds for you, is created as a Contact in DealCloud, unless Metal already links that person to another source such as LinkedIn. People that Metal imports from other sources are not created in the CRM.- Person with a company: Metal waits until that company is linked in DealCloud. Then Metal creates the Contact with the company link.
- Person without a company: Metal creates the Contact right away, unless your configuration requires a company. In that case Metal does not create the Contact and reports the missing company as a blocked create.
- Person on hold for duplicate review: Metal does not create the Contact until the duplicate review is resolved.
Activities created in Metal
When your organization creates activities in DealCloud, an activity you add in Metal, or that chat adds for you, is created in DealCloud with its notes. This includes emails you add or that chat records for you; mail Metal syncs from your mailbox is not created. Private activities and activities that Metal imports from other sources are not created in the CRM. Metal waits until every mapped person, company, and deal linked to the activity is linked in DealCloud. Then Metal creates the activity with those links. If a linked relation has no writable mapping in your DealCloud configuration, the activity is never created and reports Metal cannot write. If your organization has several activity destinations and none is chosen, the create waits until you choose a target.Fix writeback errors (admin)
When the CRM rejects a write, Metal records a writeback error. Admins review these at Settings → CRM Writeback. Each error can show a summary and a suggested next step. Each cause can show:- The CRM’s description of the problem.
- The record’s current value in Metal.
- Where to fix it: the record, CRM Mappings for a mapping problem (a Metal-team surface, so ask your Metal contact to change it), or Connections for a permission problem.
Retry an error
1
Fix the cause
Correct the value on the record, update the mapping, or fix the CRM connection.
2
Click Retry
Open the error and click Retry. Metal re-sends the pending fields, or republishes the create, using current Metal values.
3
Check the result
The Latest retry section shows the outcome. Accepted resolves the error as Corrected once no fields stay pending; if some were skipped, the error stays open with those fields still pending. Rejected shows the new cause. No result means Metal never got a result back — you can retry again.
Errors that close automatically
- A newer edit that rewrites all of the error’s pending fields closes the older error as superseded; a partial edit trims the pending fields and keeps the error open.
- A successful create closes its create errors.
- Deleting the record closes its errors.
Notifications
Org admins get an in-app notification when Metal records a new writeback error. The notification links straight to the error. To turn this notification type off, go to Settings → Notifications. It is in-app only, with no email.Get help in chat
Click Open in chat on an active error to start a chat that explains the error and suggests next steps. Admins can also ask chat to list, explain, and retry writeback errors. Chat asks your permission before it retries or changes a value.Deal intake and workflow writes
Teaser and CIM intake can create or update the CRM as a configured workflow step. That path is organization-specific. It is not the same as editing a field on a record in Metal and waiting for writeback. Do not assume every workflow write uses this in-app writeback path. Confirm the review step and CRM write behavior with your Metal admin before you treat an intake run as the system of record.Edit activity notes
You can edit an activity’s notes from its detail page. Click Edit notes to open a plain-text editor. Metal saves the text exactly as you type it. Use Clear notes to remove the notes. Edit notes is available when the activity has no linked file, or when its linked notes file is a.md or .txt file. Activities with another kind of linked document cannot be edited this way. Mailbox activities, such as email and calendar items from a connected mailbox, have no notes editor.
The editor works the same on activities that are not linked to a CRM. The badges described below appear only on CRM-linked activities.
On a CRM-linked activity, the page shows the notes ownership badge and the notes sync badge:
- When writeback is on and notes are mapped, saving the notes writes the change back to your CRM. If the sync fails, use Retry on the badge.
- When the CRM refuses a clear, Metal hides Clear notes and shows the reason.
- When notes are mapped but cannot be written, Metal shows the notes as read-only with the reason.
Notes format in the CRM
Your organization’s notes mapping sets the format Metal uses when it writes activity notes to DealCloud or Salesforce:
When Metal imports activities, it compares the CRM text with Metal’s notes in the same format. Notes that Metal wrote are not replaced by the CRM’s copy on the next import. To change the format, contact support@metal.ai.