Bulk SMS - API


Bulk SMS Check & Telephone Number Change API Functions.

One or more telephone, assigned to you for specified number of days, during which you can check sms more than one time and change telephone multiple number of times. Additionally you may be assigned a dedicated machine. Custom pricing, talk to our representative prior proceeding.

Pre-Requisites

Download API Clients

Documentation

All dates are in Eastern Standard Time (EST or EDT) ISO 8601 formatted, e.g 2021-09-19 23:59:28

Bulk SMS

Get all of assigned telephone numbers with their respective telephone_id to interact with couple of API Functions.

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/telephones

Parameter(s) Description
none

Output

Parameter(s) Description
success True or Flase
message null or error message
data
  • telephone_id: An integer ID assigned to your telephone. Even if you change telephone this ID will persist
  • telephone: The 10-digit telephone number assigned to you, at the moment
  • added_at: The date telephone_id (or telephone) is assigned to you
  • expired_at: The date telephone_id (or telephone) will be expired

Raw Output in Python 2.7

{
     'success' : True
     'message' : None,
     'data'    : [
                    {
                         'telephone_id' : '23354',
                         'telephone'    : '2123451356',
                         'added_at'     : '2018-02-11',
                         'expired_at'   : '2018-03-10'
                    }
                 ]
}

This API Call will create a SMS Check PENDING Request for the telephone ID you've provided.

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/request/23354

Parameter(s) Description
Telephone ID An integer ID that you've got from bulk_sms/telephones API Call

Output

Parameter(s) Description
success True or Flase
message null or error message
data
  • request_id: An integer ID assigned to your request for SMS Check.

Raw Output in Python 2.7

{
     'success' : True
     'message' : None,
     'data'    : [
                    {
                         'request_id'   : '15682'
                    }
                 ]
}

Errorneous Raw Output in Python 2.7

If you try to pass a Telephone ID which do not exist in data against your call to bulk_sms/telephones following error message will appear

{
     'success' : False,
     'message' : "Unable to find Telephone ID",
     'data'    : None
}

Once after creating bulk_sms/request, you will be momentarily (a fair delay among your each status call will be appreciated) api calling this method to get latest status of your SMS Check Request. Keep an eye over Status.

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/status/15682

Parameter(s) Description
Request ID The integer Request ID that you've recieved via bulk_sms/request API Call

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer ID assigned to particular request for SMS Check
  • agent_name: The name of Server, serving this particular request
  • telephone: The telephone number being checked for SMS
  • smses: None or one or more SMS could arrive at each request processing, if they are there, they will be separated via | (pipe)
  • status:
    • PENDING: Request for SMS Check is submitted
    • ACQUIRED: Request for SMS Check is acquired by Server
    • STARTED: SMS Check process has started
    • SUCCESS: The SMS Check process ended successfully
    • FAIL: The SMS Check was failed due to some internal server error
    • CANCELED: The SMS Check was canceled (only PENDING SMS Check Requests can be canceled)
    • REMOVED: The SMS Check request is removed
  • updated_at: Last processing timestamp during whole life cycle of a SMS Check process
  • queued_at: The timestamp when you submitted the request
  • acquired_at: The timestamp when one of server (agent_name) picked particular request
  • started_at: The timestamp when SMS Check process has started
  • ended_at: The timestamp when SMS Check process has ended
  • canceled_at: The timestamp when SMS Check process is canceled

Raw Output in Python 2.7

{
     'message' : None,
     'success' : True,
     'data'    : {
                    'request_id'   : '15682',
                    'agent_name'   : None,
                    'telephone'    : '2123451356',
                    'smses'        : 'Test SMS 1|Test SMS 2',
                    'status'       : 'PENDING',
                    'updated_at'   : '2018-04-25 20:14:16',
                    'queued_at'    : '2018-04-25 20:14:16',
                    'acquired_at'  : None,
                    'started_at'   : None,
                    'ended_at'     : None,
                    'canceled_at'  : None
                 }
}

Errorneous Raw Output in Python 2.7

If you try to pass a Request ID which do not exist in data against your call to bulk_sms/request following error message will appear

{
     'success' : False,
     'message' : "Unable to find request",
     'data'    : None
}

SMS Check Request can be canceled, if and only if, its status is PENDING

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/cancel/15682

Parameter(s) Description
Request ID The integer Request ID that you've recieved via bulk_sms/request API Call

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer ID assigned to particular request for SMS Check

Raw Output in Python 2.7

