Advanced Patterns > Collection runner
Collection organization best practices
To organize Postman collections for Tallyfy’s API effectively, group requests by resource type, use folders for workflows, and implement consistent naming conventions. Well-organized collections reduce errors and speed up Tallyfy integration development.
Postman experts recommend organizing by domain resources, following RESTful API patterns. Structure your collection to mirror Tallyfy’s resources:
📁 Tallyfy API Collection 📁 [SETUP] Authentication - Get Access Token (Password Grant) - Refresh Access Token - Test Authentication - Multi-User Token Manager 📁 [CORE] Templates (Checklists) - List All Templates - Get Template Details - Get Template with Prereqs - Search Templates by Category - Template Permissions Check 📁 [CORE] Processes (Runs) - Launch Process - Launch with Kick-off Data - Launch with Dynamic Assignees - List Active Processes - Get Process Details - Update Process Metadata - Archive Process - Bulk Process Operations 📁 [CORE] Tasks - List My Tasks - List Org Tasks (Filtered) - Get Task Details - Complete Task - Complete with Form Data - Bulk Complete Tasks - Add Task Comment - Reassign Task - Task Escalation 📁 [UTILS] Files - Upload File to Task - Upload Multiple Files - Download File - Get File Metadata - Delete File - File Type Validation 📁 [ADMIN] Members & Groups - List Organization Members - Get Member Details - Invite New Member - Update Member Role - Create Group - Assign Group to Task - Group Permissions 📁 [DEMO] Workflows (End-to-End) - Complete Onboarding Flow - Approval Process Demo - Document Review Cycle - Emergency Process Override 📁 [ADMIN] Reports & Analytics - Organization Settings - Export Process Data - Analytics Queries - Performance Metrics - Audit Trail Access
Expert insight: The bracket prefixes ([SETUP], [CORE], [UTILS], [ADMIN], [DEMO]) help team members quickly identify the purpose and access level required for each folder section.
For process-specific collections:
📁 HR Processes Collection 📁 Employee Onboarding 📂 Setup - Authenticate - Get Onboarding Template 📂 Launch - Create New Employee Process - Assign to HR Manager 📂 Day 1 Tasks - Complete Paperwork Task - Upload Documents - IT Equipment Request 📂 Week 1 Tasks - Training Assignments - Manager Check-in 📂 Verification - Check All Tasks Complete - Generate Report 📁 Performance Reviews ... 📁 Leave Requests ...
Postman community research shows that consistent naming reduces onboarding time by 60%. Use this proven pattern:
Format: [METHOD] - [Action] [Resource] [Context]
✅ Expert-level names:- POST - Launch Process from Template with Assignees- GET - List Active Tasks for Current User (Filtered)- PUT - Complete Task with Form Data and File Upload- DELETE - Archive Completed Process (Bulk Operation)- PATCH - Update Task Assignment by Workload- GET - Search Templates by Category and Permissions
❌ Beginner mistakes:- Test- New Request- API Call 1- Process Stuff- Copy of Launch Process- Untitled Request
Advanced naming patterns:
// Environment-specific naming- [PROD] GET - List Templates- [STAGE] POST - Launch Test Process- [DEV] DELETE - Cleanup Test Data
// User context naming- [ADMIN] PUT - Update Organization Settings- [USER] GET - List My Assigned Tasks- [GUEST] POST - Submit External Form
// Workflow sequence naming- [1] POST - Authenticate User- [2] GET - Fetch Available Templates- [3] POST - Launch Selected Process- [4] PUT - Complete First Task- [5] GET - Verify Process Status
Based on Postman enterprise best practices, establish clear variable hierarchies:
// Global variables (SCREAMING_SNAKE_CASE) - rarely usedAPP_VERSIONAPI_SPECIFICATION_VERSIONDEFAULT_TIMEOUT
// Environment variables (UPPERCASE with prefix)TALLYFY_BASE_URLTALLYFY_ORG_IDTALLYFY_ACCESS_TOKENTALLYFY_CLIENT_IDTALLYFY_RATE_LIMIT
// Collection variables (PascalCase with context)CurrentProcessIdActiveTemplateIdTestUserEmailDefaultAssigneeGroupBaselineResponseTime
// Request-local variables (camelCase)const taskCount = 5;const processName = "Onboarding";const iterationIndex = pm.info.iteration;
// Temporary variables (prefix with TEMP_)TEMP_AUTH_STATETEMP_UPLOAD_TOKENTEMP_VALIDATION_RESULT
// Debug variables (prefix with DEBUG_)DEBUG_REQUEST_COUNTDEBUG_ERROR_LOGDEBUG_PERFORMANCE_METRICS
Variable scoping best practices:
// Use appropriate scope for data lifecycle
// Global: App-wide constants (rarely changes)pm.globals.set("API_VERSION", "v2");
// Environment: Environment-specific configpm.environment.set("TALLYFY_BASE_URL", "https://go.tallyfy.com/api");
// Collection: Shared across requests in collectionpm.collectionVariables.set("CurrentSessionId", sessionId);
// Local: Single request onlypm.variables.set("tempCalculation", result);
// Best practice: Clear temporary variablespm.test("Cleanup", () => { ["TEMP_AUTH_STATE", "TEMP_UPLOAD_TOKEN"].forEach(key => { pm.environment.unset(key); });});
Enterprise teams use standardized prefixes to indicate purpose and access levels:
📁 [SETUP] - Authentication & Configuration📁 [CORE] - Primary Business Operations📁 [UTILS] - Helper Requests & Utilities📁 [TEST] - Testing Scenarios & Validation📁 [DEMO] - Example Workflows & Training📁 [ADMIN] - Administrative Operations📁 [DEBUG] - Debugging & Diagnostics📁 [DEPRECATED] - Legacy Requests (Keep for Reference)
Advanced folder organization patterns:
// By API version📁 [V1] Legacy API Endpoints📁 [V2] Current API Endpoints📁 [V3] Beta API Endpoints
// By user role📁 [ADMIN_ONLY] Administrative Functions📁 [USER_STD] Standard User Operations📁 [GUEST_ACCESS] External User Functions
// By environment📁 [PROD_SAFE] Production-Safe Operations📁 [STAGE_TEST] Staging Test Operations📁 [DEV_EXPERIMENTAL] Development Experiments
// By workflow stage📁 [01_SETUP] Initial Configuration📁 [02_ONBOARD] User Onboarding Flow📁 [03_OPERATE] Daily Operations📁 [04_MAINTAIN] Maintenance Tasks📁 [05_CLEANUP] Cleanup & Archival
Folder ordering best practices:
// Use numeric prefixes for logical ordering📁 01-Authentication📁 02-Templates📁 03-Processes📁 04-Tasks📁 05-Files📁 06-Admin📁 99-Utilities
// Or use emoji for visual distinction📁 🔐 Authentication📁 📋 Templates📁 ⚙️ Processes📁 ✅ Tasks📁 📎 Files📁 👥 Admin📁 🛠️ Utilities
Based on enterprise team feedback, comprehensive documentation reduces support requests by 70%:
# Tallyfy API Collection v2.1
## 🎯 OverviewThis collection provides complete coverage of Tallyfy's REST API for workflow automation.Designed for developers, QA engineers, and integration specialists.
## 📋 Prerequisites- Tallyfy account with API access enabled- Client ID and Secret from Settings > Integrations > REST API- Basic understanding of OAuth 2.0 and REST APIs- Postman v10.0+ (for advanced scripting features)
## 🚀 Quick Start1. **Import collection**: Use "Import" button and select this file2. **Create environment**: - Name: "Tallyfy Production" (or "Staging") - Add required variables (see Variables section below)3. **Run setup**: Execute "[SETUP] Get Access Token" request first4. **Verify connection**: Run "[TEST] Authentication Check"5. **Explore workflows**: Start with "[DEMO] Workflows" folder
## 🔧 Required Environment Variables| Variable | Description | Example ||----------|-------------|----------|| `TALLYFY_BASE_URL` | API base URL | `https://go.tallyfy.com/api` || `TALLYFY_CLIENT_ID` | OAuth client ID | `3MVG9...` || `TALLYFY_CLIENT_SECRET` | OAuth client secret | ⚠️ Store in vault || `TALLYFY_USERNAME` | Your email | `you@company.com` || `TALLYFY_PASSWORD` | Your password | ⚠️ Store in vault || `TALLYFY_ORG_ID` | Organization ID | `org_abc123` |
## 🛡️ Security Best Practices- **Use Postman Vault** for sensitive data (passwords, secrets)- **Never commit** environment files with real credentials- **Rotate credentials** every 90 days- **Use separate** environments for prod/staging/dev
## ✨ Key Features- 🔄 Automatic token refresh (1-hour tokens)- 📊 Built-in performance monitoring- 🐛 Comprehensive error handling and logging- 📝 Request/response validation- 🔀 Bulk operation support- 🌐 Multi-environment support- 🧪 Data-driven testing capabilities
## 📚 Folder Structure Guide- **[SETUP]**: Authentication and configuration- **[CORE]**: Primary business operations (templates, processes, tasks)- **[UTILS]**: Helper requests and utilities- **[DEMO]**: Example workflows and training scenarios- **[ADMIN]**: Administrative operations (requires admin role)- **[TEST]**: Validation and testing requests
## 🔍 Debugging1. **Enable console**: View → Show Postman Console2. **Check debug variables**: Look for DEBUG_* variables in environment3. **Review error log**: Check ERROR_LOG environment variable4. **Performance metrics**: Check RESPONSE_METRICS for timing data
## 📊 Collection Metrics- **Total requests**: 47- **Coverage**: Templates, Processes, Tasks, Files, Members, Admin- **Test coverage**: 100% of requests have validation scripts- **Last updated**: {{$timestamp}}- **Maintainer**: API Team
## 🆘 Support- **API Documentation**: [https://go.tallyfy.com/api/](https://go.tallyfy.com/api/)- **Status Page**: [https://status.tallyfy.com/](https://status.tallyfy.com/)- **Community Forum**: [https://community.postman.com/](https://community.postman.com/)- **Internal Support**: #api-support (Slack)- **Email Support**: support@tallyfy.com
## 📋 Common Issues & Solutions| Issue | Cause | Solution ||-------|-------|----------|| 401 Unauthorized | Missing X-Tallyfy-Client header | Add to pre-request script || Token expired | >1 hour since last refresh | Run "Refresh Access Token" || File upload fails | Manual Content-Type header | Remove Content-Type, use form-data || Rate limit hit | >1000 requests/hour | Implement delays in bulk operations |
## 📈 Changelog- **v2.1** (2024-01-15): Added bulk operations, improved error handling- **v2.0** (2023-12-01): OAuth 2.0 migration, security enhancements- **v1.5** (2023-10-15): Multi-environment support- **v1.0** (2023-08-01): Initial release
Enterprise teams document requests with this proven template:
## Complete Task with Form Data
### 📝 DescriptionCompletes a task and submits any required form field data. This endpoint triggers workflow progression and notifications.
### 🎯 Use Cases- Approve/reject requests with comments- Submit completed work with evidence- Progress multi-step workflows- Capture structured data for reporting
### ✅ Prerequisites- Task must be assigned to authenticated user (or user has admin role)- Task must be in 'active' status- All required form fields must be provided- User must have completion permissions
### 📥 Request**Method**: `PUT`**Endpoint**: `/tasks/{taskId}/complete`**Content-Type**: `application/json`
**Path Parameters**:- `taskId` (string, required): The task identifier
**Request Body**:```json{ "captures": { "field_status": "Approved", // Select field "field_amount": 1500.00, // Number field "field_notes": "Approved per policy", // Text field "field_approved": true, // Boolean field "field_date": "2024-01-15" // Date field (YYYY-MM-DD) }, "comment": "Optional completion comment" // Optional}
Success (200):
{ "id": "task_123", "status": "completed", "completed_at": "2024-01-15T10:30:00Z", "completed_by": "user_456", "captures": { "field_status": "Approved", "field_amount": 1500.00, "field_notes": "Approved per policy" }, "next_tasks": ["task_789"] // Tasks created by completion}
Code | Reason | Solution |
---|---|---|
400 | Invalid JSON format | Check request body syntax |
401 | Authentication failed | Verify token and X-Tallyfy-Client header |
403 | Permission denied | Task not assigned to you |
404 | Task not found | Check task ID and organization |
422 | Validation failed | Check required fields and data types |
429 | Rate limit exceeded | Add delays between requests |
// Validation tests included with requestpm.test("Task completed successfully", () => { pm.expect(pm.response.code).to.equal(200); const response = pm.response.json(); pm.expect(response.status).to.equal("completed"); pm.expect(response.completed_at).to.exist;});
pm.test("Form data captured", () => { const response = pm.response.json(); pm.expect(response.captures).to.exist; pm.expect(response.captures.field_status).to.equal("Approved");});
- Typical response time: 200-500ms
- Rate limit: 1000 requests/hour
- Timeout: 30 seconds
GET /tasks/{taskId}
- Get task detailsPOST /tasks/{taskId}/comments
- Add commentPUT /tasks/{taskId}/assign
- Reassign task
- Use dynamic field validation from task schema
- Implement retry logic for network issues
- Cache form field definitions to reduce API calls
- Consider bulk completion for multiple tasks
## Environment management
### Environment hierarchy
Set up multiple environments:
```javascript// Production (Default){ "TALLYFY_BASE_URL": "https://go.tallyfy.com/api", "TALLYFY_ORG_ID": "org_prod_123", "LOG_LEVEL": "ERROR"}
// Staging{ "TALLYFY_BASE_URL": "https://go.tallyfy.com/api", "TALLYFY_ORG_ID": "org_stage_456", "LOG_LEVEL": "INFO"}
// Development{ "TALLYFY_BASE_URL": "https://go.tallyfy.com/api", "TALLYFY_ORG_ID": "org_dev_789", "LOG_LEVEL": "DEBUG", "USE_MOCK": "false"}
Use appropriate scope for variables:
// Global variables - Rarely usedpm.globals.set("APP_VERSION", "1.0.0");
// Collection variables - Shared across requestspm.collectionVariables.set("DefaultTimeout", 5000);
// Environment variables - Environment-specificpm.environment.set("TALLYFY_ORG_ID", "org_123");
// Local variables - Single request onlypm.variables.set("tempValue", "abc");
Add to collection for all requests:
// Auto-add required headersif (!pm.request.headers.has("X-Tallyfy-Client")) { pm.request.headers.add({ key: "X-Tallyfy-Client", value: "APIClient" });}
// Add auth header if token existsconst token = pm.environment.get("TALLYFY_ACCESS_TOKEN");if (token && !pm.request.headers.has("Authorization")) { pm.request.headers.add({ key: "Authorization", value: `Bearer ${token}` });}
// Performance trackingpm.variables.set("requestStartTime", Date.now());
Add specific behavior to folders:
// For "Files" folder - add multipart handlingif (pm.request.body && pm.request.body.mode === 'formdata') { console.log("File upload request detected"); // Add file-specific handling}
// For "Admin" folder - add extra loggingconsole.log("Admin operation:", pm.request.name);pm.environment.set("ADMIN_ACTION_LOG", pm.request.name);
Create reusable test utilities:
// In collection Tests tabpm.collectionVariables.set("testUtils", { // Check successful response expectSuccess: function(responseCode = 200) { pm.test(`Status code is ${responseCode}`, () => { pm.expect(pm.response.code).to.equal(responseCode); });
pm.test("Response time is acceptable", () => { pm.expect(pm.response.responseTime).to.be.below(1000); }); },
// Validate response structure expectFields: function(fields) { pm.test("Response has required fields", () => { const json = pm.response.json(); fields.forEach(field => { pm.expect(json).to.have.property(field); }); }); },
// Save ID for chaining saveId: function(idField, variableName) { const id = pm.response.json()[idField]; if (id) { pm.collectionVariables.set(variableName, id); console.log(`Saved ${variableName}: ${id}`); } }});
// Usage in request tests:const utils = pm.collectionVariables.get("testUtils");utils.expectSuccess(201);utils.expectFields(['id', 'name', 'status']);utils.saveId('id', 'lastProcessId');
Best practices for version control:
-
Export settings:
- Export collection as v2.1 format
- Include collection variables
- Exclude environment values
-
Directory structure:
postman/collections/tallyfy-api-v1.jsontallyfy-workflows.jsonenvironments/production.template.jsonstaging.template.jsonschemas/openapi-spec.jsonscripts/pre-request-global.jstest-utils.js -
Environment templates:
{"name": "Tallyfy Production","values": [{"key": "TALLYFY_CLIENT_ID","value": "REPLACE_ME","type": "secret"},{"key": "TALLYFY_BASE_URL","value": "https://go.tallyfy.com/api","type": "default"}]}
Add version info to collection:
// In collection description or pre-requestconst collectionInfo = { version: "2.1.0", lastUpdated: "2024-01-15", author: "API Team", changelog: [ "2.1.0 - Added bulk operations", "2.0.0 - Migrated to OAuth", "1.0.0 - Initial release" ]};
pm.collectionVariables.set("COLLECTION_INFO", collectionInfo);
Organize for team use:
-
Workspace structure:
Tallyfy API Workspace/Official Collections/- Tallyfy API v2- Tallyfy WebhooksTeam Collections/- HR Workflows- Finance ProcessesPersonal/- [User] Test Collection -
Permissions:
- Official: View only for most
- Team: Edit for department
- Personal: Private drafts
-
Forking strategy:
- Fork official collections for experiments
- Submit pull requests for improvements
- Maintain clear fork naming
Include a README in your collection:
## Quick Start
1. Fork this collection to your workspace2. Create environment from template3. Add your credentials (see Setup Guide)4. Run "Test Authentication" to verify5. Explore example workflows in /Demos
## Common Issues
- 401 Errors: Check X-Tallyfy-Client header- Rate limits: See /Utils/Check Rate Limit- File uploads: Must use form-data
## Contributing
1. Fork the collection2. Make changes in your fork3. Test thoroughly4. Submit pull request with description
Monthly maintenance tasks:
// Find unused variablesconst env = pm.environment.toObject();const unused = [];
Object.keys(env).forEach(key => { // Search collection for variable usage const used = pm.collectionVariables.get(`${key}_USED`); if (!used) { unused.push(key); }});
console.log("Potentially unused variables:", unused);
Keep collections fast:
- Minimize pre-request scripts - Only essential logic
- Async operations - Use promises for parallel requests
- Conditional tests - Skip tests when not needed
- Archive old requests - Move to separate collection
Postman experts follow “Don’t Repeat Yourself” principles:
// Collection-level pre-request script (applies to all requests)const baseConfig = { timeout: 30000, retries: 3, rateLimit: { requestsPerHour: 1000, minDelay: 100 }};
// Auto-add required headersif (!pm.request.headers.has("X-Tallyfy-Client")) { pm.request.headers.add({ key: "X-Tallyfy-Client", value: "APIClient" });}
// Auto-refresh token if neededconst tokenExpiry = pm.environment.get("TALLYFY_TOKEN_EXPIRY");if (tokenExpiry && Date.now() >= tokenExpiry - 300000) { // 5 min buffer console.log("Token refresh needed - consider running refresh request");}
// Apply base configurationpm.request.timeout = baseConfig.timeout;
Utilize Postman’s deep nesting capabilities:
📁 Tallyfy API Collection 📁 [CORE] Templates 📁 Template CRUD - Create Template - Read Template - Update Template - Delete Template 📁 Template Workflows - Launch Process - Clone Template - Export Template 📁 Template Admin - Set Permissions - Archive Template - Audit Template Changes 📁 [CORE] Processes 📁 Process Lifecycle 📁 Creation - Launch from Template - Launch with Data - Bulk Launch 📁 Management - Update Process - Add Participants - Change Deadlines 📁 Completion - Archive Process - Export Data - Generate Reports
// Collection variables for shared configurationpm.collectionVariables.set("API_VERSION", "v2");pm.collectionVariables.set("DEFAULT_TIMEOUT", 30000);pm.collectionVariables.set("MAX_RETRIES", 3);pm.collectionVariables.set("DEBUG_MODE", "INFO");
// Shared utilitiesconst utils = { formatDate: (date) => date.toISOString().split('T')[0], generateId: () => pm.variables.replaceIn('{{$randomUUID}}'), logError: (context, error) => { const errorLog = JSON.parse(pm.environment.get("ERROR_LOG") || '[]'); errorLog.push({ timestamp: new Date().toISOString(), context: context, error: error, request: pm.request.url.toString() }); pm.environment.set("ERROR_LOG", JSON.stringify(errorLog)); }};
pm.collectionVariables.set("UTILS", JSON.stringify(utils));
// Dependency tracking systemconst dependencies = { "Complete Task": ["Get Task Details", "Authenticate"], "Launch Process": ["Get Template", "Authenticate"], "Upload File": ["Complete Task", "Authenticate"]};
// Auto-validate dependenciesconst currentRequest = pm.info.requestName;const requiredDeps = dependencies[currentRequest] || [];
requiredDeps.forEach(dep => { const depCompleted = pm.environment.get(`DEP_${dep.replace(/\s+/g, '_').toUpperCase()}`); if (!depCompleted) { console.warn(`⚠️ Dependency not met: ${dep}`); }});
// Mark current request as completedpm.test("Mark dependency completed", () => { if (pm.response.code < 400) { pm.environment.set(`DEP_${currentRequest.replace(/\s+/g, '_').toUpperCase()}`, true); }});
// Collection health monitoringconst collectionHealth = { totalRequests: pm.info.requestId, averageResponseTime: pm.environment.get("AVERAGE_RESPONSE_TIME") || 0, errorRate: pm.environment.get("ERROR_RATE") || 0, lastMaintenance: pm.environment.get("LAST_MAINTENANCE") || "Never"};
// Alert on performance degradationif (collectionHealth.averageResponseTime > 2000) { console.warn("⚠️ Collection performance degraded - review slow endpoints");}
// Auto-cleanup old dataconst cleanupInterval = 7 * 24 * 60 * 60 * 1000; // 7 daysconst lastCleanup = pm.environment.get("LAST_CLEANUP") || 0;
if (Date.now() - lastCleanup > cleanupInterval) { // Clean up old logs and temporary data ["ERROR_LOG", "RESPONSE_METRICS", "DEBUG_SESSION_DATA"].forEach(key => { const data = JSON.parse(pm.environment.get(key) || '[]'); if (data.length > 100) { pm.environment.set(key, JSON.stringify(data.slice(-50))); } });
pm.environment.set("LAST_CLEANUP", Date.now()); console.log("🧹 Performed automated cleanup");}
Remember: A well-organized collection is a joy to use and maintain. These enterprise patterns reduce onboarding time, improve reliability, and scale with your team’s growth. Invest time in structure - it pays dividends over months and years.
Templates > Organization best practices
Troubleshooting > Debugging guide
- 2025 Tallyfy, Inc.
- Privacy Policy
- Terms of Use
- Report Issue
- Trademarks