Telecom Management APIs

With Telecom Management, you can manage the full lifecycle of a subscription — from activation to disconnection.

---

What can you do with this product

This product supports the following processes:

1. Activate Subscription
2. Change Profile of Subscription
3. Perform SIM Swap
4. Suspend / Unsuspend SIM
5. Retrieve PIN/PUK
6. Employee Details
7. Deactivate Subscription
8. Convert to Prepaid
9. Number Port-In
10. Number Port-Out

---

Prerequisites

Before you start, make sure you have:

• Access to the Odido Developer Portal
• OAuth client credentials (client_id and client_secret)
• The required roles/scopes to perform the processes you intend to use

Authentication

All APIs are secured using OAuth 2.0 Client Credentials:

1. Request an access token using your client credentials
2. Include it in every API request:

Authorization: Bearer <access_token>

---

Common error responses

These error responses are shared across the documented endpoints unless stated otherwise.

HTTP status	Meaning	Description
400	Bad Request	Invalid request or missing required parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
500	Internal Server Error	Internal server error

---

1) Activate Subscription

Use this endpoint when you want to activate a new mobile subscription for an employee.
In this process, you link a SIM card and mobile number to the correct customer account and activation profile, so the subscription can be created and made ready for use.

Typical use cases:

• onboarding a new employee
• activating a temporary number for number porting

Activate a SIM by selecting the correct billing account, optionally checking remaining activation authorizations, selecting an activation profile, and submitting an activation request.

Version history	Release Date	Description
1.0	RELEASE DATE	Release of activate subscription

What you need

• accountId — identifier of your customer number
• profileId — identifier of your activation profile
• For each subscription:
  • msisdn — mobile number
  • iccid — SIM card number

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. (Optional) Retrieve accounts to find the correct accountId.
3. (Optional) Check the available authorization count for that accountId.
4. (Optional) Retrieve activation profiles for that accountId and select the correct profileId.
5. Submit the activation request.

Sequence diagram

sequenceDiagram
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  autonumber
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  opt If accountId unknown
    Client->>TM: GET /accounts/v1
    TM-->>Client: accounts [] (includes accountId)
  end
  
  opt If you want to check remaining activation authorizations
    Client->>TM: GET /v1/mobile/accounts/{accountId}/authorization-count
    TM-->>Client: availableAuthorizationCount
  end

  opt If profileId unknown
    Client->>TM: GET /v1/mobile/accounts/{accountId}/activation-profiles
    TM-->>Client: activationProfiles [] (includes profileId)
  end

  Client->>TM: POST /v1/mobile/subscriptions/activate
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoints

1.1 Get Accounts (optional)

Endpoint
GET https://connect-staging.odido.nl/accounts/v1

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token

Output

Field	Type	Description
accounts	array	List of available accounts
accounts[].customerCode	string	Customer code
accounts[].id	string	Identifier of your customer number
accounts[].name	string	Name of your customer number
accounts[].type	string	Type of your customer number

Error codes

HTTP status	Meaning
401	Unauthorized
403	Forbidden
500	Internal Server Error

---

1.2 Get available SIM authorizations (optional)

Endpoint
GET https://connect-staging.odido.nl/telecom-management/v1/mobile/accounts/{accountId}/authorization-count

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
accountId	Path	Yes	string	Identifier of your customer number

Output

Field	Type	Description
account.customerCode	string	Customer code
account.id	string	Identifier of your customer number
account.name	string	Name of your customer number
account.type	string	Type of your customer number
availableAuthorizationCount	integer	Number of authorizations left to activate

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

1.3 Get Activation Profiles (optional)

Endpoint
GET https://connect-staging.odido.nl/telecom-management/v1/mobile/accounts/{accountId}/activation-profiles

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
accountId	Path	Yes	string	Identifier of your customer number

Output

Field	Type	Description
account.customerCode	string	Customer code
account.id	string	Identifier of your customer number
account.name	string	Name of your customer number
account.type	string	Type of your customer number
activationProfiles	array	Available activation profiles
activationProfiles[].description	string	Description of the activation profile
activationProfiles[].id	string	Identifier of the activation profile
activationProfiles[].name	string	Name of the activation profile
activationProfiles[].type	string	Profile type, for example voice or data

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

