Quickstart

Get your first eSIM provisioned in just a few API calls.

By the end of this guide, you'll have successfully:

Authenticated with the Connect API
Retrieved available Product Offerings
Created an Account and Subscriber
Provisioned an eSIM
Received installation details through webhooks

All requests are server-to-server and should be executed from your backend or terminal environment.

Before you begin — API credentials

Your API credentials (client ID and client secret) are shared with you at the end of the onboarding process. If you have not received them yet, please contact your Customer Success Manager.

Request and response examples below follow the latest official OpenAPI specification.

1. Get an Access Token

Connect uses OAuth 2.0 Client Credentials authentication.

Request an access token using your client credentials:

curl -X POST \
  https://api.1global.com/auth/realms/1global-connect/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

Expected result:

200 OK
Response contains an access_token

Use the token as a Bearer token in subsequent API requests.

For more details, see Authentication.

2. Retrieve Available Product Offerings

Product Offerings represent the plans or bundles that can be purchased by your users.

Retrieve the available offerings:

curl -X GET \
  https://api.1global.com/connect/product-offerings \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/hal+json,application/problem+json' \
  -H 'Correlation-Id: YOUR_UNIQUE_CORRELATION_ID'

Example response:

{
  "_embedded": {
    "product_offerings": [
      {
        "id": "prdoff_01J83E2WMQBDBEK70SX0N5RJ1P",
        "name": "Local Portugal - 1 Day",
        "created_at": "2024-09-18T20:44:51.223Z",
        "updated_at": "2024-09-18T21:50:51.233Z",
        "status": "active",
        "type": "addon",
        "category": "allowance",
        "availability": {
          "start_at": "2024-09-18T19:59:56.000Z",
          "end_at": "2025-09-18T19:59:56.000Z"
        },
        "validity": {
          "type": "duration",
          "unit": "month",
          "unit_count": 1,
          "is_recurrent": false
        },
        "_embedded": {
          "allowances": [
            {
              "type": "data",
              "unit": "gigabytes",
              "unit_count": 100,
              "is_unlimited": false,
              "_embedded": {
                "coverage_area": {
                  "id": "cov_01J83E2VNKR4GD78MF1R43YWTK",
                  "name": "Portugal",
                  "type": "local",
                  "created_at": "2024-09-18T20:44:50.227Z",
                  "updated_at": "2024-09-18T20:44:50.227Z",
                  "countries": ["PT"],
                  "_links": {
                    "self": {
                      "href": "https://api.1global.com/connect/coverage-areas/cov_01J83E2VNKR4GD78MF1R43YWTK"
                    }
                  }
                }
              }
            }
          ],
          "prices": [
            {
              "type": "recurring",
              "unit_amount": 50,
              "currency": "EUR",
              "recurrence": {
                "unit": "month",
                "unit_count": 3
              }
            }
          ]
        },
        "_links": {
          "self": {
            "href": "https://api.1global.com/connect/product-offerings/prdoff_01J83E2WMQBDBEK70SX0N5RJ1P"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.1global.com/connect/product-offerings"
    },
    "prev": {
      "href": "https://api.1global.com/connect/product-offerings?cursor=eyJzbyI6eyJkIjoiREVTQyIsInAiOiJleHRlcm5hbElkIn0sInNpZCI6bnVsbCwicyI6bnVsbCwidCI6Ik5FWFQiLCJpZCI6InN1YnNfMDFKQTVESzdEOFBEQ0hTSDI3RjMzUjVXNDYifQ=="
    },
    "next": {
      "href": "https://api.1global.com/connect/product-offerings?cursor=eyJzbyI6eyJkIjoiREVTQyIsInAiOiJleHRlcm5hbElkIn0sInNpZCI6bnVsbCwicyI6bnVsbCwidCI6Ik5FWFQiLCJpZCI6InN1YnNfMDFKQTVESzdEOFBEQ0hTSDI3RjMzUjVXNDYifQ=="
    }
  }
}

Expected result:

200 OK
One or more Product Offerings returned in _embedded.product_offerings
Product Offerings with type: plan are used to create an activation order in the next step. Save the id of the plan you want to activate.

Tip
Most partners periodically synchronize Product Offerings and maintain a local catalog for faster customer experiences.

Open the Product Offerings API Explorer
Learn more about Product Offerings

3. Create an Account and Subscriber

An Account represents the paying customer or organization. A Subscriber represents the end user consuming the connectivity service.

Before provisioning connectivity:

Create an Account
Create a Subscriber associated with that Account

Example Account creation:

curl -X POST \
  https://api.1global.com/connect/accounts \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/hal+json,application/problem+json' \
  -H 'Correlation-Id: YOUR_UNIQUE_CORRELATION_ID' \
  -H 'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY' \
  -d '{
    "name": "Test account name",
    "type": "personal",
    "owner": {
      "first_name": "First name",
      "last_name": "Last Name",
      "address": {
        "line1": "Avenue 1",
        "line2": "Central Park",
        "city": "Berlin",
        "country": "DE",
        "postal_code": "123-456"
      }
    },
    "metadata": {
      "key1": "value1",
      "new_metadata": "example",
      "affiliateId": "12345"
    }
  }'

Example response:

{
  "id": "acc_01J806F9TNFYTQM3Z4THPTJEVY",
  "name": "Test account name",
  "type": "personal",
  "number": "C2024AAAA0000",
  "owner": {
    "first_name": "First name",
    "last_name": "Last Name",
    "address": {
      "line1": "Avenue 1",
      "line2": "Central Park",
      "city": "Berlin",
      "country": "DE",
      "postal_code": "123-456"
    }
  },
  "metadata": {
    "key1": "value1",
    "new_metadata": "example",
    "affiliateId": "12345"
  },
  "created_at": "2024-09-17T14:34:06.037Z",
  "updated_at": "2024-09-17T14:34:06.037Z",
  "_links": {
    "self": {
      "href": "https://api.1global.com/connect/accounts/acc_01J806F9TNFYTQM3Z4THPTJEVY"
    }
  }
}

Expected result:

201 Created
Response contains an Account id (for example acc_01J806F9TNFYTQM3Z4THPTJEVY)

Example Subscriber creation:

curl -X POST \
  https://api.1global.com/connect/subscribers \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/hal+json,application/problem+json' \
  -H 'Correlation-Id: YOUR_UNIQUE_CORRELATION_ID' \
  -H 'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY' \
  -d '{
    "account_id": "acc_01J806F9TNFYTQM3Z4THPTJEVY",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@dummy.com",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Los Angeles",
      "country": "US",
      "state": "CA",
      "postal_code": "90001"
    },
    "birth_date": "2074-04-12",
    "locale": "en-GB"
  }'

