Skip to content
Bitta Apps

Bitta Collections reference

Collections API

The Bitta Collections API pages for Power Automate, Power BI and other API clients: entities, bound actions, permission sets, seats and example requests.

updated: applies-to: 1.2.0.0

Bitta Collections publishes its collections data as Business Central API pages. Power Automate, Power BI and any other client of the Business Central API can read work items, activities, promises, disputes, payment plans, mail requests and remittances, and can log activities, record promises and open disputes.

Applies to: Bitta Collections 1.2 on Business Central online, version 28 or later.

Every action runs the same code as the action on the Bitta Collections page, with the same checks, permissions, license and seat rules, and the same error messages. No API call posts, sends email or letters, applies cash or moves money.

The API route

All pages are in one API group: publisher bittaApps, group collections, version v1.0.

https://api.businesscentral.dynamics.com/v2.0/<tenantId>/<environment>/api/bittaApps/collections/v1.0/companies(<companyId>)/<entitySet>

Each record has an id and a lastModifiedDateTime. Business Central's own customers and customerLedgerEntries APIs cover customers and invoices.

Entities

Entity set What it holds Bound actions
customerCollectionStatuses Per customer: balance, overdue amount, collector, risk rating, credit hold, next action, priority score, earliest promised pay date, open disputes and last activity logActivity, createPromise, openDispute
workItems The collections worklist: status, priority score and explanation, overdue amount, next action, snooze and close snoozeWorkItem, closeWorkItem, logActivity
activities Calls, emails, notes, letters and every logged step
promises Promises to pay with date, amount, amount received, status and the documents they cover
disputes Invoice disputes with reason, amount, owner, due date and resolution
paymentPlans Payment plans with totals, next due date and status
paymentPlanInstallments The installments of each plan
mailRequests Letters and statements sent by post, with status and tracking
remittances Remittance advices with sender, customer, amounts and the matched payment

customerCollectionStatuses has the navigation parts workItems, activities, promises, disputes, paymentPlans, mailRequests and remittances, so $expand works on them. paymentPlans has installments.

Filtering

Every field works in $filter and $orderby except four that are calculated for each record when it is read: three on customerCollectionStatuses and one on promises. A filter on one of them fails with "Field ... is not filterable".

Field Instead, filter on
assignedCollectorCode collectorCode (blank means the default collector), or collectorCode on workItems
oldestDaysOverdue daysOverdue or oldestDueDate on workItems
promisedAmountText promisedAmount on promises
documentNumbers on promises customerNumber; the list names the documents the promise covers, so read it from the results

So customerCollectionStatuses?$filter=nextAction eq 'Call', openDisputes gt 0 and promisedPayDate gt 0001-01-01 all work. Use $top on large lists.

Values and blanks

Choice fields

A choice field returns the value name: the name you see on the page without spaces or parentheses. For example, Follow Up Broken Promise returns FollowUpBrokenPromise and Left Message returns LeftMessage. Filter on the name: $filter=nextAction eq 'FollowUpBrokenPromise'. A field that is blank on the page returns None, for example nextAction on a work item without a next action. The risk rating shows Not Rated on the page and returns None.

Two Business Central fields keep Business Central's own names, as in Microsoft's APIs: blocked on customerCollectionStatuses and documentType on disputes. Their blank value and the spaces in their names are written _x0020_, for example Credit_x0020_Memo.

Entity set Field Values
workItems status Open, Snoozed, Closed
workItems, customerCollectionStatuses nextAction None, Call, Email, Statement, FollowUp, FollowUpBrokenPromise, ReviewDispute, ReviewCreditHold, ReviewReminder, EscalationReview, ReviewPaymentPlan, ReviewAgencyPlacement, ApproveMail, FixMailAddress, ReviewRemittance, ReviewCustomerReply
workItems closeReason None, Paid, NoActionNeeded, ManuallyClosed
activities activityType Note, Call, Email, Statement, Reminder, Promise, Dispute, CreditHold, CreditRelease, Escalation, PaymentApplied, Meeting, SequenceSkipped, PaymentPlan, AgencyPlacement, AgencyRecovery, Mail, Remittance, OnlinePayment, CustomerReply, Portal
activities direction Outbound, Inbound, Internal
activities outcome None, Reached, LeftMessage, NoAnswer, WrongContact, PromiseMade, DisputeRaised, WillCallBack, Refused, Kept, PartlyKept, Broken, Resolved, Sent, Delivered, Returned, Withdrawn, Recovered
activities emailStatus None, Queued, Sent, Failed
promises, paymentPlanInstallments status Open, Kept, PartlyKept, Broken, Canceled
disputes status Open, Resolved
disputes resolution None, CreditMemoIssued, CustomerWillPay, WrittenOff, Withdrawn, EntryClosed
customerCollectionStatuses riskRating None, Low, Medium, High
customerCollectionStatuses creditHoldReason None, Manual, Overdue, OverCreditLimit, BrokenPromise, DunningStep
paymentPlans status Draft, Active, Completed, Broken, Canceled
mailRequests document CollectionLetter, Statement
mailRequests letterTone Friendly, Firm, Final
mailRequests status Draft, Approved, Sent, Printed, InTransit, Delivered, Returned, Failed, Canceled
mailRequests provider Lob
mailRequests addressCheck NotChecked, Deliverable, DeliverableUnitIssue, Undeliverable, NotVerifiedTestMode, NotCheckedInternational
mailRequests mailClass FirstClass, Standard
mailRequests extraService None, Certified, CertifiedReturnReceipt
remittances source EmailBody, CSV, Excel, PDF, TextFile
remittances status New, Ready, NeedsReview, Matched, Applied, Ignored, Failed
remittances matchedBy None, Sender, Document, Manual
remittances matchSource UnappliedPayment, PaymentReconciliation

