The Ads Brothers

Authentication

API Key Required

All API requests require an API key sent via the X-API-Key header.

X-API-Key: tab_your_api_key_here

Contact us to get your API key provisioned.

Endpoints

POST /api/v1/pin/send

Sends an SMS PIN/OTP to the given mobile number.

Request Body

Field	Required	Type	Description
msisdn	Yes	string	Customer mobile number (e.g. `964xxxxxxxx`)
pixel	Yes	string	Your pixel / click ID
cycle	Yes	string	Billing cycle — use `daily`

Example Request

curl -X POST https://api.theadsbrothers.com/api/v1/pin/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tab_your_api_key_here" \
  -d '{
    "msisdn": "964xxxxxxxx",
    "pixel": "ads-xxx",
    "cycle": "daily"
  }'

Responses

Success (200)

{
  "code": 200,
  "status": "OK",
  "data": "succes request otp"
}

Error (400)

{
  "code": 400,
  "status": "Bad Request",
  "data": "invalid msisdn"
}

POST /api/v1/pin/verify

Validates the PIN/OTP the user received via SMS. On success, the user is automatically subscribed.

Request Body

Field	Required	Type	Description
msisdn	Yes	string	Customer mobile number (e.g. `964xxxxxxxx`)
pin	Yes	string	The PIN/OTP the user received via SMS
pixel	Yes	string	Your pixel / click ID
cycle	Yes	string	Billing cycle — use `daily`

Example Request

curl -X POST https://api.theadsbrothers.com/api/v1/pin/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tab_your_api_key_here" \
  -d '{
    "msisdn": "964xxxxxxxx",
    "pin": "1234",
    "pixel": "ads-xxx",
    "cycle": "daily"
  }'

Responses

Success (200)

{
  "code": 200,
  "status": "OK",
  "data": "success verify otp"
}

Error (400)

{
  "code": 400,
  "status": "Bad Request",
  "data": "The pin is not valid."
}

Error Reference

Error Message	Description
`invalid operator`	The mobile number's operator is not supported
`invalid service`	The service/cycle is not valid
`invalid msisdn`	The mobile number format is incorrect
`msisdn already active`	The user is already subscribed
`msisdn already inactive`	The user is already unsubscribed
`msisdn not found`	The mobile number was not found
`The pin is not valid.`	The OTP entered is wrong
`The pin has expired.`	The OTP has expired, request a new one
`PIN request needed`	Must call PIN Send before PIN Verify
`MSISDN Blacklisted.`	The mobile number is blacklisted

HTTP Status Codes

200

Success

400

Bad request or upstream error

401

Missing or invalid API key

403

Publisher account disabled

502

Could not reach upstream advertiser

503

No active advertisers configured

Integration Flow

Publisher calls POST /api/v1/pin/send with the user's MSISDN — TAB API automatically routes to the best available advertiser.

User receives an SMS with a PIN/OTP on their device.

Publisher collects the PIN from the user.

Publisher calls POST /api/v1/pin/verify with the MSISDN + PIN to complete the subscription.