Internal · provider notes

Atlas × 1GLOBAL Integration Notes

Based on 1GLOBAL's public Connect API docs (docs.connect.1global.com). v2 endpoints are truphone-hosted (1GLOBAL = former Truphone); a newer v3 lives at api.1global.com. Confirm your version at onboarding.

Requirements mapping: P0 list vs. what Connect exposes

Atlas requirement	Status	1GLOBAL mechanism
Profile detail view (1.2)	✓	`GET /sims/{iccid}` → profile state, matching ID, LPA string, QR link, sim_type, last_modified
QR consumed / dead profile	✓	Profile state incl. `Unavailable` = don't reuse; new activation order (new ICCID) is the path
Usage view (1.4)	✓	`GET /subscriptions?iccid=` → status, activation_date, expiry_date, initial/current/spent balance (bytes)
Resend QR (A1)	✓	QR link is retrievable any time from the order/SIM resources. Resend is just re-sending the link
Reissue (A2)	~	= new ACTIVATION order → new ICCID. Balance carry-over is NOT automatic: you comp it manually (your cost). See §3.
Top-up (A3)	✓✓	`TOPUP` order type against existing ICCID. Unlimited renewals to the same installed profile.
Deactivate (A4)	✓	Expire-subscription endpoint; delete SIM for full teardown
Refund / cancel (A5)	✓*	Delete SIM endpoint frees resources & enables refund, only if profile never installed on a device
Extend validity (A6)	✓	Custom activation & expiration dates on orders; expire endpoint for the reverse
Webhooks	~	Confirmed events: order completed (contains QR), order failed, profile deleted. Config is manual at onboarding; HMAC signing was "in progress", so ask. Everything else = poll.
Connectivity view (1.3: last-attach, serving operator)	?	Not visible in public docs. Top onboarding question.
New-phone flow	✓ bonus	EID-rebind endpoint moves a profile to a different device (eSIM + Apple only)
Push install	✓ bonus	Provide target EID at order → device gets a push notification triggering install. No QR. Captures EID for free.
Error taxonomy	✓	Single documented error model (INVALID_REQUEST_PARAMS, UNAUTHORISED, ACCESS_DENIED, …). Map to internal codes early
API roles	✓	RESELLER (connectivity ops only) vs ACCOUNT_MANAGER (also customer data). Start as RESELLER unless you store customer accounts with them.

Questions for the 1GLOBAL onboarding call

The gaps the public docs don't answer. Ask before or during integration.

Connectivity / diagnostics: any endpoint or portal view for last network attach, serving operator (MCC/MNC), or line registration status? If not, what's the escalation path + SLA when a customer is installed/enabled but has zero data?
Usage freshness: what's the actual lag on current_balance? (Minutes? Hours?) → this number goes in Atlas's "data as of" display.
Full webhook catalog: complete event list beyond order completed/failed and profile deleted. Is there an installed event? HMAC signing live yet? Retry policy?
Profile lifecycle granularity: full list of SIM states returned by the SIM endpoint (docs show Released, Unavailable. What else? Downloaded? Installed? Enabled?).
Deleted-eSIM policy: when a customer deletes an installed profile from their device, is there any recovery / re-download, or is a new activation order the only path? Any goodwill / credit mechanism for the unused balance?
EID rebind scope: Apple-only today. Android on roadmap? Any cost or limits per rebind?
Sandbox: test environment with test ICCIDs/EIDs? If not, cheapest bundle for a reserved test pool.
Rate limits and recommended polling interval for order status.
APN: is an APN set automatically by the profile, or are there cases where customers must configure it manually? (Feeds the help center article.)
Refund window: confirm the exact conditions on delete-SIM (never installed + anything else? time limit?).

Policy decisions this unlocks (decide once, write everywhere)

Refund policy: uninstalled eSIM = automatic full refund (delete SIM endpoint makes this ~free to offer, and it's a marketing point). Installed = case-by-case.
Deleted-eSIM policy: new profile = new activation order = real cost to Atlas. Decide: full courtesy replacement (eat cost, cap at 1 per order), replacement minus a fee, or replacement with remaining balance manually comped. Write the choice into Playbook E and the help center.
Validity clock: 1GLOBAL supports activate-on-first-usage AND fixed activation dates. Recommended: first usage. It is the most customer-friendly and kills the "my plan started before my trip" ticket class. Then update the bracketed placeholder in the activation article.
Repeat customers: unlimited top-ups go to the same installed profile, so the retention play is "keep your Atlas eSIM installed forever; just top up next trip." Put this in the help center and post-trip emails. It also reduces deleted-eSIM tickets.
Push install as default for app / EID-capable flows: better UX, no QR-loss tickets, EID captured automatically.

Runbook adjustments (applied)

Playbook A/E: "reissue" = new ACTIVATION order with new ICCID; old QR/profile is dead; balance carry-over is manual.
Playbook E: for iPhone-to-iPhone moves, try EID rebind before issuing a new profile.
Actions table: refund self-serve path = delete SIM (uninstalled only); validity extension = supported via custom dates.
Escalation list: "no connectivity diagnostics available in-house (pending Q1 answer)": installed + enabled + configured but zero data goes upstream to 1GLOBAL with ICCID + timestamps.

Build notes (dev hat)

OAuth2 client-credentials; tokens expire → build auto-refresh.
Order fulfillment is async → poll order status (or webhook where covered). Never assume instant.
Send an X-Correlation-ID on every call and log it. It's your join key with 1GLOBAL support on escalations.
All timestamps UTC.
Cache the product catalog locally (Refresh Catalog) and use Quick Activation in production. The docs explicitly steer away from the on-the-fly Activation flow.
Map 1GLOBAL error types to Atlas-internal codes on day one; never surface raw vendor JSON in support notes or customer emails.