{
  "info": {
    "name": "WAAPI — Contact Management API",
    "description": "Postman collection for the WAAPI External Contact Management API.\n\nSet these collection variables before running:\n- base_url   → your backend URL (e.g. http://localhost:4151)\n- api_token  → Bearer token with read_contacts / write_contacts permission\n- phone_id   → Base64-encoded phone number ID (shown on API Keys page)\n- contact_id → a contact _id returned from List or Create\n- group_id   → a group _id returned from List Groups or Create Group\n\nOpen Collection → Variables tab to configure.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url",   "value": "http://localhost:4151",      "type": "string" },
    { "key": "api_token",  "value": "YOUR_API_TOKEN_HERE",        "type": "string" },
    { "key": "phone_id",   "value": "YOUR_ENCODED_PHONE_ID",      "type": "string" },
    { "key": "contact_id", "value": "CONTACT_ID_HERE",            "type": "string" },
    { "key": "group_id",   "value": "GROUP_ID_HERE",              "type": "string" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{api_token}}", "type": "string" }]
  },
  "item": [
    {
      "name": "── Contacts ──",
      "item": [
        {
          "name": "1. List Contacts",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}?page=1&limit=20",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}"],
              "query": [
                { "key": "page",   "value": "1"  },
                { "key": "limit",  "value": "20" },
                { "key": "search", "value": "",   "disabled": true },
                { "key": "tag",    "value": "",   "disabled": true }
              ]
            },
            "description": "List contacts with optional search, tag filter and pagination.\n\nRequired permission: read_contacts\n\nQuery params:\n- search  (string)  — search by name or phone\n- tag     (string)  — filter by tag label\n- page    (number)  — default 1\n- limit   (number)  — default 20, max 100"
          }
        },
        {
          "name": "2. Get Contact",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/{{contact_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "{{contact_id}}"]
            },
            "description": "Retrieve a single contact by ID.\n\nRequired permission: read_contacts"
          }
        },
        {
          "name": "3. Create Contact",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Jane Smith\",\n  \"phone\": \"+919876543210\",\n  \"email\": \"jane@example.com\",\n  \"language_code\": \"en\",\n  \"tags\": [\"customer\", \"vip\"],\n  \"notes\": \"Referred by existing customer.\",\n  \"opt_out\": false,\n  \"opt_out_marketing\": false,\n  \"reply_bot_enabled\": true,\n  \"custom_fields\": {\n    \"city\": \"Mumbai\",\n    \"loyalty_tier\": \"gold\"\n  }\n}"
            },
            "description": "Create a new contact.\n\nRequired permission: write_contacts\n\nRequired fields: name, phone\nPhone must be in E.164 format (e.g. +919876543210)"
          }
        },
        {
          "name": "4. Update Contact",
          "request": {
            "method": "PUT",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/{{contact_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "{{contact_id}}"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"tags\": [\"vip\", \"renewed\"],\n  \"notes\": \"Renewed subscription in Jan 2025.\",\n  \"opt_out_marketing\": false,\n  \"custom_fields\": {\n    \"loyalty_tier\": \"platinum\"\n  }\n}"
            },
            "description": "Update contact fields. Send only the fields you want to change.\n\nRequired permission: write_contacts"
          }
        },
        {
          "name": "5. Delete Contact",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/{{contact_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "{{contact_id}}"]
            },
            "description": "Permanently delete a contact. Also removes them from all groups.\n\nRequired permission: write_contacts"
          }
        }
      ]
    },
    {
      "name": "── Bulk Import ──",
      "item": [
        {
          "name": "6. Bulk Import Contacts",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/bulk",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "bulk"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"contacts\": [\n    {\n      \"name\": \"John Doe\",\n      \"phone\": \"+919876543210\",\n      \"email\": \"john@example.com\",\n      \"language_code\": \"en\",\n      \"tags\": [\"newsletter\"],\n      \"groups\": [\"VIP Customers\"],\n      \"custom_fields\": {\n        \"city\": \"Delhi\"\n      }\n    },\n    {\n      \"first_name\": \"Priya\",\n      \"last_name\": \"Sharma\",\n      \"phone\": \"+918123456789\",\n      \"tags\": [\"lead\"]\n    },\n    {\n      \"name\": \"Ravi Kumar\",\n      \"phone\": \"+919900112233\"\n    }\n  ]\n}"
            },
            "description": "Bulk import (upsert) up to 50,000 contacts in one request.\nContacts are matched by phone number — existing ones are updated, new ones are created.\n\nRequired permission: write_contacts\n\nSupports:\n- name OR first_name + last_name\n- groups (auto-created if not existing)\n- custom_fields (matched by field_name key)\n\nReturns: { created, updated, skipped, errors }"
          }
        }
      ]
    },
    {
      "name": "── Groups ──",
      "item": [
        {
          "name": "7. List Groups",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups?page=1&limit=20",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups"],
              "query": [
                { "key": "page",   "value": "1"  },
                { "key": "limit",  "value": "20" },
                { "key": "search", "value": "",   "disabled": true }
              ]
            },
            "description": "List all contact groups with optional search and pagination.\n\nRequired permission: read_contacts"
          }
        },
        {
          "name": "8. Create Group",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"VIP Customers\",\n  \"description\": \"High-value customers with premium plans\"\n}"
            },
            "description": "Create a new contact group.\n\nRequired permission: write_contacts\n\nRequired: name\nOptional: description"
          }
        },
        {
          "name": "9. Get Group",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups/{{group_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups", "{{group_id}}"]
            },
            "description": "Get a single group with full contact member list.\n\nRequired permission: read_contacts"
          }
        },
        {
          "name": "10. Update Group",
          "request": {
            "method": "PUT",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups/{{group_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups", "{{group_id}}"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Premium Subscribers\",\n  \"description\": \"Updated group description\"\n}"
            },
            "description": "Update a group's name or description.\n\nRequired permission: write_contacts"
          }
        },
        {
          "name": "11. Delete Group",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups/{{group_id}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups", "{{group_id}}"]
            },
            "description": "Delete a group. Contacts inside are NOT deleted — only the group is removed.\n\nRequired permission: write_contacts"
          }
        },
        {
          "name": "12. Add Contacts to Group",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups/{{group_id}}/add",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups", "{{group_id}}", "add"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"contact_ids\": [\n    \"64f1a2b3c4d5e6f7a8b9c0d1\",\n    \"64f1a2b3c4d5e6f7a8b9c0d2\"\n  ]\n}"
            },
            "description": "Add one or more contacts (by ID) to a group.\n\nRequired permission: write_contacts\n\ncontact_ids: array of contact _id strings"
          }
        },
        {
          "name": "13. Remove Contacts from Group",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{base_url}}/api/external/contacts/{{phone_id}}/groups/{{group_id}}/remove",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "contacts", "{{phone_id}}", "groups", "{{group_id}}", "remove"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"contact_ids\": [\n    \"64f1a2b3c4d5e6f7a8b9c0d1\"\n  ]\n}"
            },
            "description": "Remove one or more contacts from a group. Contacts themselves are NOT deleted.\n\nRequired permission: write_contacts"
          }
        }
      ]
    }
  ]
}