Subscribers Management

Learn how to manage your subscribers with their dedicated APIs


Subscriber overview

This API will help you to manage your subscribers and their lifecycle. Please refer to the below diagram in order to get an overview of the subscriber entity.

Subscriber schema

This API will allow you to interact with the following:

  • Status: Subscriber status is managed through the subscriber lifecycle and drives the Network services (Communications active or inactive) and Billing status (Active or inactive).
  • Rate plan: Depending on your contract you may get multiple rate plans which can be applied to your subscriber through this API.
  • Options: The API provides ability to configure options for a specific subscriber including: network services & configuration, billing options and Value Added Services options. Options depend on the offer and rate plan assigned to the subscriber.
  • SIM Card: When a SIM Card in available status is activated, it is linked to a newly created subscriber. SIM card can be swapped during subscriber lifetime.
  • MSISDN: Depending on your offer the MSISDN can be attributed at SIM order, at preactivation or activation. It can be swapped during the subscriber lifetime. Depending on your use case you may get regular localized MSISDN or long M2M MSISDN.
  • Group, external reference and subscriber contact information can also be managed through this API in order to persist your own business references or subscriber information.

Subscriber lifecycle and statuses

Before proceeding to your first subscriber activation you need to be aware of your overall subscriber lifecycle. Please note that depending on your offer, the lifecycle may include some optional statuses.

For more information about your subscriber's lifecycle and available statuses, please refer to your Service Order Form.

While this API gives you ability to trigger transition from one status to another, transitions can also be triggered by external events like the first usage of the connectivity service by your subscriber. The below state machine describes extensively the allowed transitions as well as actions that may trigger them.

Subscriber lifecycle

Subscriber lifecycle

Subscriber statuses

Mandatory Statuses

Mandatory statuses are available independently of your offer.

StatusDescriptionNetwork servicesBilling status
available_status_imgAvailableSIM card is ready to be activatedInactiveInactive
active_status_imgActiveSubscriber is fully activated in all systemsActiveActive
suspended_status_imgSuspendedNetwork services are suspendedInactiveActive
terminated_status_imgTerminatedSubscriber and related SIM card are terminated in all systemsInactiveInactive

Optional statuses

You may have the need to use the following optional statuses depending on your use case or offer.

StatusDescriptionNetwork servicesBilling status
loaded_status_imgLoadedOnly for MVNO France customers on a light network architecture. SIM card is activated only on Orange France side to allocate the MSISDN.InactiveInactive
preac_status_imgPre-ActivatedSubscriber has a limited set of network services but is able to do a first usage which will trigger the complete activation (voice, SMS or data).ActiveInactive

IoT lifecycle optional statuses

IoT customers may get additional statuses: Tariff holiday and / or Test mode. For more detailed information you can refer to IoT optional statuses page. For standard offers these statuses are not enabled by default. If you are interested please reach out to your Transatel account manager.

Status transition events

Every status transition generates an event. A transition can be triggered manually or automatically, and in some cases, both.
You can refer to the connectivity management events page for a comprehensive list of all events.

Subscriber Management

Information presented below are applicable for all Transatel customers.

Retrieve subscriber information

Using this operation, you can easily retrieve subscriber information such as: current status, rate plan, configured options, and important dates (activation, last modified and end of contract dates where applicable).

Preactivate a subscriber

Subscriber preactivation is interesting when dealing with prepaid subscriptions, where ready to use SIM cards with preloaded bundles can be distributed in sales points. Note that preactivation order is not yet available through API, please refer to your account manager for more information about preactivation management.

For every preactivation, a preactivation event will be generated.

Activate a subscriber

Subscriber activation operation initializes network services and enables the SIM card to attach to the network and make calls. The subscriber is created if not yet existing (through preactivation) and becomes billable. You can refer to our step by step guide to perform your first activation.

Every activation order will trigger an activation event.

Modify a subscriber

Subscriber modification operation allows you to modify rate plan, options and external reference configured for a specific subscriber.

Only the options provided are changed, all other options remains unaffected.

The modification order is allowed for subscribers with following statuses: Active, Suspended, TestMode.

Modification on suspended status is not allowed for MVNO France light architecture.

Every modification order will trigger a modification event.

Suspend a subscriber

