Skip to main content

1GLOBAL Enterprise APIs (1.0)

Download OpenAPI specification:Download

1GLOBAL Enterprise APIs

Accounts

The Accounts API provides organizations with a complete view of their active business accounts(individual accounts representing specific organizational units, departments), offering information to enhance compliance monitoring and centralized management.

Use cases:

  • Compliance Oversight: Consolidates account details for streamlined compliance and regulatory monitoring.
  • Centralized Account Visibility: Enables administrators to access all organizational accounts, simplifying management with quick visibility into key details such as account name, status, and associated countries.

Prerequisites:

  • Obtain a relevant license for the API.

List Accounts

Get a list of all accounts associated with the organization.

Authorizations:
JWT
query Parameters
limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10

Specifies the maximum number of results to return in the response.

cursor
string (Cursor) [ 1 .. 128 ] characters

Marker used for pagination to retrieve the next set of results in a list.

Responses

Response samples

Content type
application/json
{}

Get Account

Returns information for a specific business account.

Authorizations:
JWT
path Parameters
id
string
Example: acc_01HTJA47C93ABKKR58T05JBAJB

Unique identifier for the business account.

Responses

Response samples

Content type
application/json
{}

Subscribers

The Subscriber API allows organizations to retrieve a detailed list of their subscribers (individual users associated with the organization’s accounts e.g. employees).

Use cases:

  • Compliance and Security Oversight: Supports compliance requirements by giving visibility into individual subscriber data, allowing quick verification of subscriber name, group, and identification details.
  • Contact and Group Information Access: Allows administrators to view key subscriber details, including names, email addresses, employee IDs, and group affiliations, helping ensure data accuracy and alignment across the organization.

Pre-requisites:

  • Obtain a relevant license for the API.

List Subscribers

Authorizations:
JWT
query Parameters
limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10

Specifies the maximum number of results to return in the response.

cursor
string (Cursor) [ 1 .. 128 ] characters

Marker used for pagination to retrieve the next set of results in a list.

Responses

Response samples

Content type
application/json
{}

Get Subscriber

Authorizations:
JWT
path Parameters
id
string
Example: sbr_01HTQ8Z5HR26EN2HE797W5SZP9

A unique identifier for the subscriber, formatted as a 26-character alphanumeric string prefixed with "sbr_"

Responses

Response samples

Content type
application/json
{}

Subscriptions

Endpoints for managing your subscriptions.

List Subscriptions

Authorizations:
JWT
query Parameters
status
string
Enum: "active" "terminated"

The status of the subscription

limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10

Specifies the maximum number of results to return in the response.

cursor
string (Cursor) [ 1 .. 128 ] characters

Marker used for pagination to retrieve the next set of results in a list.

header Parameters
Prefer
string
Example: transclude="subscriber;account;sim_profile;phone_numbers;services"

What embedded resources to include in the response

Responses

Response samples

Content type
application/json
{}

Get Subscription

Authorizations:
JWT
path Parameters
id
string
Example: sub_01HTJA47C93ABKKR58T05JBAJB

The ID of the subscription

header Parameters
Prefer
string
Example: transclude="subscriber;account;sim_profile;phone_numbers;services"

What embedded resources to include in the response

Responses

Response samples

Content type
application/json
{}

Get Subscription's Phone Numbers

Authorizations:
JWT
path Parameters
id
string
Example: sub_01HTJA47C93ABKKR58T05JBAJB

The ID of the subscription

Responses

Response samples

Content type
application/hal+json
{}

Messages

The Messages API allows organizations to send SMS messages directly from authorized subscription numbers to one or more recipients.

Use cases:

  • Alert messages: for critical situations requiring immediate action such as emergency alerts or safety notifications.
  • Updates and Notifications: keep customers informed with reminders, updates, and notifications.
  • Marketing messages: send targeted promotional SMS messages to drive engagement,sales and customer interest.
  • Customer service: enable proactive engagement improving customer experience.

Notes:

  • This API incurs separate billing, and the charges for messages sent are consumed by the SMS plan associated with the authorized subscription number.
  • This is a Premium API, and is licensed separately.
  • Sending international messages is not supported.

Prerequisites:

  • Obtain a relevant license for the API.
  • Provide 1GLOBAL with a list of allowed subscription numbers authorized to send SMS messages through the API.

Send SMS

Sends SMS messages from authorized subscription numbers to specified recipients.

Authorizations:
JWT
Request Body schema: application/json
from
string^(\+\d{1,15}|\d{1,15})$

Authorized subscription number sending the message, in E.164 format

to
Array of strings (Msisdn) <= 1000 items [^(\+\d{1,15}|\d{1,15})$]

Array of up to 1,000 recipient phone numbers in E.164 format

text
string <= 500 characters

The content of the SMS message, limited to 500 characters.

Responses

Request samples

Content type
application/json
{
  • "from": "+11114567890",
  • "to": [
    ],
  • "text": "Thank you for using our service"
}

Response samples

Content type
application/json
{
  • "sms_id": "sms_01JBCG33BC2PS4J76JN685GN56"
}

