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-01keeps the rows that have a date, and$filter=snoozedUntil eq 0001-01-01keeps 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 withif [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 to0001-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.