> For the complete documentation index, see [llms.txt](https://docs.reachplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reachplatform.com/technical/api/api-onboarding-guide.md).

# API Onboarding Guide

Get API credentials, tenant scoping, and a staging endpoint for integration.

Use this checklist to get Reach API access and start integrating in staging.

### Overview

Use this guide to onboard to the Reach Mobile Platform API suite.

This is for MVNO API integration using REST APIs (JSON over HTTPS).

You provide brand details and an MNO preference.

Reach provisions your tenant and API gateway access.

Reach emails your credentials and environment base URLs (staging and production).

### What you submit

* **Brand name**
* **Primary email address** (credential delivery)
* **Primary contact** (first name, last name, phone)
* **MNO preference**

### What you receive

* API credentials for authentication (API Key, plus any required gateway keys)
* Tenant ID (tenant scoping)
* Staging base URL (sandbox for development and testing)
* Production base URL (shared after non-production sign-off)
* API docs, [API specs](https://api.reachplatform.com/), and implementation guide

### Use cases covered

See [API Implementation Guide](broken://spaces/qCk68BPk2GwsjGvR7LAT/pages/g6Fe8ihM7VCdNmG9eTHv).

These use cases map to end-to-end MVNO customer journeys.

* **Learn**: coverage checks, device compatibility (IMEI), product catalog.
* **Buy**: quotes, purchases, payment redirects, purchase status, renewals.
* **Card management**: add, list, update, delete saved cards.
* **Activation**: pSIM/eSIM activation, port-in, activation status, port-in updates.
* **Support**: ZIP validation, outbound SMS.
* **Webhooks**: usage notifications and async callbacks (purchase and activation).
* **Subscriber management**: suspend/restore, reconnect/disconnect, SIM/MDN swaps, usage, profile updates.
* **Billing**: bills, payments, invoice PDFs, invoice email.
* **Top-up**: quote and purchase data packs.
* **Plan change**: estimate, execute, status tracking.
* **ILD credits**: balance, usage, quote/purchase, history.
* **Shipment**: track and cancel SIM shipments.
* **International roaming**: supported countries, packs, quote/purchase, auto-renew, usage.
* **SIM swap (OTP)**: OTP-secured SIM swap and status.
* **Data cutoff**: enable or disable data access.
* **Port validation**: validate port-in eligibility.

{% hint style="warning" %}
Treat the **Secret Key** and **API Key** like passwords. Never commit them to source control.
{% endhint %}

### How onboarding works

{% stepper %}
{% step %}

#### Submit onboarding details

Share your brand details and select your preferred MNO (network).
{% endstep %}

{% step %}

#### Reach provisions access

Reach provisions your tenant and enables API access for the selected MNO.
{% endstep %}

{% step %}

#### Receive credentials and URLs

Reach emails your credentials, Tenant ID, and environment base URLs.
{% endstep %}

{% step %}

#### Start integrating in staging

Use the staging base URL for development and testing.
{% endstep %}
{% endstepper %}

### Onboarding form fields

#### Brand information

Provide these details to set up your Reach API account.

* **Brand name** (required). Example: `"SkyWave Mobile"`.
* **Primary email address** (required). Used for credentials and notifications. Example: `"hello@skywavemobile.com"`.
* **Contact first name** (required). Example: `"Jordan"`.
* **Contact last name** (required). Example: `"Rivera"`.
* **Contact phone number** (required). Example: `"+1-415-555-0192"`.

#### Technical configuration

This is the only technical input needed at onboarding time.

* **MNO preference** (required). Example: `"T-Mobile"`, `"AT&T"`, `"Verizon"`.

### Credentials, URLs, and docs

Reach sends an email to your primary email address with the items below.

| Credential                                                   | What It Is & How to Use It                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Access Key ID — Identifies your client                       | A unique public identifier for your API gateway client. The Access Key ID is not secret on its own — it is used in combination with the Secret Key to authenticate API requests. Include this in the header of every API call to identify your brand account. Example use: Authorization header alongside your Secret Key.                                |
| Secret Key — Authenticates your requests                     | A confidential key paired with your Access Key ID. Together, they form your authentication credentials. The Secret Key must never be shared, exposed in client-side code, or committed to version control. If compromised, contact Reach immediately to rotate your keys. Treat this like a password.                                                     |
| API Key — Authorizes API access                              | A token that grants access to Reach API resources. Pass it on each request per the API spec. Example header: `x-api-key: <api-key>`.                                                                                                                                                                                                                      |
| Tenant ID — Your unique account identifier                   | A unique identifier that represents your brand as a tenant within the Reach platform. The Tenant ID is used to scope all data and operations to your specific account, ensuring complete separation from other brands on the platform. Example use: Included in API request paths or body parameters where tenant context is required.                    |
| API Documentation — Complete integration reference           | A link to the full Reach API reference documentation. This covers all available endpoints, request and response schemas, authentication patterns, error codes, and integration examples. Review this before beginning your integration to understand the full capabilities of the platform.                                                               |
| API Specifications Document — Technical contract for the API | The formal specification document defining all API contracts — including endpoint definitions, request and response schemas, data types, field constraints, and authentication requirements. Use this as the authoritative reference when designing and validating your integration to ensure full compatibility with the Reach platform.                 |
| API Implementation Document — Step-by-step integration guide | A practical guide covering the end-to-end process of integrating with the Reach API. This document includes setup instructions, code examples, common integration patterns, error handling guidance, and troubleshooting tips. Follow this guide alongside the API Specifications Document to get your integration up and running as quickly as possible. |
| Staging Endpoint — Your sandbox environment URL              | The base URL for the Reach staging (sandbox) environment. Use this endpoint for all development and testing before going live. The staging environment mirrors production behavior but operates on test data, so you can validate your integration safely without affecting real customers. Example: "<https://staging-api.reach.com/v1>"                 |

#### Credentials

Use these for API authentication and request signing where required.

* **API Key**. Required on every request. Header: `x-api-key: <api-key>`.
* **Authorization credentials**. Used for the `Authorization` header (format per API spec).
* **Access Key ID**. Identifies your API gateway client.
* **Secret Key**. Used with the Access Key ID. Treat as a password.
* **Tenant ID**. Used for tenant scoping where required.

#### Environment URLs

* **Staging base URL**. Sandbox environment for development and QA testing.
* **Production base URL**. Live environment. Shared after non-production sign-off.

#### Docs

* **API documentation**. Reference for endpoints, schemas, and errors.
* **API specifications**. Contract for requests and responses.
* **API implementation guide**. Journey-level flows and integration patterns.

### Security practices

* Never share the Secret Key or API Key publicly.
* Never store credentials in client-side code.
* Store credentials in env vars or a secrets manager.
* Request key rotation if you suspect exposure.

### Getting started after you receive credentials

{% stepper %}
{% step %}

#### Review the API docs and specs

Confirm auth requirements, headers, and request/response schemas.
{% endstep %}

{% step %}

#### Configure authentication in your dev environment

Load Access Key ID, Secret Key, and API Key from a secure store.
{% endstep %}

{% step %}

#### Make a first call in staging

Use the staging endpoint and validate connectivity and auth.
{% endstep %}

{% step %}

#### Apply Tenant ID scoping (where required)

Use Tenant ID in paths or request bodies when the API requires it.
{% endstep %}

{% step %}

#### Plan production rollout

After staging sign-off, contact Reach for production enablement.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Questions or clarification? Reach out to your respective account manager or email at <accounts@reachmobile.com> for help and support.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.reachplatform.com/technical/api/api-onboarding-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.