API integration guide

Integrating with the Tallyfy REST API

Tallyfy’s REST API lets you connect workflow features to your own applications and systems.

API documentation

Full API reference at https://go.tallyfy.com/api/ ↗

API terminology

The Tallyfy API uses different names than what you’ll see in the web app. Here’s the mapping:

• API Checklists = Templates in the UI (containing Steps)
• API Runs = Processes in the UI (containing Tasks)
• API Captures = Task form fields in the UI
• API Preruns = Kick-off form fields in the UI

Keep these distinctions in mind when reading the API docs - they’ll help you match API data to what users actually see in Tallyfy.

Required headers

Every API call must include these headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
X-Tallyfy-Client: APIClient
Accept: application/json

Important: Requests without the X-Tallyfy-Client header will be rejected.

Authentication methods

Tallyfy supports two authentication approaches:

1. User-based authentication

For integrations acting on behalf of a specific Tallyfy user:

1. Go to Settings > Integrations > REST API in your Tallyfy account
2. Copy your personal access_token
3. Include this token in the Authorization header of your API requests

This video shows how to get your access token:

2. Application-based authentication

For third-party apps needing client credentials:

1. Contact Tallyfy Support describing your integration needs
2. You’ll receive a Client ID and Client Secret
3. Implement the OAuth 2.0 flow to get and refresh access tokens

OAuth authentication flow

This diagram shows the full OAuth flow for both authentication methods.

What to notice:

• Steps 1-4 show initial authentication - use password grant for user context or client credentials for app-only access
• Step 5 shows required headers for all API requests - both Authorization and X-Tallyfy-Client headers are mandatory
• Steps 6-10 show token refresh when a 401 error occurs - your app should handle this retry automatically

Token management

Handling token invalidation

Personal access tokens are invalidated when users log out. To reduce disruption:

1. Automated systems: Use application tokens (Enterprise plans) instead of personal tokens when possible
2. User-based integrations:
   • Let users know that logging out breaks automations
   • Add error handling to detect invalidated tokens
   • Provide clear steps for getting new tokens after logout
3. Monitoring: Log authentication failures to spot patterns early

Token security

• Store tokens with encryption at rest
• Never expose tokens in client-side code or logs
• Rotate tokens regularly for sensitive operations
• Handle token expiration by refreshing automatically

Working with multi-organization users

Tallyfy users can belong to multiple organizations¹. This matters for API integrations:

Organization context in API requests

• A user’s access token is tied to their current organization
• API requests operate within that organization’s context
• Organization IDs are required in most API endpoint URLs (e.g., /organizations/{org_id}/checklists)

Collecting organization IDs

When building integrations:

1. Collect the organization ID during setup
2. Store it alongside user credentials in your app
3. Include it in your API request URLs

Multiple organizations

For users belonging to more than one organization:

1. Let users pick which organization to work with
2. Store multiple organization IDs if your app spans organizations
3. Permissions and data differ between organizations
4. You may need updated tokens when switching organizations

Organization switching

Users can switch organizations in the Tallyfy UI. Learn more in Switch between organizations.

Getting access tokens with password grant

Getting 401 “Unauthenticated” errors despite having valid client credentials? You likely need the password grant flow.

Grant type selection

The client_credentials grant type won’t provide tokens that work for user-specific endpoints. For standard API endpoints requiring user context, you must use the password grant type.

1. Make a POST request to the OAuth token endpoint:

POST https://go.tallyfy.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
username=YOUR_EMAIL&
password=YOUR_PASSWORD

2. You’ll get a response with an access token:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGci...",
  "refresh_token": "def50200..."
}

3. Use this token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Security note

The password grant requires transmitting user credentials. Only use this in secure server-side environments where you control both the client app and user accounts.

Understanding grant types

Grant type	Purpose	Access context	Best for
client_credentials	App-to-app authentication	Application context only	Backend services, system integrations
password	User-based access via application	Full user context	Endpoints requiring user permissions

Key distinction: Most Tallyfy API endpoints require user context, so password grant is usually what you need. If you’re getting 401 errors with a client_credentials token, switch to password grant.

Token refresh

Access tokens expire after 1 hour and need refreshing:

1. Store both the access_token and refresh_token when first obtained
2. When the access token expires, POST to the token endpoint with your refresh token
3. You’ll receive a new access token (and sometimes a new refresh token)

This video shows the token refresh process:

Troubleshooting authentication

401 unauthenticated errors

1. Token format: Make sure your Authorization header is exactly:

   Authorization: Bearer YOUR_ACCESS_TOKEN

   There must be exactly one space between “Bearer” and your token.

2. Token expiration: Tokens expire after 1 hour. Refresh or request a new one.

3. Invalid credentials: Double-check your client ID, client secret, username, and password.

4. Missing headers: Every request needs the X-Tallyfy-Client: APIClient header.

5. Wrong token endpoint: Confirm you’re hitting https://go.tallyfy.com/api/oauth/token with the correct grant_type.

6. Logout invalidation: Personal tokens are immediately invalidated on logout. If your automation stops working, check whether the user logged out.

If problems persist, check the response body for specific error messages or contact Tallyfy Support with your full error response.

CORS or preflight issues

For cross-origin challenges:

• Watch for CORS preflight (OPTIONS) requests
• Check response headers for CORS permissions
• Verify allowed origins and methods

Preventing duplicate operations

Implement idempotency

External systems might send duplicate requests from network retries, user errors, or repeated webhook events. Implement idempotency handling to prevent unintended duplicate operations - especially when:

• Launching processes from external triggers
• Updating task form fields
• Completing tasks programmatically

Date format standards

When working with dates in the Tallyfy API:

Direction	Format	Example
Request (to API)	YYYY-MM-DD HH:MM:SS	2025-05-15 14:30:00
Response (from API)	ISO 8601 (Zulu time)	2025-05-15T14:30:00.000Z

Make sure your code handles both formats correctly.

Webhook integration

For event-driven integrations, Tallyfy offers webhooks that don’t require polling the API:

• Configure webhooks at the process or step level
• Get real-time notifications when specific events happen
• Process the webhook payload to trigger actions in your systems

For setup details, see the webhooks setup guide.

Related articles

Integrations > Open API

Tallyfy’s REST API gives developers full programmatic access to the same platform features that power its web app — including process management and task operations and template control and data export — with three authentication methods and standard JSON responses and required headers for every request.

Code Samples > Authentication methods

Tallyfy API authentication requires either a personal access token (from Settings lasting 6 months) or a client credentials OAuth flow (using client ID and secret for 7-day tokens) and every request must include Authorization Bearer token along with Accept and X-Tallyfy-Client headers to work properly.

Open Api > API usage as a third-party application instead of a user

Third-party apps can access Tallyfy’s API through an OAuth 2.0 client credentials flow where the app first obtains an application-level token using a client ID and secret and then exchanges it for user-specific tokens to perform workflow actions on behalf of individual users within a paid organization.

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.

Footnotes

1. Organizations in Tallyfy are isolated tenants - each with its own templates, processes, members, and settings ↩

Was this helpful?

YesNo