API Implementation Guide
Step-by-step Reach platform REST API integration guide. Covers authentication, purchase, activation/eSIM, port-in, billing, webhooks/callbacks, and error handling.
This document is proprietary and confidential. It is provided solely to enable integration with Reach APIs. Do not reproduce or distribute without written consent.
Reach Mobile Platform REST API integration guide
Integrate your MVNO customer lifecycle with the Reach Mobile Platform APIs. Use REST APIs over HTTPS with JSON request and response bodies. Implement purchase, activation, billing, and subscriber management flows.
Search keywords included on this page:
Reach Mobile Platform API, Reach API integration, MVNO REST API integration
API authentication (JWT token +
x-api-key),Authorization: Basic <Base64(...)>Purchase API: quote, purchase, payment redirect, status polling
Activation API: ICCID validation, pSIM activation, eSIM activation, IMEI check
Port-in API: MDN port validation, port-in activation, port-in update
Billing API: bill retrieval, invoice link, bill payment
Webhooks/callbacks:
/notification,/notification/callback
Related docs:
1. Getting Started
This guide walks you through every integration scenario step-by-step, using a flow-first approach. Before calling any API, complete the three setup steps in this section.
1.1 How to Get Your API Keys
Your API credentials are provisioned during the onboarding process. You will receive two separate sets — one for Staging and one for Production.
What you receive
Two credentials: (1) JWT Token (2) API Key (x-api-key)
Staging set
Used for development and testing only. Request from your Reach onboarding contact.
Production set
Issued only after staging testing is signed off. Never use production keys during development.
Revocation
Credentials can be revoked immediately. If you suspect exposure, contact Reach support at once.
Never hard-code API keys or JWT tokens. Store them in a secrets manager. Examples: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault.
1.2 API authentication (Authorization header + x-api-key)
Every API request must carry two authentication headers. Here is the exact process to build them:
Step
Action
Example
Step 1
Take your JWT token as-is
Example JWT (truncated): eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Step 2
Prepend the literal prefix clientapi|
Result: clientapi|eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Step 3
Base64-encode the entire string from Step 2
Result: Y2xpZW50YXBpfGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS4uLg==
Step 4
Set the Authorization header
Authorization: Basic Y2xpZW50YXBpfGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS4uLg==
Step 5
Set the x-api-key header
x-api-key: <your_api_key_from_onboarding>
Every request must include both headers:
Encode the literal string clientapi|<JWT_Token>. Do not add spaces. Use standard Base64 (not URL-safe).
1.3 Generate permanent access keys (one-time setup)
After receiving your JWT token and API key, make the following call once to obtain a permanent accountAccessKeyId and accountAccessSecreteKey. These are your long-lived keys for operational use.
Headers:
Request body:
Example response:
This is a one-time setup call. Store the returned keys immediately. Send bypass-token: true only for this endpoint.
1.4 Important Keywords & Concepts
The following terms are used throughout this guide. Familiarise yourself with them before reading the flow scenarios.
Term
Meaning
customerId
The platform-assigned unique identifier for a subscriber. Created on first purchase. Required for all subsequent calls for that subscriber.
clientAccountId
Your brand's own reference ID for the account. You supply this during purchase. Use it to look up customers from your side.
transactionId
A unique ID returned by asynchronous operations (purchase, activation). Use it to poll the corresponding status endpoint.
planId / serviceCode
The unique identifier of a plan or service. Obtained by calling the product fetch APIs. Must be passed exactly as received.
iccId
Integrated Circuit Card Identifier — the 19–20 digit number printed on a physical SIM card. Required for SIM-based activation.
IMEI
International Mobile Equipment Identity — the 15-digit number that uniquely identifies a mobile device. Required for device compatibility checks.
eSIM
Embedded SIM — a software-based SIM provisioned remotely. No physical card needed. Activated using IMEI, not iccId.
ccUUID / cardId
The UUID of a saved payment card on the customer's account. Obtained by calling the List Cards API.
redirectUrl
A brand-hosted HTTPS URL. The platform redirects the customer to this URL after payment or card addition. Must start with https://.
groupId
An identifier that groups multiple lines under one account (e.g. a family plan). Used in billing, ILD, and IR APIs.
Async / Async API
An API that accepts a request and returns a transactionId immediately, completing the actual work in the background. You must poll or receive a callback to know the outcome.
Callback
An HTTP POST that the platform sends to your server when an async operation completes. You must implement and expose these endpoints.
Port-In
The process of transferring a mobile number from another carrier to the Reach network. Requires the subscriber's account details from their current carrier.
MDN
Mobile Directory Number — the subscriber's phone number.
MNO / MVNE
Mobile Network Operator / Mobile Virtual Network Enabler. For this platform, the underlying network is AT&T (mvne=ATT).
2. Production prerequisites (security + webhooks)
The following must be completed before your integration can go live in the production environment. None of these apply to staging.
2.1 IP Whitelisting
All production API calls must originate from your pre-registered server IP addresses. The Reach platform will reject requests from unknown IPs with a 403 Forbidden response.
Item
Detail
What to provide
All egress IP addresses of your servers that will call the Reach APIs in production. Include NAT gateway IPs if you are behind one.
How to provide
Submit your IP list to your Reach onboarding contact via the provisioning form. Allow 2 business days for activation.
Changes
Any IP changes must be communicated at least 24 hours in advance to avoid service disruption.
Staging
IP whitelisting is not enforced on staging. You may call from any IP during development.
2.2 HTTPS Requirement
All calls to the Reach API must use HTTPS. HTTP connections are rejected at the gateway. Additionally, any redirectUrl or callback URL you provide must also be HTTPS.
2.3 Webhooks and callback endpoints
Before go-live, your server must expose the following HTTPS endpoints. The platform will call these to deliver real-time events and async operation results:
POST /apisvc/v0/notification
Receives real-time usage events, port-out notifications, and IMEI change alerts
POST /apisvc/v0/notification/callback
Receives async operation results: purchase completed, activation completed, etc.
Both endpoints must return HTTP 200 within 10 seconds. On timeout or non-2xx, Reach retries up to 3 times. Use transactionId for idempotency.
2.4 Rate Limiting
The platform enforces rate limits per API key. If you exceed the limit you will receive a 429 Too Many Requests response. Implement exponential back-off:
Retry 1: wait 1 second
Retry 2: wait 2 seconds
Retry 3: wait 4 seconds — continue doubling up to 60 seconds maximum
After 5 consecutive failures, alert your operations team and stop retrying
2.5 Pre-Go-Live Sign-Off Checklist
Complete these go-live requirements before production cutover.
Security and access
Production egress IPs submitted and allowlisted.
Production JWT token and
x-api-keyreceived (separate from staging).Secrets stored in a secrets manager (no keys in source code).
All
redirectUrlvalues usehttps://.
Webhooks (platform → brand)
POST /apisvc/v0/notificationdeployed and returns HTTP 200.POST /apisvc/v0/notification/callbackdeployed and returns HTTP 200.Callback processing is idempotent using
transactionId.
Reliability
Rate limit handling implemented (
429exponential back-off).Async handling verified (polling and/or callbacks) for purchase + activation.
End-to-end functional validation
All integration scenarios tested end-to-end on staging.
customerIdis persisted after purchase and reused for future calls.
3. API integration scenarios (purchase, activation, billing)
The following scenarios describe the end-to-end API flows for each customer journey. Each scenario lists the exact API calls in order, what to pass, what to expect, and what to do with the response. Read each scenario fully before implementing.
Scenario A — New customer purchase API (quote → purchase → payment)
Discover plans → quote → purchase → payment → confirm
This is the primary purchase flow for a brand-new subscriber. Follow these steps in order.
Check Network Coverage
Before showing plans, verify the customer's address is within the network coverage area.
Request body:
Key response fields:
brandCoverage(boolean) — iffalse, do not proceedcoverageStrength5G(string)coverageStrength4G(string)
If brandCoverage=false, stop the flow. Show a “not available in your area” message.
Fetch Available Plans
Retrieve the product catalog to display plans, pricing, and available services to the customer.
Key plan fields to display:
serviceCode— use asplanIdin subsequent callsbaseLinePrice— monthly base pricemaxLines— max lines per accountfccLabel— FCC disclosure (must display)upGradableTo[]— eligible upgrade targetsdownGradableTo[]— eligible downgrade targets
Cache the product catalog. Refresh it at least every 24 hours.
Get a Purchase Quote
Once the customer selects a plan, call the Quote API to get the exact amount they will pay today and the estimated monthly charge. Always show the customer this breakdown before confirming.
Request body (example):
Key response fields to show the customer:
oneTimeCharge.totalOneTimeCost— total due todayoneTimeCharge.simKitCostoneTimeCharge.activationCostoneTimeCharge.shipmentoneTimeCharge.taxestimatedMonthlyCost.total— estimated monthly going forward
redirectUrl must start with https://. After payment, the customer returns to {redirectUrl}?transId={transactionId}. Persist transId and correlate it to the order.
Submit the Purchase
After the customer confirms the quote, submit the purchase. This is an async operation — it returns a transactionId immediately and processes in the background.
Request body:
Same structure as the Quote body (previous step).
Immediate response:
Store the transactionId — you will need it in subsequent steps.
Poll Purchase Status — Wait for Payment Link
Poll the status endpoint every 5 seconds until the status includes a payment link. This is where the customer is sent to complete card payment.
Poll until:
statusisPAYMENT_PENDINGlink.urlis present
Key response fields:
status— current transaction statepaymentStatus— payment processor statelink.url— payment page URL (redirect customer here)link.expireDate— link expiry timestamp
The payment link expires (see link.expireDate). Redirect the customer immediately. If it expires, resubmit the order.
Redirect Customer to Payment Page
Redirect the customer's browser to the link.url returned in the previous step. The customer enters card details on the payment processor's hosted page. After completion, the processor redirects the customer back to your redirectUrl.
Your redirectUrl will receive the customer with a transId query parameter: https://yourbrand.com/payment/confirm?transId=TXN-98765
Extract the transId and use it in the next step to check final status.
Poll Purchase Status — Wait for Completion
Continue polling the status endpoint after the customer returns from payment. The status will transition through PAYMENT_PROCESSING → COMPLETED (or FAILED).
Poll every 5 seconds until status is COMPLETED or FAILED.
On COMPLETED:
Store customerId — required for ALL future calls for this subscriber
Store clientAccountId
shipmentStatus shows SIM dispatch state
On FAILED:
Show error to customer using paymentStatusDesc
Allow retry — restart from the quote step
Persist customerId when status becomes COMPLETED. Most downstream APIs require it.
Navigate to Post-Purchase UI
Once COMPLETED, navigate the customer to the relevant screen based on shipment type.
If simType = PSIM (physical SIM): → Show SIM shipping confirmation screen → Prompt customer to activate once SIM arrives (Scenario C)
If simType = ESIM: → Proceed directly to eSIM activation (Scenario D) → Customer does not need to wait for a physical delivery
Prefer callbacks over polling. Handle callback type PRODUCT_PURCHASE.
Scenario B — Returning customer renewal or add-on
Existing customer → quote → subsequent purchase → confirm
Use this flow when an existing customer (customerId is already known) wants to renew their plan, add lines, or purchase a top-up.
Scenario C — Physical SIM activation API (ICCID → activation → status)
Physical SIM → activate → poll → live
After a customer receives their SIM kit, they must activate it. This flow covers physical SIM activation.
Poll Activation Status
Poll the activation status endpoint to track progress. Activation typically completes within 2–10 minutes.
Status codes to handle:
0—INACTIVE(not yet submitted)1—ACTIVATION_IN_PROGRESS(keep polling)2—ACTIVE(success, stop polling)8—ACTIVATION_FAILED(show error, contact support)
Navigate Based on Activation Status
Handle each terminal status appropriately in your UI.
If status=2 (ACTIVE):
Show activation success screen
Display mobileNo (the subscriber's assigned phone number)
Show planName and activationDate
If status=8 (ACTIVATION_FAILED):
Show activationMsg to agent / customer
Offer retry or escalate to support
Prefer callbacks over polling. Handle callback type ACTIVATION.
Scenario D — eSIM activation API (IMEI → activation → status)
No physical SIM → activate by IMEI
eSIM activation is identical to physical SIM activation except that the IMEI is used instead of iccId, and the esim flag is set to true.
Scenario E — Number port-in API (port validation → activation → update)
Keep existing number → port → activate
Port-in allows a customer to transfer their existing phone number from another carrier. Collect the customer's port-in details before submitting.
Collect Port-In Details from Customer
You must collect the following from the customer before submitting. These must exactly match what's on file with their current carrier:
numberToPort— 10-digit number to transferoldCarrier— carrier name (example: T-Mobile)oldCarrierAccountNumber— carrier account numberpassword— transfer PIN / account PINoldZip— billing ZIP with losing carrier
Poll Port-In Status
Port-in is processed between carriers and may take minutes to hours. Poll regularly and update the customer's status screen.
Port-in specific status codes:
9—PORTING_IN_PROGRESS(keep polling)2—ACTIVE(port complete, number is live)10—PORTING_FAILED(seeactivationMsg)11—PORT_CANCELLED(customer or carrier cancelled)
Handle Port-In Failure — Correct and Resubmit
If port-in fails (status 10), the customer's details were likely incorrect. Call the update endpoint with corrected information.
Request body (example):
type values:
UPDATE_PIN— wrong PIN/passwordUPDATE_ACCOUNT— wrong account numberUPDATE_ZIP— wrong ZIP codeRESUBMIT_PORT— resubmit with same detailsCANCEL_PORT— cancel the port-inCANCEL_AND_NEW— cancel and start with a new number
Scenario F — Plan change (upgrade or downgrade)
Check eligibility → estimate cost → execute change
Use this flow when a subscriber wants to move to a different plan. Always check eligibility first, then show the cost estimate before confirming.
Fetch Plans and Check Eligibility
Retrieve the plan catalog and check the subscriber's current plan's upGradableTo and downGradableTo lists.
Find the subscriber's current plan in the list.
Use:
upGradableTo[]— plans they can upgrade todownGradableTo[]— plans they can downgrade to
Only offer the customer plan options that appear in these lists.
Scenario G — Add a payment card
Generate secure link → customer enters card → card stored
Card details are captured through the payment processor's hosted page — your integration never handles raw card numbers. Use this flow to add a card to a customer's account.
Scenario H — Billing and payment API (bills → invoice → payment)
Get bills → show invoice → process payment
Scenario I — Subscriber lifecycle management
Suspend · restore · disconnect · reconnect
Use these flows to manage subscriber account states. Always verify the current status via customerinfo before taking an action.
Temporarily Suspend Service
Restore Suspended Service
Disconnect a Subscriber
Reconnect a Disconnected Subscriber
Scenario J — International roaming pack purchase
Browse countries → select pack → quote → purchase → monitor
Scenario K — Data cut-off management
Restrict → restore data access
Use data cut-off to restrict a subscriber's mobile data access (e.g. for non-payment) and remove the restriction once resolved.
4. Notification & Callback Reference
The platform sends events to your server in two ways. You must implement both endpoints before going live.
4.1 Incoming Notification Events
The platform sends these events to POST {your_host}/apisvc/v0/notification:
Event Type
Trigger
Action
USAGE_NOTIFICATION
Data threshold reached (e.g. 80%, 100% of plan)
Show usage alert in customer app
RDN_IMEI_CHANGE
Device IMEI changed on the line
Log the change, alert if unexpected
PORT_OUT
Customer initiated port-out to another carrier
Begin off-boarding flow
PORT_OUT_CONFIRMED
Port-out completed by gaining carrier
Close the account, stop billing
4.2 Async Operation Callbacks
The platform sends these to POST {your_host}/apisvc/v0/notification/callback when async operations complete:
Callback Type
Trigger
Key Fields
ACTIVATION
Activation or port-in completed
customerId, status, mobileNo
PRODUCT_PURCHASE
New purchase completed
customerId, transactionId, status
PURCHASE_SUBSEQUENT
Renewal or subsequent purchase completed
customerId, transactionId, status
Use transactionId as your idempotency key. Callbacks can be retried. Processing twice must be safe.
5. HTTP Status Codes & Error Handling
Code
Status
Meaning
What to do
200
OK
Request succeeded
Use the response body
202
Accepted
Async request accepted
Store transactionId, poll status
400
Bad Request
Invalid payload or missing fields
Log the response body for field-level errors
401
Unauthorized
Bad or expired credentials
Rebuild auth header; rotate token if needed
403
Forbidden
Valid creds but no permission / IP not whitelisted
Check IP whitelist; verify API key
404
Not Found
Resource does not exist
Check IDs — customerId, billId, transactionId
409
Conflict
Duplicate request or conflicting state
Check if operation already succeeded
429
Too Many Requests
Rate limit exceeded
Implement exponential back-off
500
Internal Server Error
Unexpected platform error
Retry after 5 seconds; alert support if persistent
503
Service Unavailable
Platform temporarily down
Retry with back-off; alert operations
504
Gateway Timeout
Upstream timeout
Retry — the request may have partially succeeded; check status
6. API Quick Reference Index
Complete list of all available endpoints for reference. See the flow scenarios in Section 3 for usage context.
Method
Endpoint
Description
PUT
/opssvc/v0/clientapi/account/generataccesskey
Generate permanent access key (one-time setup)
POST
/apisvc/v0/network/coverage
Check mobile network coverage for an address
GET
/apisvc/v0/device/imei/{imei}
Validate device IMEI compatibility
GET
/apisvc/v0/product/fetch
Fetch all products (plans, services, offers)
GET
/apisvc/v0/product/fetch/plan
Fetch available plans only
GET
/apisvc/v0/product/fetch/offer
Fetch available coupons/offers
GET
/apisvc/v0/product/fetch/service
Fetch available services (shipping etc.)
POST
/apisvc/v0/product/quote
Get purchase price quote
POST
/apisvc/v0/product
Submit new customer purchase [ASYNC]
GET
/apisvc/v0/product/status/{transactionId}
Poll purchase transaction status
POST
/apisvc/v0/product/subsequent
Submit renewal/add-on for existing customer [ASYNC]
PUT
/apisvc/v0/account/generate/addcard/link/{customerId}
Generate secure link to add a payment card
GET
/apisvc/v0/account/card?customerId={customerId}
List all cards for a customer
GET
/apisvc/v0/account/card/specific?cardId={id}
Get a specific card by ID
PUT
/apisvc/v0/account/card?id={cardId}&default=true
Set card as default
PUT
/apisvc/v0/account/card
Update card details (expiry, priority)
DELETE
/apisvc/v0/account/card?cardId={id}&customerId={cid}
Delete a card from account
POST
/apisvc/v0/iccid/validate
Validate SIM ICCID before activation
POST
/apisvc/v0/activation
Activate SIM or initiate port-in [ASYNC]
GET
/apisvc/v0/activation/status?customerId={cid}
Poll activation / port-in status
PUT
/apisvc/v0/update/portin
Correct and resubmit failed port-in
PUT
/apisvc/v0/port/validate/mdn?mdn={mdn}
Validate MDN for port-in eligibility
POST
/apisvc/v0/zipCode/validate
Validate a ZIP code is serviceable
POST
/apisvc/v0/sendsms/{customerId}
Send SMS to an active subscriber
GET
/apisvc/v0/customerinfo?customerId={cid}
Get full subscriber info / status
PUT
/apisvc/v0/account/update/fields/{customerId}
Update customer name, email, address
PUT
/apisvc/v0/reconnect
Reconnect a disconnected subscriber
PUT
/apisvc/v0/disconnect
Disconnect a subscriber
PUT
/apisvc/v0/suspend
Suspend a subscriber's service
PUT
/apisvc/v0/restore
Restore a suspended subscriber
PUT
/apisvc/v0/mdn/swap
Swap subscriber's phone number (MDN)
GET
/apisvc/v0/mdn/swap/status/{customerId}
Get MDN swap status
POST
/apisvc/v0/iccid/swap
Swap SIM card on a subscriber's line
PUT
/apisvc/v0/customers/swap
Swap primary/secondary line designation
PUT
/apisvc/v0/leaving/customer
Record customer leaving (port-out or disconnect)
POST
/apisvc/v0/customer/reset/{customerId}
Reset customer account [ASYNC]
GET
/apisvc/v0/customer/reset/status/{customerId}
Get customer reset status
PUT
/apisvc/v0/customer/reset/voicemail/password/{customerId}
Reset voicemail PIN
GET
/apisvc/v0/usage/summary?usageData={type}
Query data/ILD/IR usage summary
PUT
/apisvc/v0/customer/manage/feature/{customerId}
Enable / remove data cut-off
GET
/apisvc/v0/billing/customer/{customerId}
Get all bills for a customer
GET
/apisvc/v0/billing/customize/{billId}
Get specific bill details
POST
/apisvc/v0/payment/customer
Pay a bill
GET
/apisvc/v0/invoice/history/{customerId}
Get invoice history
GET
/apisvc/v0/invoice/link/generate
Generate invoice PDF download link
POST
/apisvc/v0/invoice/sendemail
Email invoice to customer
POST
/apisvc/v0/topup/quote
Get top-up data pack quote
POST
/apisvc/v0/topup/purchase
Purchase top-up data pack
POST
/apisvc/v0/estimate/plan/change
Estimate cost of plan upgrade/downgrade
POST
/apisvc/v0/purchase/plan/change
Execute plan upgrade/downgrade
GET
/apisvc/v0/status/plan/change/{txnId}
Get plan change status
GET
/apisvc/v0/ild/status?groupId={id}
Get ILD credit balance
GET
/apisvc/v0/ild/usage?groupId={id}
Get ILD usage by destination
GET
/apisvc/v0/ild/purchase/history/{customerId}
Get ILD credit purchase history
POST
/apisvc/v0/ild/quote
Get ILD credit purchase quote
POST
/apisvc/v0/ild/purchase
Purchase ILD credits
GET
/apisvc/v0/shipment/order/customer/{customerId}
Get shipment order details
PUT
/apisvc/v0/shipment/order/cancel/{customerId}
Cancel pending shipment order
GET
/apisvc/v0/intl/roaming/countries/mvne?mvne=ATT
Get supported roaming countries
POST
/apisvc/v0/get/additional/offerings
Get available IR packs for countries
POST
/apisvc/v0/intl/roaming/pack/quote/customer/{customerId}
Get IR pack quote
POST
/apisvc/v0/intl/roaming/pack/purchase/customer/{customerId}
Purchase IR pack
GET
/apisvc/v0/intl/roaming/pack/group
Get IR pack group details
POST
/apisvc/v0/intl/roaming/pack/{packId}/autorenew
Set IR pack auto-renew
GET
/apisvc/v0/intl/roaming/pack/usage
Get IR pack remaining usage
POST
/apisvc/v0/generate/otp/sim/swap
Generate OTP for SIM swap verification
POST
/apisvc/v0/perform/otp/sim/swap
Execute OTP-verified SIM swap
GET
/apisvc/v0/get/status/sim/swap?id={id}
Get SIM swap status
Last updated