This article is part of this article serie: API Best Practices - Introduction
In this article we'll explain how you can download all customers and/or suppliers from Twinfield and keep a shadow database in your own software. We ask you to follow this best practice because it supports our Fair Use Policy. You can read about our Fair Use Policy here: https://accounting.twinfield.com/webservices/documentation/#/GettingStarted/FUP
Good to know: There is a Postman-collection in the attachment of this article with ready to use examples of the xml requests that are mentioned in this article.
The process of keeping a shadow database in your own software has three steps:
- Download the intial load only once
- Download the incremental load daily or weekly
- Periodically validate if your shadow database is correct
During the initial load you will request all the customers and/or suppliers from Twinfield. This is your starting point. After you have done this, you will continue by requesting only the changes since the initial load. This is called the incremental load. You can do the incremental load daily or weekly depending on your needs.
The initial load
For the initial load you can use the Finder. Please refer to the request Find customer/supplier codes in the Postman collection in the attachment of this article for a ready to use example. Please refer to this article for the complete documentation about using the Finder:
https://accounting.twinfield.com/webservices/documentation/#/ApiReference/Miscellaneous/Finder
Important: Please follow the best practice by limiting the amount of codes that you download to 25 at a time. You can use the firstRow and maxRows parameters for this:
<twin:firstRow>1</twin:firstRow>
<twin:maxRows>25</twin:maxRows>
Important: You must download the customer and supplier codes separately. Use dimtype DEB for customers and dimtype CRD for suppliers.
<twin:ArrayOfString>
<twin:string>dimtype</twin:string>
<twin:string>DEB</twin:string>
</twin:ArrayOfString>
After you have downloaded all the customer and/or supplier codes you can make a separate request to download all the details. You can use the <Read> to download the details of one customer or suppliers at a time. Please refer to the Postman collection in the attachment for an example.
Good to know: Use dimtype DEB for customers and CRD for suppliers.
<soap:Body>
<twinfield:ProcessXMLDocument>
<twinfield:xmlRequest>
<read>
<type>dimensions</type>
<office>TEST10</office>
<code>1000</code>
<dimtype>DEB</dimtype>
</read>
</twinfield:xmlRequest>
</twinfield:ProcessXMLDocument>
</soap:Body>
The incremental load
After you have downloaded the initial load you can set up a daily or weekly request that only downloads customer and/or supplier codes that were added or changed since your last download. You can use the same Finder request as you used for the initial load, but this time you will add this extra criteria:
<twin:ArrayOfString>
<twin:string>modifiedsince</twin:string>
<twin:string>20260325000000</twin:string>
</twin:ArrayOfString>
This will limit the customer and/or supplier codes that you download to only those that were added or changed within the time range that you specify. The date/time format is "yyyymmddhhmmss". 20260325000000 means 25 March 2026 at 00:00:00 hours.
Good to know: The API only uses universal time (UTC). You can check the current time in UTC here: https://time.is/utc
The next step is to download the details for each customer and/or supplier. You can use the same request as you used for the initial load.
Periodically validate your shadow database
Keep in mind that the above steps will not tell you if a customer and/or supplier has been deleted in Twinfield. The only way to verify if there are deleted customers and/or suppliers is to periodically request all customer and/or supplier codes via the Finder and to compare them with your shadow database.
If a customer and/or supplier exists in your shadow database but not in the result of the Finder, then the customer and/or supplier must have been deleted in Twinfield. You can now also delete it in your shadow database.
Good to know: You can repeat the steps of the Finder in the initial load to find all customer and/or supplier codes.
