Collection organization best practices

Group your Postman requests by resource type, use folders for workflows, and stick to consistent naming conventions. A well-structured collection cuts errors and speeds up your Tallyfy integration work from day one.

Collection structure patterns

Resource-based organization

Structure your collection to mirror Tallyfy’s actual API resources. The API organizes around templates (called “checklists” internally), processes (runs), tasks, assets, members, guests, and groups.

📁 Tallyfy API Collection
  📁 [SETUP] Authentication
    - Get Access Token (Password Grant)
    - Refresh Access Token
    - Test Authentication
  📁 [CORE] Templates (Checklists)
    - List All Templates
    - Get Template Details
    - Create Template
    - Update Template
    - Clone Template
    - Get Template Permissions
    - Export Template
  📁 [CORE] Processes (Runs)
    - Launch Process from Template
    - Launch with Kick-off Data
    - List Active Processes
    - Get Process Details
    - Update Process
    - Archive Process
    - Export Process Data
  📁 [CORE] Tasks
    - List My Tasks
    - List Org Tasks
    - Get Task Details
    - Update Task
    - Mark Task Complete
    - Add Task Comment
    - Report Problem on Task
  📁 [UTILS] Files & Assets
    - Upload File
    - Get File / Asset
    - Delete File
    - Download File
  📁 [ADMIN] Members & Groups
    - List Organization Members
    - Get Member Details
    - Invite New Member
    - Update Member Role
    - List Groups
    - Create / Update Group
  📁 [UTILS] Guests
    - Create Guest
    - List Guests
    - Update Guest
    - Guest-to-Member Conversion
  📁 [DEMO] Workflows (End-to-End)
    - Complete Onboarding Flow
    - Approval Process Demo

Bracket prefixes like [SETUP], [CORE], [UTILS], [ADMIN], and [DEMO] let team members quickly spot each folder’s purpose and access level.

Workflow-based organization

For process-specific collections, organize by business workflow instead:

📁 HR Processes Collection
  📁 Employee Onboarding
    📂 Setup
      - Authenticate
      - Get Onboarding Template
    📂 Launch
      - Create New Employee Process
    📂 Day 1 Tasks
      - Complete Paperwork Task
      - Upload Documents
    📂 Verification
      - Check All Tasks Complete
  📁 Performance Reviews
    ...
  📁 Leave Requests
    ...

Naming conventions

Request naming standards

Clear, descriptive names save everyone time. Use this pattern:

Format: [METHOD] - [Action] [Resource] [Context]

Good names:
- POST - Launch Process from Template
- GET - List Active Tasks for Current User
- PUT - Update Task with Form Data
- DELETE - Archive Completed Process
- GET - Get Template with Steps and Permissions

Bad names:
- Test
- New Request
- API Call 1
- Copy of Launch Process

You can layer in extra context with prefixes:

// Environment-specific
- [PROD] GET - List Templates
- [STAGE] POST - Launch Test Process

// User context
- [ADMIN] PUT - Update Organization Settings
- [GUEST] POST - Submit External Form

// Workflow sequence
- [1] POST - Authenticate User
- [2] GET - Fetch Available Templates
- [3] POST - Launch Selected Process
- [4] PUT - Complete First Task

Variable naming standards

Pick a consistent naming convention per scope and stick to it:

// Environment variables (UPPERCASE with prefix)
TALLYFY_BASE_URL
TALLYFY_ORG_ID
TALLYFY_ACCESS_TOKEN
TALLYFY_CLIENT_ID

// Collection variables (PascalCase)
CurrentProcessId
ActiveTemplateId
TestUserEmail

// Request-local variables (camelCase)
const taskCount = 5;
const processName = "Onboarding";

Use the right scope for each variable’s lifecycle:

// Environment: config that changes per environment
pm.environment.set("TALLYFY_BASE_URL", "https://go.tallyfy.com/api");

// Collection: shared across requests in this collection
pm.collectionVariables.set("CurrentSessionId", sessionId);

// Local: single request only
pm.variables.set("tempCalculation", result);

// Clean up temporary variables after use
pm.test("Cleanup", () => {
    ["TEMP_AUTH_STATE", "TEMP_UPLOAD_TOKEN"].forEach(key => {
        pm.environment.unset(key);
    });
});

Folder prefixes and organization

Standardized prefixes make structure self-documenting:

📁 [SETUP] - Authentication & Configuration
📁 [CORE] - Primary Business Operations
📁 [UTILS] - Helper Requests & Utilities
📁 [TEST] - Testing Scenarios & Validation
📁 [DEMO] - Example Workflows & Training
📁 [ADMIN] - Administrative Operations
📁 [DEPRECATED] - Legacy Requests (Keep for Reference)

