API Booking Error: Issuing Country Cannot Be Null - Incomplete PGI Identity Document Fields

Problem

When attempting to book services through third-party supplier APIs, the booking fails with an error message containing ‘issuing country cannot be null’ or ‘identification_document > [issuing country] [This field may not be null]’. This occurs when passport/identity document information is partially completed in the passenger PGI data.

What We Found

The API requires identity document information to be either completely filled or completely empty. If some fields are provided (e.g., Identity Number and Expiration Date), ALL identity document fields must be completed including: Document Number (passport number), Expiry Date (passport expiry), Document Type (e.g., passport), and Issuing Country (two-character country code from Issue Location field). Salesforce PGI schemes may allow optional identity document fields, permitting users to save partial information that the API then rejects.

Solution

1. Verify the passenger PGI data has complete identity document information - check that Issue Location (issuing country) is filled if any passport fields are populated
2. Navigate to Kaptio Settings > PGI Settings > PGI Schemes to review your PGI scheme configuration
3. Option 1: Make all identity document fields mandatory in the PGI scheme so users must complete all fields when entering passport information
4. Option 2: If hiding the Identity Type field, create a flow or trigger to auto-populate it with ‘Passport’ value, and make all other identity document fields required
5. Option 3: Create a validation rule on the Passenger object that prevents saving PGI if identity document fields are partially filled
6. For existing bookings with this error: Complete the missing Issue Location field for all passengers and retry the booking

Notes

• Successful bookings require either ALL identity document fields completed OR none at all - partial completion is not permitted by the API
• The client (customer) controls which PGI fields are mandatory via PGI Scheme configuration - this is not a Kaptio-side setting
• If deactivating Identity Type values except Passport, ensure users are trained to complete all identity document fields when entering passport information
• This behavior applies to all third-party supplier API integrations that require passenger identification documents

Warnings

⚠️ Do not hide the Issue Location field without implementing a compensating control (validation rule or mandatory field setting) ⚠️ Changes to PGI schemes affect all future passenger data entry - test in sandbox before production deployment

---

Source: KHELP-10655