Example response:

{
  "id": "subr_01HXF4F4VYTCPVMBPBK3T52TN7",
  "created_at": "2024-09-17T14:34:06.037Z",
  "updated_at": "2024-09-17T14:34:06.037Z",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@dummy.com",
  "locale": "en-GB",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Los Angeles",
    "country": "US",
    "state": "CA",
    "postal_code": "90001"
  },
  "birth_date": "2074-04-12",
  "_embedded": {
    "account": {
      "id": "acc_01J806F9TNFYTQM3Z4THPTJEVY",
      "_links": {
        "self": {
          "href": "https://api.1global.com/connect/accounts/acc_01J806F9TNFYTQM3Z4THPTJEVY"
        }
      }
    }
  },
  "_links": {
    "self": {
      "href": "https://api.1global.com/connect/subscribers/subr_01HXF4F4VYTCPVMBPBK3T52TN7"
    },
    "subscriptions": {
      "href": "https://api.1global.com/connect/subscriptions?subscriber-id=subr_01HXF4F4VYTCPVMBPBK3T52TN7"
    }
  }
}

Expected result:

201 Created
Response contains a Subscriber id (for example subr_01HXF4F4VYTCPVMBPBK3T52TN7)
Open the Accounts API Explorer
Open the Subscribers API Explorer

4. Create an Order

Create an Order to provision the eSIM connectivity.

Most provisioning operations in Connect are asynchronous and finalized through webhook events.

Example request:

curl -X POST \
  https://api.1global.com/connect/orders \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/hal+json,application/problem+json' \
  -H 'Correlation-Id: YOUR_UNIQUE_CORRELATION_ID' \
  -H 'Idempotency-Key: YOUR_UNIQUE_IDEMPOTENCY_KEY' \
  -d '{
    "type": "activate_subscription",
    "subscriber_id": "subr_01HXF4F4VYTCPVMBPBK3T52TN7",
    "purchase_location": "US",
    "sim_profile": {
      "sim_type": "esim"
    },
    "products": {
      "plan": {
        "product_offering_id": "prdoff_01HRD00B0K1EPRZ9WEVGEMUIJ6E"
      },
      "addons": [
        {
          "activation_mode": "first_usage",
          "product_offering_id": "prdoff_01HRD00B0K1EPRZ91XEFRYPPTVX"
        }
      ]
    }
  }'

Example response:

{
  "id": "ord_01HV3KWPNRCT870WV3XG41UTG4",
  "status": "accepted",
  "type": "activate_subscription",
  "created_at": "2024-08-02T09:13:28.384Z",
  "_links": {
    "self": {
      "href": "https://api.1global.com/connect/orders/ord_01HV3KWPNRCT870WV3XG41UTG4"
    },
    "subscriber": {
      "href": "https://api.1global.com/connect/subscribers/subr_01HXF4F4VYTCPVMBPBK3T52TN7"
    }
  }
}

Expected result:

201 Created
Response contains an Order id (for example ord_01HV3KWPNRCT870WV3XG41UTG4) with status: accepted
Connectivity provisioning starts asynchronously

Tip
Always send an Idempotency-Key header when creating orders. This allows requests to be safely retried without creating duplicate orders.

Once the order is accepted:

The request is validated
Connectivity provisioning starts
A SIM Profile is assigned
Installation details become available asynchronously
Open the Orders API Explorer

5. Receive eSIM Installation Events

Connect communicates provisioning progress asynchronously through webhooks.

When the eSIM is ready for installation, Connect sends:

subscription.sim_profile.ready_for_installation

The webhook payload contains the installation details required by the end user, including QR code and LPA information.

Once the eSIM is successfully installed on the device, Connect sends:

subscription.sim_profile.installed

The order lifecycle is also communicated through webhook events:

order.completed
order.failed

Typical installation methods include:

QR Code (or manual LPA installation)
Direct integration in your iOS or Android application — see Install an eSIM

Tip
Use tools like webhook.site or ngrok during development to test webhook delivery locally.

Open the Webhooks API Explorer
Learn more about Webhook Events

What Just Happened

You completed the core provisioning flow used by most Connect integrations:

Product Offering → Account → Subscriber → Order → Subscription → SIM Profile → Connectivity

You now have the foundation required to build eSIM purchase and provisioning experiences using Connect.

Next Steps

Before going to production:

Set up webhook delivery and signature validation: Webhooks Guide
Handle safe retries and duplicate prevention: Idempotency
Understand API quotas and limits: Rate Limiting
Review the production launch checklist: Go to Production

Want to better understand the resources used in this guide?

Read the Connect API Mental Model.

On this page