Other extensions can add values to some of these fields, so a flow or report should handle a value it doesn't know.

Empty dates

An empty date returns 0001-01-01, and an empty date and time returns 0001-01-01T00:00:00Z. This is how every Business Central API returns an empty date. Treat it as blank:

  • In a request: $filter=nextActionDate gt 0001-01-01 keeps the rows that have a date, and $filter=snoozedUntil eq 0001-01-01 keeps the rows that don't.
  • In Power BI: in Power Query, replace the value with null after loading, for example Table.ReplaceValue(Source, #date(1, 1, 1), null, Replacer.ReplaceValue, {"nextActionDate", "oldestDueDate"}), or add a column with if [nextActionDate] = #date(1, 1, 1) then null else [nextActionDate].
  • In Power Automate: use the expression if(equals(item()?['nextActionDate'], '0001-01-01'), null, item()?['nextActionDate']), or a condition that the date is not equal to 0001-01-01.

Actions

Bound actions are POST requests to .../<entitySet>(<id>)/Microsoft.NAV.<action> with a JSON body that names every parameter. Send "" for a blank text, 0 for a blank amount and "0001-01-01" for a blank date. An action that returns a number returns it as {"value": ...}.

Action Parameters Returns Seat
logActivity on workItems activityType (Note, Call, Email or Meeting), outcome, direction, description, notes, followUpDate The activity entry number No
logActivity on customerCollectionStatuses The same, plus documentNo The activity entry number No
snoozeWorkItem untilDate, reason Nothing No
closeWorkItem reason: Paid, NoActionNeeded or ManuallyClosed Nothing No
createPromise promiseDate, documentNo, promisedAmount, notes The promise number Yes
openDispute documentNo, reasonCode, disputedAmount, description The dispute number Yes

Choice parameters take the value name or the name shown on the page, in any case: "PromiseMade", "Promise Made" and "promiseMade" are the same. "" and "None" both mean blank, such as no outcome. With a blank documentNo, createPromise covers the entries the New Promise dialog offers and promisedAmount must be 0. openDispute with an amount of 0 disputes the remaining amount. Recording a promise sets the native Promised Pay Date, and opening a dispute sets the native Dispute Status, as in the app.

Permission sets and seats

The Bitta Collections permission sets cover collections data. The API pages also read customers and customer ledger entries, so a user or Microsoft Entra application needs a Business Central set as well. Set an application's permission sets on the Microsoft Entra Applications page.

Client Permission sets Seat
Reads only, such as reports and dashboards D365 READ, which includes BAA COLL READ No
Logs activities, snoozes and closes work items D365 READ and BAA COLL EDIT, or D365 ACC. RECEIVABLE No
Also records promises and opens disputes The same Yes

D365 BUS FULL ACCESS alone covers all three. Without read access to customers, every API page refuses with an error that names D365 READ. To give an application a seat, choose Assign Seat on the Bitta Collections License page and pick the application. See License and seats.

Examples

Customers more than 10,000 overdue and not on hold:

GET <base>/companies(<companyId>)/customerCollectionStatuses?$filter=overdueAmountLCY gt 10000 and onCreditHold eq false&$top=20

One customer with promises, disputes and work items:

GET <base>/companies(<companyId>)/customerCollectionStatuses(<customerId>)?$expand=promises,disputes,workItems

Record a promise of 5,000 on invoice 103021:

POST <base>/companies(<companyId>)/customerCollectionStatuses(<customerId>)/Microsoft.NAV.createPromise
Content-Type: application/json

{ "promiseDate": "2026-11-20", "documentNo": "103021", "promisedAmount": 5000, "notes": "Promised on the phone by AP" }

Log a call and follow up on Tuesday:

POST <base>/companies(<companyId>)/workItems(<workItemId>)/Microsoft.NAV.logActivity
Content-Type: application/json

{ "activityType": "Call", "outcome": "LeftMessage", "direction": "", "description": "", "notes": "Voicemail for AP", "followUpDate": "2026-11-17" }

AI assistants (preview)

Microsoft's Business Central MCP server can offer API pages to AI assistants such as Microsoft Copilot and assistants built in Copilot Studio. Using the Bitta Collections API pages through the MCP server is in preview. The assistant works with the permissions and seat of the signed-in user, or of the Microsoft Entra application it connects as, and the same checks apply. See Microsoft's Configure Business Central MCP Server.

Next step

Ready to try Bitta Collections?