ACD passport uploads

Some flight bookings are ACD bookings. FX-Port needs one passport copy for every traveler on the booking, and you send the copies after the booking exists. This page is the reference for the two endpoints that do it: get_acd_documents tells you what a booking needs and what it already has, upload_acd_documents adds or replaces the files.

Both are in the default rate group (6,000 requests per minute per key). They answer only for bookings of your agency and of the environment of your key: a sandbox key never sees a live booking, and a booking of another agency looks exactly like a booking that does not exist (404 BOOKING_NOT_FOUND, see Which bookings you can reach).

What ACD means for a booking

An ACD booking is a booking made with an ACD fare. Only the Amadeus Algeria supplier (amadeus_aqc_dz_1) sells them. The price of such a fare is adjusted by a rule (see Flight pricing), and the booking is completed with passports:

• One passport per traveler on the booking. The travelers are the passengers stored on the booking, so the list exists as soon as the booking exists. No ticket is needed: ticket_number is null for a hold, and for an instant booking until the airline returns it.
• Upload at any time after the booking was created, also while it is still a hold (Hold bookings). A booking that is cancelled, failed, voided, refunded or expired refuses uploads (BOOKING_NOT_ELIGIBLE).
• The set is complete when every traveler has a passport. The booking then becomes acd_submitted: true, and for an issued booking in the live environment FX-Port's ACD team is told by e-mail (Notifications).
• A wrong or unreadable scan is replaced with replace=true. FX-Port keeps the replaced file and tells the ACD team about the change.
• Duffel bookings are never ACD bookings: their offers have no acd key, and get_acd_documents answers acd_required: false.

Recognise an ACD booking

The flag has several spellings, one for each step of the booking flow:

Test it in the sandbox

ACD fares exist only on amadeus_aqc_dz_1, and in the sandbox a search from CDG to ALG on that supplier returns only ACD fares: all 62 offers of a search on 2026-11-01 had pricing.acd.applied: true, and so did every offer of every earlier run (38 to 62 offers). Five calls give you a booking that needs passports.

1. 1

   Search CDG → ALG on the ACD supplier

   curl --request POST 'https://api.fx-port.com/api/v1/get_flights' \
     --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
     --header 'Content-Type: application/json' \
     --compressed \
     --data '{
       "origin": "CDG",
       "destination": "ALG",
       "departure_date": "2026-12-20",
       "cabin_class": "economy",
       "passengers": { "adults": 1 },
       "supplier_id": "amadeus_aqc_dz_1"
     }'

   Use a date 30 to 60 days ahead. Every offer carries the flag:

   {
     "id": "fx_offer_3cb9ee1c",
     "requiresACD": true,
     "pricing": {
       "agencyCurrency": "DZD",
       "finalPrice": 52078.03,
       "acd": { "applied": true, "scenario": "B", "...": "..." }
     }
   }

   Other routes also give ACD fares: a departure from Algeria to some countries does (ALG → JFK: 146 of 146 offers on 2026-11-01), most other Algerian routes do not (ALG → CDG: 1 offer of 90, a mixed-carrier fare). In production, read pricing.acd.applied of the offer you book. In a search that also covers Duffel (no supplier_id), only the Amadeus Algeria offers have it.

2. 2

   Price the offer

   Send the searchId of the supplier entry and the id of the offer to price_flight (search_id, offer_id). The priced offer has pricing.acd and requiresACD again.

3. 3

   Book it

   book_flight with "booking_type": "issue" (instant) or "hold", and "send_email": false. The answer says "requiresACD": true. Keep the PNR (booking.pnr): it is the booking_id of the ACD calls.

   {
     "success": true,
     "booking": { "status": "confirmed", "pnr": "Y7HWMD", "type": "instant" },
     "requiresACD": true,
     "pricing": { "acd": { "applied": true, "scenario": "B", "...": "..." }, "...": "..." }
   }

   A hold of the cheapest offers can fail at the supplier (we saw 2 holds of 3 fail on 2026-11-01); book another offer, or use issue. Each failed booking leaves a FAILED-… record: see the errors of the book call.

