{
	"info": {
		"_postman_id": "bulksms-nigeria-api-v2",
		"name": "BulkSMS Nigeria API v2",
		"description": "Complete API collection for BulkSMS Nigeria service.\n\n## Authentication\nAll requests require Bearer token authentication. Get your API token from: https://www.bulksmsnigeria.com/user/api-tokens\n\n## Base URL\n`https://www.bulksmsnigeria.com/api`\n\n## Important Notes\n- All sender IDs must be registered at `/sender-ids` before use\n- Ensure sufficient wallet balance before sending SMS\n- Phone numbers can be in local (08012345678) or international (+2348012345678) format\n- Rate limits apply to prevent abuse\n\n## Error Codes\n- BSNG-1000 to 1099: Authentication errors\n- BSNG-2000 to 2099: Validation errors\n- BSNG-2011: Sender ID not registered\n- BSNG-3000 to 3099: Wallet/balance errors\n- BSNG-4000 to 4099: SMS processing errors\n\nAuthor: BulkSMS Nigeria\nVersion: 2.0\nLast Updated: November 27, 2025",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"auth": {
		"type": "bearer",
		"bearer": [
			{
				"key": "token",
				"value": "{{api_token}}",
				"type": "string"
			}
		]
	},
	"item": [
		{
			"name": "SMS",
			"description": "SMS sending and management endpoints",
			"item": [
				{
					"name": "Send Single SMS",
					"event": [
						{
							"listen": "test",
							"script": {
								"exec": [
									"// Test for successful response",
									"pm.test(\"Status code is 200\", function () {",
									"    pm.response.to.have.status(200);",
									"});",
									"",
									"pm.test(\"Response has success status\", function () {",
									"    var jsonData = pm.response.json();",
									"    pm.expect(jsonData.status).to.eql(\"success\");",
									"});",
									"",
									"pm.test(\"Response contains message ID\", function () {",
									"    var jsonData = pm.response.json();",
									"    pm.expect(jsonData.data).to.have.property('id');",
									"});",
									"",
									"pm.test(\"Response contains cost\", function () {",
									"    var jsonData = pm.response.json();",
									"    pm.expect(jsonData.data).to.have.property('cost');",
									"});",
									"",
									"// Save message ID for later use",
									"if (pm.response.code === 200) {",
									"    var jsonData = pm.response.json();",
									"    if (jsonData.data && jsonData.data.id) {",
									"        pm.environment.set(\"message_id\", jsonData.data.id);",
									"    }",
									"}"
								],
								"type": "text/javascript"
							}
						}
					],
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json",
								"type": "text"
							},
							{
								"key": "Accept",
								"value": "application/json",
								"type": "text"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"from\": \"{{sender_id}}\",\n    \"to\": \"2348012345678\",\n    \"body\": \"Hello! This is a test message from BulkSMS Nigeria API.\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{base_url}}/v2/sms",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"v2",
								"sms"
							]
						},
						"description": "Send a single SMS message to a recipient.\n\n**Required Fields:**\n- `from`: Your registered sender ID (must be registered at /sender-ids)\n- `to`: Recipient phone number (local or international format)\n- `body`: Message content (max 160 chars for single SMS)\n\n**Optional Fields:**\n- `gateway`: Specific gateway to use (mtn, airtel, glo, 9mobile)\n- `schedule_time`: Schedule message for future delivery (Y-m-d H:i:s format)\n\n**Response:**\n```json\n{\n    \"status\": \"success\",\n    \"message\": \"SMS sent successfully\",\n    \"data\": {\n        \"id\": \"MSG123456\",\n        \"cost\": 2.50,\n        \"units\": 1,\n        \"recipients\": 1\n    }\n}\n```"
					},
					"response": [
						{
							"name": "Success Response",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"from\": \"BulkSMS\",\n    \"to\": \"2348012345678\",\n    \"body\": \"Test message\"\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{base_url}}/v2/sms",
									"host": [
										"{{base_url}}"
									],
									"path": [
										"v2",
										"sms"
									]
								}
							},
							"status": "OK",
							"code": 200,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"cookie": [],
							"body": "{\n    \"status\": \"success\",\n    \"message\": \"SMS sent successfully\",\n    \"data\": {\n        \"id\": \"MSG123456789\",\n        \"cost\": 2.50,\n        \"units\": 1,\n        \"recipients\": 1,\n        \"sender_id\": \"BulkSMS\",\n        \"created_at\": \"2025-11-27 10:30:00\"\n    }\n}"
						},
						{
							"name": "Insufficient Balance",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"from\": \"BulkSMS\",\n    \"to\": \"2348012345678\",\n    \"body\": \"Test message\"\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{base_url}}/v2/sms",
									"host": [
										"{{base_url}}"
									],
									"path": [
										"v2",
										"sms"
									]
								}
							},
							"status": "Payment Required",
							"code": 402,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"cookie": [],
							"body": "{\n    \"status\": \"error\",\n    \"code\": \"BSNG-3000\",\n    \"message\": \"Insufficient wallet balance. Please fund your account.\",\n    \"data\": {\n        \"current_balance\": 10.50,\n        \"required_amount\": 25.00\n    }\n}"
						},
						{
							"name": "Sender ID Not Registered",
							"originalRequest": {
								"method": "POST",
								"header": [],
								"body": {
									"mode": "raw",
									"raw": "{\n    \"from\": \"UnregisteredID\",\n    \"to\": \"2348012345678\",\n    \"body\": \"Test message\"\n}",
									"options": {
										"raw": {
											"language": "json"
										}
									}
								},
								"url": {
									"raw": "{{base_url}}/v2/sms",
									"host": [
										"{{base_url}}"
									],
									"path": [
										"v2",
										"sms"
									]
								}
							},
							"status": "Forbidden",
							"code": 403,
							"_postman_previewlanguage": "json",
							"header": [
								{
									"key": "Content-Type",
									"value": "application/json"
								}
							],
							"cookie": [],
							"body": "{\n    \"status\": \"error\",\n    \"code\": \"BSNG-2011\",\n    \"message\": \"Sender ID not registered or not approved. Please register at /sender-ids\",\n    \"data\": {\n        \"sender_id\": \"UnregisteredID\",\n        \"registration_url\": \"https://www.bulksmsnigeria.com/sender-ids\"\n    }\n}"
						}
					]
				},
				{
					"name": "Send SMS with Gateway",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"from\": \"{{sender_id}}\",\n    \"to\": \"2348012345678\",\n    \"body\": \"Message sent via specific gateway\",\n    \"gateway\": \"mtn\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{base_url}}/v2/sms",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"v2",
								"sms"
							]
						},
						"description": "Send SMS using a specific network gateway.\n\n**Available Gateways:**\n- `mtn` - MTN Nigeria\n- `airtel` - Airtel Nigeria\n- `glo` - Glo Nigeria\n- `9mobile` - 9mobile Nigeria\n\nNote: Gateway routing may affect delivery speed and cost."
					},
					"response": []
				},
				{
					"name": "Send Scheduled SMS",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"from\": \"{{sender_id}}\",\n    \"to\": \"2348012345678\",\n    \"body\": \"This message will be sent at the scheduled time\",\n    \"schedule_time\": \"2025-11-27 15:00:00\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{base_url}}/v2/sms",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"v2",
								"sms"
							]
						},
						"description": "Schedule an SMS for future delivery.\n\n**schedule_time format:** `Y-m-d H:i:s` (e.g., \"2025-11-27 15:00:00\")\n\nNote: Scheduled time must be in the future."
					},
					"response": []
				},
				{
					"name": "Send Bulk SMS",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"from\": \"{{sender_id}}\",\n    \"to\": [\n        \"2348012345678\",\n        \"2348087654321\",\n        \"2347012345678\",\n        \"2349012345678\"\n    ],\n    \"body\": \"Bulk message to multiple recipients\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{base_url}}/v2/sms",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"v2",
								"sms"
							]
						},
						"description": "Send the same message to multiple recipients.\n\n**to field:** Can be:\n- Single number: `\"2348012345678\"`\n- Comma-separated: `\"2348012345678,2348087654321\"`\n- Array: `[\"2348012345678\", \"2348087654321\"]`\n\nCost is calculated per recipient."
					},
					"response": []
				}
			]
		},
		{
			"name": "Sender IDs",
			"description": "Manage sender ID registration and approval",
			"item": [
				{
					"name": "List Sender IDs",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/sender-ids",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"sender-ids"
							]
						},
						"description": "Get all sender IDs registered by the authenticated user.\n\n**Response includes:**\n- Sender ID name\n- Status (pending, approved, rejected)\n- Purpose/description\n- Approval/rejection timestamps\n- Admin notes"
					},
					"response": []
				},
				{
					"name": "Register Sender ID",
					"request": {
						"method": "POST",
						"header": [
							{
								"key": "Content-Type",
								"value": "application/json"
							},
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"body": {
							"mode": "raw",
							"raw": "{\n    \"sender_id\": \"MyBrand\",\n    \"purpose\": \"Marketing and promotional messages for my business\"\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{base_url}}/sender-ids",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"sender-ids"
							]
						},
						"description": "Register a new sender ID for approval.\n\n**Requirements:**\n- 3-11 alphanumeric characters\n- Maximum 5 sender IDs per account\n- Must provide purpose/description\n- Requires admin approval before use\n\n**Validation Rules:**\n- No special characters (except hyphens)\n- No spaces\n- Case-insensitive (stored as uppercase)"
					},
					"response": []
				},
				{
					"name": "Check Sender ID Status",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/sender-ids/:sender_id/status",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"sender-ids",
								":sender_id",
								"status"
							],
							"variable": [
								{
									"key": "sender_id",
									"value": "MyBrand",
									"description": "The sender ID to check"
								}
							]
						},
						"description": "Check the approval status of a specific sender ID."
					},
					"response": []
				}
			]
		},
		{
			"name": "Wallet & Balance",
			"description": "Check wallet balance and transaction history",
			"item": [
				{
					"name": "Get Wallet Balance",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/wallet/balance",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"wallet",
								"balance"
							]
						},
						"description": "Get current wallet balance for the authenticated user.\n\n**Response includes:**\n- Current balance\n- Currency\n- Last transaction date"
					},
					"response": []
				},
				{
					"name": "Get Transaction History",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/wallet/transactions?page=1&limit=20",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"wallet",
								"transactions"
							],
							"query": [
								{
									"key": "page",
									"value": "1",
									"description": "Page number"
								},
								{
									"key": "limit",
									"value": "20",
									"description": "Records per page (max 100)"
								},
								{
									"key": "type",
									"value": "debit",
									"description": "Filter by type (debit, credit)",
									"disabled": true
								},
								{
									"key": "start_date",
									"value": "2025-11-01",
									"description": "Filter from date (Y-m-d)",
									"disabled": true
								},
								{
									"key": "end_date",
									"value": "2025-11-27",
									"description": "Filter to date (Y-m-d)",
									"disabled": true
								}
							]
						},
						"description": "Get wallet transaction history with pagination and filters."
					},
					"response": []
				}
			]
		},
		{
			"name": "Delivery Reports",
			"description": "Check SMS delivery status and reports",
			"item": [
				{
					"name": "Get Message Delivery Report",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/delivery-reports/:message_id",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"delivery-reports",
								":message_id"
							],
							"variable": [
								{
									"key": "message_id",
									"value": "{{message_id}}",
									"description": "Message ID from send response"
								}
							]
						},
						"description": "Get detailed delivery report for a specific message.\n\n**Report includes:**\n- Delivery status (pending, sent, delivered, failed)\n- Recipient details\n- Timestamp\n- Failure reason (if applicable)\n- Cost breakdown"
					},
					"response": []
				},
				{
					"name": "List All Delivery Reports",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/delivery-reports?page=1&status=all",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"delivery-reports"
							],
							"query": [
								{
									"key": "page",
									"value": "1"
								},
								{
									"key": "status",
									"value": "all",
									"description": "Filter by status: all, pending, sent, delivered, failed"
								},
								{
									"key": "start_date",
									"value": "2025-11-01",
									"description": "Filter from date",
									"disabled": true
								},
								{
									"key": "end_date",
									"value": "2025-11-27",
									"description": "Filter to date",
									"disabled": true
								}
							]
						},
						"description": "Get paginated list of all delivery reports for the authenticated user."
					},
					"response": []
				}
			]
		},
		{
			"name": "Account",
			"description": "User account and profile management",
			"item": [
				{
					"name": "Get Account Info",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/account",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"account"
							]
						},
						"description": "Get authenticated user's account information.\n\n**Response includes:**\n- User details\n- Account status\n- Verification level\n- Account limits\n- Created date"
					},
					"response": []
				},
				{
					"name": "Get API Usage Statistics",
					"request": {
						"method": "GET",
						"header": [
							{
								"key": "Accept",
								"value": "application/json"
							}
						],
						"url": {
							"raw": "{{base_url}}/account/usage?period=month",
							"host": [
								"{{base_url}}"
							],
							"path": [
								"account",
								"usage"
							],
							"query": [
								{
									"key": "period",
									"value": "month",
									"description": "Period: today, week, month, year"
								}
							]
						},
						"description": "Get API usage statistics for the specified period.\n\n**Statistics include:**\n- Total messages sent\n- Total cost\n- Success rate\n- Failed messages\n- Top recipients"
					},
					"response": []
				}
			]
		}
	],
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					"// Pre-request script for all requests",
					"",
					"// Check if API token is set",
					"if (!pm.environment.get('api_token')) {",
					"    console.warn('⚠️ API token not set! Set api_token in environment variables.');",
					"}",
					"",
					"// Check if sender_id is set for SMS requests",
					"if (pm.request.url.path.includes('sms') && pm.request.method === 'POST') {",
					"    if (!pm.environment.get('sender_id')) {",
					"        console.warn('⚠️ Sender ID not set! Set sender_id in environment variables.');",
					"    }",
					"}",
					"",
					"// Log request details",
					"console.log('🚀 Request:', pm.request.method, pm.request.url.toString());"
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					"// Global test script for all requests",
					"",
					"// Check response time",
					"pm.test('Response time is less than 10s', function () {",
					"    pm.expect(pm.response.responseTime).to.be.below(10000);",
					"});",
					"",
					"// Check for valid JSON response",
					"pm.test('Response is valid JSON', function () {",
					"    pm.response.to.be.json;",
					"});",
					"",
					"// Log response status",
					"console.log('📥 Response:', pm.response.code, pm.response.status);"
				]
			}
		}
	],
	"variable": [
		{
			"key": "base_url",
			"value": "https://www.bulksmsnigeria.com/api",
			"type": "string"
		},
		{
			"key": "api_token",
			"value": "your-api-token-here",
			"type": "string"
		},
		{
			"key": "sender_id",
			"value": "BulkSMS",
			"type": "string"
		},
		{
			"key": "message_id",
			"value": "",
			"type": "string"
		}
	]
}