The new iteration of the Simbase Public API is now available to everyone!
\nDocumentation is now held at the Simbase Developer Portal (developer.simbase.com).
\nIf you are new to Simbase APIs, please skip this API version as it won't be accessible with API Keys created on your account.
\nIf you are currently using API v1, we highly recommend you check out API v2 and its new enhancements, including:
\nScoped API Keys to enhance the security of your resources
\nConsistent and robust endpoints with standardized data structures, formats and types
\nBrand new features!
\n\n\n❗ HEADS UP ❗
\n
Newly created API keys will NOT work with API v1. Your current API keys will continue to work indefinitely and Simbase API v1 will stick around for the foreseeable future.
This is to ensure that the authorization scopes you select at creation will be enforced, something that this API version does not support.
If you are still using Simbase API v1, can not migrate to Simbase API v2 and need new API Keys to be authorized on Simbase API v1, let us know at support@simbase.com
To get started and see the results, make sure to get a Simbase SIM and sign-up or login to our dashboard.
\nSimbase continuously adds more APIs and features. If you have questions or have any requests for future APIs, submit a support request or create a feature request at https://feedback.simbase.com.
\nAll customers can use the API free of charge. Please be aware that some API calls trigger events, like sending an SMS, that bear costs. The SMS message is billed according to the rate plan assigned to your SIM card.
\nTo make a successful API call, you need your account's API key. You can obtain and reset your API key in the Simbase dashboard. Log in and go to 'API Key' under 'Settings'. API keys are only visible for Admin users.
\nTo make a successful API call put the header below in every API call:
\n{\"x-api-key\":\"{{Your API Key}}\" }\n\nPlease limit your request to a maximum of 10 calls/second and 5000 calls/day. Should you require more calls, submit a support request
\nThe device_name is a custom identifier you can assign to a SIM card. The value will also appear in the dashboard.
\nTo address an individual SIM card in your account, the API requires an iccid to identify the subscription. The iccid is the barcode printed on the SIM card. You can get an overview of the iccid's in the dashboard of your account, or call the 'sims' API.
\nThe plan_id is the identifier of the rate plan that is assigned to this SIM card. A rate plan is a commercial plan or bundle, that defines how usage of a SIM card is billed.
\nThere are 4 SIM states that you can assign to your SIM card. The different SIM states have implications on service- and billing states.
\nThe aggregated data usage of a SIM in bytes for the current calendar month. Please note that 1MB = 1024kb = 1048576 bytes.
\nThe number of SMS messages sent by this SIM card during this calendar month.
\nThe number of SMS messages received by this SIM card during this calendar month.
\nCall this API to retrieve all the SIM cards registered to your account. Optionally, you can filter on specific identifiers, such as sim_state, coverage, and tags. It is also possible to search on text values, for example (a part of) the device, iccid, etc with the search parameter.
\nA maximum of 250 cards is returned in one response message. You can set the number of SIM cards in the return message with the pagesize param. To retrieve the next 'page' of SIM cards, use the page parameter. The response will always return the total number of pages found by your search query.
\ntotal_records: The total number of records found in the database with the applied search query.
\nrecords: The total number of records in this response. The maximum is 250 and this number can be reduced with the pagesize param.
\ntotal_pages: The total number of 'pages' based on the query-based result from the database and the maximum number of records per page param (pagesize).
\npage: The page number of this page.
\nsims[coverage]: Geographical coverage where this SIM card can be used.
\nsims[device_name]: Custom identifier assigned to this SIM that facilitates easy identification.
\nsims[ip_address]: If a static IP is assigned to this SIM card, this value will show that IP. If no static IP is assigned, the API will return 'Dynamic'.
\nsims[sim_state]: Network state of this SIM card.
\nsims[tags]: Tags that are assigned to this SIM card. Tags are an easy way to categorize SIM cards into groups.
\nsims[last_update]: Timestamp in UTC when the last Call Detail Record (cdr) for this SIM card was received.
\nsims[usage_sms_mo]: Total number of sent SMS messages (Mobile Originated) by the device during the current calendar month.
\nsims[usage_sms_mt]: Total number of received (Mobile Terminated) sms messages by the device during the current calendar month.
\nsims[usage_data]: Total number of bytes sent to and from the device during the current calendar month. Please note that 1MB = 1024 kB = 1048576 bytes.
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"Can be either 'enabled' or 'disabled'.
\n","type":"text/plain"},"key":"sim_state","value":"enabled"},{"description":{"content":"Array of coverages to filter for. Please note that this is an OR filter. Possible options are: 'USA', 'Americas', 'Europe', 'Oceania', 'Global' and 'Global+'
\n","type":"text/plain"},"key":"coverage","value":"Global+"},{"disabled":true,"description":{"content":"Array of tags that are assigned to a SIM. Please note that this filter is an OR filter.
\n","type":"text/plain"},"key":"tags","value":"Test SIM"},{"disabled":true,"description":{"content":"String to search for in the database. Can be (parts of) device_name or ip_address.
\n","type":"text/plain"},"key":"search","value":"test device"},{"description":{"content":"Number of maximum number of SIM cards returned in the API response. If no value is specified max 250 will be returned.
\n","type":"text/plain"},"key":"pagesize","value":"20"},{"description":{"content":"Page number. If no page number is specified, page 1 is returned.
\n","type":"text/plain"},"key":"page","value":"2"}],"variable":[]}},"response":[{"id":"52314a7d-18e7-4f04-800d-b3a5a31c2023","name":"SIM cards","originalRequest":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"url":{"raw":"https://api.simbase.com/simcards?sim_state=enabled&coverage=Global+,Europe&tags=Test SIM&search=test&pagesize=10&page=2","protocol":"https","host":["api","simbase","com"],"path":["simcards"],"query":[{"key":"sim_state","value":"enabled","description":"Can be either 'enabled' or 'disabled'."},{"key":"coverage","value":"Global+,Europe","description":"Array of coverages to filter for. Please note that this is an OR filter. Possible options are: 'USA', 'Americas', 'Europe', 'Oceania', 'Global' and 'Global+'"},{"key":"tags","value":"Test SIM","description":"Array of tags that are assigned to a SIM. Please note that this filter is an OR filter."},{"key":"search","value":"test","description":"String to search for in the database. Can be (parts of) device_name or ip_address."},{"key":"pagesize","value":"10","description":"Number of maximum number of SIM cards returned in the API response. If no value is specified max 250 will be returned."},{"key":"page","value":"2","description":"Page number. If no page number is specified, page 1 is returned. If you specify a number higher than the total number of pages, the last page is returned."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"1293"}],"cookie":[],"responseTime":null,"body":"{\n \"total_records\": 4,\n \"records\": 4,\n \"total_pages\": 1,\n \"page\": 1,\n \"sims\": [\n {\n \"usage_sms_mo\": 3,\n \"usage_data\": 456768798,\n \"usage_voice\": 0,\n \"coverage\": \"Europe\",\n \"iccid\": \"8912300000000000001\",\n \"sim_state\": \"enabled\",\n \"usage_sms_mt\": 0,\n \"device_name\": \"test SIM 14\",\n \"tags\": [\n \"Test SIM\"\n ],\n \"ip_address\": \"10.0.0.14\",\n \"last_update\": \"2022-03-23 18:00:45\"\n },\n {\n \"usage_sms_mo\": 2,\n \"usage_data\": 74031104,\n \"usage_voice\": 0,\n \"coverage\": \"Europe\",\n \"iccid\": \"8912300000000000002\",\n \"sim_state\": \"enabled\",\n \"usage_sms_mt\": 2,\n \"device_name\": \"test SIM 22\",\n \"tags\": [\n \"Test SIM\"\n ],\n \"ip_address\": \"10.0.0.22\",\n \"last_update\": \"2022-04-07 10:40:25\"\n },\n {\n \"usage_sms_mo\": 1,\n \"usage_data\": 13423341,\n \"usage_voice\": 0,\n \"coverage\": \"Europe\",\n \"iccid\": \"8912300000000000003\",\n \"sim_state\": \"enabled\",\n \"usage_sms_mt\": 0,\n \"device_name\": \"test sim 23\",\n \"tags\": [\n \"Test SIM\"\n ],\n \"ip_address\": \"10.0.0.23\",\n \"last_update\": \"2022-03-22 12:55:21\"\n },\n {\n \"usage_sms_mo\": 0,\n \"usage_data\": 0,\n \"usage_voice\": 0,\n \"coverage\": \"Global+\",\n \"iccid\": \"8912300000000000004\",\n \"sim_state\": \"enabled\",\n \"usage_sms_mt\": 0,\n \"device_name\": \"test sim 2\",\n \"tags\": [\n \"Test SIM\"\n ],\n \"ip_address\": \"10.0.0.2\",\n \"last_update\": \"2021-07-22 14:23:56\"\n }\n ]\n}"}],"_postman_id":"ad908f94-7915-4931-b416-f97a806d1d54"},{"name":"Get SIM","id":"6bf05b2b-3e5c-42b7-a780-01a4fb746ce3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"url":"https://api.simbase.com/simcards/8912300000000000001","description":"Use this API to obtain a detailed overview of a specific SIM card in your account.
\napn: Access Point Name that is provisioned on this SIM card and that should be set in the device.
\ncarrier: Last mobile network carrier that registered this SIM card on its network.
\ncountry: Country where this SIM was lastly registered.
\ncountry_iso: 2 letters ISO code of the country where this SIM was lastly registered.
\ncoverage: Country where this SIM was last seen.
\ndevice_name: Custom identifier assigned to this SIM that facilitates easy identification.
\nhardware: Based on the IMEI, we have identified the brand and model of the manufacturer of the hardware that was last used by the customer.
\nimei: Last registered International Mobile Equipment Identity (IMEI) number that was registered by the network.
\nimei_lock: If the IMEI lock or theft protection is enabled on the SIM card, the SIM will automatically be disabled when a new IMEI number is detected by the network.
\nip_address: If a static IP is assigned to this SIM card, this value will show that IP. The API will return 'Dynamic' if no static IP is assigned.
\nlast_update: Timestamp in UTC when the last Call Detail Record (cdr) for this SIM card was received.
\nlat: Latitude of the cell tower to which this SIM card is connected.
\nlon: Longitude of the cell tower to which this SIM card is connected.
\nlocation_updates: Number of location updates generated by the SIM card during the current calendar month. A location update is generated when a SIM tries to connect to a network. High numbers of location_updates (>60) indicate something is wrong with the device as it indicates the device is continuously trying to connect.
\nmsisdn: If a Mobile Subscriber ISDN Number (phone number) is assigned to this SIM card, the value is shown hear. On default, no msisdn is assigned to our SIM cards.
\nplan_id: Identifier of the rate plan assigned to this SIM card. A rate plan is a commercial plan or bundle, that defines how usage of a SIM card is billed and if a SIM is allowed on a network.
\nradio: This radio network technology was last used by this SIM card.
\nsessions: Total number of data sessions in which
\nsim_state: Network state of this SIM card.
\ntags: Tags that are assigned to this SIM card. Tags are an easy way to categorize SIM cards into groups.
\nthrottle: It is possible to throttle the maximum bandwidth of a SIM card. You can throttle the bandwidth via API. Please note that we do not throttle any SIM card. All throttling settings are initiated by the customer.
\nusage_sms_mo: The device's total number of sent SMS messages (Mobile Originated) during the current calendar month.
\nusage_sms_mt: Total number of received (Mobile Terminated) SMS messages by the device during the current calendar month.
\nusage_data: Total number of bytes sent to and from the device during the current calendar month. Please note that 1MB = 1024 kB = 1048576 bytes.
\nzero_sessions: Number of data sessions during the current calendar month in which no data was sent. The number of zero sessions is a strong indicator of issues with your hardware. If sessions are opened and no data is sent possible reasons are:
\nUse this API to obtain a detailed overview of a specific SIM card usage and cost overview.
\nThe URL for this endpoint takes an ICCID and year-month input.
\nhttps://api.simbase.com/simcards/{ICCID}/usage/{YYYY-MM}
\ncost: Total costs for the SIM card in this calendar month in the currency of your account.
\ncost_data: Total charge for the used data in this calendar month in the currency of your account.
\ncost_month: Total line rental for this calendar month in the currency of your account.
\ncost_netw: Total costs for networking services (for example fixed IP) during this calendar month in the currency of your account.
\ncost_sms: Total costs for SMS services during this calendar month in the currency of your account.
\ncost_voice: Total costs for Voice services during this calendar month in the currency of your account.
\nlocation_updates: Number of location updates generated by the SIM card during the current calendar month. When a SIM tries to connect to a network a location update is generated. High numbers of location_updates (>60) indicate something is wrong with the device as it indicates the device is continuously trying to connect.
\nsession_count: Total number of non-zero sessions (data sessions in which data was sent) for this SIM during a calendar month.
\nzero_sessions: Number of data sessions during the current calendar month in which no data was sent. The number of zero sessions is a strong indicator of issues with your hardware. If sessions are opened and no data is sent possible reasons are:
\nusage_data: If a static IP is assigned to this SIM card, this value will show that IP. The API will return 'Dynamic' if no static IP is assigned.
\nusage_sms_mo: The device's total number of sent SMS messages (Mobile Originated) during the current calendar month.
\nusage_sms_mt: Total number of received (Mobile Terminated) SMS messages by the device during the current calendar month.
\nusage_data: Total number of bytes sent to and from the device during the current calendar month. Please note that 1MB = 1024 kB = 1048576 bytes.
\nusage_voice: Total number of seconds of consumed voice services.
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"Use this method to update a SIM card. You can assign tags, change the sim_state, plan_id, throttle the connection, or manage the imei_lock.
\nBody
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"Use this API to get an overview of the available rate plans that can be assigned to your SIM cards. The obtained plan IDs are required to change the rate plan of a SIM card.
\ncountries: Total number of available countries in this rate plan.
\ncurrency: The currency of this rate plan.
\nday: The daily rate per enabled SIM card.
\nmb: The rate that is charged per used MegaBytes.
\nname: The name of the rate plan.
\nsms: The rate that is charged per sent SMS message (SMS MO).
\nsms_to_device: The rate that is charged per received SMS message (SMS MT).
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"Use this endpoint to send SMS messages to your devices. All SMS messages will be sent from our own shortcode 55555.
\nsender: The MSISDN (phone number) of our server that sends the SMS to the SIM card.
\nmessage: The message that was sent to the device.
\ntime: timestamp (YYYY-MM-DD HH:MM:SS) in UTC of the moment the SMS was sent to the device.
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"Use this endpoint to obtain the last SMS messages sent to the device and SMS messages sent by the device to our servers.
\ni.e. sim -> 55555 and 55555 -> sim
\nPlease note that on default our SIM cards are only able to send SMS messages to our server. If you have more than 100 registered and enabled SIM cards, you can apply for outbound SMS by submitting a support request
\ncount: Total number of SMS messages returned in this response body.
\nmessages[message]: The message that was sent via SMS.
\nmessages[direction]: The direction of the sent SMS message is seen from the server's perspective. 'In' means sent to the server, and 'out' means sent from the server to the device.
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"This API can be used to retrieve the up-to-date balance of an account.
\nbalance: The up-to-date account balance
\ncurrency: The currency of the balance in the ISO 4217 format.
\nlast_update: Timestamp in UTC when the balance was last updated.
\nauto_topup: Boolean indicating whether auto top-up by credit card has been activated for this balance.
\ntopup_threshold: If the auto top-up functionality is activated for this balance, it is automatically topped up if the balance falls below this value.
\ntopup_amount: If the auto top-up functionality is activated for this balance, it is automatically topped up to this value.
\n","auth":{"type":"apikey","apikey":{"value":"YoUR ApI KeY 1234","key":"