sim_handling

The following methods allow for interaction with the ZCell SIM Handling API endpoints. Includes SIM details, CSV download, tag assignment, lock/status/state updates, and SIM search.

Methods are accessible via zcell.sim_handling

Copyright (c) 2023, Zscaler Inc.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class SimHandlingAPI

Bases: APIClient

create_sims_download(id=None, query_params=None, filename=None, **kwargs)

Downloads SIM data as a CSV file.

This endpoint streams a CSV file directly to the response (Content-Type: text/csv). The response is a file download, not a JSON body, so this method writes the stream to disk and returns the path to the saved file.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • query_params (dict, optional) –

    Map of query parameters for the request.

    [query_params.sort_by] {str}: Field to sort by. Defaults to usage.

    [query_params.sort_dir] {str}: Sort direction (ASC or DESC). Defaults to ASC.

  • filename (str, optional) – Custom filename for the CSV file. Defaults to a timestamped name.

  • **kwargs – Optional request body filters. Supported fields include: iccid (list[str]), status (str), network_status (str), ip_address (list[str]), location_country (str), tag (list[str]), device_type (str), brand_name (str), marketing_name (str), model_name (str), form_factor (str), imei_status (str: Locked, Unlocked, InProgress).

Returns:

Path to the downloaded CSV file.

Return type:

str

Examples

Download SIM data as a CSV:

>>> try:
...     # Invoke the create_sims_download method with correct parameters
...     filename = client.zcell.sim_handling.create_sims_download(
...         id='gi754cvqb07r0',
...         query_params={"sort_by": "usage", "sort_dir": "ASC"},
...         status="active",
...         filename="zcell_sims.csv",
...     )
...     print(f"SIM data downloaded successfully: {filename}")
... except Exception as e:
...     print(f"Error during download: {e}")

Get all sims data with filter and pagination.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • **kwargs – Request body fields.

Returns:

(result, Response, error)

Return type:

tuple

Examples

>>> result, response, error = client.zcell.sim_handling.create_sims_search(id='...', name='example')
>>> if error:
...     print(f"Error: {error}")
...     return
>>> print(result.as_dict())
list_sims_details(id=None, icc_id=None, query_params=None)

Get sim details by icc_id.

This endpoint returns a single SIM resource (not a paginated list), matched by the required iccId query parameter.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • icc_id (str) – Required query parameter. The ICCID of the SIM to retrieve.

  • query_params (dict) – Map of query parameters for the request. [query_params.icc_id] {str}: Required. The ICCID (alternatively pass icc_id directly).

Returns:

(SimData, Response, error)

Return type:

tuple

The returned response supports resp.search(<jmespath>) for client-side filtering/projection.

Examples

>>> fetched_status, _, error = client.zcell.sim_handling.list_sims_details(
...     id='gi754cvqb07r0',
...     icc_id='89852350525020075842'
... )
>>> if error:
...     print(f"Error fetching SIM details: {error}")
...     return
>>> print(f"SIM details fetched successfully: {fetched_status.as_dict()}")
update_sims_assign(id=None, iccid=None, assignment=None, **kwargs)

Assigns an eSIM to the user and returns the activation code.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • iccid (str) – The ICCID of the eSIM to assign (path parameter).

  • assignment (str) – The user to assign the eSIM to. Sent in the request body as {"assignment": ...}.

Returns:

A tuple containing the GetActivationCodeResponse (iccid, activation_code, qr_code), the raw Response, and error (if any).

Return type:

tuple

Examples

>>> result, response, error = client.zcell.sim_handling.update_sims_assign(
...     iccid='89852350525020075842',
...     assignment='testuser',
... )
>>> if error:
...     print(f"Error: {error}")
...     return
>>> print(result.activation_code)
>>> print(result.qr_code)
update_sims_assign_tag(id=None, **kwargs)

Assigns a tag to the sim.

This endpoint returns 204 No Content on success (no response body), so result is None when the assignment succeeds. Use the returned response (e.g. response.get_status()) to confirm success.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • **kwargs –

    Request body fields.

    icc_id (str): The ICCID of the SIM to tag.

    tag_ids (list[str]): The tag IDs to assign to the SIM.

Returns:

(None, Response, error)

Return type:

tuple

Examples

>>> _, response, error = client.zcell.sim_handling.update_sims_assign_tag(
...     id='gi754cvqb07r0',
...     tag_ids=['1558'],
...     icc_id='89852350525020075842'
... )
>>> if error:
...     print(f"Error updating SIM tag: {error}")
...     return
>>> # This endpoint returns 204 No Content (no response body).
>>> print(f"SIM tag assigned successfully (status {response.get_status()}).")
update_sims_lock(id=None, **kwargs)

Lock the sims for provided sim ids.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • **kwargs – Request body fields.

Returns:

(result, Response, error)

Return type:

tuple

Examples

>>> result, response, error = client.zcell.sim_handling.update_sims_lock(id='...', name='example')
>>> if error:
...     print(f"Error: {error}")
...     return
>>> print(result.as_dict())
update_sims_state(id=None, iccid=None, **kwargs)

Fetch and Refresh Provider eSim State.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • iccid (str) – Path parameter.

  • **kwargs – Request body fields.

Returns:

(result, Response, error)

Return type:

tuple

Examples

>>> result, response, error = client.zcell.sim_handling.update_sims_state(
...     id='...',
...     iccid='...',
... )
>>> if error:
...     print(f"Error: {error}")
...     return
>>> print(result.as_dict())
update_sims_status(id=None, **kwargs)

Update the sim status for provided sim ids.

Parameters:

  • id (str) – Optional. The ZCell customer ID. Defaults to the zcellCustomerId config value or the ZCELL_CUSTOMER_ID environment variable when omitted.

  • **kwargs – Request body fields.

Returns:

(result, Response, error)

Return type:

tuple

Examples

>>> result, response, error = client.zcell.sim_handling.update_sims_status(
... id='...',
... name='example')
>>> if error:
...     print(f"Error: {error}")
...     return
>>> print(result.as_dict())