When particular request is successfully canceled, following will be returned

{
     'message' : None,
     'success' : True,
     'data'    : {
                    'request_id'   : '15682'
                 }
}

Errorneous Raw Output in Python 2.7

If you try to cancel an already canceled request, following error message will be displayed

{
     'success' : False,
     'message' : "Perhaps time to cancel request has elapsed",
     'data'    : None
}

Errorneous Raw Output in Python 2.7

If you try to cancel a non-existing request, following error message will be displayed

{
     'success' : False,
     'message' : "Unable to find request",
     'data'    : None
}

Get SMS received at telephone (if any)

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/smses_by_tid/23354

Parameter(s) Description
Telephone ID An integer ID that you've got from bulk_sms/telephones API Call

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer ID assigned to particular request for SMS Check
  • telephone_id: A persisting integer ID to relate telephone number
  • smses: If any, SMS is received during particular SMS Check request, they will be provided here
  • telephone: Telephone Number associated with particular Telephone ID at the time of SMS Check
  • updated_at: Time of most recent action taken on particular SMS Check Request

Raw Output in Python 2.7

If here is any SMS(es) received over particular telephone id, they will be returned as follows

{
     'success' : True,
     'message' : None,
     'data'    : [
                    {
                         'request_id'        : '11184',
                         'telephone_id'      : '23354',
                         'smses'             : 'Test SMS 1',
                         'telephone'         : '2123451356',
                         'updated_at'        : '2018-02-26 13:21:19'
                    },
                    {
                         'request_id'        : '11183',
                         'telephone_id'      : '23354',
                         'smses'             : 'Test SMS 4|Test SMS 5',
                         'telephone'         : '9171234567',
                         'updated_at'        : '2018-02-26 12:57:42'
                    }
                 ]
}
Note:
  • The Telephone IDs in both items at request_id 11184 & 11183, the telephone_id is same, that is, 23354, while their telephone numbers differ, this is because, Telephone ID persist, while you can pass API call nc/request to change Telephone Number assigned at particular Telephone ID
  • If there are more than one SMSes as a result of particular SMS Check, they will be appended by | pipe-character in single request, notice request_id 11183

Auto Check is a feature, that allow particular telephone to be kept checking for SMS multiple times, alternatively it can be used to disable this feature for a particular telephone ID as well. Enabling is useful when you do not want to keep calling bulk_sms/request multiple times to get SMS. This feature is by-default disable, however using this API Call you can enable it for particular Telephone ID

IMPORTANT:

a) Once after enabling auto-check, you should try to create atleast one SMS Check Request bulk_sms/request for same Telephone ID (for which you've enabled auto-check), if you dont do that, it wont auto-check

b) All Auto-Check will be disabled by 12am everyday. Next day you will need to enable auto-check again and atleast request one bulk_sms/request manually

Input http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/autocheck/23354/enable or http://smspins.com/apiv2/YOUR_API_KEY/bulk_sms/autocheck/23354/disable

Parameter(s) Description
Telephone ID An integer ID that you've got from bulk_sms/telephones API Call
Action enable or disable

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data None

Raw Output in Python 2.7

When particular autocheck for Telephone ID is successfully enabled or disabled, following JSON output will be returned.

{
     'success' : True,
     'message' : None,
     'data'    : None
}

Errorneous Raw Output in Python 2.7

The errorneous output can be as follows;

{
     'success' : False,
     'message' : 'Unable to find Telephone ID',
     'data'    : None
}

Number Change

IMPORTANT: Once a telephone number is changed, there is no way to get back the old telephone number

When you want to change telephone number associated with particular telephone id.

Input http://smspins.com/apiv2/YOUR_API_KEY/nc/request/23354/95129

23354 is Telephone ID, while 95129 is zip code for San Jose, CA.

Parameter(s) Description
Telephone ID An integer ID that you've got from bulk_sms/telephones API Call
Zip 5 Digit Zip Code. Number availability depends upon if zip code covers larger area. For zip codes that do not have much population, the number change request will be failed

Output

Parameter(s) Description
success True or Flase
message null or error message
data
  • request_id: An integer Number Change (NC) Request ID, that you will use to interact with the system for particular Number Change (NC) Request

Raw Output in Python 2.7

{
     'success' : True
     'message' : None,
     'data'    : [
                    {
                         'request_id'   : '11111'
                    }
                 ]
}

Get all Number Change (NC) requests made within last 48 hours

Input http://smspins.com/apiv2/YOUR_API_KEY/nc/requests

