Godwit SIM
← Godwit SIM

Godwit SIM API and developer docs

Find plans, create an order and read the eSIM with a JSON API or MCP. No sign-up, no API keys, no accounts.

Quickstart

  1. List plans. No key. market is AU (AUD), UK (GBP) or US (USD, the default). Each plan has planId, dataLabel, days, price, surcharge and total. Add billingState=CA for a California billing address.
curl "https://api.godwitsim.com/plans?country=JP&market=UK"
  1. Create an order. Send a planId from step 1. The 201 response has orderId, checkoutUrl, orderUrl, total, expiresAt and nextStep, plus orderSecret (osk_...) and, on your first order, buyerKey (agsk_...). Both are shown once. Open checkoutUrl in a browser to pay. Send Authorization: Bearer agsk_... on later orders to group them.
curl -X POST "https://api.godwitsim.com/checkout" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"planId":"<planId>","market":"UK"}'
  1. Get the order. Poll every few seconds until status is delivered. Without a key the response has access statusOnly. With the order secret it has access full and adds the eSIM (install links, SM-DP+ address, activation code), usage, topupOptions and travelerMessage.
curl "https://api.godwitsim.com/orders/<orderId>" \
  -H "Authorization: Bearer osk_..."
  1. Optional: claim for the traveler. Attaches an Australian, UK or US phone to the order. Godwit texts the install details to it, and the traveler can then text Godwit for help.
curl -X POST "https://api.godwitsim.com/orders/<orderId>/claim" \
  -H "Content-Type: application/json" \
  -d '{"orderSecret":"osk_...","phone":"<E.164>","channel":"sms"}'

Authentication without sign-up

Keys: every agent order has an ID and an order secret (osk_...). The first order without a buyer key also returns a buyer key (agsk_...). Both are returned once and cannot be recovered. Without a key, GET /orders/{id} returns status only. With the order secret, or the buyer key that bought it, it returns the eSIM, usage, top-up options and travelerMessage. A wrong key gets 401, never a status-only answer. The buyer key also lists orders (GET /orders) and manages a low-data callback (/webhook). There are no accounts or passwords. Never put a key in the traveler message.

The concierge endpoints (/orders/by-phone, /esims/..., /gifts/by-phone, and /plans or /checkout with a phone) are for Godwit SIM's own AI assistant and need its private key. Endpoints for Godwit staff, inbound payment and telecom webhooks, and scheduled jobs are not part of the public API and are left out of the spec.

Endpoints

Paths are relative to https://api.godwitsim.com.

Method Path Auth Purpose
GET /plans Godwit key or none Plans for a destination, priced for the customer's market
POST /checkout Godwit key or buyerKey or none Create a Stripe Checkout for a plan and return a short payment link
GET /orders/by-phone Godwit key Orders placed from a phone number, newest first
GET /orders buyerKey The buyer key's orders, newest first, up to 200
GET /orders/{id} orderSecret or buyerKey or none An agent order. Status only without a key; the eSIM with its order secret or buyer key
POST /orders/{id}/claim none Attach the traveller's phone to an agent order
POST /orders/{id}/topup orderSecret or buyerKey Pay for more data on a delivered agent eSIM
GET /webhook buyerKey The buyer key's low-data callback
PUT /webhook buyerKey Register one low-data callback for the buyer key
DELETE /webhook buyerKey Remove the buyer key's callback
GET /esims/{iccid}/usage Godwit key Data left, validity and top-up options for an eSIM
POST /esims/{iccid}/verification-code Godwit key Text a one-time code to the number on file
POST /esims/{iccid}/resend Godwit key Resend the installation message
POST /esims/{iccid}/topup Godwit key Create a Stripe Checkout for a top-up package
POST /orders/{id}/refund Godwit key or orderSecret or buyerKey Refund or credit an order under the refund policy
GET /gifts/by-phone Godwit key Whether a number has a gift waiting, and only what the customer may be told
GET /r/{code} none Short-link redirector for payment and install links
GET /mcp none Not offered; the server sends no server-initiated messages
POST /mcp none MCP server (streamable HTTP, stateless)
GET /.well-known/mcp/server-card.json none Describes the MCP server, its tools and auth model, for discovery
GET /health none Liveness check

MCP server

