diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md index b7e32d2..5b005a3 100644 --- a/documentation/GUIDE__AE_API_V3_for_Frontend.md +++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md @@ -293,6 +293,73 @@ Frontend guidance: --- +## Axonius Zoom CSV Upload (Temporary — Apr 2026) + +Purpose: Staff-only quick upload to upsert Event Person + Event Badge records from a Zoom Events registrant CSV. + +- **Endpoint:** `POST /event/{event_id}/badge/import/zoom_csv` +- **Auth:** include `x-aether-api-key` (if required) and account context via `x-account-id: `. Admin bypass (`x-no-account-id: bypass`) or `?jwt=` are accepted per site policy. +- **Request:** `multipart/form-data` with single file field `file` (Zoom CSV). Query params: + - `begin_at` (int, default `0`) + - `end_at` (int, default `20000`) + - `return_detail` (bool, default `false`) + - Delimiter is auto-detected; Zoom CSV layout: row 1 = metadata, row 2 = blank, row 3 = headers (the backend skips the first two rows). + +Behavior / notes: +- The handler forces `Registrant email` to be used as the `external_id`. `Unique identifier` is used as `external_registration_id` only when it is meaningful (placeholders like `N/A`, `NA`, `UNKNOWN` are ignored). +- Per-ticket custom fields are parsed (Organization, Job title, Phone, Address lines, City, State/Province, Postal/Zip, Country, etc.). +- Marketing-consent values are mapped to `agree_to_tc` and `allow_tracking`. +- TEMP AXONIUS MAPPING: the import temporarily defaults `event_badge_template_id` to `21` and `event_badge_template_id_random` to `RKYp2HcQm9o`. Ticket-name → `badge_type_code` mapping is applied for some labels (e.g., contains "sponsor" → `sponsor`; contains "attend"/"attendee" → `attendee`). This mapping is temporary (April 2026) — surface this to staff. +- Rows missing `Registrant email` are skipped. +- The server upserts via existing backend methods and creates/updates `event_person`, `event_person_profile`, and `event_badge` records as needed. + +Frontend guidance: +- UI must be staff-only and should validate an `event_id` is selected. +- For large files, use `begin_at`/`end_at` to process in chunks. +- Prefer `return_detail=false` for large imports to reduce payload size. + +Common errors: +- `403` — missing/invalid account context or API key. +- `404` — event not found. +- `500` — file save or processing error. + +Example curl (replace placeholders): +```bash +curl -v -X POST "https://api.example.com/event//badge/import/zoom_csv?begin_at=0&end_at=20000&return_detail=false" \ + -H "x-aether-api-key: " \ + -H "x-account-id: " \ + -F "file=@/path/to/zoom_export.csv" +``` + +Sample success (summary mode, `return_detail=false`): +```json +{ + "data": [ + { + "event_id": "xK9mP3qRtL2", + "event_id_random": "xK9mP3qRtL2", + "external_id": "alice@example.com", + "given_name": "Alice", + "family_name": "Smith", + "email": "alice@example.com" + } + ], + "meta": { + "status_code": 200, + "status_name": "OK", + "success": true, + "data_type": "list", + "data_list_count": 1 + } +} +``` + +Sample success (detailed, `return_detail=true`) — `data` contains full `event_person` objects with nested `event_badge` (may include temporary `event_badge_template_id`: `21` and `event_badge_template_id_random`: `RKYp2HcQm9o`). + +Paste this section into the guide as a temporary Axonius-specific note (April 2026). Consider linking staff to a sample Zoom CSV for QA. + +--- + ## 7. User Actions (`/v3/action/user/`) Stateful user account operations that are not standard CRUD. All require `x-aether-api-key`.