Parameter(s) Description
None

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer Number Change (NC) Request ID, that you will use to interact with the system for particular Number Change (NC) Request
  • last_telephone: The telephone associated with particular Telephone ID at the time of this request made
  • telephone: The new telephone, now associated with particular Telephone ID, if any, will be provided here
  • status:
    • PENDING: Number Change Request is made, its status will be PENDING
    • ACQUIRED: Number Change Request is acquired by server
    • STARTED: The Number Change Request in question has started
    • SUCCESS: Number Change Request is processed successfully and number is changed
    • FAILED: The Number Change Request is not successful, if its not internal server, check if you've Zip code that covers bigger area and have much population
    • CANCELED: The Number Change Request is canceled. It will be CANCELED, if and only if, the request has PENDING status
  • updated_at: The timestamp of last action performed on particular Number Change Request
  • submitted_at: The timestamp when the Number Change Request is created
  • canceled_at: The timestamp when the Number Change Request is canceled. Only PENDING Number Change Requests can be CANCELED

Raw Output in Python 2.7

{
     'success' : True
     'message' : None,
     'data'    : [
                    {
                         'request_id'        : '44444',
                         'last_telephone'    : '2121231234',
                         'telephone'         : '9171231234',
                         'updated_at'        : '2018-04-25 20:14:16',
                         'submitted_at'      : '2018-04-25 20:10:16',
                         'canceled_at'       : None
                    }
                 ]
}

Once after creating nc/request, you will be momentarily (a fair delay among your each status call will be appreciated) api calling this method to get latest status of your Number Change Request. Keep an eye over Status.

Input http://smspins.com/apiv2/YOUR_API_KEY/nc/status/15682

Parameter(s) Description
Request ID The integer Request ID that you've recieved via nc/request API Call

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer ID assigned to particular request for Number Change
  • agent_name: The name of Server, serving this particular request
  • telephone: The telephone number associated rightnow
  • status:
    • PENDING: Request for Number Change Request is submitted
    • ACQUIRED: Request for Number Change Request is acquired by Server
    • STARTED: Number Change Request process has started
    • SUCCESS: The Number Change Request process ended successfully
    • FAILED: The Number Change Request was failed due to some internal server error
    • CANCELED: The Number Change Request was canceled (only PENDING requests can be canceled)
  • updated_at: Last processing timestamp during whole life cycle of a Number Change process
  • submitted_at: The timestamp when you submitted the request
  • acquired_at: The timestamp when one of server (agent_name) picked particular request
  • processed_at: The timestamp when Number Change process has started
  • completed_at: The timestamp when request is completed
  • canceled_at: The timestamp when Number Change process is canceled

Raw Output in Python 2.7

{
     'message' : None,
     'success' : True,
     'data'    : {
                    'request_id'        : '15682',
                    'agent_name'        : None,
                    'telephone'         : '2123451356',
                    'last_telephone'    : 'Test SMS 1|Test SMS 2',
                    'status'            : 'PENDING',
                    'updated_at'        : '2018-04-25 20:14:16',
                    'submitted_at'      : '2018-04-25 20:14:16',
                    'acquired_at'       : None,
                    'processed_at'      : None,
                    'completed_at'      : None,
                    'canceled_at'       : None
                 }
}

Errorneous Raw Output in Python 2.7

If you try to pass a Request ID which do not exist in data against your call to nc/request following error message will appear

{
     'success' : False,
     'message' : "Unable to find request",
     'data'    : None
}

Number Change Request can be canceled, if and only if, its status is PENDING

Input http://smspins.com/apiv2/YOUR_API_KEY/nc/cancel/11111

Parameter(s) Description
Request ID The integer Request ID that you've recieved via nc/request API Call

Output

Parameter(s) Description
success Boolean True or Flase
message null or error message
data
  • request_id: An integer ID assigned to particular request for Number Change

Raw Output in Python 2.7

When particular request is successfully canceled, following will be returned

{
     'message' : None,
     'success' : True,
     'data'    : {
                    'request_id'   : '15682'
                 }
}

Errorneous Raw Output in Python 2.7

If you try to cancel an already canceled request, following error message will be displayed

{
     'success' : False,
     'message' : "Perhaps time to cancel request has elapsed",
     'data'    : None
}

Errorneous Raw Output in Python 2.7

If you try to cancel a non-existing request, following error message will be displayed

{
     'success' : False,
     'message' : "Unable to find request",
     'data'    : None
}