Numeric prefixes enforce ordering:

📁 01-Authentication
📁 02-Templates
📁 03-Processes
📁 04-Tasks
📁 05-Files
📁 06-Admin
📁 99-Utilities

Documentation standards

Collection description

A solid collection description cuts support questions. Here’s a template that works well:

# Tallyfy API Collection

## Overview
Complete coverage of Tallyfy's REST API for workflow automation.

## 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

## Quick start
1. Import this collection
2. Create an environment with required variables (see below)
3. Run "[SETUP] Get Access Token" first
4. Verify with any GET request

## Required environment variables
| Variable | Description | Example |
|----------|-------------|----------|
| `TALLYFY_BASE_URL` | API base URL | `https://go.tallyfy.com/api` |
| `TALLYFY_CLIENT_ID` | OAuth client ID | Your client ID |
| `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 | Your org ID |

## Security
- Use Postman Vault for passwords and secrets
- Never commit environment files with real credentials
- Use separate environments for production and staging

## Common issues
| Issue | Cause | Fix |
|-------|-------|-----|
| 401 Unauthorized | Missing X-Tallyfy-Client header | Add header via pre-request script |
| Token expired | Tokens last ~1 hour | Run "Refresh Access Token" |
| File upload fails | Manual Content-Type set | Remove Content-Type, use form-data |

Request documentation

Document individual requests so teammates don’t have to guess. Here’s a good template, using the task update endpoint as an example:

## Update task with form data

### Description
Updates a task and submits form field data. The API endpoint is
PUT /organizations/{org}/runs/{run_id}/tasks/{task}

### Prerequisites
- Valid Bearer token and X-Tallyfy-Client header
- Task must exist within the specified run
- User must have access to the task

### Request body
```json
{
  "taskdata": {
    "field_alias": "value"
  }
}

Error responses

Code	Reason	Fix
401	Auth failed	Check token and X-Tallyfy-Client header
403	No access	Verify task assignment
404	Not found	Check task ID, run ID, and org ID
422	Validation error	Check required fields and data types

Test script

pm.test("Task updated", () => {
    pm.expect(pm.response.code).to.equal(200);
    const body = pm.response.json();
    pm.expect(body.data).to.exist;
});

Related endpoints

• GET /organizations/{org}/runs/{run_id}/tasks/{task} - Get task details
• POST /organizations/{org}/tasks/{task}/comment - Add comment

## Environment management

### Environment setup

Tallyfy's API uses the same base URL for all environments - you differentiate by org ID:

