How to sync companies and contacts from a CRM

Use these steps when your CRM is where people keep company and contact details, and Drum needs the same records for opportunities, projects and invoices.

The sync runs one way, from the CRM to Drum. Drum matches companies by name and contacts by email or mobile, so running the same sync twice does not create duplicates.

Before you start

You need:

• An API token for a Drum user whose role has api_read, api_create, api_update, read_companies, create_companies and update_companies
• To link contacts to opportunities, the opportunity update permission for those opportunities
• To merge duplicates, also api_delete and delete_companies
• A field in your CRM to store each record’s Drum id

The examples use $DRUM_API_TOKEN for the token. All requests go to https://app.getdrum.com/api/v1/.

1. Find the company in Drum

If your CRM already stores the company’s Drum id, read it directly and skip to step 3:

curl -H "Authorization: Bearer $DRUM_API_TOKEN" \
  "https://app.getdrum.com/api/v1/companies/789"

A 404 means the company was deleted in Drum, or merged into another company. Clear the stored id and go to step 2.

2. Create the company, or match the one Drum has

Send the company to Drum. Nest the fields under company.

curl -X POST "https://app.getdrum.com/api/v1/companies" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": {"trading_name": "Acme Corporation", "legal_name": "Acme Corporation Pty Ltd", "email": "accounts@acme.example", "phone": "+61 2 5550 1234", "company_tags": ["CRM"]}}'

• 201 with "matched_existing": false: Drum created the company.
• 200 with "matched_existing": true: a company with that trading or legal name already exists. Drum returns it and changes nothing.

Store the id in your CRM either way.

A 409 company_name_taken means a company with that name exists but the token’s user cannot read it. Give the user read_companies.

3. Update the company’s details

When the CRM record differs from Drum, send only the fields that changed:

curl -X PATCH "https://app.getdrum.com/api/v1/companies/789" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": {"phone": "+61 2 5550 9999", "add_company_tags": ["Key account"]}}'

Use add_company_tags and remove_company_tags to change tags. Tags added by people in Drum are kept. Send null to clear a field such as legal_name or phone.

4. Create the contact and link it to the company

Send the contact with a link to the company from step 2:

curl -X POST "https://app.getdrum.com/api/v1/contacts" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contact": {"first_name": "Mia", "last_name": "Chen", "title": "Accounts manager", "email": "mia.chen@acme.example", "mobile_phone": "0412 555 307", "link": {"record_kind": "company", "record_id": 789, "pinned": true}}}'

• 201 with "matched_existing": false: Drum created the contact and linked it.
• 200 with "matched_existing": true: a contact with that email, or that mobile, already exists. Drum returns it and links it to the company, but does not change its fields.

Store the contact’s id in your CRM.

If the response is 409 contact_deleted, a deleted contact has that email or mobile. The message gives its id. Restore it, then send the POST again:

curl -X PATCH "https://app.getdrum.com/api/v1/contacts/307/restore" \
  -H "Authorization: Bearer $DRUM_API_TOKEN"

5. Update the contact’s details

When the contact matched an existing one, or changed in the CRM, send the fields that differ:

curl -X PATCH "https://app.getdrum.com/api/v1/contacts/307" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Finance director", "office_phone": "+61 2 5550 1240"}'

6. Link the contact to an opportunity

When the CRM deal has a Drum opportunity, link the contact to it:

curl -X PATCH "https://app.getdrum.com/api/v1/opportunities/12001/contacts/307" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "owner", "pinned": true}'

Drum answers 201 for a new link, or 200 when the contact was already on the opportunity. Use /projects/:id/contacts/:contact_id for a delivery project.

When a contact leaves the deal in the CRM, remove the link. The contact stays in Drum:

curl -X DELETE "https://app.getdrum.com/api/v1/opportunities/12001/contacts/307" \
  -H "Authorization: Bearer $DRUM_API_TOKEN"

7. Merge duplicate companies

When the CRM merges two companies, or you find duplicates in Drum, merge them into the company you keep. Check the ids first: a merge cannot be undone through the API.

curl -X POST "https://app.getdrum.com/api/v1/companies/789/merge" \
  -H "Authorization: Bearer $DRUM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_company_ids": [815]}'

Projects, opportunities, unsent invoices and supplier records move to company 789, and company 815 is deleted. Contacts stay on the deleted company, so link the ones you need to the kept company (step 6, with /companies/789/contacts/:contact_id) before you merge. Then replace 815 with 789 in your CRM.

Tips

• Stay under the rate limit. The API allows 300 requests a minute for each account. For a large first sync, pause when you get a 429 and wait for Retry-After. See Rate limits.
• Retry safely. Steps 2 and 4 match the existing record, so a retry after a timeout does not create a second one. For a contact you can also send an idempotency_key beside the other fields.
• Leave Drum-only fields alone. Addresses, the website and custom fields are kept in Drum and cannot be set through the API.

Related

• Companies and contacts
• Opportunities
• Notes
• Requests, errors and limits
• Set up a webhook