Set Custom Data

5 min

Purpose

Assigns values to the customer field and custom fields used in the Insight Portal to collate and categorise SIM cards.

The target device is specified using the <iccid> element.

Each field setting is optional:

<customer> If included, must exactly match a customer entry that has already been configured in the Insight Portal. If an incorrect customer value is supplied, it will be ignored, any existing value will remain unchanged, and the API will still return Success.

<field-x> Sets the value of Custom Field x (where x = 1, 2, 3, or 4). Any existing data in the field will be completely overwritten.

Field length limits apply:

Fields 1 and 2: maximum 20 characters

Fields 3 and 4: maximum 50 characters

Data longer than the allowed field length will be truncated. Empty fields will be ignored.

Data must be entered as plain text. Reserved XML characters must be escaped as described in the XML format section.

Operational Impact

API commands perform live configuration changes.

Changes take effect immediately.

Commands may affect SIM status, service availability, charging, or usage limits.

Requests cannot be undone automatically.

Ensure all parameters are validated before submitting requests to the production environment.

Endpoint

POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xml

Request (XML)

<set-custom-data version="1" api-id="123456">
  <authentication>
    <username>username</username>
    <password>password</password>
  </authentication>
  <iccid>1234567890123456789</iccid>
  <customer>ACME Tracking</customer>
  <field-1>HP16 BVV</field-1>
  <field-2>Telit CV590</field-2>
  <field-3>VIN-1278649998</field-3>
  <field-4>26 The Gables, Whitmarsh, Lancs</field-4>
</set-custom-data>

Response (Success)

<set-custom-data-response api-id="123456">
  <api-outcome>Success</api-outcome>
</set-custom-data-response>

Response (Failure)

If a request cannot be processed, the response will include:

api-outcome indicating failure

An error description explaining the reason

Failure responses may occur due to:

Invalid authentication credentials

Invalid or unknown identifiers (for example ICCID or MSISDN)

Invalid or missing parameters

Values not permitted for the specified SIM type or account configuration

Insufficient permissions

Integrating systems should validate input data before submission and implement appropriate error handling and logging.