4. 4

   Read the state

   curl --request POST 'https://api.fx-port.com/api/v1/flights/get_acd_documents' \
     --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
     --header 'Content-Type: application/json' \
     --data '{ "booking_id": "Y7HWMD" }'

   Expect acd_required: true, required_documents equal to the number of passengers, missing_traveler_ids: ["1"] and can_upload: true.

5. 5

   Create two fake files and upload them

   echo 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4//8/AAX+Av4N70a4AAAAAElFTkSuQmCC' | base64 -d > passport-1.png
   printf '%%PDF-1.4\n1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj\n3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 10 10]>>endobj\ntrailer<</Root 1 0 R>>\n%%%%EOF\n' > passport-2.pdf
   
   curl --request POST 'https://api.fx-port.com/api/v1/flights/upload_acd_documents' \
     --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
     --form booking_id=Y7HWMD \
     --form traveler_ids=1 \
     --form [email protected]

   Use your own PNR. The booking is now acd_submitted: true. The answer says notification.reason: "sandbox_environment" (an issued booking) or "hold_booking" (a hold): the sandbox never sends the e-mail. The second file is for a booking with two passengers: the program examples send both.

How it works

1. 1

   Check what is needed

   Call get_acd_documents with the booking. The response lists every traveler of the booking with a traveler_id, a status (missing or uploaded) and the ticket number when there is one. Each traveler needs one passport, so required_documents is the number of travelers.

2. 2

   Upload passports

   Send upload_acd_documents as multipart/form-data. You can send one passport, several passports or all of them at once. Each file is linked to its traveler through traveler_ids.

3. 3

   Submission completes automatically

   When every traveler has a passport, the booking switches to acd_submitted: true and FX-Port's ACD team is notified (see Notifications for when the e-mail is sent). If you send the passports over several requests, you do not need to do anything else.

4. 4

   Replace a passport if needed

   To correct a wrong or unreadable scan, upload the new file for that traveler with replace=true. The new file becomes the current passport, the old one is kept in the history, and the ACD team is told about the change.

POST /api/v1/flights/get_acd_documents

Permission: Read. The body is JSON.

Request body

Legacy names: bookingId and orderId still work and are answered with a deprecated_field warning. If booking_id is sent together with order_id or pnr and the values differ, booking_id wins and an ignored_field warning names the dropped one.

curl https://api.fx-port.com/api/v1/flights/get_acd_documents \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "Y7IA34"
}'

Response

A booking with three travelers, one passport uploaded. Real response of 2026-11-01, traveler data replaced by a fake name, bucket address replaced:

{
  "environment": "sandbox",
  "success": true,
  "requestId": "8201f6f6",
  "booking_id": "Y7IA34",
  "acd": {
    "booking_id": "Y7IA34",
    "acd_required": true,
    "acd_waived": false,
    "acd_submitted": false,
    "acd_paid": false,
    "complete": false,
    "can_upload": true,
    "blocked_reason": null,
    "required_documents": 3,
    "uploaded_documents": 1,
    "missing_documents": 2,
    "missing_traveler_ids": ["1", "3"],
    "travelers": [
      {
        "traveler_id": "1",
        "traveler_name": "JANE DOE",
        "traveler_type": "ADULT",
        "ticket_number": null,
        "status": "missing",
        "document": null
      },
      {
        "traveler_id": "2",
        "traveler_name": "JOHN DOE",
        "traveler_type": "ADULT",
        "ticket_number": null,
        "status": "uploaded",
        "document": {
          "filename": "john-passport.pdf",
          "content_type": "application/pdf",
          "size_bytes": 482113,
          "download_url": "https://s3.example.com/fx-port/acd_passports/Y7IA34/2/20261101142618_ec9632ab.pdf",
          "uploaded_at": "2026-11-01T14:26:18.120000+00:00",
          "replaced_count": 0
        }
      },
      {
        "traveler_id": "3",
        "traveler_name": "JAMES DOE",
        "traveler_type": "ADULT",
        "ticket_number": null,
        "status": "missing",
        "document": null
      }
    ],
    "unassigned_documents": [],
    "revision": 1,
    "limits": {
      "accepted_formats": ["avif", "bmp", "gif", "heif", "jp2", "jpeg", "jxl", "pdf", "png", "tiff", "webp"],
      "accepted_extensions": ["avif", "bmp", "dib", "gif", "heic", "heif", "j2k", "jfif", "jp2", "jpeg", "jpg", "jpx", "jxl", "pdf", "pjp", "pjpeg", "png", "tif", "tiff", "webp"],
      "max_file_size_bytes": 10485760,
      "max_request_size_bytes": 26214400,
      "max_documents_per_request": 3
    }
  }
}