1.4 Activate Subscription

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/activate

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
customerOrderReference	Body	No	string	Your own reference
subscriptions	Body	Yes	array	List of subscriptions to activate
subscriptions[].accountId	Body	Yes	string	Identifier of your customer number
subscriptions[].activationDate	Body	Yes	string	Requested activation date
subscriptions[].companyDetails.employeeNumber	Body	Yes	string	Employee number
subscriptions[].iccid	Body	Yes	string	SIM card number
subscriptions[].msisdn	Body	Yes	string	Mobile number
subscriptions[].personalDetails.emailAdress	Body	Yes	string	Email address
subscriptions[].personalDetails.firstName	Body	Yes	string	First name
subscriptions[].personalDetails.lastName	Body	Yes	string	Last name
subscriptions[].personalDetails.prefix	Body	No	string	Prefix / middle name addition
subscriptions[].profileId	Body	Yes	string	Identifier of the activation profile

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference, if provided
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

---

2) Change Profile Subscription

Change the profile of an existing subscription. The API returns an order confirmation.

What you need

For each subscription:

• msisdn — mobile number
• profileId — identifier of the activation profile

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Submit a change-profile request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/change-profile
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/change-profile

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
customerOrderReference	Body	No	string	Your own reference
subscriptions	Body	Yes	array	List of subscriptions
subscriptions[].msisdn	Body	Yes	string	Phone number
subscriptions[].profileId	Body	Yes	string	Identifier of the activation profile

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

3) Perform SIM Swap

Request a SIM swap to replace the current SIM with a new SIM for the specified MSISDN.

What you need

• msisdn — phone number of the subscription to be swapped
• newSIMNumber — SIM number of the new blank SIM card

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Submit a SIM swap request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/replace-sim
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/sims/sim-swap

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Body	Yes	string	Phone number
newSIMNumber	Body	Yes	string	SIM number of the new blank SIM card
customerOrderReference	Body	No	string	Your own reference

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference
orderId	string	Internal order identifier
orderReference	string	Order reference
simStatus.current	string	Current SIM status
simStatus.new	string	New SIM status

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

---

4) Suspend / Unsuspend SIM

Temporarily suspend service for one or more SIMs, or re-enable service after suspension. Both operations create an order.

What you need

• msisdn — phone number

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Submit a suspend request.
3. Submit an unsuspend request when needed.

Suspend — Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/suspend
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Unsuspend — Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/unsuspend
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoints

4.1 Suspend SIM

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/sims/suspend

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
customerOrderReference	Body	No	string	Your own reference
SIMs	Body	Yes	array	List of SIMs
SIMs[].msisdn	Body	Yes	string	Phone number

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

4.2 Unsuspend SIM

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/sims/unsuspend

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
customerOrderReference	Body	No	string	Your own reference
SIMs	Body	Yes	array	List of SIMs
SIMs[].msisdn	Body	Yes	string	Phone number

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

5) Get PIN/PUK codes

Retrieve PIN and PUK codes for a SIM using the MSISDN.

What you need

• msisdn — phone number

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Call the PIN/PUK endpoint with the MSISDN.

Sequence diagram

sequenceDiagram
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  autonumber
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: GET /v1/{msisdn}/pin-puk
  TM-->>Client: 200 OK

Endpoint

Endpoint
GET https://connect-staging.odido.nl/telecom-management/v1/mobile/sims/{msisdn}/pin-puk

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Path	Yes	string	Phone number

Output

Field	Type	Description
msisdn	string	Phone number
pin	string	PIN code
puk	string	PUK code

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

6) Employee Details

Retrieve and maintain employee details linked to a subscription.

What you need

• msisdn — phone number

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Retrieve employee details (GET).
3. Update employee details when needed (PATCH).
4. Delete employee details when needed (DELETE).

Get Employee Details — Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: GET /v1/{msisdn}/employee-details
  TM-->>Client: 200 OK

Update Employee Details — Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: PATCH /v1/{msisdn}/employee-details
  TM-->>Client: 204 No Content

Delete Employee Details — Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: DELETE /v1/{msisdn}/employee-details
  TM-->>Client: 204 No Content

Endpoints

6.1 Get Employee Details

Endpoint
GET https://connect-staging.odido.nl/telecom-management/v1/mobile/subscribers/{msisdn}/employee-details

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Path	Yes	string	Phone number

Output

Field	Type	Description
email	string	Email address
employeenumber	string	Employee number
firstName	string	First name
lastName	string	Last name
middleName	string	Middle name

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

6.2 Update Employee Details

Endpoint
PATCH https://connect-staging.odido.nl/telecom-management/v1/mobile/subscribers/{msisdn}/employee-details

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Path	Yes	string	Phone number
email	Body	No	string	Email address
employeenumber	Body	No	string	Employee number
firstName	Body	No	string	First name
lastName	Body	No	string	Last name
middleName	Body	No	string	Middle name

Output

No content.

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

6.3 Delete Employee Details

Endpoint
DELETE https://connect-staging.odido.nl/telecom-management/v1/mobile/subscribers/{msisdn}/employee-details

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Path	Yes	string	Phone number