Orders

The Orders API enables organizations to streamline subscription management, including provisioning new services, suspending or resuming subscriptions, and swapping SIMs.

Use cases:

  • Automated Onboarding: Connect to HR systems to provision eSIMs for new joiners, sending activation QR codes automatically.
  • Lost or Stolen Devices: Instantly suspend services to secure subscriptions for lost or stolen devices.
  • Upgrade to eSIM: Seamlessly swap physical SIMs to eSIMs for compatible devices.

Prerequisites:

  • Obtain a relevant license for the API.

Create Order

Submit a request to create a new subscription or make changes to the existing subscription associated with a specific account.

Authorizations:
JWT
Request Body schema: application/json
required
type
required
string

The order's requested action - create a new subscription.

account_id
required
string^acc_[0-9A-Z]{26}$

The account where the new subscription is provisioned.

template_id
string^otpl_[0-9A-Z]{26}$

The ID of the pre-configured template which includes plans and phone numbers.

required
object

The individual utilizing the new subscription.

required
object

Configuration of the SIM profile to be provisioned.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "activate_subscription",
  • "account_id": "acc_01HTQ8VBN4DEJP5S8BPV4657VG",
  • "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XQFUT",
  • "subscriber": {
    },
  • "sim_profile": {
    }
}

Response samples

Content type
application/json
{
  • "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
  • "status": "pending",
  • "type": "activate_subscription",
  • "account_id": "acc_01HTQ8VBN4DEJP5S8BPV4657VG",
  • "subscription_id": "sub_01HTQ8ZW1JVSFRWJX51K4CTX7Y"
}

Get Order

Retrieve the status of a previously submitted order.

Authorizations:
JWT
path Parameters
id
string^order_[0-9A-Z]{26}$
Example: order_01HZQ8GENA2K171RTJ3Z5FWW9R

The uniquie identifier of the order.

Responses

Response samples

Content type
application/json
{
  • "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
  • "status": "pending",
  • "type": "activate_subscription",
  • "account_id": "acc_01HTQ8VBN4DEJP5S8BPV4657VG",
  • "subscription_id": "sub_01HTQ8ZW1JVSFRWJX51K4CTX7Y"
}

Usage

The Usage API retrieves near real-time summary of subscriptions usage items for all the business units within an organizations. It includes detailed event types such as voice, SMS, and data usage. The response items are arranged in descending order by date with the most recently usage appearing first.

Use cases:

  • Monitoring Real-Time Usage: Track real-time usage for voice, SMS, and data across different business units, allowing organizations to monitor consumption at a granular level for various user groups or departments.
  • Tracking Roaming Usage for Employees: Organizations can monitor whether employees are roaming and track their data, voice, and SMS usage ensuring better management of roaming charges.
  • Optimizing Resource Allocation: By monitoring detailed usage patterns for data, voice, and SMS services, organizations can identify underused or overused resources and make informed decisions about resource allocation and cost optimization.
  • Real-Time Alerts for Out-of-Bundle Usage: Alerts can be set up to notify organizations when their users exceeds their included bundle for services like data, voice, or SMS. These out-of-bundle usages could incur additional charges, and real-time notifications help businesses proactively manage potential extra costs.

Prerequisites:

  • Obtain a relevant license for the API.

List usage

Authorizations:
JWT
query Parameters
from-date
string <date> (Iso8601Date) ^([0-9]{4})-(?:[0-9]{2})-([0-9]{2})$

The start date of the usage event.

to-date
string <date> (Iso8601Date) ^([0-9]{4})-(?:[0-9]{2})-([0-9]{2})$

The end date of the usage event.

account-id
string (AccountID) ^acc_[0-9A-Z]{26}$
Example: account-id=acc_01HTQ8VBN4DEJP5S8BPV4657VG

Unique identifier for the account associated with the usage data.

subscription-id
string (SubscriptionID) ^sub_[0-9A-Z]{26}$
Example: subscription-id=sub_01HTJA47C93ABKKR58T05JBAJB

Unique identifier for the subscription linked to the usage data.

subscriber-id
string (SubscriberID) ^sbr_[0-9A-Z]{26}$
Example: subscriber-id=sbr_01CWCM8KDGFTCYVH3KDP46HDXV

Unique identifier for the subscriber linked to the usage data.

msisdn
string (UsageMsisdn) ^\d{12,15}$
Example: msisdn=44000000000001

Mobile number related to the usage event (E.164 format).

type
Array of strings (Type)
Items Enum: "voice" "data" "sms"

The type of usage item.

direction
string (Direction)
Enum: "inbound" "outbound"

The direction of the usage.

cost-type
Array of strings (CostType)
Items Enum: "free" "in_bundle" "out_of_bundle"

Costs associated with the usage event.

limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10

Specifies the maximum number of results to return in the response.

cursor
string (Cursor) [ 1 .. 128 ] characters

Marker used for pagination to retrieve the next set of results in a list.

Responses

Response samples

Content type
application/json
{}