The top-level booking_id is the PNR, whatever identifier you sent (twin: pnr). requestId has the twin request_id. Every other key is already snake_case.

acd fields

travelers[] fields

limits fields

A booking that does not need ACD

get_acd_documents does not fail for a booking without ACD: it answers 200, lists the travelers with status: "missing" and says why you cannot upload. Only upload_acd_documents answers 409 ACD_NOT_REQUIRED. Real response of 2026-11-01 for an Amadeus Algeria booking without ACD (limits shortened):

{
  "environment": "sandbox",
  "success": true,
  "requestId": "8b5b5c52",
  "booking_id": "Y7HKJM",
  "acd": {
    "booking_id": "Y7HKJM",
    "acd_required": false,
    "acd_waived": false,
    "acd_submitted": false,
    "acd_paid": false,
    "complete": false,
    "can_upload": false,
    "blocked_reason": "ACD_NOT_REQUIRED",
    "required_documents": 0,
    "uploaded_documents": 0,
    "missing_documents": 0,
    "missing_traveler_ids": [],
    "travelers": [
      {
        "traveler_id": "1",
        "traveler_name": "JOHN SMITH",
        "traveler_type": "ADULT",
        "ticket_number": "124-2446977395",
        "status": "missing",
        "document": null
      }
    ],
    "unassigned_documents": [],
    "revision": 0,
    "limits": { "max_file_size_bytes": 10485760, "max_request_size_bytes": 26214400, "max_documents_per_request": 1, "...": "..." }
  }
}

blocked_reason values

The order of the checks is the order of the table: a booking without ACD is ACD_NOT_REQUIRED even if it is also cancelled.

Errors of get_acd_documents

MISSING_BOOKING_ID, INVALID_BOOKING_ID, INVALID_JSON, INVALID_BODY (400), BOOKING_NOT_FOUND (404), INTERNAL_ERROR (500): see Error codes. The authentication errors are described in Errors.

POST /api/v1/flights/upload_acd_documents

Permission: Read+Write. A Read key is refused with 403 read_write_permission_required before anything is read. The body is multipart/form-data: a JSON body is refused (415 UNSUPPORTED_MEDIA_TYPE).

Request (multipart/form-data)

Rules of the multipart request

• Matched by order. The first traveler_ids value goes with the first documents file, the second with the second, and so on. The two lists must have the same length (DOCUMENT_COUNT_MISMATCH) and a traveler can appear once per request (DUPLICATE_TRAVELER_ID).
• Fewer files than travelers is fine. Send what you have; the booking stays acd_submitted: false until the last missing traveler is uploaded. More files than travelers on the booking is TOO_MANY_DOCUMENTS.
• replace is request-wide. With replace=true, travelers who already have a passport get it replaced (status: "replaced") and travelers who have none are added (status: "uploaded"), so you can do both in one request.
• Do not set the Content-Type header yourself in an HTTP library: it must carry the multipart boundary that the library creates.
• The content decides. The file name and the Content-Type of a part are not used to accept a file (Accepted files).
• Limits of the request: at most 40 files, 64 form fields and 64 KiB for one text field, and 10 MiB per file and 25 MiB for all files together (Size limits).
• Nothing is stored unless everything is valid. If any file is rejected, no file of the request is stored and the booking does not change.

