Collections Web Service Definition
Schedule 3
Referenced in Exhibit A of subscriber agreement
For notes on the Fair Credit Reporting Act (FCRA) and other general matters, see General notes on web services.
This web service searches for all cases explicitly referred to collections by the court since a certain date, as well as those which experienced one or more "collection events" of interest to a collections agency (e.g. a change in the amount owed or a payment taken at the court).
The court decides how to refer the cases:
in large groups based on delinquency and case type and/or file date
in small groups, as due process milestones pass
on a case-by-case basis
The web service does not include tools for importing payments made to the collection agency.
Sample calls on Judici test server
If any of the following don't work, contact Web Service User Support
Sample search #1- Note 9/23/2013: the "ALL" query is no longer supported.
Sample search #2- for a specified COLDATE
Data retention and synchronization
All of the Data obtained using this Service may be retained in the Compiled Index Records. This is because this Service, rather than providing a complete snapshot with every search, instead is sophisticated enough to update only those cases which have changed since a specified date. That said, there are some limits in the Service's ability to keep retained data "in sync" with the court's, especially when data can be added, modified or deleted by either party:
With the exception of payments and amounts owed, deletion of data at the court is not flagged for sending to the user. So the web service will not flag, for example, deletion of phone number and address
Some data elements in the court's case management system may not have a data element indicating when they were last updated.
For this and other reasons, it is wise for users of this web service to periodically re-acquire all cases ever referred to collections, in order to re-sync. If such a re-sync shows something out of sync, whether it the original data source was the court or the user, the user should work with the court to resolve the problem.
Summary/trailer records (e.g. total number of payments made on collections cases), are not used, since they wouldn't pinpoint the cases which are out of sync.
In order to re-sync in courts where both the collection agency and the court take payments, the court and the agency must both store a "source key/ID" for payments originated by the other.
SEARCHCASES call
https://www.judici.com/service/caseSearchService?SEARCHCASES&USERID=n &APPID=a&KEY=0x&BATCH=true &COURTID=ncic&COLDATE={mm/dd/yyyy|ALL}
Required parameters specific to this web service
format: mm/dd/yyyy
example: COLDATE=05/12/2010
example: ALL. Note 9/23/2013: the "ALL" query is no longer supported.
Optional parameters- none
Automatic selection criteria
The query finds all cases on which a referral, withdrawal, payment or adjustment (as indicated by the COLLECTIONSDATE in the Collections attributes ) occurred on or after the specified COLDATE, including the current date. Note: Originally, the current date was excluded. This was done because pulling data in the middle of the day would miss subsequent events that day. But in late 2014, this approach was shown to be problematic in the following rare scenario:
An event happens on Collections Date 1, and thus the case gets ignored in Pull 1
On Collections Date 2 (e.g. a week later), another collection event happens to occur, causing the case to be ignored again.
On Collections Date 3, no other events have occurred so everything after Collections Date 2 is pulled... the "sliding window" has slid past Collections Date 1, so the payment/referral etc. which happened on that date is never picked up.
Given that online payments can come in at any time, the only solution to this problem was to start picking up events occurring on the collections date... up to the point at which the data was pulled. But because of processing and communications time, you can't do a pull exactly at the stroke of midnight. So the question is whether to pull just before midnight, or just after? The answer is just after- we recommend about 12:15 or 12:20 a.m. Why? If you pull at 11:55 p.m. and an e-payment comes in at 11:58, you will miss it. If you pull at 12:15 a.m. and an e-payment comes in at 12:05, you will wind up getting it twice. But it's a good idea for agencies to check for such duplicates anyway. Every collection event transmitted by the web service definition has sufficient key data for the agency to check for duplicates.
So suppose you started referring cases on Thurs. Aug 7th, and you want to run the query after close of business each Sunday (remember that Judici E-Pay takes payments on the weekend!). Now suppose you skip the first Monday because you're not ready to pull the data in yet. You would then do the following queries:
On Mon., Aug. 19 at about 12:15 a.m., use COLDATE of Aug. 7th to get everything on or after August 7th.
On Mon. Aug. 26 at about 12:15 a.m., use COLDATE of Aug. 19th to get everything from Aug. 19th thru the time you pull
Repeat each Monday around 12:15 a.m., using the previous Monday's date as the COLDATE.
Important note: the web service calculates the InitialCollectionsBalance as of midnight on the referral data. So the Adjustment data will include the adjustment, on the referral date, by which the collections fee was added to the account. And in the odd event that the court enters some other adjustment, those would be returned by the web service. So adjustments on the same date as the case was referred should be ignored. The same is true of payments: the referral date should be compared to the ReceiptDate of regular payments, and the JournalDate of Audit type transactions- if there is a match, ignore the adjustment/transaction.
The case must have a non-zero amount of fees assigned to collections fees, as indicated in a Receivable element. Note that the collections fee could still be wrong.
Data returned
The required BATCH parameter means that the web service returns all of the case details, not just search results. It also aggregates some key elements into "flattened" XML files:
placement.xml file comprised of multiple Placement elements
withdrawals.xml file comprised of multiple Withdrawal elements
transactions.xml file comprised of multiple Payment elements to reflect payments (including any made at the court rather than to the collection agency).
adjustments.xml file comprised of multiple Adjustment elements indicating court-directed changes to the amount owed.
AppliedBonds.xml file comprised of multiple AppliedBond elements indicating the collection fee distribution in the event that a pending bond is applied.
If a court has referred cases prior to the involvement of a given collection agency, that agency may find itself with withdrawal, payment or adjustment records from cases which which predate its involvement.
The service also returns the usual xml file of search Results. But the batch/aggregate nature of the service means that this file only serves minor functions:
a source for "header" data such as that in AgreementsAndPolicies
case data for diagnostic purposes only, in the event of errors in aggregating the placements and transactions
The service also returns, for each case in the results, a file containing a single CourtDataTransfer element. But this is only needed for:
diagnostic purposes
if the user wishes to be aware of deletion of data other than payments and amounts owed
a periodic complete re-sync as described above
Data privacy override- at the request of the participating courts, the web service returns information on cases involving litigants who were minors at the time of filing.
GETCASE call
This call retrieves a litigant case available via this this web service, based on a case and litigant found using a previous search under this web serviceprevious CaseMD5 from a recent search and Litigant ID.
The SEARCHCASES call for this web service returns all the same data, so it isn't necessary to run any GETCASE calls, unless perhaps your are trying to make sure that the data you presently have on a case is correct.
https://www.judici.com/service/caseSearchService?GETCASE& USERID=n&APPID=a &KEY=0x[&COURTID=ncic] &CASEID=value from SEARCHCASES result &LITIGANTID=value from SEARCHCASES result
Keeping data in sync with the court
In Judici's xml schema, the Payment element has several attributes which hold cross-reference IDs to help the agency ensure that it is "in sync" with the court with respect to the payments on the case.
For payments originally receipted by the court, the Receipt attribute cannot (for a variety of reasons) be used as a unique and unchanging ID. Rather, the agency should track the TransactionType and Number attributes.
For payments originally receipted by the collections agency, the court should store some agency-generated ID (transaction ID or check number) in the Reference attribute (an 11-digit-maximum alpha-numeric).
Collection agency fees
If the court opts to collect the full amount from the litigant, including collection fees, they will typically add the agency's fees to the amount owed. The precise amount of fees added is indicated by a Receivable element on the case. The agency may wish to ensure that this was calculated correctly in comparison to the InitialCollectionsBalance in the Collections attributes in the LitigantDetails.
While Adjustment elements do track changes to the TotalOwed, the incremental change to a given Receivables element is not available. But the agency can still check the new amount in the Receivable.
Distributed/disbursed on a given payment
In this web service, the only distribution records provided are for the SA Collections fee. Absence of such a record usually indicates a failure by the court to distribute a portion of the payment to the collection agency.
Exception: if the payment receipt date is the same as the day the case first showed up as referred, it is almost certain that the court applied/reclassified an existing bond before referring the case.
Processing order
Naturally, referrals should be processed first. Withdrawals should be processed last, on the off chance that there was activity (payments etc) on a case the same day a case was withdrawn. Beyond that, order does not matter unless you are attempting to verify the snapshot/journal amounts referenced in datadefinitions.judici.com/900. Within any given file (e.g. transaction.xml), the data should be processed in the order presented.