The Perk Spend Integration connects Perk to Microsoft Dynamics 365 Finance (D365 Finance) so cost objects, tags, categories, suppliers, and workers sync automatically, and expenses and invoices export to the right legal entity. This article walks you through the full setup, from registering the app in Entra ID or AD FS to verifying the first sync. 

For background on what the integration syncs and how, see Integrate with Microsoft Dynamics 365 Finance for expense and invoice processing.

Before you start

Setting up the integration touches both your D365 Finance environment and your Perk account. Make sure you have the listed requirements in place before you begin. D365 Finance requirements:

• An in-service version of D365 Finance (not an out-of-service version).
• A fully functional Accounts Payable module, if you're setting up the invoice integration.
• A fully functional Expense Management module, if you're setting up the expense integration.
• Entra ID access (cloud) or AD FS access (on-premises) to register the application.
• LCS (Lifecycle Services) access to deploy the integration package.
• The right D365 Finance security roles assigned to your users: an integration manager role for admins who need full configuration access, and an integration clerk role for people who only need day-to-day operations access. Assign these via System administration Security Users.

Perk requirements:

• An active Perk account.
• Account admin access to Settings Integrations to set up integration settings, and to People to assign roles.
• The Client ID and Client Secret from your Entra ID or AD FS app registration.

Register the app in Entra ID or AD FS

Registering an app gives Perk a secure identity it can use to call your D365 Finance environment. Do this first, since later steps need the Client ID and Client Secret it produces. The system you use depends on your deployment type: cloud - D365 Finance uses Microsoft Entra ID, and on-premises - D365 Finance uses AD FS instead. Cloud: register the app in Entra ID

1. Go to Microsoft Entra ID in the Azure portal, open Properties, and note the Directory ID (your tenant ID).
2. Go to App registrations New registration.
3. Enter a name that identifies the external application, for example Perk Integration. You don't need to set a redirect URI — this app authenticates as a confidential client using a client secret, not through a sign-in redirect.
4. Copy the Application (client) ID — you'll need it in later steps.
5. Set up API permissions: select Add a permission Microsoft Dynamics ERP (Microsoft.ERP) Delegated permissions, then select Access Dynamics AX Custom Service, Access Dynamics AX data, and Access Dynamics AX online as organization users.
6. Generate a client secret: go to Certificates & secrets New client secret, and set the expiration to the longest period your organization's secret policy allows.

On-premises: register the app in AD FS If your D365 Finance environment is on-premises, register the app with AD FS instead of Entra ID. AD FS registration is specific to your on-premises deployment, so follow Microsoft's on-premises deployment documentation and your organization's AD FS setup to register the application and generate a Client ID and Client Secret for it.

Register the app in Dynamics 365 Finance

D365 Finance needs its own record of the Entra ID or AD FS application before it will accept calls from Perk. This links the Client ID to a service account inside D365 Finance.

1. Go to System administration Setup Microsoft Entra ID applications New.
2. Enter the Client ID from your Entra ID or AD FS app registration.
3. Enter a name for the application.
4. Select the appropriate user ID for the service account.
5. Save the record.

Install the integration package via Lifecycle Services

The integration ships as a deployable package that you upload and apply through Lifecycle Services (LCS), then promote from sandbox to production. This step installs the code that powers the integration inside D365 Finance. Part 1: Upload the package to LCS

1. Log in to lcs.dynamics.com.
2. Select the project for your target environment.
3. Go to More tools Asset library Software deployable package.
4. Select + to add a new package, and enter a name and description.
5. Select Add a file and upload the integration package ZIP file.
6. Select Confirm to process the upload, and wait for validation — you'll see a checkmark in the Valid column when it's done.

Part 2: Apply the package to your environment

1. Open the environment details page.
2. Go to Maintain Apply updates.
3. Enter a unique name for the update.
4. Select the uploaded package from the list.
5. Select Apply, and monitor the status as it moves from Queued to Servicing to Post-servicing to Deployed.

Part 3: Promote the update to production

1. In the sandbox environment, go to History Environment changes.
2. Select the validated update.
3. Select Mark as release candidate.
4. In the production environment, go to Maintain Update environment.
5. Select the source sandbox and the release candidate.
6. Schedule the downtime window and select Schedule.

Set integration parameters in Dynamics 365 Finance

Integration parameters tell D365 Finance which Perk organization and legal entities to sync with, and which financial dimensions and tax data to include. Set these at three levels: system, legal entity, and global integration parameters.

1. Set system parameters: go to System administration System parameters, open the General tab, find the integration section, and enter the Perk organization ID.
2. Set legal entity parameters: go to Organization administration Organizations Legal entities. For each legal entity that uses the integration, open the record, find the integration section on the General tab, and enter the Perk legal entity ID.
3. Set global integration parameters: go to the integration's parameters setup area under Organization administration, and set up the following.
   • On the General tab, set the document type used for creating attachments through the integration.
   • On the Financial Dimension tab, set the name of the financial dimension that represents cost centers, and move the dimensions you want to sync into the Selected box.
   • On the Tax Rates tab, select the sales tax groups and item sales tax groups you want to synchronize. Only the combinations you set up here sync to Perk.

Set up business event endpoints

Business events are what trigger real-time data sync from D365 Finance to Perk. You set up one endpoint for most data and activate the individual business events you need.

1. Go to System administration Business events Business events catalog Endpoints tab New.
2. Set the endpoint type to Spend connector, and give it a name (for example Perk Integration Endpoint) and description.
3. Enter the auth and endpoint URLs for your environment (see below).
4. Add the header X-Yk-Auth-Method:yokoy exactly as shown — this is a fixed technical header the integration package expects, not a display name.
5. Enter the Perk Client ID and Perk Client Secret (generated in Developer tools Spend tools Access credentials).