Subscriber suspension operation will block all network services for the subscriber thus preventing connectivity charges until reactivation. After suspension subscriber will transition to the Suspended status and recurring charges will continue to apply.

Suspension causes can vary:

  • Manual Suspension: Suspension can be done manually by customer
  • Automated Suspension: It can be triggered in an automated manner when customer has configured high usage thresholds
  • Operator Suspension: Transatel may trigger a suspension of a subscriber in the case of a malfunction or fraud

For all suspension described above a suspension event is always triggered.

Reactivate a subscriber

Subscriber reactivation operation will restore the network services and air-time charging.

A reactivation event is always triggered.

SIM card swap

SIM card swap operation will replace an existing SIM card with a new one. The existing SIM card will be terminated, and the new one activated.

The subscriber is not affected by the operation, except it's now linked to the new SIM card.

SIM card swap operation is allowed for subscribers in following statuses: Active, TestMode, Suspended, Tariff_Holiday.

For every SIM swap a SIM swap event will be generated.

MSISDN swap

MSISDN swap operation allows you to change the MSISDN of an active subscriber for a new one. In such case, the first available number found in Transatel MSISDN pool will be used.

Please note MSISDN swap is not available for MVNO France light architecture and MVNO UK customers.

MSISDN swap operation is allowed for subscribers in following statuses: Active, TestMode, Suspended, Tariff_Holiday.

For every MSISDN swap, a MSISDN swap event will be generated.

Terminate a subscriber

Subscriber termination operation is a non-reversible procedure that disables all network services and permanently deactivates the subscriber. For more details about billing aspects please refer to your commercial terms.

For every termination a termination event will be generated.

Options management

Subscriber options are configured upon SIM card activation and can be modified as long as the subscriber is in Active, Suspended or TestMode status. Depending on your offer you may have ability to configure options such as:

  • Network services: Roaming options, roaming profiles, barrings, special communications services, data routing profiles, data Fair Use Policy (FUP), ...
  • Billing options: Pricing models
  • Value Added services: Voicemail parameters, FMC, ...

You can set options upon activation and modify afterwards using the modification operation.

Please note there are two major options types:

TypeDescription
Single choice optionsThey enable or disable a specific service. This is typically provided in the case of network barring management. For example bar or unbar data.
Multiple choices optionsThey select an option value from a pre-defined list, all values are mutually exclusive so choosing one automatically deactivates others. This is typically provided for bundle selection. For example 1GB, 2GB, 5GB, or 10GB.

If you wish to go further with subscriber options modification, you can go through our step by step guide.

In order to find detailed list of available options for your specific offer, please reach your account manager.

Administration & Fleet management

In order to organize your subscribers fleet Transatel provides two custom attributes manageable through API: group and externalReference. These two attributes can be set upon activation or modified during subscriber lifecycle.

Groups and externalReference are searchable fields in our SIM management portal.

Group management

The group property allows Transatel customers to organize their subscribers and SIM card fleets. The group has no effect on subscriber network services but is very helpful for filtering on a sub-fleet in SIM management portal.

Activate subscriber with a group

The activation method allows you to specify group for the selected subscriber.

Update a group for a specific subscriber

You can manage the group attribute by using the contact info operation. Please note the group update is subject to specific rules.

External reference management

External reference is an optional field which service providers can use to persist their own internal subscriber reference or IDs in Transatel’s systems. This field can be set upon subscriber activation or modification. Please note there is no unique constraint on this field.

External reference is searchable field in our SIM management portal.

Contact info management

For each subscriber, you are able to update personal information such as: name, address, country, dateOfBirth, contactEmail, ... by using the proper operation.

This information will be available in our SIM management portal in Line / Subscriber tab. Please note first name, last name, company are searchable fields.

SIM card information

By using this operation, you can retrieve the technical details of a SIM card:

  • Security codes: PINs and PUKs
  • SIM profile: Manufacturer, electrical profile reference, SIM application compatibility, release of the Transatel applet, type, ...
  • MSISDN potentially assigned

Transaction information

For each request triggering an asynchronous process, you will receive a transactionId in the response. Since activation requests are asynchronous, in case of success the HTTP response code will be 201 Activation Accepted and transaction status Pending until order has been processed by our systems. You can store the transactionId in order to request the status of the previously submitted request via this operation.