Skip to content
Tallyfy

Postman collection organization

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

CodeReasonFix
401Auth failedCheck token and X-Tallyfy-Client header
403No accessVerify task assignment
404Not foundCheck task ID, run ID, and org ID
422Validation errorCheck 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:

  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.

Get in touch
About Tallyfy