Endpoint URLs for the test environment:

• Auth endpoint: https://accounts.test.yokoy.ai/oauth2/token
• Master data endpoint: https://api.test.yokoy.ai/v1
• Supplier endpoint: https://service.test.yokoy.ai/microsoft-dynamics-service/api/eu/public/be-terna/v1

Endpoint URLs for the production environment:

• Auth endpoint: https://accounts.yokoy.ai/oauth2/token
• Master data endpoint: https://api.yokoy.ai/v1
• Supplier endpoint: https://service.yokoy.ai/microsoft-dynamics-service/api/eu/public/be-terna/v1

Once your endpoint is set up, activate the business events you need in the Business events catalog:

• For the invoice integration: the vendor data event, cost center dimension event, other financial dimensions event, procurement categories event, purchase order confirmation event, purchase order product receipt event, payment terms event, and tax rate event.
• For the expense integration: the worker data event, expense categories event, and projects event. The cost center dimension event and other financial dimensions event are shared between both integrations.

You can activate business events without specifying a legal entity — they trigger for every legal entity that has the required integration configuration.

Run initial data sync

Before you rely on ongoing automatic sync, run one-time batch jobs to bring your existing master data across from D365 Finance to Perk. You'll find these batch jobs in the integration's batch job processing area under Organization administration. Run the following batch jobs:

• Workers, expense categories, and projects, if you're setting up the expense integration.
• Financial dimension synchronization for cost centers and other financial dimensions as custom fields.
• Vendors, using the correct supplier endpoint, with Send test request turned off. (invoice processing only)
• Procurement categories, which needs category hierarchy role associations set up first. (invoice processing only)
• Tax rates, which you should schedule to run recurringly, for example every ten minutes, since tax rates only ever sync via batch job, not business events.
• Purchase orders, which only syncs confirmed purchase orders that already have a confirmation journal. (invoice processing only)
• Payment terms, which is query-based and supports filtering. (invoice processing only)
• Product receipts.

Set up the integration in Perk

With D365 Finance set up, finish the setup on the Perk side: link your legal entities, and set up expense and invoice export.

1. Set up the company code: go to Settings Account Company Spend settings General, and enter the D365 Finance legal entity ID in Company code (ERP) for each Perk legal entity. This makes sure expenses and invoices export to the correct D365 Finance legal entity.
2. Set up two technical custom fields on the cost object, which are used for synchronizing cost centers and projects. Go to Settings Account Companies Spend settings and click Add Cost centers custom field:

1. Set up expense export: go to Settings Integrations Expense export, select Finance & Operations from the ERP system list, enter the Client ID and Client Secret from your Entra ID or AD FS app registration, and select Update ERP to save the credentials. Then set the Token URL and the Base URL (your D365 Finance environment URL):
   • Cloud: Token URL is https://login.microsoftonline.com/{tenant-id}/oauth2/token, replacing {tenant-id} with your Entra ID Directory ID. Base URL is your cloud environment URL, for example https://your-company.operations.dynamics.com.
   • On-premises: Token URL is your AD FS server's token endpoint instead of login.microsoftonline.com — get this from your network or AD FS admin team. Base URL is your on-premises server URL, for example https://your-msd365f-server.yourdomain.com.

Optionally, turn on Send documents to send receipts and attachments, Submit Expense in Finance and Operations to auto-submit expenses to the D365 Finance workflow, Include tax in Finance and Operations to export tax group fields, and set up payment method mapping. Repeat this for each expense type: reimbursable expenses, transactions, and travel expenses.

1. Set up invoice export: go to Settings Integrations Invoice export, select Finance & Operations Supplier Invoice Export, and on the Configuration tab enter the Token URL and Base URL using the same pattern as expense export — cloud or on-premises, depending on your deployment. Optionally turn on Send documents and Post Invoice in Finance and Operations to auto-post invoices. On the Authorization tab, enter the Client ID and Client Secret, then select Save to finish the wizard.
2. If you use financial dimensions as custom fields, check Settings Cost management Custom fields to see your synchronized custom fields.

Verify the sync

After your initial sync runs, confirm the data landed correctly in Perk before you go live. Check each of the following areas:

• Settings Cost management Cost objects, for cost centers and projects.
• Settings Cost management Custom fields, for financial dimensions.
• Settings Expense settings Expense categories, for expense categories.
• Settings Supplier invoices Invoice categories, for procurement categories.
• People, for workers and users.
• Invoice Supplier invoices Suppliers, for vendors.

If any of these areas look empty or incomplete, go back and check the corresponding batch job or business event from the earlier steps before rolling the integration out to your wider team.

Troubleshoot configuration issues

Here are some potential issues you may encounter and how to fix them.

Business events aren't reaching Perk

• Confirm the business event is activated in System administration Business events.
• Check the endpoint configuration (auth URL, endpoint URL, credentials).
• Make sure the legal entity has its Perk legal entity ID set.
• Review the business event log for errors.

Initial sync didn't bring data across

• Confirm the batch job parameters are set correctly.
• Check the endpoint matches the one required for that batch job (vendors use the separate supplier endpoint, with Send test request off).
• Make sure the service account has sufficient permissions.
• Review the batch job history for error details.

Expenses or invoices aren't exporting

• Check the export configuration in Perk (Token URL, Base URL, credentials).
• For expenses, confirm the worker has a valid, active D365 Finance user connection (or a delegate that does).
• For invoices, confirm the vendor exists in D365 Finance.
• Review the export logs for error details.

Tax rates aren't updating

Tax rates sync via a scheduled batch job, not in real time.

• Confirm the tax rate batch job is scheduled and running.
• Check the Sales tax group / Item sales tax group combinations are selected in the integration parameters.