Skip to content

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 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

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:

  1. Make a POST request to the OAuth token endpoint:
Terminal window
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
  1. You’ll receive a response with an access token:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJhbGci..."
}
  1. Use this token in subsequent API requests in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN

Understanding grant types

Grant TypePurposeAccess ContextSuitable For
client_credentialsApplication-to-application authenticationApplication context onlyBackend services, system integrations
passwordUser-based access via applicationFull user contextAPIs 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
Token refresh request example

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

Date format standards

When working with dates in the Tallyfy API:

DirectionFormatExample
Request (to API)YYYY-DD-MM HH:MM:SS2023-15-05 14:30:00
Response (from API)YYYY-MM-DDThh:mm:ss.000Z2023-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.

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.

Authentication > Use the Client Credentials Flow

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