Legacy names

These spellings still work and are answered with a deprecated_field warning. Send the name in the second column.

order_id and pnr are other names of booking_id that are not deprecated. When the form holds several spellings of the booking with different values, the first one of this list wins and an ignored_field warning names each dropped one: booking_id, bookingId, order_id, orderId, pnr. The same booking twice, or an empty value, gives no ignored_field warning.

Upload examples

The same request in every language of the site. The program sends two passports for one booking (traveler 1 and traveler 2, matched by order) and reads the answer the way the sections below describe it. Put your PNR in BOOKING_ID, the traveler_id values of get_acd_documents in PASSPORTS and the paths of your files. For the sandbox, create passport-1.png and passport-2.pdf as shown in Test it in the sandbox.

# traveler_ids and documents are matched by order: the first id goes with the first file.
# Do not set Content-Type yourself: curl sends multipart/form-data with its own boundary.
curl --silent --show-error --write-out '\nHTTP %{http_code}\n' \
  --request POST "https://api.fx-port.com/api/v1/flights/upload_acd_documents" \
  --header "Authorization: Bearer fxp_test_YOUR_KEY" \
  --form booking_id=Y7IA34 \
  --form traveler_ids=1 \
  --form traveler_ids=2 \
  --form [email protected] \
  --form [email protected] \
  --form replace=false

Replace a passport that was already uploaded: the same request with replace=true (--form replace=true, or REPLACE = "true" in the programs).

curl --request POST 'https://api.fx-port.com/api/v1/flights/upload_acd_documents' \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
  --form booking_id=Y7IA34 \
  --form traveler_ids=2 \
  --form [email protected] \
  --form replace=true

• Without replace=true, a file for a traveler who already has a passport is rejected with 409 DOCUMENT_ALREADY_UPLOADED and nothing is changed. This prevents accidental overwrites.
• With replace=true, the new file becomes the current passport, the old one is kept in the history, status is replaced and document.replaced_count goes up by one.
• If the booking was already fully submitted, the ACD team is told about the change (notification.type: "updated"). The booking stays acd_submitted: true.

Response: success (200)

Every file was stored. Real response of 2026-11-01 for the last two travelers of a three-traveler booking (fake names, bucket address replaced):

{
  "environment": "sandbox",
  "success": true,
  "status": "success",
  "requestId": "58bfcf4a",
  "booking_id": "Y7IA34",
  "message": "2 documents saved.",
  "summary": { "received": 2, "uploaded": 2, "replaced": 0, "failed": 0 },
  "results": [
    {
      "index": 0,
      "traveler_id": "1",
      "traveler_name": "JANE DOE",
      "filename": "passport-1.png",
      "status": "uploaded",
      "content_type": "image/png",
      "size_bytes": 69,
      "download_url": "https://s3.example.com/fx-port/acd_passports/Y7IA34/1/20261101142620_28e115c8.png"
    },
    {
      "index": 1,
      "traveler_id": "3",
      "traveler_name": "JAMES DOE",
      "filename": "passport-3.pdf",
      "status": "uploaded",
      "content_type": "application/pdf",
      "size_bytes": 191,
      "download_url": "https://s3.example.com/fx-port/acd_passports/Y7IA34/3/20261101142620_4194315e.pdf"
    }
  ],
  "acd": {
    "booking_id": "Y7IA34",
    "acd_required": true,
    "acd_submitted": true,
    "complete": true,
    "can_upload": true,
    "required_documents": 3,
    "uploaded_documents": 3,
    "missing_documents": 0,
    "missing_traveler_ids": [],
    "revision": 2,
    "...": "same shape as get_acd_documents"
  },
  "notification": { "sent": false, "type": "submitted", "skipped": true, "reason": "sandbox_environment" },
  "warnings": []
}

