logo
Documentation Powered by ReDoc

BDApps API Documentation (1.0)

Download OpenAPI specification:Download

sms/send

This service allows the user to send SMS to one or more terminals (phones or any SMS-enabled device) from their application.

SMS send service supports only POST HTTP requests. This is used when sending SMS to a mobile phone from an application.

An application wishing to initiate an MT SMS message should use this operation type.

SMS Mobile Termination

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
message
required
string

Content of the message that needs to be sent.

Messages over the limit shall be broken up by the platform before sending
destinationAddresses
required
Array of strings

List of destination addresses should be telephone numbers.(tel - for MSISDN).

tel:8801812345678.

Address can also have the value - tel: all

which will in return be a message to the subscribed base of the application

at least one should be specified

Note : tel might be a masked number depending on the type of application
sourceAddress
string

Address of the source.

sourceAddress: tel:8801812345678

at least one will be specified
deliveryStatusRequest
string
Enum: 0 1

Indicates the need of a Delivery Status Report for the message.

0 - Delivery Report not required

1 - Delivery Report Required
encoding
string
Enum: 0 240 245

Encoding scheme used in the message

If not specified taken as Text

If the encoding type is “Binary” then the message content will be represented as hex encoded.

0 - Text

240 - Flash SMS

245 - Binary SMS
binaryHeader
string <hexadecimal>

For advanced type of messages where the binary header shall be sent from the application

Responses

200

success
post /sms/send
https://developer.bdapps.com/sms/send

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "applicationId": "APP_999999",
  • "password": "password",
  • "message": "Hello",
  • "destinationAddresses":
    [
    ],
  • "sourceAddress": "77000",
  • "deliveryStatusRequest": "1",
  • "encoding": "245",
  • "binaryHeader": "526574697265206170706c69636174696f6e20616e642072656c6561736520524b7320696620666f756e642065787069726564"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "requestId": "101901031657410007",
  • "destinationResponses":
    [
    ],
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

sms/receive

This service retrieves the SMS sent to the web application. Receive service returns only a list of SMS messages received since the previous invocation of the method.

SMS Mobile Origination

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
sourceAddress
required
string

Address of the source.

sourceAddress: tel:8801812345678

at least one will be specified
message
required
string

Content of the message sent by the user
requestId
required
string

Uniquely identifies a request within TAP
encoding
required
string
Enum: 0 240 245

Encoding scheme used in the message.

If the encoding type is “Binary” then the message content will be represented as hex encoded.

0 - Text

240 - Flash SMS

245 - Binary SMS

Responses

200

success
post /sms/receive
https://developer.bdapps.com/sms/receive

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "applicationId": "APP_000029",
  • "sourceAddress": "tel:8801812345678",
  • "message": "string",
  • "requestId": "APP_000001",
  • "encoding": "0"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

sms/report

When performing a SendSms Operation if an application has requested for a Delivery Response message from the Message Centre, then TAP will initiate the Delivery Report service to hand over the Delivery Response message to the application. The messageId should be used to match the MT response with the Delivery Report.

Delivery Status Report Service

Request Body schema: application/json;charset=utf-8
destinationAddress
required
string

Address of the subscriber
timeStamp
required
string

The timestamp sent from the SMS

"yyMMddHHmm"

yy – last two digits of the year (00-99)

MM – month (01-12)

dd – day (01-31)

HH – hour (00-23)

mm- minute (00-59)
requestId
required
string

Uniquely identifies a request within TAP
deliveryStatus
required
string
Enum: "DELIVERED" "EXPIRED" "DELETED" "UNDELIVERABLE" "ACCEPTED" "UNKNOWN" "REJECTED"

Enum from TAP to Application:

DELIVERED ,EXPIRED ,DELETED ,UNDELIVERABLE ,ACCEPTED ,UNKNOWN ,REJECTED

Responses

200

success
post /sms/report
https://developer.bdapps.com/sms/report

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "destinationAddress": "tel:8801812345678",
  • "timeStamp": "20120113082110",
  • "requestId": "MSG_000111",
  • "deliveryStatus": "DELIVERED"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

ussd/send

This service is used when sending USSD messages to a mobile phone from an application.USSD send service supports only POST HTTP requests.

Ussd Send Services

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
message
required
string

Content of the message sent by the application
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
sessionId
required
string

Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.

ussdOperation
required
string
Enum: "mo-init" "mo-cont" "mt-init" "mt-cont" "mt-fin"

USSD operation

