Integrate with Tallyfy using the API

Tallyfy API Integration Guide

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

API Documentation

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

API terminology

While the Tallyfy web application uses certain terms in its user interface, the underlying API sometimes uses different terms for the same concepts. Understanding these differences is important when working directly with the API.

Here’s a mapping of key API objects to their corresponding terms in the Tallyfy UI:

• API Checklists correspond to Blueprints in the UI. A Blueprint contains Steps.
• API Runs correspond to Processes in the UI. A Process contains Tasks.
• API Captures correspond to Task form fields in the UI.
• API Preruns correspond to Kick-off form fields in the UI.

Keeping these distinctions in mind will help you navigate the API documentation and map API data to what users see in the Tallyfy application.

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.

CORS or preflight issues

For cross-origin implementation challenges:

• Note any CORS preflight (OPTIONS) requests
• Check response headers for CORS permissions
• Understand allowed origins and methods

Preventing duplicate operations

Implement idempotency

When integrating with the Tallyfy API, external systems might send duplicate requests due to network retries, user errors, or webhook events firing multiple times. Implement idempotency handling to ensure operations aren’t performed multiple times unintentionally. This is especially important 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-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

Integrations > Open API

The Tallyfy REST API enables developers to build custom integrations access core platform features and automate workflows through secure authentication methods while adhering to rate limits and technical requirements for making API requests.

Open Api > OAuth authorization flow for third-party applications

A comprehensive guide for implementing OAuth authorization flow in third-party applications that enables secure user authentication with Tallyfy through client IDs redirect URIs and access tokens while following security best practices and handling multi-organization scenarios.

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

A detailed walkthrough for integrating third-party applications with Tallyfy API using client credentials to make API requests and manage users through secure token-based authentication and authorization flows.

Authentication > Use the Client Credentials Flow

OAuth 2.0 Client Credentials flow enables secure machine-to-machine authentication for third-party applications to access Tallyfy API functionality through client ID and secret tokens while supporting user provisioning and system-level integrations.