Integrate with Tallyfy using the API

Tallyfy API Integration Guide

Tallyfy provides a comprehensive REST API that enables developers to integrate workflow functionality into external applications and systems. This guide covers the essential steps and requirements for successful API integration.

API Documentation

Complete API reference documentation is available at https://go.tallyfy.com/api/ ↗

Required Headers

All direct API calls to Tallyfy endpoints must include the following header:

X-Tallyfy-Client: APIClient

Important: Requests without this header will be automatically rejected.

Authentication Methods

Tallyfy supports two authentication approaches depending on your integration scenario:

1. User-Based Authentication

For integrations acting on behalf of a specific Tallyfy user:

1. Navigate 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 demonstrates how to obtain your access token:

2. Application-Based Authentication

For third-party applications or dedicated integrations requiring client credentials:

1. Contact Tallyfy Support with details about your integration requirements
2. Receive your application’s Client ID and Client Secret
3. Implement the OAuth 2.0 flow to obtain and refresh access tokens

Working with Multi-Organization Users

Tallyfy supports users belonging to multiple organizations (tenants). This has important implications for API integrations:

Organization Context in API Requests

• A user’s access token is tied to their current organization context
• API requests will operate within the organization context associated with the token
• Organization IDs are required in many API endpoints

Collecting and Storing Organization IDs

When building integrations that require organization-specific data:

1. Collect the organization ID during user onboarding or application setup
2. Store this ID alongside user credentials in your application
3. Include the organization ID in relevant API requests

Handling Users with Multiple Organizations

For users who belong to multiple organizations:

1. Consider allowing users to select which organization they want to work with
2. Store multiple organization IDs if your application needs to work across organizations
3. Be aware that permissions and available data may vary between organizations
4. For users switching between organizations, you may need to update tokens or credentials

Organization Switching

Users can switch between organizations in the Tallyfy interface using the Organization Switcher. Learn more in Switch Between Organizations.

Obtaining Access Tokens with Password Grant

If you’re receiving a 401 “Unauthenticated” error despite having valid client credentials, you may need to use the password grant authentication flow:

Grant Type Selection

The client_credentials grant type will not provide access tokens that work for user-specific endpoints. For accessing standard API endpoints that require user context, you must use the password grant type as shown below.

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=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

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

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

3. Use this token in subsequent API requests in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Security Note

The password grant type requires transmitting user credentials. Use this method only in secure environments where you control both the client application and user accounts.

Understanding Grant Types

Grant Type	Purpose	Access Context	Suitable For
client_credentials	Application-to-application authentication	Application context only	Backend services, system integrations
password	User-based access via application	Full user context	APIs requiring user permissions, accessing user data

Important distinction:

• Tokens obtained with client_credentials grant type can only access endpoints that don’t require user context
• Most Tallyfy API endpoints require user context, so the password grant is necessary for accessing these endpoints
• If you’re getting 401 “Unauthenticated” errors when using an access token from client_credentials, switch to the password grant type

Token Refresh Procedure

Access tokens expire periodically and must be refreshed for continued API access:

1. Store both the access_token and refresh_token when first obtained
2. When the access token expires, use the refresh token to obtain a new one
3. Send a POST request to the token endpoint with your refresh token

This video demonstrates the token refresh process:

Troubleshooting Authentication Issues

If you encounter authentication problems when using the Tallyfy API, check these common issues:

401 Unauthenticated Errors

1. Invalid Token Format: Ensure your Authorization header uses the exact format:

   Authorization: Bearer YOUR_ACCESS_TOKEN

   Note: There should be exactly one space between “Bearer” and your token.

2. Token Expiration: Tokens typically expire after 1 hour. Implement token refresh logic or request a new token.

3. Invalid Credentials: Verify your client ID, client secret, username, and password are correct.

4. Missing Required Headers: Ensure all API requests include the X-Tallyfy-Client: APIClient header.

5. Incorrect Token Request: When requesting a token, verify:

   • You’re using the correct endpoint (https://go.tallyfy.com/api/oauth/token)
   • The grant_type parameter matches your authentication flow
   • All required parameters for your grant type are included

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

Date Format Standards

When working with dates in the Tallyfy API:

Direction	Format	Example
Request (to API)	YYYY-DD-MM HH:MM:SS	2023-15-05 14:30:00
Response (from API)	YYYY-MM-DDThh:mm:ss.000Z	2023-05-15T14:30:00.000Z

Ensure your code properly handles these date format conventions to avoid errors.

Webhook Integration

For event-driven integrations, Tallyfy provides webhook capabilities that don’t require direct API calls:

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

For details on webhook configuration, see the webhooks setup guide.

Related articles

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

The guide outlines the integration process between third-party applications and Tallyfy API using client credentials flow to enable programmatic user provisioning and API request handling through application-level and user-specific access tokens.

Integrations > Open API

The Tallyfy REST API enables programmatic access to platform functionality through user-based or application authentication with features for process management task operations user administration template management data access and file operations.

Open Api > OAuth authorization flow for third-party applications

A comprehensive guide to implementing OAuth authorization flow for third-party applications to authenticate users with Tallyfy using secure token-based authentication and proper handling of multi-organization scenarios.

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

Organizations can seamlessly integrate Tallyfy into their applications by provisioning users and making API requests on their behalf through client credentials and user-specific access tokens.