mo-cont:TAP to assign for and USSD message originated from subscriber, that comes after a init

nmt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message

Data type will be string where the operation name itself will be used in the parameter value.
destinationAddress
required
string

Destination address should be a telephone number (tel - for MSISDN)

Note : tel might be a masked number depending on the type of application

encoding
string
Value: 440

Encoding scheme used in the message

440 - Plain ASCII characters

Responses

200

success
post /ussd/send
https://developer.bdapps.com/ussd/send

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "applicationId": "APP_000001",
  • "message": "1. Press One\n 2. Press two\n 3. Press three\n 4. Exit\n",
  • "password": "password",
  • "sessionId": "1330929317043",
  • "ussdOperation": "mt-cont",
  • "destinationAddress": "tel: 8801812345678 ",
  • "encoding": "440"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "requestId": "101901031657410007",
  • "timeStamp": "20190103165801",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

ussd/receive

This service allows TAP to deliver MO messages to the application using HTTP – based API. The flow of messages is initiated by a MO request sent to an application,TAP will deliver the message to the application as an acknowledgement. Hence it could be either request-response exchange or a request-exception exchange.

Receive USSD request is a MO message which will be sent to the application through bdapps as a delivery request.

Ussd Receive Services

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
message
required
string

Content of the message sent by the user

requestId
required
string

Uniquely identifies a request within TAP
sessionId
required
string

Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.

ussdOperation
required
string
Enum: "mo-init" "mo-cont" "mt-init" "mt-cont" "mt-fin"

USSD operation

mo-cont:TAP to assign for and USSD message originated from subscriber, that comes after a init

mt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message
sourceAddress
required
string

Address of the source.

sourceAddress: tel:8801812345678

at least one will be specified
vlrAddress
string

VLR(Visitor Location Register) address of the sender
encoding
required
string
Value: 440

Encoding scheme used in the message

440 - Plain ASCII characters

Responses

200

success
post /ussd/receive
https://developer.bdapps.com/ussd/receive

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "applicationId": "APP_000029",
  • "message": "*141#",
  • "requestId": "1330933229901",
  • "sessionId": "1330929317043",
  • "ussdOperation": "mt-cont",
  • "sourceAddress": "tel:8801812345678",
  • "vlrAddress": "tel:8801812345678",
  • "encoding": "440"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "statusCode": "S1000",
  • "statusDetail": "Success"
}

caas/queryBalance

This service retrieves the account balance and related information of a given subscriber MSISDN. Account information comprises of Account type (Pre paid or Post paid) and Account’s status (Activate or Disable).

Query Balance

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
subscriberId
required
string

This can be the MSISDN or the username of the subscriber whose account balance is being queried.

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.
paymentInstrumentName
required
string
Value: "MobileAccount"

The name of the payment instrument.

Only a single value can be sent per request.
accountId
string

The account of the payment instrument.

Only a single value can be sent per request.
currency
string

Currency unit of the amount.

Only a single value can be sent per request.

Only ‘BDT’ is allowed.

Responses

200

success
post /caas/get/balance
https://developer.bdapps.com/caas/get/balance

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "8801812345678",
  • "paymentInstrumentName": "MobileAccount",
  • "accountId": "12345",
  • "currency": "BDT"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "accountType": "Pre Paid",
  • "accountStatus": "Active",
  • "statusCode": "S1000",
  • "statusDetail": "Success.",
  • "chargeableBalance": "300.0"
}

caas/directDebit

This service charges a specific amount from a subscriber’s account.

Direct Debit

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated by the system when provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
externalTrxId
required
string

This is the transaction ID generated by the application to map the request with the response.

This is needed to avoid any conflicts when SP inquires about a transaction.

Only a single value can be sent per request.
subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel: is for MSISDN

Subcriber: tel: 8801812345678

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.
paymentInstrumentName
required
string
Value: "MobileAccount"

The name of the payment instrument.

Only a single value can be sent per request.
accountId
string

The account of the payment instrument.

Only a single value can be sent per request.
amount
required
string

Amount to be reserved for charging.

Only a single value can be sent per request.
currency
string

Currency unit of the amount.

Only a single value can be sent per request.

Only ‘BDT’ is allowed.

Responses

200