```javascript
// Production
{
  "TALLYFY_BASE_URL": "https://go.tallyfy.com/api",
  "TALLYFY_ORG_ID": "your_prod_org_id",
  "LOG_LEVEL": "ERROR"
}

// Staging / testing
{
  "TALLYFY_BASE_URL": "https://go.tallyfy.com/api",
  "TALLYFY_ORG_ID": "your_test_org_id",
  "LOG_LEVEL": "DEBUG"
}

Pre-request scripts

Collection-level script

Add this to your collection so every request gets the right headers automatically:

// Auto-add required headers
if (!pm.request.headers.has("X-Tallyfy-Client")) {
    pm.request.headers.add({
        key: "X-Tallyfy-Client",
        value: "APIClient"
    });
}

// Add auth header if token exists
const token = pm.environment.get("TALLYFY_ACCESS_TOKEN");
if (token && !pm.request.headers.has("Authorization")) {
    pm.request.headers.add({
        key: "Authorization",
        value: `Bearer ${token}`
    });
}

Folder-level scripts

You can add behavior scoped to specific folders:

// For "Files" folder - log upload requests
if (pm.request.body && pm.request.body.mode === 'formdata') {
    console.log("File upload request detected");
}

// For "Admin" folder - extra logging
console.log("Admin operation:", pm.request.name);

Test organization

Shared test functions

Build reusable test utilities at the collection level:

// In collection Tests tab
pm.collectionVariables.set("testUtils", {
    expectSuccess: function(responseCode = 200) {
        pm.test(`Status code is ${responseCode}`, () => {
            pm.expect(pm.response.code).to.equal(responseCode);
        });
    },

    expectFields: function(fields) {
        pm.test("Response has required fields", () => {
            const json = pm.response.json();
            fields.forEach(field => {
                pm.expect(json).to.have.property(field);
            });
        });
    },

    saveId: function(idField, variableName) {
        const id = pm.response.json()[idField];
        if (id) {
            pm.collectionVariables.set(variableName, id);
            console.log(`Saved ${variableName}: ${id}`);
        }
    }
});

// Usage in any request's tests:
const utils = pm.collectionVariables.get("testUtils");
utils.expectSuccess(201);
utils.expectFields(['data']);
utils.saveId('id', 'lastProcessId');

Version control

Exporting for Git

Keep your Postman work in version control:

1. Export collection as v2.1 format, including collection variables but excluding environment secrets.

2. Use a clean directory structure:

   postman/
     collections/
       tallyfy-api.json
     environments/
       production.template.json
       staging.template.json

3. Environment templates should use placeholder values:

   {
     "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"
       }
     ]
   }

Sharing and collaboration

Team workspace setup

Organize workspaces by access level:

1. Official Collections - View-only for most team members. Contains the canonical Tallyfy API collection.
2. Team Collections - Editable by department. HR workflows, finance processes, etc.
3. Personal - Private drafts and experiments.

Fork official collections for experiments, then submit pull requests for improvements you want to share back.

Maintenance practices

Keep collections healthy with regular upkeep:

1. Trim pre-request scripts - only keep what’s needed
2. Archive old requests - move deprecated requests to a separate folder or collection
3. Review variables - remove unused environment and collection variables
4. Update documentation - keep request descriptions current when the API changes

Advanced organization

DRY pre-request scripts

Put shared logic at the collection level so you don’t repeat it in every request:

// Collection-level pre-request: runs before every request
if (!pm.request.headers.has("X-Tallyfy-Client")) {
    pm.request.headers.add({
        key: "X-Tallyfy-Client",
        value: "APIClient"
    });
}

// Check token expiry
const tokenExpiry = pm.environment.get("TALLYFY_TOKEN_EXPIRY");
if (tokenExpiry && Date.now() >= tokenExpiry - 300000) {
    console.log("Token expires soon - run refresh request");
}

Multi-level folder structure

Postman supports nested folders. Use them for large collections:

📁 Tallyfy API Collection
  📁 [CORE] Templates
    📁 Template CRUD
      - Create Template
      - Get Template
      - Update Template
      - Delete Template
    📁 Template Operations
      - Launch Process from Template
      - Clone Template
      - Export Template
  📁 [CORE] Processes
    📁 Lifecycle
      - Launch from Template
      - Update Process
      - Archive Process
      - Export Data

Request dependencies

Track which requests depend on others:

const dependencies = {
    "Complete Task": ["Get Task Details", "Authenticate"],
    "Launch Process": ["Get Template", "Authenticate"],
    "Upload File": ["Authenticate"]
};

const currentRequest = pm.info.requestName;
const requiredDeps = dependencies[currentRequest] || [];

requiredDeps.forEach(dep => {
    const depDone = pm.environment.get(
        `DEP_${dep.replace(/\s+/g, '_').toUpperCase()}`
    );
    if (!depDone) {
        console.warn(`Dependency not met: ${dep}`);
    }
});

// Mark this request as completed on success
pm.test("Mark dependency completed", () => {
    if (pm.response.code < 400) {
        pm.environment.set(
            `DEP_${currentRequest.replace(/\s+/g, '_').toUpperCase()}`,
            true
        );
    }
});

A well-organized collection pays for itself quickly. Spend time on structure upfront and you’ll save hours of confusion later.

Related articles

Postman > Troubleshooting common issues

Most Tallyfy API failures in Postman stem from three issues: a missing X-Tallyfy-Client header and wrong grant type or expired tokens and this guide covers how to diagnose and fix every common error including 401 authentication problems and 404 path mistakes and 422 validation failures and rate limiting and file upload issues along with ready-to-use debugging scripts for your Postman collection.

Api Clients > Getting started with Postman API testing

Postman serves as a code-free testing environment for Tallyfy’s REST API where you authenticate using the password grant type and then explore endpoints for templates (called checklists) and processes (called runs) and tasks across your organization.

Postman > Advanced patterns and testing

Postman’s collection runners and Newman CLI enable teams to move from manual Tallyfy API testing to fully automated workflow validation across multiple organizations with features like environment switching scripts and data-driven test runs that plug directly into CI/CD pipelines through GitHub Actions while also supporting performance monitoring and Slack alerting for stuck processes or degraded response times.

Open Api > API integration guide

Tallyfy’s REST API enables you to connect workflow features to external systems using OAuth 2.0 authentication with required Bearer tokens and X-Tallyfy-Client headers while mapping API terminology like Checklists and Runs to their UI equivalents of Templates and Processes and handling token refresh and multi-organization context for reliable integrations.

Was this helpful?

YesNo