Learn how to manage your subscribers with their dedicated APIs
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.
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. Please refer to our FAQ in order to find your rate plan.
- 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.
Mandatory statuses are available independently of your offer.
|Status||Description||Network services||Billing status|
|Available||SIM card is ready to be activated||Inactive||Inactive|
|Active||Subscriber is fully activated in all systems||Active||Active|
|Suspended||Network services are suspended||Inactive||Active|
|Terminated||Subscriber and related SIM card are terminated in all systems||Inactive||Inactive|
You may have the need to use the following optional statuses depending on your use case or offer.
|Status||Description||Network services||Billing status|
|Loaded||Only for MVNO France customers on a light network architecture. SIM card is activated only on Orange France side to allocate the MSISDN.||Inactive||Inactive|
|Pre-Activated||Subscriber 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).||Active||Inactive|
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.
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:
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:
For every SIM swap a SIM swap event will be generated.
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:
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.
Subscriber options are configured upon SIM card activation and can be modified as long as the subscriber is in
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
|Single choice options||They 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 options||They 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
optionsfor your specific offer, please refer to our FAQ.
Administration & Fleet management
In order to organize your subscribers fleet Transatel provides two custom attributes manageable through API:
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.
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:
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
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.