The Ads Brothers

Integration Flow (for Publishers)

Request OTP — Call POST /api/v1/pin/send with the user's MSISDN (and optionally their country for GEO routing). TAB API automatically routes to the best available advertiser for that GEO.
User receives SMS — The user receives an SMS with a PIN/OTP on their device.
Collect PIN — Your page or app collects the PIN from the user.
Complete subscription — Call POST /api/v1/pin/verify with the MSISDN and PIN. On success, the user is automatically subscribed.

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.

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`
`country`	No	string	Geo location — ISO 2-letter country code (e.g. IQ, AE, OM) for routing. Used to select advertisers that support this GEO. If your publisher account is restricted to certain GEOs, include the user's country; requests for a country your account is not allowed for return 403 with message `Publisher not authorized for country: {code}`.

Geo location (country): Optional. When provided, the API routes the lead to advertisers that support that GEO and enforces your account's allowed GEOs. Use ISO 3166-1 alpha-2 codes (e.g. IQ Iraq, AE UAE, OM Oman). If your account has allowed GEOs and you send a country not in that list, the API responds with 403 Forbidden. Omitting country is allowed.

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", "country": "IQ" }'

Responses

Success (200):

{ "code": 200, "status": "OK", "data": "success 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.

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

The data field in error responses may contain:

Error Message	Description
`Publisher not authorized for country: {code}`	The country sent is not in your publisher account's allowed GEOs (PIN Send).
`Publisher send rate limit exceeded`	Too many PIN Send requests; wait before retrying.
`Publisher verify rate limit exceeded`	Too many PIN Verify requests; wait before retrying.
`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

Code	Meaning
200	Success
400	Bad request or upstream error
401	Missing or invalid API key
403	Publisher account disabled or GEO not allowed for the given country
429	Rate limit exceeded (send or verify)
502	Could not reach advertiser
503	No active advertisers configured

Quick Start

# 1. Request OTP (add "country": "IQ" for GEO-aware routing if needed)
curl -X POST https://api.theadsbrothers.com/api/v1/pin/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"msisdn":"964xxxxxxxx","pixel":"your-pixel","cycle":"daily"}'

# 2. Verify OTP
curl -X POST https://api.theadsbrothers.com/api/v1/pin/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"msisdn":"964xxxxxxxx","pin":"1234","pixel":"your-pixel","cycle":"daily"}'

Health Check

curl https://api.theadsbrothers.com/health
# => { "status": "ok", "timestamp": "..." }