results[] fields

Response: partial success (207)

The files are validated together first. If they are valid, they are stored one by one. If the storage fails for some of them, the files that were stored are kept and the answer is HTTP 207 with success: true and status: "partial_success". This cannot be provoked in the sandbox; the shape comes from the service code and its tests:

{
  "success": true,
  "status": "partial_success",
  "message": "1 of 2 documents saved; 1 failed — retry the failed travelers.",
  "summary": { "received": 2, "uploaded": 1, "replaced": 0, "failed": 1 },
  "results": [
    { "index": 0, "traveler_id": "1", "traveler_name": "JANE DOE", "filename": "passport-1.png", "status": "uploaded", "content_type": "image/png", "size_bytes": 69, "download_url": "https://s3.example.com/fx-port/acd_passports/Y7IA34/1/20261101142620_28e115c8.png" },
    {
      "index": 1,
      "traveler_id": "3",
      "traveler_name": "JAMES DOE",
      "filename": "passport-3.pdf",
      "status": "failed",
      "error": { "code": "STORAGE_UPLOAD_FAILED", "message": "The document could not be stored. Retry this traveler.", "reason": "storage_error" }
    }
  ],
  "acd": { "missing_traveler_ids": ["3"], "...": "..." },
  "notification": { "sent": false, "skipped": true, "reason": "awaiting_remaining_documents" },
  "warnings": []
}

Retry only the travelers listed in acd.missing_traveler_ids: their files were not saved, so replace=true is not needed. The reason of a failed storage is always the fixed text storage_error: the message of the storage system is never returned. A 207 has a second cause: another request stored a passport for the same traveler a moment before yours. That item is failed with DOCUMENT_ALREADY_UPLOADED.

Response: failure (4xx / 5xx)

The whole request is checked first, so a failure lists every problem at once, no file is stored and the booking does not change. Real response of 2026-11-01 (two files, two different problems; accepted_extensions shortened):

{
  "environment": "sandbox",
  "success": false,
  "status": "failed",
  "error": "validation_failed",
  "code": "VALIDATION_FAILED",
  "message": "2 of 2 documents were rejected. Nothing was uploaded.",
  "results": [
    {
      "index": 0,
      "traveler_id": "1",
      "traveler_name": "JANE DOE",
      "filename": "bad.pdf",
      "status": "failed",
      "error": {
        "code": "UNSUPPORTED_FILE_TYPE",
        "message": "'bad.pdf' is not a supported passport document. Upload a PDF or a JPEG, PNG, WebP, HEIC/HEIF, AVIF, TIFF, BMP, GIF, JPEG 2000 or JPEG XL image.",
        "accepted_extensions": ["avif", "bmp", "dib", "..."]
      }
    },
    {
      "index": 1,
      "traveler_id": "2",
      "traveler_name": "JOHN DOE",
      "filename": "empty.pdf",
      "status": "failed",
      "error": { "code": "EMPTY_FILE", "message": "Uploaded document 'empty.pdf' is empty." }
    }
  ],
  "acd": { "booking_id": "Y7IA34", "acd_required": true, "complete": false, "...": "the state, unchanged" },
  "requestId": "34d61957"
}

• One problem for every rejected file, or only one file: code and the HTTP status are that problem. With several files the message starts with the count: 2 documents were rejected: A passport is already uploaded for traveler '1'. Send replace=true to replace it.
• Different problems: VALIDATION_FAILED, with the status of the problems when they share one, 400 otherwise. Read results[].error.
• Valid files of a failed request have status: "skipped". Send them again with the corrected request.
• Request-shape errors (missing field, count mismatch ...) carry only counters: received_traveler_ids, received_documents, expected_travelers, duplicate_traveler_ids.
• A failure that depends on the booking (its state, too many files, the total size) also carries the current acd state, so you do not need another call.

