Skip to content
Developers

API integration guide

Your own applications and systems can launch processes, complete tasks and update form fields in Tallyfy through its REST API. Every call needs three headers, and one of them carries an access token.

The Tallyfy API uses different names than what you’ll see in the web app. Here’s the mapping you’ll need when reading API responses, building integrations, or browsing the API reference ↗:

What users see in the appAPI endpointOther names you might see in code or older docs
Template/checklistsBlueprint, checklist
Process/runsRun, workflow
Step (inside a template)/stepsStep
Task (inside a running process)/tasksTask
Task form field/form-fieldsCapture, form field
Kick-off form field/prerunsPrerun, KO form, kick-off form
Comment or issue on a process/runs/{id}/comment, /runs/{id}/problem, /runs/{id}/resolved-threadsThread
Comment or issue on a template/checklists/{id}/comment, /checklists/{id}/problem, /checklists/{id}/resolved-threadsThread

A template “becomes” a process when launched. A step “becomes” a task once the process is running. Form fields collect data inside tasks; kick-off form fields collect data before a process starts.

These name differences are historical and only show up when reading API responses or older code. The Tallyfy app itself only uses the user-facing names (Template, Process, Task, etc.).

Every API call must include these headers:

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

Important: Tallyfy rejects requests without the X-Tallyfy-Client header.

Tallyfy supports two authentication approaches:

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:

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

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

Getting, using and refreshing an API token1. App requests a tokenwith its credentials2. Tallyfy returnsthe access token3. App calls the API withBearer token and headersToken stillvalid?4. API sendsthe response5. App refreshes, orasks for a new token6. Tallyfy returns anew access token Yes No, 401Retry

What to notice:

  • Steps 1-2 show initial authentication - use password grant for user context or client credentials for app-only access
  • Step 3 shows required headers for all API requests - both Authorization and X-Tallyfy-Client headers are mandatory
  • Steps 5-6 show getting a new token after a 401 error. A password grant token can be refreshed with its refresh token; a client credentials token has none, so request a new one. Your app should handle this retry automatically

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

  1. Automated systems: Use application tokens instead of personal tokens when possible. Any paid organization can have them, but not during a free trial, and Tallyfy Support sets them up
  2. User-based integrations: Tell users that logging out of Tallyfy stops their automations. Your error handling should spot the 401 an invalidated token returns, and show the user how to copy a new token from Settings > Integrations > REST API.
  3. Monitoring: Log each authentication failure with the user whose token failed. When one user’s calls all start failing at once, check whether that person logged out.
  • Encrypt tokens wherever you store them.
  • Never put a token in client-side code or a log. Anyone who can read it can call the API as its owner until it expires, and a personal access token lasts 6 months.
  • For sensitive operations, replace tokens on your own schedule, before they expire.
  • Refresh expired access tokens automatically.

Tallyfy users can belong to multiple organizations1, so your integration has to know which organization each call is for.

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

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

Let each user pick which organization your app works in, and store an ID for every organization your app spans. Permissions and data differ between organizations, and you may need updated tokens when a user switches.

Getting 401 “Unauthenticated” errors despite having valid client credentials? You likely need the password grant 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=password&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
username=YOUR_EMAIL&
password=YOUR_PASSWORD
  1. You’ll get a response with an access token:
{
"token_type": "Bearer",
"expires_in": 15724800,
"access_token": "eyJhbGci...",
"refresh_token": "def50200..."
}
  1. Use this token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN
Grant typePurposeAccess contextBest for
client_credentialsApp-to-app authenticationApplication context onlyBackend services, system integrations
passwordUser-based access via applicationFull user contextEndpoints 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.

A password grant access token lasts about 6 months, and its refresh token about 12 months. When the access token runs out, refresh it:

  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)
Swagger docs for Tallyfy OAuth 2.0 POST /oauth/token endpoint

This video shows the token refresh process:

  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: An access token lasts about 6 months (a client_credentials token, 7 days). Refresh it 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 errors only come from browsers. Every Tallyfy call carries custom headers, so before a cross-origin call the browser first sends a preflight OPTIONS request, and it reuses a passed one for up to 2 hours. If the preflight fails, the real call never goes out. Read the Access-Control-Allow-Origin, Access-Control-Allow-Methods and Access-Control-Allow-Headers headers on the preflight response to see what’s allowed. A custom header that isn’t in that list fails the preflight. A few basic headers, such as Accept, don’t need to be listed. Server-side code doesn’t send preflight requests.

The API reads dates in one format and returns them in another:

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

Descriptions that reference form fields or people

Section titled “Descriptions that reference form fields or people”

The summary, title, guidance, default_value and content parameters accept HTML, and inside that HTML you can reference a form field’s answer, a snippet, another template, or a person. Each reference type is a specific piece of markup carrying a specific identifier.

Send the wrong shape and the API still accepts it, so nothing tells you it was wrong. See rich text references for the exact markup, where to read each identifier from the API, and what happens when a reference stops resolving.

Webhooks tell your system when something happens in Tallyfy, so you don’t have to poll the API. A webhook set on a template fires when a process launches, when any of its steps is completed, and when the process is completed. A webhook set on one step fires only when that step is completed. Each one POSTs a JSON payload to your URL for your system to act on.

For setup details, see the webhooks setup guide.

If your team has developers and clear requirements, an AI assistant can draft working integration code for you. Use it when you want custom logic beyond what middleware offers, and you need it quickly.

  1. Write a precise spec of the workflow and the data mappings.
  2. Ask your AI assistant to generate code that calls Tallyfy’s Open API.
  3. Review, test, and deploy the code.
  4. When the rules change, update the spec first, then have the AI revise the code and test it again.

Tell it which language your team uses, such as Python or JavaScript. Ask it to log every API call and to handle errors, including a 401 from an expired token.

For example, a logistics team whose shipping steps vary by weight, destination and carrier writes a spec for one shipping template. Weight, destination and carrier are kick-off fields, and rules show each carrier’s steps only when that carrier is picked. The AI drafts Python code that launches a process from that template for each shipment, and a developer tests it before it goes live.

Integrations > Open API

Tallyfy’s REST API gives developers full programmatic access to the same platform features that…
  1. Organizations in Tallyfy are isolated tenants - each with its own templates, processes, members, and settings ↩