Skip to main content
This how-to explains how an integration validates readiness before processing Export Items. Pre-export validation ensures that the Accounting System and integration configuration are ready before any data is transferred. This step occurs after an Export Job has been claimed and before any Export Items are fetched or processed. At this stage, the Export Job is in progress and no accounting entries have been created, so failures can safely stop the workflow. Your integration must verify:
  • The Accounting System is available
  • The correct company context is selected for multi-entity scenarios
  • The correct Integration Configuration exists

​
Prerequisites

Before you begin:

​
Steps

​
1. Validate Accounting System Connectivity

Ensure the Accounting System is reachable and ready to accept data. Confirm:
  • API authentication is valid
  • required permissions are available
  • key operations are supported
Typical checks include:
  • ability to create journal entries
  • support for vendor bookkeeping (if applicable)
  • support for attachments
Example Pseudo: 
if not canAuthenticate():
    failExportJob(job.id, "accounting_system_unreachable")

if not hasRequiredPermissions():
    failExportJob(job.id, "invalid_configuration")

​
2. Validate Company Context

API Endpoint: GET /v3/export-jobs Example parameters: companyId: 12abc3d4-e567-890e-1234-abc56e78fabc Use Export Job metadata to ensure the correct company context is selected. This is important in multi-entity setups. 
{
  "companyId": "12abc3d4-e567-890e-1234-abc56e78fabc"
}
Example Pseudo: 
if not companyExists(job.companyId):
    failExportJob(job.id, "invalid_configuration")

​
3. Validate Bookkeeping Capability

API Endpoint: GET /v3/export-jobs Export Jobs may require specific bookkeeping workflows. For example: 
{
   "vendorBasedBookkeeping": true
}
If vendor-based bookkeeping is required, your integration must support it. Example Pseudo: 
if job.vendorBasedBookkeeping and not supportsVendorMode():
    failExportJob("invalid_configuration")

​
4. Fail Early if Validation Fails

API Endpoint: POST /v3/export-job-events Example parameters: jobId: 8eb648ab-464b-42a0-ba17-eda703657e33 If any validation step fails, the Export Job must be explicitly marked as failed. Failing early ensures:
  • no Export Items are processed
  • the system remains consistent
  • users receive clear feedback in Pleo’s Web App
Example Pseudo: 
if validationFails:
    failExportJob(job.id, reason)
    stop processing

​
Example Request

      curl -X POST "https://external.staging.pleo.io/v3/export-job-events" \
      -H "Authorization: Bearer <access_token>" \
      -H "Content-Type: application/json" \
      -d '{
              "event": "failed",
              "jobId": "8eb648ab-464b-42a0-ba17-eda703657e33",
              "failureReason": "vendorBasedBookkeeping not supported by this integration",
              "failureReasonType": "invalid_configuration"
          }'

​
Example Response

API Endpoint: GET /v3/export-jobs/{jobId} If the request succeeds, re-running the /v3/export-jobs/{jobId} command will return an updated status of failed. 
{
  "status": "failed",
  "failureReasonType": "invalid_configuration",
  "failureReason": "vendorBasedBookkeeping not supported by this integration",
}

​
Pleo Web App

The failed export status is updated in the Pleo Web App. Once any issues have been resolved, rerun the export job by clicking Export at the bottom of the screen.
Export Job Error

​
Common Failure Reasons

Use clear and actionable failure reasons:
  • invalid_configuration — unsupported workflows
  • missing_configuration — missing mappings or setup
  • accounting_system_unreachable — connectivity or API issues

​
Result

After completing these steps:
  • The integration has verified readiness for export processing
  • Invalid or unsupported scenarios are safely rejected
  • Only valid Export Jobs proceed to item processing

​
What Comes Next?

this how-to is part of:
Export Integration Workflow Guide