Real response of a booking that does not need ACD:

{
  "environment": "sandbox",
  "success": false,
  "status": "failed",
  "error": "acd_not_required",
  "code": "ACD_NOT_REQUIRED",
  "message": "This booking does not require ACD documents.",
  "acd": { "booking_id": "Y7HKJM", "acd_required": false, "can_upload": false, "blocked_reason": "ACD_NOT_REQUIRED", "...": "..." },
  "requestId": "5b73272a"
}

The order of the checks

A request is checked in this order; the first problem found is the answer. This is what makes the same mistake answer the same code every time:

1. Authentication, permission, rate limit and size of the whole body (413 request_too_large above 26 MiB).
2. The body is multipart (UNSUPPORTED_MEDIA_TYPE, INVALID_MULTIPART).
3. booking_id (MISSING_BOOKING_ID, INVALID_BOOKING_ID), then replace (INVALID_REPLACE_FLAG).
4. MISSING_TRAVELER_IDS or MISSING_DOCUMENTS, then DOCUMENT_COUNT_MISMATCH, then DUPLICATE_TRAVELER_ID.
5. The booking is looked up among the bookings of your agency and of your environment (BOOKING_NOT_FOUND). A booking of another agency is not found: it answers exactly like an id that does not exist.
6. The state of the booking (409: ACD_NOT_REQUIRED, ACD_WAIVED, BOOKING_NOT_ELIGIBLE, TRAVELERS_NOT_AVAILABLE). This comes before the files are looked at: a booking without ACD answers 409 even for an unreadable file.
7. TOO_MANY_DOCUMENTS.
8. Each file, in order, and the first problem of a file wins: UNKNOWN_TRAVELER_ID, DOCUMENT_ALREADY_UPLOADED (unless replace), EMPTY_FILE, FILE_TOO_LARGE, UNSUPPORTED_FILE_TYPE.
9. REQUEST_TOO_LARGE (the files together are over 25 MiB). It wins over the problems of step 8.
10. If any file failed: nothing is stored; VALIDATION_FAILED or the common code.
11. Storage (STORAGE_UNAVAILABLE, STORAGE_UPLOAD_FAILED) and the write (CONCURRENT_UPDATE).

Accepted files

FX-Port checks the actual content of a file. The file name and the Content-Type you send are not used to decide whether a file is accepted. A text file renamed to .pdf is rejected with UNSUPPORTED_FILE_TYPE; a PDF named passport.jpg is accepted. The stored extension follows the detected format.

SVG, Office documents, archives (ZIP) and every other type are not accepted. An empty file is EMPTY_FILE.

Size limits

The messages of the API say "MB"; the numbers are MiB (1,048,576 bytes). If a large group would go over 25 MiB, split the passports over several requests: each request adds to what was already uploaded. get_acd_documents returns the limits in acd.limits.

Notifications

When a passport set becomes complete, FX-Port's ACD team is told by e-mail. The e-mail goes to FX-Port, not to you or to the traveler; notification only reports what happened, and nothing has to be done with it. The API sends it from an upload only: paying a hold does not send it.

The sandbox never sends the e-mail. Only the type key is missing from the first two forms.

Hold bookings

A hold has a traveler list and no tickets, and it accepts uploads:

• get_acd_documents lists the travelers with ticket_number: null, and can_upload is true.
• When the set is complete, acd_submitted becomes true before payment, and the answer says notification.reason: "hold_booking": no e-mail is sent for an unpaid hold.
• When you pay the hold with pay_order the files stay and the booking stays acd_submitted: true. The e-mail to the ACD team is sent from an upload on an issued booking: the first complete set (submitted) or the replacement of a passport of a complete set (updated).
• A hold that is not paid in time is cancelled by FX-Port, and a hold that you cancel with cancel_order is cancelled at once: the booking is then cancelled and refuses uploads (BOOKING_NOT_ELIGIBLE).

