Create a subscription

In the following guide, we will walk through how you can get up and running quickly, integrating the Core Gigs API into your own product.

By the time we're finished, you will have used our API to create a new Gigs subscription. Let's get started!

Prerequisites

In order to complete this guide, you'll need to have a valid API key, and contacted us to create an organization with your first project and plan. If you're missing any of these, please reach out to support@gigs.com for assistance.

Overview

We will be walking through the process of creating a new user and associated address. Then using this new user, along with an eSIM compatible plan associated to your project we will be able to setup a new subscription.

Creating a User

We can create a user by sending a POST request to the /users endpoint. In this walkthrough, we'll do this using cURL:

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/users" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "jerry@example.com",
    "fullName": "Jerry Seinfeld"
  }'

If the request is successful, you should receive a response like this:

{
  "object": "user",
  "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "birthday": null,
  "email": "jerry@example.com",
  "emailVerified": false,
  "fullName": "Jerry Seinfeld",
  "preferredLocale": "en-US",
  "createdAt": "2021-12-07T09:31:39Z"
}

Be sure to hold on to the user id, as we'll need it going forward.

Selecting a Plan

Now that we've created a user, we need to select a plan.

To find one, we can list the plans for our project by making an API request to the /plans endpoint. Because we are interested in creating a subscription for an eSIM, we can filter the plans by simType, returning only those with eSIM compatibility:

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/plans?simType=eSIM" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

You should receive a successful response back from the API listing the eSIM-compatible plans in your project:

{
  "object": "list",
  "items": [
    {
      "object": "plan",
      "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "name": "Gigs Global",
      "description": "A data plan you will love! Operates in most countries of the world.",
      // ...
      "allowances": {
        "dataBytes": 10000000000,
        "voiceSeconds": 30000,
        "smsMessages": 100,
      },
      "price": {...},
      "provider": "p9",
      "requirements": {"address": "present"},
      "simTypes": ["eSIM"],
      "status": "active",
      // ...
    }
  ],
  // ...
}

While we have shortened the above response body for brevity, you can choose whichever plan you'd like from the list. In this case, we'll save the id of the first plan we received ("pln_0SNlurA049MEWV3V0q7gjQbM4EVo"). You can view the full response from GET /plans by navigating to the following API documentation: list all plans.

Note that different providers might have distinct requirements. In the example above, the plan response indicates that only a user address is needed. In other cases, different information might be requested, such as device details or user name.

Creating a User Address

As explained above, a user address is not required in all cases. It is only required when the plan associated to the user's subscription needs it. From the above plan response, we can see that an address is required for eSIM plan "pln_0SNlurA049MEWV3V0q7gjQbM4EVo". An address can be created for the new user with a POST to the /users/{USER_ID}/addresses endpoint. Where USER_ID is the id returned by the previous user create request: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/users/${USER_ID}/addresses" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "line1": "129 West 81st Street",
    "line2": "Apartment 5",
    "city": "New York City",
    "state": "NY",
    "postalCode": "10024",
    "country": "US"
  }'

After creating the user address it will be returned in the response:

{
  "object": "userAddress",
  "id": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "city": "New York City",
  "country": "US",
  "line1": "129 West 81st Street",
  "line2": "Apartment 5",
  "postalCode": "10024",
  "state": "NY",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "createdAt": "2021-01-21T19:38:34Z"
}

Creating a Subscription

Now that we have a user, an address and a plan we can go ahead and create the subscription. We will do this with a POST to the /subscriptions API endpoint. Using the values obtained in the above examples:

• ${USER_ID} => "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
• ${ADDRESS_ID} => "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
• ${PLAN_ID} => "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"

we can define a new request. As we are creating an eSIM subscription, we can pass "auto" in the sim property, as the SIM details will be provisioned for us during the subscription creation process. If we were trying to create a subscription with a physical SIM (pSIM), we would need to pass the specific SIMS's details through in the subscription create request.

To attempt to reuse a user's last used SIM when creating a subscription, pass "preferLastUsed" instead of "auto".

curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "sim": "auto",
    "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }'