Streamable HTTP at https://api.godwitsim.com/mcp, stateless, no headers. Client config:

{"mcpServers":{"godwit-sim":{"url":"https://api.godwitsim.com/mcp"}}}
Tool Key Purpose
searchDestinations none Find a destination by name or code.
listPlans none Plans for a destination, priced for a market.
getPlan none One plan and its price.
listRecommendations none The cheapest plan per country that lasts the stay with enough data.
createOrder optional buyerKey Create an order. Returns checkoutUrl, orderSecret once, and buyerKey once on the first order without one. Pass idempotencyKey to make retries safe.
getOrder optional orderSecret or buyerKey Status only without a key. With one: the eSIM and travelerMessage.
listOrders buyerKey Every order the buyer key placed.
getUsage orderSecret or buyerKey Data left on a delivered eSIM.
listTopupPackages orderSecret or buyerKey Top-ups the eSIM can take.
createTopup orderSecret or buyerKey Pay for more data on the same eSIM.
claimOrder orderSecret Attach the traveler's phone to an eSIM order and text them the install details. At most 3 phones per order.
requestRefund orderSecret or buyerKey Ask for a refund under the refund policy.

Errors

Errors have the shape {"error":"<code>","message":"<detail>"}. message is present when there is more to say than the code.

Status Codes Meaning
400 invalid_request, invalid_json The body or a parameter fails validation. The message names the field.
401 unauthorized, invalid_order_secret, invalid_buyer_key, buyer_key_required The key is missing, unknown, or does not open this order. Never retry an unknown buyer key as a new buyer.
403 verification_required, code_expired, too_many_attempts Concierge resends to a new number need the 6-digit code texted to the number on file.
404 plan_not_found, order_not_found, esim_not_found No such plan, order or eSIM.
409 idempotency_conflict, idempotency_in_progress The Idempotency-Key was used for a different request, or its first request is still running.
409 order_closed, order_not_claimable, claim_limit_reached The order cannot be claimed: it is closed, it is a top-up, or it has had 3 phones.
409 order_provisioning, refund_in_progress, credit_only, order_not_refundable, refund_budget_exceeded The order cannot be refunded now. order_provisioning: retry in a minute. credit_only: the policy gives credit, which an agent order cannot hold.
409 topup_unavailable The order is not a delivered eSIM, or the top-up is not offered for it now.
422 unsupported_market, plan_unavailable The number or market is not one Godwit sells to, or the plan has no price in that currency.
429 rate_limited, too_many_codes Too many requests. Wait for the Retry-After header's seconds.

Rate limits

  • Checkouts and top-ups: 10 a minute per buyer key and per address.
  • Order reads (GET /orders/{id}, GET /orders): 60 a minute per key and per address.
  • Plan reads without a key: 10 a minute per address.
  • Claims: 10 a minute per address and 5 an hour per order. Agent refunds: 5 an hour per order.
  • MCP: 120 requests and 60 tool calls a minute per address, on top of the limits above.
  • Over a limit: 429 rate_limited with a Retry-After header in seconds.

Idempotency-Key

  • Send Idempotency-Key on POST /checkout, or idempotencyKey in the body (and in MCP createOrder). Up to 200 characters. Without a buyer key it must be 22 or more random letters, digits, - or _, because an address can be shared.
  • The same key from the same buyer key, or the same address without one, within 24 hours returns the first response again with 200 and Idempotent-Replayed: true, including orderSecret and buyerKey. In MCP the result carries _meta.idempotentReplayed: true.
  • A different request with the same key gets 409 idempotency_conflict. A retry while the first request is still running gets 409 idempotency_in_progress.

Low-data callbacks

  • Register one HTTPS callback per buyer key with PUT /webhook and Authorization: Bearer agsk_.... The response returns a signing secret once. GET shows the callback and DELETE removes it.
  • Godwit posts once per threshold when an eSIM has used 75% or 90% of its data. The body has type, eventId, orderId, iccid, level and remainingPercent, never a key.
  • Verify Godwit-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>. Reject a t more than 5 minutes off, and drop an eventId you have already seen: the signature alone does not stop a replay.
  • One POST, a 5-second timeout and no redirects.

Buying by text

Without code, text or call +44 7886 075616 (United Kingdom) or +61 420 114 041 (Australia).

Files