success
post /caas/direct/debit
https://developer.bdapps.com/caas/direct/debit

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "externalTrxId": "12345678901234567890123456789012",
  • "subscriberId": " 8801812345678",
  • "paymentInstrumentName": "MobileAccount",
  • "accountId": "12345",
  • "amount": "12345",
  • "currency": "BDT"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "externalTrxId": "12345678901234567890123456789012",
  • "internalTrxId": "321",
  • "referenceId": "12345678",
  • "timeStamp": "2012-07-30T12:48:10-0400",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

subscription/userSubscription

This service handles user subscription process(subscription/unsubscription)

User Subscription

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel: is for MSISDN

Subcriber: tel:8801812345678

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.
action
required
string
Enum: 0 1

0 -user unsubscription

1 -user subscription

Responses

200

success
post /subscription/send
https://developer.bdapps.com/subscription/send

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:8801812345678",
  • "action": "0"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "not registered",
  • "subscriptionStatus": "UNREGISTERED."
}

subscription/baseSize

This service returns the number of registered subscribers

Base Size

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

Responses

200

success
post /subscription/query-base
https://developer.bdapps.com/subscription/query-base

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_000201",
  • "password": "39a8d1cb245029d0560619a2b388669c"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "baseSize": "0",
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

subscription/subscriberStatus

This service returns the user subscription status(unregistered,registered)

Subscriber Status

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel: is for MSISDN

Subcriber: tel:8801812345678

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.

Responses

200

success
post /subscription/getStatus
https://developer.bdapps.com/subscription/getStatus

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:8801812345678"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "Request was successfully processed",
  • "subscriptionStatus": "UNREGISTERED."
}

subscription/notify

This service sends notifications to the users

Subscriber Notifications

Request Body schema: application/json;charset=utf-8
timeStamp
required
string

The timestamp sent from the SMS. "yyMMddHHmm" yy – last two digits of the year (00-99) MM – month (01-12) dd – day (01-31) HH – hour (00-23) mm- minute (00-59)
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.
password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.
subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel: is for MSISDN

Subcriber: tel:88018123456785

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.
frequency
required
string
Enum: "daily" "weekly" "monthly" "yearly"

Frequency of notifications being sent
status
required
string

Status of the subscription eg:UNREGISTERED,REGISTERED

Responses

200

success
post /subscription/notify
https://developer.bdapps.com/subscription/notify

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "timeStamp": "20120113082110",
  • "version": "1.0",
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:8801812345678",
  • "frequency": "monthly",
  • "status": "REGISTERED."
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "statusCode": "S1000",
  • "statusDetail": "Request was successfully processed"
}

otp/request

This service is used by the developer to request an OTP for a subscriber's MSISDN. Upon the request, bdapps will generate and send an OTP to the subscriber's MSISDN. This OTP must be entered by the subscriber into the mobile/web application to activate a subscription.

Request OTP

Request Body schema: application/json;charset=utf-8
applicationId
required
string

ID of the application
password
required
string

Password/API key given to uniquely identify the application
subscriberId
required
string

Mobile number of the end consumer
applicationHash
string

Hash string to determine which verification messages to send to your app.
applicationMetaData
object

Responses

200

success
post /otp/request
https://developer.bdapps.com/otp/request

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_000375",
  • "password": "a07118cda5215fc6d01db5b2ab848edd",
  • "subscriberId": "tel:8801812345678",
  • "applicationHash": "abcdefgh",
  • "applicationMetaData":
    {}
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "statusCode": "S1000",
  • "referenceNo": "213561321321613",
  • "statusDetail": "Success"
}

otp/verify

This service is used by the developer to verify an OTP entered by a subscriber into the application. Upon a successful verification the subscription process of bdapps will be activated.

Verify OTP

Request Body schema: application/json;charset=utf-8
applicationId
required
string

ID of the application
password
required
string

Password/API key given to uniquely identify the application
referenceNo
required
string

Reference number returned with request OTP API
otp
required
string

One time password (OTP) to be used to MSISDN verification for the application

Responses

200

success
post /otp/verify
https://developer.bdapps.com/otp/verify

Request samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "applicationId": "APP_000375",
  • "password": "a07118cda5215fc6d01db5b2ab848edd",
  • "referenceNo": "213561321321613",
  • "otp": "123564"
}

Response samples

Content type
application/json;charset=utf-8
Copy
 Expand all Collapse all
{
  • "version": "1.0",
  • "statusCode": "S1000",
  • "subscriptionStatus": "REGISTERED",
  • "statusDetail": "Success",
  • "subscriberId": "tel:sdfasdfasdfwqerqwtgfgsafgasfgasdfasdfasdfasdfasdfasf"
}