SIM Management
Submissions

Creating a Submission

To create a job submission, you will need to perform a POST to one of our endpoints. As with all requests to the API, you will need to include a bearer token (see previous example). There are a number of different types of requests that you can make which will operate on a set of SIMs. For example, you might want to bar certain features, swap or provision SIMs. You might also want to check which bars are currently in place, or what features are enabled, in which case you would need to request a SIM Status Report.

Assuming that your request is valid, you will receive back a submission identifier. You should store this value as you will need it later to check on the status of your submission. If you do not submit a valid request, you may receive an HTTP error code. For example, if you are not permitted to perform a request, you will receive a 403 Forbidden response. Please see the FAQs section for additional information on this.

Check Submission status

Periodically check the status of your submission, until you get a status back indicating that it has finished executing. This can be accomplished by performing a GET request to /api/simSubmission.

Request

curl --location 'https://api.cellhire.com/api/simSubmission/fc33f231-8796-404f-b452-61665b0de0c5' \
--header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \

Response

Successful Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "ticketNumber": "fc33f231-8796-404f-b452-61665b0de0c5",
    "companyId": 123,
    "description": "Configure Bundle Monitor",
    "type": "configure-bundle-monitor",
    "createdOn": "2024-06-19T14:37:19.03Z",
    "createdBy": "Demo User",
    "cancelledOn": null,
    "cancelledBy": null,
    "cancelledReason": null,
    "status": "complete",
    "completedOn": "2024-06-19T14:37:39.587Z",
    "errorId": null,
    "errorText": null
}

Unsuccessful Response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
    "errors": {
        "ticketNumber": [
            "The value 'fc33f231-8796-404f-b452-61665b0dse0c6' is not valid."
        ]
    }
}

Possible Submission Statuses

Below is a list of the current statuses in use and what they mean:

  • pending The submission is pending validation.
  • validating The submission is validating.
  • invalid The submission has failed our validation checks. (There is something wrong with your request).
  • ready The submission is ready to be actioned. CAUTION: this status should not be confused with “complete” – it means only that the item has passed the validation stage.
  • running The submission is currently being processed.
  • cancelled The submission has been cancelled.
  • failed The submission failed. (The submission appeared to be valid, but there was a problem processing it).
  • complete The submission is complete.
  • network-notified The network provider has been notified of the change and will process the request at the next opportunity (only relevant for certain operations on the Orange network which may take a long time for the Orange network to process).

Please note that in the event of a validation error, the system will never attempt to process your submission. However, in the event of a failure, some parts of your submission may be successfully processed.

Warning: These statuses can be applied at each layer in the hierarchy (at the submission, command and individual SIM levels) – it is important to inspect each layer to get the full overview. For example consider:

  • A validation error. You might have an “invalid” submission, with two commands, one that is “ready” and one that is “invalid”. The “ready” command will contain only SIMs which are “ready”, whereas the “invalid” submission may contain a mixture of “ready” and “invalid” SIMs. A common mistake that people make is to confuse “ready” with “complete”. If the overall submission is “invalid”, the submission will never actually be processed. In the event of a validation error, you may wish to resubmit a partial request, omitting the invalid items.
  • A partial failure. You might have a “failed” submission, with two commands, one which is “complete” and one which “failed”. All SIMs on the “complete” submission will also be “complete”. However, the “failed” submission might have 5 SIMs that are “complete” and 1 that “failed”.
AuthenticationGet Requests