Skip to content

Searching Efficiently⚓︎

This page concentrates on searching for Subscribers, which is the resource with the most search options. However, the same logic can be applied to searching for other resources such as Sites or Systems.

The API method for searches is always GET.

//api.example.com/v1/subs/search/findByDeepSearch

Deep search allows you to search for Subscribers using any extensions that have been set for the user. Extensions are key value pairs expressed as key=value. It also allows you to search using partial match for specific values such as ICCID.

The following API call returns all Subscribers with the extension user=sam:

Example: user=sam

curl --request GET \
    --url 'http://localhost/v1/subs/search/findByDeepSearch?searchString=user%3Dsam
    --header 'Accept: application/hal+json'

Note that the \"=\" character in the extension is expressed as its Unicode equivalent: %3D.

The same deep search could be performed by omitting the key and the Unicode and just using the value, however this is less precise.

Example: sam

curl --request GET \
    --url 'http://localhost/v1/subs/search/findByDeepSearch?searchString=sam
    --header 'Accept: application/hal+json'

You may return an instance where the same value you\'re searching with is set for a different extension key. For example, the deep search shown here for sam would return Subscribers with the user of Sam but also with a device type of Samsung.

Find by Site, System, or Group IDs⚓︎

Subscribers belong to certain organizational resources in your network. The Site is the largest entity, often containing multiple Systems. A single System can span Sites. A Subscriber is assigned a single System Profile.

The following findBys extend the /subs/search/ endpoint path to search for Subscribers within organizational resources:

  • /v1/subs/search/findBySite
  • /v1/subs/search/findBySystem
  • /v1/subs/search/findByGroup
  • /v1/subs/search/findBySiteAndSystem

NOTE

To search by the organizational resource, you must user the associated ID value not the name of the Site, System, or Group. You can find the ID value by making an additional API call on the organizational entity.

--

You can discover the ID by using findByName on the resource, then applying the ID to the path.

Find By Name⚓︎

The findByName path allows you to discover the resource ID value as well as other details.

  • /v1/customers/search/findByName
  • /v1/sites/search/findByName
  • /v1/sys/search/findByName

To discover the ID value, make a findByName call on the resource. For example, make the following call and specify the System Name:

//api.example.com/v1/sys/search/findByName?name=*systemName*

The following API call searches for the System ID for the site \"xAuto\".

curl --request GET \
    --url 'http://localhost/v1/sys/search/findByName?name=xAuto' \
    --header 'Accept: application/hal+json'

This returns the system ID of 12319402.

Apply the ID value to the Path⚓︎

Now you know the system ID, you can use it in the search field

//api.example.com/v1/subs/search/findBySystem?system= SystemID

For example, the following call returns all Subscribers assigned to the system xAuto that has a system ID of 12319402.

curl --request GET \
    --url 'http://localhost/v1/subs/search/findBySystem?system=12319402
    --header 'Accept: application/hal+json'

Find By SIM card Values⚓︎

You can search for a Subscriber based on the following SIM card values:

  • /v1/subs/search/findByIccid
  • /v1/subs/search/findByMsisdn

ICCID -- a unique 18-22 digit code often printed on the back of the SIM card that includes a country code, home network, and identifier.

//api.example.com/v1/subs/search/findByIccid?iccid= ICCID number

MSISDN -- a unique code maximum 15 characters that identifies a SIM card in its mobile network. Often the phone number to which you call or send an SMS message.

//api.example.com/v1/subs/search/findByMsisdn?msisdn= MSISIDN number

The entire value must be entered. Use findByDeepSearch to enter partial values.

The following example searches for a Subscriber using a known MISIDN value.

curl --request GET \
   --url 'http://localhost/v1/subs/search/findByMsisdn?msisdn=123438386906424'
   --header 'Accept: application/hal+json'