Sync expense transactions
Record expense transactions in your customer's accounting software and monitor the progress of dataset syncs
Sync transactions
Once you have pushed your customer's expense transaction data to Codat, you need to initiate the sync process that records the expenses in the customer's accounting software.
Use the Initiate sync endpoint to trigger a transaction sync. The process fetches the datasets from Codat's cache, validates and maps the data, and then pushes it to the target platform.
You can continue pushing new expenses to Codat while a sync is ongoing.
POST https://api.codat.io/companies/{companyId}/sync/expenses/syncs
{
"datasetIds": ["fd4cc60e-8666-4443-8fad-12c56d7420ee"]
}
Check sync status
Once you have initiated the sync, you may want to check whether the sync was completed successfully and view the details of any errors that may have occurred.
Webhook events
We recommend you use webhooks to track the sync status, navigate to Settings > Webhooks > Rules in the Codat Portal and click Create new rule to set up the following webhooks:
- Expenses sync failed webhook of
Sync Failedtype is triggered if any failures occurred during the sync process. - Expenses sync completed webhook of
Sync Completedtype is triggered when a sync completes without any failures.
You can read more about webhooks at Codat and various trigger events we offer to monitor.
Sync status codes
| Code | Reason |
|---|---|
| 1000 | In progress |
| 1010 | In progress (Long running - over ten minutes) |
| 2000 | Success (Data pushed) |
| 2040 | Success (No data pushed) |
| 4000 | Configuration error |
| 4040 | Company deleted/de-authorized |
| 4220 | Company deleted/de-authorized |
| 4260 | Accounting platform billing expiry |
| 5000 | Generic server error |
| 5080 | Duplication protection |
| 5120 | Data processing error |
| 5130 | Data push error |
Sync status via API
Alternatively, you can check the sync status via our API using any of the following endpoints:
- Latest sync status to check the status of the last initiated sync.
- Last successful sync to view the most recent sync that completed successfully.
- List sync statuses to display status details of all syncs for a specified company.
- Get sync status to check the status details of a specified sync.
- Request URL
- Sync Successful
- Sync Failed
GET https://api.codat.io/companies/{companyId}/sync/expenses/syncs/syncId/status
{
"companyId": "71c1fdae-e104-4668-8a4c-7f795aafc2a4",
"syncId": "ea86bb15-7a89-4b2d-a18d-626cc0e28137",
"syncStatusCode": 2000,
"syncStatus": "Complete",
"errorMessage": "",
"syncExceptionMessage": "",
"syncUtc": "2022-08-03T01:30:09.0797213Z",
"dataPushed": true
}
{
"companyId": "8cba59e5-ae8a-418b-918a-09f90850e8d8",
"syncId": "2b5d5fd1-f4b2-49de-98c3-ca37a0dcd8cd",
"syncStatusCode": 5130,
"syncStatus": "PushError",
"errorMessage": "An error occurred in a downstream service. Correlation ID: 1f6ab1bc-58c8-4c1a-a654-86464b065f69. Message: Feed Connection failed(409): The AccountToken, AccountId or AccountNumber is already connected to another Xero Bank Account in the selected Xero Organization.",
"syncExceptionMessage": "An error occurred in a downstream service. Correlation ID: 62f0f708-ae37-4b3a-81b1-41f1361f0b40. Message: Feed Connection failed(409): The AccountToken, AccountId or AccountNumber is already connected to another Xero Bank Account in the selected Xero Organization.",
"syncUtc": "2022-08-03T01:11:33.6279333Z",
"dataPushed": false
}
Transaction status
If you want to check the status of individual transactions, use the Get sync transaction endpoint. It also returns errors associated with the transaction if it was unsuccessful.
Alternatively, use the List sync transactions endpoint to view statuses for all transactions in a specified sync.
- Request URL
- Successful Transactions
- Failed Transactions
GET https://api.codat.io/companies/{companyId}/sync/expenses/syncs/{syncId}/transactions
{
"results": [
{
"transactionId": "0331d9b9-a1cd-4d46-84d3-5a17dc6ad43e",
"status": "Completed",
"integrationType": "bankfeeds"
},
{
"transactionId": "0331d9b9-a1cd-4d46-84d3-5a17dc6ad43e",
"status": "Completed",
"integrationType": "expense"
}
],
"pageNumber": 1,
"pageSize": 100,
"totalResults": 134,
"_links": {
"current": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions?page=1&pageSize=100"
},
"self": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions"
},
"next": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions?page=2&pageSize=100"
}
}
}
{
"results": [
{
"transactionId": "0331d9b9-a1cd-4d46-84d3-5a17dc6ad43e",
"status": "PushError",
"message": "An error occurred in a downstream service. Correlation ID: 0e7ee4bc-50d2-4e07-8f9e-25fdda6bc004. Message: Feed Connection failed(409): The AccountToken, AccountId or AccountNumber is already connected to another Xero Bank Account in the selected Xero Organization.",
"integrationType": "bankfeeds"
},
{
"transactionId": "0331d9b9-a1cd-4d46-84d3-5a17dc6ad43e",
"status": "PushError",
"message": "An error occurred in a downstream service. Correlation ID: 0e7ee4bc-50d2-4e07-8f9e-25fdda6bc004. Message: Feed Connection failed(409): The AccountToken, AccountId or AccountNumber is already connected to another Xero Bank Account in the selected Xero Organization.",
"integrationType": "bankfeeds"
}
],
"pageNumber": 1,
"pageSize": 100,
"totalResults": 134,
"_links": {
"current": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions?page=1&pageSize=100"
},
"self": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions"
},
"next": {
"href": "/companies/0c690bba-9fdc-435b-9790-b22928ce1c96/syncs/3f652c19-b6d8-477a-a853-5b726d145cde/transactions?page=2&pageSize=100"
}
}
}
Monitor sync health
Use the Sync for Expenses product menu in the Codat Portal to navigate to Sync Health and monitor the status of your syncs, review detailed logs and error messages, and view and retry pushing failed items. This helps your support team to resolve common issues with the customer's settings or actions.
- Check the dashboard (1) for a visual summary of sync totals.
- Use the search bar (2) to narrow down the records by sync ID or company ID.
- Display the sync history for a specific period by indicating a date range (3).
- Review the possible statuses of the syncs and filter the records by their status code (4).
- Use the menu (6) to sort and amend the sync history (5) table as needed.
View detailed records
To view more detailed information about a record, click on an item in your sync history. The information appears in the Sync Details window and provides sync start and end times, and sync source and target platforms.
It also displays client-friendly notes and error messages in case of sync failures.
You can also navigate to the Config tab to view and download the customer's sync configuration, which helps establish root causes for any errors that ocurred.
View push items
In the same detailed record view, select the Push items tab to access a list of push items. The list contains an item for each accounting data type that was produced in the selected sync.
Here, you can view each item's status, search the items by their core ID or data type, or filter them by status.
Retry push items
On the Push items tab, you can also retry the push items in failed status. Click the Retry failed items button to trigger another attempt to push the data of all failed push items into the accounting platform. The button is only enabled if there are failed items to retry.
💡 Tips and traps
- Syncs are shown as failed if any of the included items fail to push. Therefore, if a sync contains a mix of failed and successfully pushed records, it will still be marked as failed.
- Sync history does not display the date range for data pulled from the platform that is used in the sync.
Read next
- Attach receipts to the expense transaction using attachment upload
- Review our FAQ to find out more about Sync for Expenses
- Try Sync for Expenses in our interactive API reference