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;
});

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:

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

Use a clean directory structure:

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

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

Team workspace setup

Organize workspaces by access level:

Official Collections - View-only for most team members. Contains the canonical Tallyfy API collection.
Team Collections - Editable by department. HR workflows, finance processes, etc.
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:

Trim pre-request scripts - only keep what’s needed
Archive old requests - move deprecated requests to a separate folder or collection
Review variables - remove unused environment and collection variables
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.

Postman > Troubleshooting common issues

Fixing Postman errors with Tallyfy’s API requires checking the X-Tallyfy-Client header first then verifying the authentication grant type is password (not client_credentials) and ensuring tokens haven’t expired since these three issues cause most API failures.

Api Clients > Getting started with Postman API testing

Set up Postman with Tallyfy’s REST API to test workflow automation endpoints including OAuth authentication with the password grant type, required headers, and common operations like launching processes and completing tasks.

Postman > Advanced patterns and testing

Implement advanced Postman workflows for Tallyfy API testing - including multi-org environment switching, performance monitoring, mock servers, CI/CD with Newman and GitHub Actions, and data-driven testing with CSV/JSON files.

Templates > Organizing templates

Organizing your Tallyfy template library through smart folder structures and naming conventions and tags and proper step grouping ensures teams can instantly find and run the right process while maintaining clean version control and regular audit cycles to keep everything accurate and up to date.

Was this helpful?

Get in touch

About Tallyfy