Sync Payments and Companies from Business Central to folk CRM

This guide explains how to fetch company and payment information from Microsoft Dynamics 365 Business Central using its API, and sync it to folk using folk’s API. You can schedule this automation (daily, weekly, or monthly) based on your business needs.

I. Get Payment & Company Information from Business Central

You’ll use Microsoft Business Central’s API for three main tasks:

List all companies
Retrieve detailed information for each company
Retrieve customer payment information

🧾 A. List All Companies

Endpoint:

GET https://{businesscentralPrefix}/api/v2.0/companies

This API returns all companies in your Business Central instance.

Example Response:

[ { "id": "824820a2-508c-ed11-aada-000d3a298ab3", "systemVersion": "21.2.49946.51685", "timestamp": 50516, "name": "CRONUS US", "displayName": "CRONUS USA, Inc.", "businessProfileId": "", "systemCreatedAt": "2023-01-04T16:55:47.367Z", "systemCreatedBy": "f2a5738a-44e3-ea11-bb43-000d3a2feca1", "systemModifiedAt": "2023-01-04T16:55:47.367Z", "systemModifiedBy": "f2a5738a-44e3-ea11-bb43-000d3a2feca1" } ]

B. Get Detailed Company Information

Once you have a list of company IDs, fetch full company profiles to send to folk.

Endpoint:

GET https://{businesscentralPrefix}/api/v2.0/companies({id})/companyInformation

Example Response:

{ "id": "86f5f171-44e3-ea11-bb43-000d3a2feca1", "displayName": "CRONUS USA, Inc.", "addressLine1": "7122 South Ashford Street", "addressLine2": "Westminster", "city": "Atlanta", "state": "GA", "country": "US", "postalCode": "31772", "phoneNumber": "+1 425 555 0100", "faxNumber": "+1 425 555 0101", "email": "", "website": "", "taxRegistrationNumber": "", "currencyCode": "USD", "currentFiscalYearStartDate": "2021-01-01", "industry": "", "picture@odata.mediaReadLink": "https://api.businesscentral.dynamics-tie.com/.../picture", "lastModifiedDateTime": "2020-08-21T00:24:33.793Z" }

🔁 Field mapping suggestion for folk:

Business Central Field	folk Field
`displayName`	`name`
`addressLine1/2`	`address.line1/2`
`city`	`address.city`
`state`	`address.state`
`postalCode`	`address.postalCode`
`country`	`address.country`
`phoneNumber`	`phone`
`email`	`email`
`website`	`website`
`taxRegistrationNumber`	`customFields.Tax ID`
`currencyCode`	`customFields.Currency`
`industry`	`customFields.Industry`

💳 C. Get Customer Payments Information

To retrieve payment information for customers linked to each company:

Endpoint:

http CopyEdit GET https://{businesscentralPrefix}/api/v2.0/companies({companyId})/customers?$expand=customerPayments

This returns a list of customers and their associated payments. The $expand parameter allows you to retrieve related entities in one call.

Note: Depending on Business Central setup, you may need to retrieve payments separately via /customerPayments.

II - Update folk with Business Central’s data

Once you've retrieved companies and customer payment data from Business Central, you'll interact with the folk API to:

Search a company using Business Central's internal ID (stored in folk) or Company name
Create a company in folk if it doesn’t exist
Update an existing company if it already exist

All folk API calls must be authenticated with an API key (passed as a bearer token). You’ll find it within the Integration section of your settings.

1. Search a Company by Business Central ID or Name

This is critical for deduplication and future updates.

Option A: Search by `BusinessCentralCompanyId`

Example:

GET https://api.folk.app/companies?filter[customFieldValues.{group_id}.BusinessCentralCompanyId][in][eq]={BusinessCentralCompanyId}

Option B: Search by name (fallback)

GET https://api.folk.app/companies?filter[name][eq]={company_name}

🛑 Note: Searching by name is not reliable alone for automation — use stored IDs for precise matching.

2. Update a Company with Payment Info Only if it exists

If the company already exists in folk (e.g., previously imported), you might only want to update specific fields, such as payments or related metadata — without overwriting other values.

Step A: Find the company in folk

Use the Business Central ID you previously stored to search.

Endpoint:

GET https://api.folk.app/companies?customField=BusinessCentralCompanyId:{companyId}

Replace {companyId} with the value Business Central.

If a company exist: Update the company

Endpoint:

PATCH https://api.folk.app/companies/{folkCompanyId}

You get the folkCompanyId from the search result.

Example Response:

{ "customFields": { "Last Payment Date": "2024-12-20", "Total Paid This Year": "15000 USD", "Outstanding Balance": "5000 USD" } }

Only fields specified in the body are updated. Existing data not included remains unchanged.

3. Create a Company in folk - if doesn’t exist

You’ll send a POST request to create a company. Include all useful information retrieved from Business Central, including the Business Central companyId or customerId — stored in a customField so you can search by it later.

Endpoint:

POST https://api.folk.app/companies

Request Header:

Authorization: Bearer Content-Type: application/json

Example Response:

{ "name": "CRONUS USA, Inc.", "email": "info@cronus.com", "phone": "+1 425 555 0100", "website": "https://cronus.com", "address": { "line1": "7122 South Ashford Street", "line2": "Westminster", "city": "Atlanta", "state": "GA", "postalCode": "31772", "country": "US" }, "customFields": { "BusinessCentralCompanyId": "86f5f171-44e3-ea11-bb43-000d3a2feca1", "Tax ID": "123456789", "Currency": "USD", "Fiscal Year Start": "2021-01-01", "Industry": "Consulting", "Source": "Business Central" } }

Best practice: Always include BusinessCentralCompanyId or CustomerId in customFields. This enables easy matching in future updates.

✅ Summary: Field Strategy for Tracking

Purpose	Field in folk (`customFields`)
Match company to Business Central	`BusinessCentralCompanyId`
Match to customer ID	`BusinessCentralCustomerId`
Store last payment info	`Last Payment Date`, `Amount`