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

Section titled “Collection structure patterns”

Resource-based organization

Section titled “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

Section titled “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

Section titled “Naming conventions”

Request naming standards

Section titled “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

Section titled “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

Section titled “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

Section titled “Documentation standards”

Collection description

Section titled “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

Section titled “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

Section titled “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

Section titled “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;
});
Section titled “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

Section titled “Pre-request scripts”

Collection-level script

Section titled “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

Section titled “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

Section titled “Test organization”

Shared test functions

Section titled “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

Section titled “Version control”

Exporting for Git

Section titled “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

Section titled “Sharing and collaboration”

Team workspace setup

Section titled “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

Section titled “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

Section titled “Advanced organization”

DRY pre-request scripts

Section titled “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

Section titled “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

Section titled “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.

Section titled “Related articles”
Get in touch
About Tallyfy