FAQ

Frequently Asked Questions

How do I get my credentials?

If you are already a Cellhire customer then you can contact your Account Manager and ask to be setup with API access. Otherwise you can contact our sales team who will be happy to organize a demo.

What company or accounts do I have access to?

You can get a list of companies and accounts by querying the following endpoints:

curl --location 'https://api.cellhire.com/api/company' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'
curl --location 'https://api.cellhire.com/api/company/[companyid/[account]]' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'

Why does the API use SIM serial numbers rather than MSISDNs to action changes?

We use the SIM serial number to identify a SIM card (i.e. the physical piece of plastic you would put in your device). A SIM card does not have a MSISDN assigned to it until after it has been provisioned with the network. This means we cannot use a MSISDN to reference a non-active SIM, rendering its use impractical. A MSISDN may also be swapped around between different SIM cards.

My in-house system relies on using MSISDNs / MSISDNs rather than serial numbers. How can I use the API with my system?

It is possible to perform a query to obtain a set of SIM Serial numbers from a set of MSISDNs, using the auto-queryable syntax supported by many of our endpoints. The example below shows how to obtain the serial numbers for a set of SIMs, identified by MSISDN:

curl --location 'https://api.cellhire.com/api/company/your_company_number/sim?select=tel,serialNumber&tel=0111111111,0222222222,0333333333,04444444444,055555555,06666666,077777777,088888888&wrapWith=total-count' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'

or if you know which account the SIMs are on, the following will be more efficient

curl --location 'api/company/your_company_number/account/your_account_number/sim?select=tel,serialNumber&tel=0111111111,0222222222,0333333333,04444444444,055555555,06666666,077777777,088888888&wrapWith=total-count' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'

Breaking the URL down into its segments:

  • select=tel,serialNumber – This tells the API to return just the tel & serialNumber as you are not interested in the other fields. Omit this clause if you want to return all the fields.
  • `tel=0111111111,0222222222,0333333333,04444444444,055555555,06666666,077777777,088888888 – This tells the API to return only those SIMs with the specified MSISDN.
  • wrapWith=total-count – This tells the API to return the total number of results. This is only really relevant if there are > 250 items and you need to page through the results. Please note that this approach is only scalable to a certain number of SIMs, as there is limit on the maximum length of a URL. Also, you may find that the query slows down if a very long list of MSISDNs is provided. Please note that you can get a list of companies and accounts to which you have access by querying the following endpoints:
curl --location 'https://api.cellhire.com/api/company' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'
curl --location 'https://api.cellhire.com/api/company/your_company_number/account' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjRBMDlENTFBMDhEOEUxMTU0OTkyODFDN...' \
--header 'Content-Type: application/json'

When I request a token, why do I get a response from the authentication API saying "invalid_client"?

We sometimes get asked whether the credentials we have supplied are correct. We always check your particular setup before sending out any connection credentials. The most common reasons for this error are:

  • Your request is not in the correct format.
  • The system you are using to insert your credentials is distorting the special characters included in your credentials.

Why am I getting a 401 Response when I attempt to connect to the SIM Management API?

Please check that you are including a valid bearer token in your request headers. Note that the bearer token will expire after approximately one hour, and you will then need to request a new one.

Why do I get a 403 Forbidden Response when I attempt to create a submission?

There are a number of reasons you may receive this response, including:

  • You do not have access to this SIM.
  • The SIM is not in a valid state for the operation.
  • The SIM is not on a network which supports this type of operation.
  • You do not have permission to perform this type of operation. In the first instance, we recommend that you check whether you can see the relevant SIM on your account, and also check that the SIM is in a suitable state for the operation to take place. Most of our operations require the SIM to be currently on-hire, while provisioning is only permitted on SIMS that are currently available for hire.

How long will it take for my submission to complete?

This depends on the nature of your request, current loads and the responsiveness of the network provider itself. As a general rule, expect the submission to take minutes or even hours rather than seconds. The larger your request, the longer it is likely to take. Certain operations on the Orange network may take time for Orange to action. The time of day the submission is submitted can also have an impact since some networks systems shut down at certain times for maintenance. For example the O2 network does not process requets between 22:00 and 05:00 UK Time and the Orange (France) LMVNO does not process requests between 22:00 and 06:00 French time. Submissions still running at this time will be held and processed when network service become available again.

Porting