Error codes

Every error of these endpoints is a flat body: success: false, status: "failed", error (the code in lower case), code (the code in upper case), message and the keys listed with the code, plus requestId. The unified error body of Errors is added next to them: errors[0].code is the lower-case code (acd_not_required) and errors[0].type follows the status (validation_error, not_found, conflict, internal_error). The codes below are written in upper case, as in code.

The last column says whether you can provoke the error in the sandbox: Yes (reproduced on 2026-11-01), Not run (should be reproducible, not run), No (cannot be provoked from outside; the shape is taken from the service code and its tests).

Which bookings you can reach

A key finds only the bookings of its own agency and of its own environment. These three cases answer the same 404 BOOKING_NOT_FOUND, with the same message (No flight booking found for '<booking_id>'.) and the same shape, so an answer never tells you whether a booking exists:

• an id that does not exist;
• a booking of another agency;
• a booking of the other environment (a sandbox key does not read a live booking, and the other way round).

A booking that has no agency attached is hidden from API keys as well. The lookup runs among your own bookings, so when two agencies hold the same PNR, each one finds its own. 403 BOOKING_FORBIDDEN exists only for FX-Port's own tools (the dashboard and internal callers): a key never receives it.

Retries and idempotency

• Read before you write. Call get_acd_documents first and use its traveler_id values and missing_traveler_ids. Do not build traveler ids yourself.
• Without replace, a retry is safe. A traveler who was already saved is rejected with DOCUMENT_ALREADY_UPLOADED and nothing changes, so a passport is never overwritten without you asking for it. Retry only the travelers in missing_traveler_ids.
• With replace=true, a retry is not harmless. It replaces the file again: replaced_count goes up, revision goes up, and in the live environment the ACD team gets another updated e-mail. Use replace=true only for a correction.
• After a timeout or a dropped connection, do not resend blindly: call get_acd_documents and send what is missing.
• Send one request at a time for a booking. Two requests that write the same booking at the same moment can end with CONCURRENT_UPDATE; read the state and send again.
• Read the status. 200 means every file was saved, 207 means only some were (read results), 4xx means nothing changed. A 5xx after the files were stored cannot be told from the outside: call get_acd_documents.
• 502 STORAGE_UPLOAD_FAILED and 503 STORAGE_UNAVAILABLE changed nothing: retry the same request after a short wait.

Security: file links are public

download_url (here and in get_ticket, bucket_link in other answers) is an address anyone can open without a key. It is the only protection a file has: whoever holds the address can download the passport.

• Treat every download_url as a secret: do not log it, do not put it in a URL you show to other users, do not send it by e-mail or to analytics, and do not store it longer than you need.
• Download the file on your server when you need it, and give your users your own, access-controlled copy.
• A passport copy is personal data. Collect it with the traveler's consent and keep it only as long as the booking needs it.
• The sandbox stores files the same way: never upload a real passport in the sandbox.

Same conventions as the rest of the flights API

Integration tips

• Sandbox keys work with sandbox bookings only. Files are stored and the state is tracked like in production, but no e-mail is sent.
• Dashboard uploads count too. Passports uploaded from the FX-Port dashboard appear in get_acd_documents, and you can replace them through the API.
• Voided travelers drop out. The number of required passports follows the travelers that are still on the booking: a passenger removed by a void is no longer in travelers and no longer counts toward required_documents.
• Send a User-Agent of your own. Cloudflare blocks the default agents of Python's urllib and Perl's libwww with an error 1010 page before the request reaches the API.

Related

• Flight pricing: the acd block of the price.
• Book a flight, Pay a held order and Cancel a held order.
• Get a flight booking: require_acd and acd_submitted of a booking.
• Sandbox and Errors.