If the request was successful, you should receive a JSON response containing an subscription id, as well as references to related objects such as plan and user:

{
  "object": "subscription",
  "id": "sub_0U1WP6391FmqGW0gb3T3TGbsb8rW",
  "currentPeriod": {...},
  "phoneNumber": "+25411865216434",
  "plan": {...},
  "porting": null,
  "sim": null,
  "status": "pending",
  "user": {...},
  "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "createdAt": "2021-01-21T19:32:13Z",
  "activatedAt": null,
  "canceledAt": null,
  "endedAt": null,
  "firstUsageAt": null
}

A complete description of the successful response can be found in our documentation. Note that in the above response the sim is null and the subscription has the status of pending.

Depending on the network provider, it may take several minutes before the SIM is fully provisioned. In order to notify users as quickly as possible when their eSIM subscription is ready you should configure a webhook endpoint in the developers section of the Gigs Dashboard, and consume the com.gigs.subscription.activated event.

Note that activation times can vary from several minutes to several hours, and that subscriptions may not activate for even longer when porting a number.

For more information on how to set up webhook endpoints, check our events and webhooks guide.

Once the sim has been fully provisioned, the status of the subscription will change from pending to active and the sim object in the subscription response will be populated:

{
  "object": "subscription",
  "id": "sub_0U1WP6391FmqGW0gb3T3TGbsb8rW",
  "currentPeriod": {...},
  "phoneNumber": "+25411865216434",
  "plan": {...},
  "porting": null,
  "sim": {
    "object": "sim",
    "id": "sim_0U1WQria1FmqGW0nNQDxZqvrX7Nr",
    "type": "eSIM",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "active",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "active",
  "user": {...},
  "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "createdAt": "2021-01-21T19:32:13Z",
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": null,
  "expiredAt": null
}

A fully provisioned SIM will also have a status of active.

Activating an eSIM

After the subscription setup is complete, the eSIM can be installed and activated on the device. There are four possible activation methods:

• Using the iosInstallUrl — recommended for iOS users (iOS 17.5 or later). A one-tap link that installs the eSIM directly, without scanning a QR-Code or entering a code manually.
• Using the androidInstallUrl — recommended for Android users (requires Google Play Services). A one-tap link that installs the eSIM directly on compatible Android devices.
• Using a QR-Code — a good fallback for any device, or when the user's platform is unknown.
• Manually entering the activation code — a fallback for older devices or edge cases.

The right method depends on your users' devices. When you know whether a user is on iOS or Android, prefer the corresponding install link for the best experience. Fall back to the QR-Code or manual code otherwise.

This sensitive information is available under a separate SIM credentials endpoint, by passing the SIM id returned above (sim_0U1WQria1FmqGW0nNQDxZqvrX7Nr). The response includes:

• iosInstallUrl — a ready-to-use deep link for iOS devices.
• androidInstallUrl — a ready-to-use deep link for Android devices.
• qrCodeUrl — a URL pointing to a hosted QR-Code that can be scanned by any device.
• activationCode — the raw code that can be manually entered in device settings.

curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/sims/${SIM_ID}/credentials" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"

{
  "object": "simCredentials",
  "activationCode": "LPA:1$smdp.gigs.com$TEST-OUKOP-8JW6Y8B",
  "androidInstallUrl": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$TEST-OUKOP-8JW6Y8B",
  "iosInstallUrl": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.gigs.com$TEST-OUKOP-8JW6Y8B",
  "qrCodeUrl": "https://files.gigs.com/qrcode/dev/6tu8ZcW5IBi.png",
  "sim": "sim_0U1WQria1FmqGW0nNQDxZqvrX7Nr"
}

When using an install link, the user simply taps it on their device and follows the on-screen prompts to add the eSIM. No manual code entry or QR scanning is required. When using the QR-Code, open the qrCodeUrl on any device to render it, then scan with your mobile device's camera. Follow the prompts to add the data plan — shortly after, network connectivity should be established.

Final Thoughts

Great work! With just a few API calls, we were able to quickly create a subscription for an eSIM plan and establish connectivity for our user!

If you want to see how users can port-in their existing numbers into their new subscription, check out our porting guide.