Output

No content.

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

7) Deactivate Subscription

Deactivate an existing subscription by creating a deactivation order.

What you need

• msisdn — phone number

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Submit a deactivation request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/deactivate
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/deactivate

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
msisdn	Body	Yes	string	Phone number

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference, if supported
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

8) Convert to Prepaid

Convert a mobile subscription from postpaid to prepaid by creating an order.

What you need

• msisdn — phone number
• migrationDate

Steps

1. Get an access token using OAuth 2.0 client credentials.
2. Submit a postpaid-to-prepaid request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/post-to-prepaid
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/post-to-prepaid

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token
customerOrderReference	Body	No	string	Your own reference
subscriptions	Body	Yes	array	List of subscriptions
subscriptions[].msisdn	Body	Yes	string	Phone number
subscriptions[].migrationDate	Body	Yes	string	Requested migration date

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

9) Number Port-In

Use this endpoint when you want to transfer an existing mobile number from another provider to Odido.
In this process, you associate the number with the correct customer account and provide the current contract details, porting date, and temporary SIM information so the port-in request can be created and processed.

Typical use cases:

• onboarding an employee who wants to keep an existing mobile number
• moving business mobile numbers from another provider to Odido

Submit a number port-in request by providing the billing account, current contract details, requested porting date, and temporary SIM details.

Version history	Release Date	Description
1.0	RELEASE DATE	Release of number port-in

What you need

• accountId — identifier of your customer number
• portingDate — requested date for the number transfer
• currentContract.msisdn — the mobile number to be ported in
• currentContract.customerCode — customer code used by the current provider
• currentContract.contractEndDate — end date of the current contract with the existing provider
• temporarySim.msisdn — temporary mobile number used during the porting process
• temporarySim.iccid — temporary SIM card number

Steps

1. Get an access token using OAuth 2.0 client credentials [1].
2. Submit the port-in request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/mobile/subscriptions/port-in
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/port-in

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token [1]
customerOrderReference	Body	No	string	Your own reference
accountId	Body	Yes	string	Billing account identifier
portingDate	Body	Yes	string	Requested porting date
currentContract.msisdn	Body	Yes	string	Phone number to be ported in
currentContract.customerCode	Body	Yes	string	Customer code at the current provider
currentContract.contractEndDate	Body	Yes	string	Contract end date at the current provider
temporarySim.msisdn	Body	Yes	string	Temporary phone number
temporarySim.iccid	Body	Yes	string	Temporary SIM card number

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference, if provided
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request [1]
401	Unauthorized [1]
403	Forbidden [1]
404	Not Found [1]
500	Internal Server Error [1]

---

10) Number Port-Out

Use this endpoint when you want to transfer an existing mobile number from Odido to another provider.
In this process, you identify the correct customer account, specify the mobile number to be ported out, and provide the requested porting date so the port-out request can be created and processed.

Typical use cases:

• ending service for an employee who wants to keep the mobile number
• moving business mobile numbers from Odido to another provider
• contract termination combined with number transfer

Submit a number port-out request by providing the billing account, the mobile number, and the requested porting date.

Version history	Release Date	Description
1.0	RELEASE DATE	Release of number port-out

What you need

• accountId — identifier of your customer number
• msisdn — the mobile number to be ported out
• portingDate — requested date for the number transfer

Steps

1. Get an access token using OAuth 2.0 client credentials [1].
2. Submit the port-out request.

Sequence diagram

sequenceDiagram
  autonumber
  participant Client as Customer
  participant Auth as OAuth Token Service
  participant TM as Telecom Management APIs
  Client->>Auth: POST /token (client_credentials)
  Auth-->>Client: access_token
  Client->>TM: POST /v1/mobile/subscriptions/port-out
  TM-->>Client: 201 Created (orderId/orderReference/correlationId)

Endpoint

Endpoint
POST https://connect-staging.odido.nl/telecom-management/v1/mobile/subscriptions/port-out

Input

Field	Location	Required	Type	Description
Authorization	Header	Yes	string	Bearer access token [1]
customerOrderReference	Body	No	string	Your own reference
accountId	Body	Yes	string	Billing account identifier
msisdn	Body	Yes	string	Phone number to be ported out
portingDate	Body	Yes	string	Requested porting date

Output

Field	Type	Description
correlationId	string	Correlation identifier for tracking
customerOrderReference	string	Your own reference, if provided
orderId	string	Internal order identifier
orderReference	string	Order reference

Error codes

HTTP status	Meaning
400	Bad Request [1]
401	Unauthorized [1]
403	Forbidden [1]
404	Not Found [1]
500	Internal Server Error [1]