{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/unknown-headline-volunteer-brochure.trycloudflare.com" } ], "info": { "name": "SocialHive Promo API Documentation", "_postman_id": "bb2e0098-1594-4679-acc4-abee4894adee", "description": "API for managing promotions, receipts, entries, members, products, locations, and more.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Promotion Participants", "description": "", "item": [ { "name": "List promotion participants", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/participants", "query": [ { "key": "filter%5Bname%5D", "value": "Alice", "description": "Filter participants by name.", "disabled": false }, { "key": "filter%5Bphone%5D", "value": "18765554444", "description": "Filter participants by phone number.", "disabled": false }, { "key": "filter%5Bid%5D", "value": "42", "description": "Filter participants by internal member ID.", "disabled": false }, { "key": "filter%5Bemail%5D", "value": "alice%40example.com", "description": "Filter participants by email address.", "disabled": false }, { "key": "sort", "value": "-joined_at", "description": "Sort by name or joined_at. Use -joined_at for descending order.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/participants?filter%5Bname%5D=Alice&filter%5Bphone%5D=18765554444&filter%5Bid%5D=42&filter%5Bemail%5D=alice%40example.com&sort=-joined_at&page=1", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a paginated list of participants for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 45,\n \"phone\": \"18765580001\",\n \"name\": \"E2E Voter\",\n \"email\": \"eve@example.com\",\n \"country\": \"JM\",\n \"status\": \"active\",\n \"pivot\": {\n \"joined_at\": \"2026-05-01T10:15:30.000000Z\",\n \"vote_status\": \"complete\",\n \"vote_rounds_completed\": 1,\n \"voted_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n }\n ],\n \"links\": {\n \"first\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/participants?page=1\",\n \"last\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/participants?page=1\",\n \"prev\": null,\n \"next\": null\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 1,\n \"path\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/participants\",\n \"per_page\": 15,\n \"to\": 1,\n \"total\": 1\n }\n}", "name": "" } ] }, { "name": "Create or attach a participant", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/participants", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/participants", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"member_id\":\"18765552222\",\"name\":\"API Participant\",\"email\":\"api@test.com\",\"dob\":\"1990-06-15\",\"country\":\"JM\",\"location\":\"Kingston\",\"opt_in\":true,\"metadata\":{\"source\":\"manual-entry\"},\"responses\":{\"district\":\"Kingston\",\"community\":\"Harbour View\"}}" }, "description": "Create a member if needed, attach them to the promotion, and optionally record voting responses." }, "response": [ { "header": [], "code": 201, "body": "{\n \"status\": \"success\",\n \"message\": \"Participant added to promotion successfully.\",\n \"data\": {\n \"id\": 45,\n \"phone\": \"18765552222\",\n \"name\": \"API Participant\",\n \"email\": \"api@test.com\",\n \"country\": \"JM\",\n \"status\": \"active\"\n }\n}", "name": "" } ] } ] }, { "name": "Promotion Entries", "description": "", "item": [ { "name": "List promotion entries", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/entries", "query": [ { "key": "filter%5Bmember_id%5D", "value": "42", "description": "Filter entries by member ID.", "disabled": false }, { "key": "filter%5Bstatus%5D", "value": "valid", "description": "Filter entries by entry status.", "disabled": false }, { "key": "filter%5Bsource_type%5D", "value": "App%5CModels%5CReceipt", "description": "Filter entries by source type.", "disabled": false }, { "key": "sort", "value": "-created_at", "description": "Sort by created_at. Use -created_at for descending order.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/entries?filter%5Bmember_id%5D=42&filter%5Bstatus%5D=valid&filter%5Bsource_type%5D=App%5CModels%5CReceipt&sort=-created_at&page=1", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "summer-cashback", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a paginated list of entries for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 123,\n \"member\": {\n \"id\": 45,\n \"phone\": \"18765580001\",\n \"name\": \"E2E Voter\",\n \"email\": \"eve@example.com\",\n \"country\": \"JM\",\n \"status\": \"active\"\n },\n \"status\": \"valid\",\n \"source_type\": \"App\\\\Models\\\\Receipt\",\n \"source_id\": 987,\n \"created_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n ],\n \"links\": {\n \"first\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/summer-cashback\/entries?page=1\",\n \"last\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/summer-cashback\/entries?page=1\",\n \"prev\": null,\n \"next\": null\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 1,\n \"path\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/summer-cashback\/entries\",\n \"per_page\": 15,\n \"to\": 1,\n \"total\": 1\n }\n}", "name": "" } ] }, { "name": "Show a promotion entry", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/entries\/:entry_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/entries\/:entry_id", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "summer-cashback", "description": "The promotion slug." }, { "id": "entry_id", "key": "entry_id", "value": "3", "description": "The ID of the entry." }, { "id": "entry", "key": "entry", "value": "123", "description": "The entry ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a single entry that belongs to the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 123,\n \"member\": {\n \"id\": 45,\n \"phone\": \"18765580001\",\n \"name\": \"E2E Voter\",\n \"email\": \"eve@example.com\",\n \"country\": \"JM\",\n \"status\": \"active\"\n },\n \"status\": \"valid\",\n \"source_type\": \"App\\\\Models\\\\Receipt\",\n \"source_id\": 987,\n \"created_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"message\": \"Not Found\"\n}", "name": "" } ] } ] }, { "name": "Promotion Codes", "description": "", "item": [ { "name": "List promotion codes", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/codes", "query": [ { "key": "page", "value": "1", "description": "The page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/codes?page=1", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "win-big-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a paginated list of codes for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"current_page\": 1,\n \"data\": [\n {\n \"id\": 12,\n \"promotion_id\": 5,\n \"code\": \"WINCODE123\",\n \"used_at\": null,\n \"used_by\": null,\n \"expired_at\": null,\n \"active\": true,\n \"metadata\": null,\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n ],\n \"first_page_url\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/win-big-2026\/codes?page=1\",\n \"from\": 1,\n \"last_page\": 1,\n \"last_page_url\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/win-big-2026\/codes?page=1\",\n \"links\": [\n {\n \"url\": null,\n \"label\": \"« Previous\",\n \"active\": false\n },\n {\n \"url\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/win-big-2026\/codes?page=1\",\n \"label\": \"1\",\n \"active\": true\n },\n {\n \"url\": null,\n \"label\": \"Next »\",\n \"active\": false\n }\n ],\n \"next_page_url\": null,\n \"path\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/win-big-2026\/codes\",\n \"per_page\": 50,\n \"prev_page_url\": null,\n \"to\": 1,\n \"total\": 1\n}", "name": "" } ] }, { "name": "Check a promotion code", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/codes\/check", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/codes\/check", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "win-big-2026", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"code\":\"VALIDCODE\"}" }, "description": "Validate a code for the given promotion without redeeming it." }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"Code is valid and available.\",\n \"status\": \"available\"\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"message\": \"Invalid code for this promotion.\",\n \"status\": \"invalid\"\n}", "name": "" } ] }, { "name": "Redeem a promotion code", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/codes\/redeem", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/codes\/redeem", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "win-big-2026", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"code\":\"REDEEMME\",\"phone\":\"18765551234\",\"member_id\":\"18765551234\"}" }, "description": "Validate and redeem a code for a member in the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"Code redeemed successfully.\",\n \"data\": {\n \"code\": \"REDEEMME\",\n \"prize\": \"Free Drink\"\n }\n}", "name": "" }, { "header": [], "code": 409, "body": "{\n \"message\": \"This code has already been used.\"\n}", "name": "" } ] } ] }, { "name": "Promotion Votes", "description": "", "item": [ { "name": "List votes", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/votes", "query": [ { "key": "filter%5Bquestion_key%5D", "value": "community", "description": "Filter votes by question key.", "disabled": false }, { "key": "filter%5Banswer%5D", "value": "Harbour+View", "description": "Filter votes by a partial answer match.", "disabled": false }, { "key": "filter%5Bmember_id%5D", "value": "45", "description": "Filter votes by member ID.", "disabled": false }, { "key": "filter%5Bvote_round%5D", "value": "1", "description": "Filter votes by vote round.", "disabled": false }, { "key": "filter%5Bdistrict%5D", "value": "Belize", "description": "Filter votes by another configured question answer.", "disabled": false }, { "key": "include", "value": "member", "description": "Include related resources. Supported value: member.", "disabled": false }, { "key": "sort", "value": "-created_at", "description": "Sort by created_at, question_key, answer, or vote_round.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/votes?filter%5Bquestion_key%5D=community&filter%5Banswer%5D=Harbour+View&filter%5Bmember_id%5D=45&filter%5Bvote_round%5D=1&filter%5Bdistrict%5D=Belize&include=member&sort=-created_at&page=1", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a paginated, filterable list of individual votes for a voting promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 91,\n \"member_id\": 45,\n \"member\": {\n \"id\": 45,\n \"phone\": \"18765580001\",\n \"name\": \"E2E Voter\",\n \"email\": \"eve@example.com\",\n \"country\": \"JM\",\n \"status\": \"active\"\n },\n \"question_key\": \"community\",\n \"answer\": \"Harbour View\",\n \"vote_round\": 1,\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n ],\n \"links\": {\n \"first\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/votes?page=1\",\n \"last\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/votes?page=1\",\n \"prev\": null,\n \"next\": null\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 1,\n \"path\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/community-vote-2026\/votes\",\n \"per_page\": 15,\n \"to\": 1,\n \"total\": 1,\n \"question_labels\": {\n \"district\": \"District?\",\n \"community\": \"Community?\"\n }\n }\n}", "name": "" } ] }, { "name": "Show the leaderboard", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/votes\/leaderboard", "query": [ { "key": "filter%5Bdistrict%5D", "value": "Belize", "description": "Filter the leaderboard by another configured question answer.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/votes\/leaderboard?filter%5Bdistrict%5D=Belize", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return ranked tallies for the promotion's configured tally field." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": {\n \"question_key\": \"community\",\n \"question_label\": \"Community?\",\n \"total_entries\": 3,\n \"leaderboard\": [\n {\n \"rank\": 1,\n \"name\": \"Harbour View\",\n \"votes\": 2\n },\n {\n \"rank\": 2,\n \"name\": \"Bull Bay\",\n \"votes\": 1\n }\n ]\n }\n}", "name": "" } ] }, { "name": "Show voting statistics", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/votes\/stats", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/votes\/stats", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return summary counts for participants and responses in a voting promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": {\n \"total_participants\": 2,\n \"completed_votes\": 1,\n \"partial_votes\": 1,\n \"total_responses\": 3,\n \"questions_configured\": 2,\n \"per_question\": [\n {\n \"question_key\": \"district\",\n \"question_label\": \"District?\",\n \"respondents\": 2\n },\n {\n \"question_key\": \"community\",\n \"question_label\": \"Community?\",\n \"respondents\": 1\n }\n ]\n }\n}", "name": "" } ] }, { "name": "Get question options", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/votes\/options\/:question_key", "query": [ { "key": "filter%5Bdistrict%5D", "value": "Belize", "description": "Provide explicit context using another question answer.", "disabled": false }, { "key": "filter%5Bmember_id%5D", "value": "18765559001", "description": "Resolve context from a member ID or phone number.", "disabled": false }, { "key": "filter%5Bmember_phone%5D", "value": "18765559002", "description": "Resolve context from a member phone number.", "disabled": false }, { "key": "api_key", "value": "1%7Cabcdefghijklmnopqrstuvwx", "description": "Alternative API token for bot callers.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/votes\/options\/:question_key?filter%5Bdistrict%5D=Belize&filter%5Bmember_id%5D=18765559001&filter%5Bmember_phone%5D=18765559002&api_key=1%7Cabcdefghijklmnopqrstuvwx", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "community-vote-2026", "description": "The promotion slug." }, { "id": "question_key", "key": "question_key", "value": "community", "description": "The question key to resolve options for." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return the available options for a question, optionally resolved from context or member history." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": {\n \"question_key\": \"community\",\n \"question_label\": \"Community?\",\n \"allow_other\": true,\n \"options\": [\n \"Belize City\",\n \"Burrell Boom\",\n \"Ladyville\"\n ],\n \"total\": 4,\n \"options_whatsapp\": \"1. Belize City\\n2. Burrell Boom\\n3. Ladyville\\n4. Other\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"status\": \"error\",\n \"message\": \"Question 'community' not found in config.\",\n \"errors\": null\n}", "name": "" } ] } ] }, { "name": "Promotion Promoters", "description": "", "item": [ { "name": "List promoters", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/promoters", "query": [ { "key": "filter%5Bname%5D", "value": "Jane", "description": "Filter promoters by name.", "disabled": false }, { "key": "filter%5Bphone%5D", "value": "18761234567", "description": "Filter promoters by phone number.", "disabled": false }, { "key": "filter%5Bidentifier%5D", "value": "PROMO001", "description": "Filter promoters by external identifier.", "disabled": false }, { "key": "filter%5Bstatus%5D", "value": "active", "description": "Filter promoters by status.", "disabled": false }, { "key": "sort", "value": "-created_at", "description": "Sort by name, created_at, or status.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/promoters?filter%5Bname%5D=Jane&filter%5Bphone%5D=18761234567&filter%5Bidentifier%5D=PROMO001&filter%5Bstatus%5D=active&sort=-created_at&page=1", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "retailer-drive-2026", "description": "The promotion slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a paginated list of promoters for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 11,\n \"promotion_id\": 5,\n \"identifier\": \"PROMO001\",\n \"name\": \"Jane Promoter\",\n \"phone\": \"18761234567\",\n \"status\": \"active\",\n \"metadata\": {\n \"region\": \"Belize City\"\n },\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n ],\n \"links\": {\n \"first\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/retailer-drive-2026\/promoters?page=1\",\n \"last\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/retailer-drive-2026\/promoters?page=1\",\n \"prev\": null,\n \"next\": null\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 1,\n \"path\": \"http:\/\/promo-next.test\/api\/v1\/promotions\/retailer-drive-2026\/promoters\",\n \"per_page\": 15,\n \"to\": 1,\n \"total\": 1\n }\n}", "name": "" } ] }, { "name": "Create a promoter", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/promoters", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/promoters", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "retailer-drive-2026", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"identifier\":\"PROMO001\",\"name\":\"API Promoter\",\"phone\":\"18761234567\",\"status\":\"active\",\"metadata\":{\"region\":\"Belize City\"}}" }, "description": "Create a new promoter for the given promotion." }, "response": [ { "header": [], "code": 201, "body": "{\n \"status\": \"success\",\n \"message\": \"Promoter created.\",\n \"data\": {\n \"id\": 11,\n \"promotion_id\": 5,\n \"identifier\": \"PROMO001\",\n \"name\": \"API Promoter\",\n \"phone\": \"18761234567\",\n \"status\": \"active\",\n \"metadata\": null,\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n}", "name": "" } ] }, { "name": "Show a promoter", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "retailer-drive-2026", "description": "The promotion slug." }, { "id": "promoter_id", "key": "promoter_id", "value": "4", "description": "The ID of the promoter." }, { "id": "promoter", "key": "promoter", "value": "11", "description": "The promoter ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return a single promoter record for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": {\n \"id\": 11,\n \"promotion_id\": 5,\n \"identifier\": \"PROMO001\",\n \"name\": \"Jane Promoter\",\n \"phone\": \"18761234567\",\n \"status\": \"active\",\n \"metadata\": {\n \"region\": \"Belize City\"\n },\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T10:15:30.000000Z\"\n }\n}", "name": "" } ] }, { "name": "Update a promoter", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "retailer-drive-2026", "description": "The promotion slug." }, { "id": "promoter_id", "key": "promoter_id", "value": "4", "description": "The ID of the promoter." }, { "id": "promoter", "key": "promoter", "value": "11", "description": "The promoter ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"identifier\":\"PROMO002\",\"name\":\"Changed Name\",\"phone\":\"18761234567\",\"status\":\"inactive\",\"metadata\":{\"region\":\"Orange Walk\"}}" }, "description": "Update a promoter record for the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Promoter updated.\",\n \"data\": {\n \"id\": 11,\n \"promotion_id\": 5,\n \"identifier\": \"PROMO002\",\n \"name\": \"Changed Name\",\n \"phone\": \"18761234567\",\n \"status\": \"inactive\",\n \"metadata\": {\n \"region\": \"Orange Walk\"\n },\n \"created_at\": \"2026-05-01T10:15:30.000000Z\",\n \"updated_at\": \"2026-05-01T11:00:00.000000Z\"\n }\n}", "name": "" } ] }, { "name": "Delete a promoter", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/promotions\/:promotion_slug\/promoters\/:promoter_id", "variable": [ { "id": "promotion_slug", "key": "promotion_slug", "value": "retailer-drive-2026", "description": "The promotion slug." }, { "id": "promoter_id", "key": "promoter_id", "value": "4", "description": "The ID of the promoter." }, { "id": "promoter", "key": "promoter", "value": "11", "description": "The promoter ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Permanently delete a promoter from the given promotion." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Promoter deleted.\",\n \"data\": null\n}", "name": "" } ] } ] }, { "name": "Tools", "description": "", "item": [ { "name": "List available tools", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tools", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tools" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Return all registered API tools and their input\/output schemas." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": [\n {\n \"slug\": \"date-formatter\",\n \"name\": \"Date Formatter & Age Gate\",\n \"description\": \"Formats a date string and checks if the person meets a minimum age requirement. Auto-detects the input date format, or accepts an explicit input_format for ambiguous dates.\",\n \"input_schema\": [\n {\n \"name\": \"date\",\n \"type\": \"string\",\n \"required\": true,\n \"description\": \"Date string (e.g., \\\"28\/11\/1972\\\", \\\"1972-11-28\\\", \\\"Nov 28, 1972\\\")\"\n }\n ],\n \"output_schema\": [\n {\n \"name\": \"formatted_date\",\n \"type\": \"string\",\n \"description\": \"Date in the requested output format\"\n }\n ]\n },\n {\n \"slug\": \"phone-country\",\n \"name\": \"Phone Country Lookup\",\n \"description\": \"Parses a phone number and returns the normalized number, country calling code, country code, and country name.\",\n \"input_schema\": [\n {\n \"name\": \"phone\",\n \"type\": \"string\",\n \"required\": true,\n \"description\": \"Phone number in any format\"\n }\n ],\n \"output_schema\": [\n {\n \"name\": \"country_code\",\n \"type\": \"string\",\n \"description\": \"ISO 3166-1 alpha-2 country code\"\n }\n ]\n }\n ]\n}", "name": "" } ] }, { "name": "Execute a tool", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tools\/:tool", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tools\/:tool", "variable": [ { "id": "tool", "key": "tool", "value": "date-formatter", "description": "The tool slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"date\":\"28\\\/11\\\/1972\",\"input_format\":\"d\\\/m\\\/Y\",\"output_format\":\"Y-m-d\",\"min_age\":18,\"phone\":\"5016283170\",\"default_region\":\"BZ\"}" }, "description": "Run the selected tool with the supplied input. Body fields depend on the tool slug." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": null,\n \"data\": {\n \"formatted_date\": \"28.11.1972\",\n \"status\": \"approved\",\n \"age\": 53\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"status\": \"error\",\n \"message\": \"Tool not found.\",\n \"errors\": null\n}", "name": "" } ] } ] }, { "name": "Webhooks", "description": "", "item": [ { "name": "Handle a MessengerPeople webhook", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/messenger-people\/:team_uuid\/:promotion_slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/messenger-people\/:team_uuid\/:promotion_slug", "variable": [ { "id": "team_uuid", "key": "team_uuid", "value": "550e8400-e29b-41d4-a716-446655440000", "description": "The team UUID." }, { "id": "promotion_slug", "key": "promotion_slug", "value": "summer-cashback", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"member_id\":\"18765551234\",\"name\":\"John Doe\",\"image\":\"https:\\\/\\\/example.com\\\/receipt.jpg\",\"chat\":\"WINCODE123\",\"chat_time\":1772426400,\"promoter\":\"PROMO001\"}" }, "description": "Accept an inbound bot payload and route it to receipt, code, sweepstakes, or voting processing.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Receipt received successfully.\",\n \"data\": {\n \"type\": \"receipt\",\n \"receipt_id\": 123,\n \"test_mode\": false\n }\n}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"status\": \"error\",\n \"message\": \"This account has been temporarily suspended.\",\n \"errors\": null\n}", "name": "" } ] }, { "name": "Handle a SendSeven webhook", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/sendseven\/:team_uuid\/:promotion_slug", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/sendseven\/:team_uuid\/:promotion_slug", "variable": [ { "id": "team_uuid", "key": "team_uuid", "value": "550e8400-e29b-41d4-a716-446655440000", "description": "The team UUID." }, { "id": "promotion_slug", "key": "promotion_slug", "value": "summer-cashback", "description": "The promotion slug." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"id\":\"evt_123456789\",\"event_id\":\"evt_123456789\",\"type\":\"message.received\",\"created_at\":\"2026-05-01T10:15:30Z\"}" }, "description": "Accept inbound message, delivery status, conversation, and contact events from SendSeven.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Receipt received successfully.\",\n \"data\": {\n \"type\": \"receipt\",\n \"receipt_id\": 123,\n \"test_mode\": false\n }\n}", "name": "" }, { "header": [], "code": 401, "body": "{\n \"status\": \"error\",\n \"message\": \"Invalid webhook signature.\",\n \"errors\": null\n}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }