# FreeAgent > Source: https://truto.one/docs/integration-guides/freeagent/ ## Install FreeAgent integration The FreeAgent integration can be found [here](https://app.truto.one/integrations/available/1df4a2d8-7ea8-467f-b6d4-4bac2716a4c1). Please install it in your environments before proceeding with the steps below. ## Connecting a FreeAgent account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their FreeAgent account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select FreeAgent ![Select FreeAgent](https://docs-assets.truto.one/select-freeagent.png) 5. You'll now be asked to log in to your FreeAgent account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new FreeAgent integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Clay HR > Source: https://truto.one/docs/integration-guides/clayhr/ ## Install the Clay HR integration The Clay HR integration can be found [here](https://app.truto.one/integrations/available/631370cb-7aae-4514-a461-ea8e29efc25e). Please install it in your environments before proceeding with the steps below. ## Connecting a Clay HR account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Clay HR account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Clay HR ![Select Clay HR](https://docs-assets.truto.one/select-ClayHR.png) ## Finding your Clay HR account 5. You'll now be prompted to add the Clay HR API Key, User ID, and company. Use [this](https://www.clayhr.com/articles/how-to-interact-with-clayhr-apis) guide from the Clay HR team to get the details. Once you have added all the details, click **Connect** ![Find your Clay HR account details](https://docs-assets.truto.one/ClayHR-details-1.png) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Clay HR integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Intercom > Source: https://truto.one/docs/integration-guides/intercom/ ## Install Intercom integration The Intercom integration can be found [here](https://app.truto.one/integrations/available/09044dd1-f73d-46a4-8050-8e1d14f18282). Please install it in your environments before proceeding with the steps below. ## Connecting an Intercom account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Intercom account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Intercom ![Select Intercom](https://docs-assets.truto.one/select-intercom.webp) 5. You'll now be asked to log in to your Intercom account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Intercom integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Box > Source: https://truto.one/docs/integration-guides/box/ ## Install Box integration The Box integration can be found [here](https://app.truto.one/integrations/available/bb7f3485-5e97-4513-b404-423ac0ebf039). Please install it in your environments before proceeding with the steps below. ## Connecting a Box account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Box account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Box ![Select Box](https://docs-assets.truto.one/select-box.png) 5. You'll now be asked to log in to your Box account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Box integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Jenkins > Source: https://truto.one/docs/integration-guides/jenkins/ ## Install Jenkins integration The Jenkins integration can be found [here](https://app.truto.one/integrations/available/7281a97d-8613-4421-9bce-45d5ff9f1333). Please install it in your environments before proceeding with the steps below. ## Connecting a Jenkins account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Jenkins account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Jenkins !['Select Jenkins'](https://docs-assets.truto.one/select-jenkins.png) ### Finding your API Token and Base URL :::callout{type="warning"} `Admin` role is required to use this API ::: You'll now be prompted to add the API Token, Username and Base URL. 1. To find the API Token, Username and Base URL. Sign in to your Jenkins account and enter the Username which you will use while logging in to Jenkins in Truto. 2. Copy the part of Base URL as shown below and enter it in Truto. !['Copy Jenkins URL'](https://docs-assets.truto.one/jenkins-url.png) 3. On top right, click on your name as shown below. !['Click on name on top right'](https://docs-assets.truto.one/admin-jenkins.png) 4. In the left navigation bar, click on `Configure`. !['Click on Configure'](https://docs-assets.truto.one/configure-jenkins.png) 5. Now, under the `API Token` Section, click on `Add new Token` and after completing this process, copy your API Token and paste it in Truto and click `Connect`. !['Create API Token'](https://docs-assets.truto.one/create-token-jenkins.png) ::: tip Integration should be Re-Authorized with new API Token every 6 Months ::: !['Jenkins Client ID and Client Secret'](https://docs-assets.truto.one/details-jenkins.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Jenkins Integrated Account'](https://docs-assets.truto.one/account-jenkins.png) ## Uninstalling the Jenkins integration To uninstall the Jenkins integration from your Truto account, select the Jenkins [integration](https://app.truto.one/integrations/installed?search=Jenkins) from the Integrations tab. Click on the `Settings` tab in Jenkins Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Jenkins integrated accounts from your Truto account. !['Uninstall Jenkins'](https://docs-assets.truto.one/uninstall-jenkins.png) --- # Paypal > Source: https://truto.one/docs/integration-guides/paypal/ ## Install Paypal integration The Paypal integration can be found [here](https://app.truto.one/integrations/available/5900d9c4-4471-4f36-84a4-15293cb7e978). Please install it in your environments before proceeding with the steps below. ## Connecting a Paypal account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Paypal account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Paypal !['Select Paypal'](https://docs-assets.truto.one/select-paypal.png) ### Finding your Client ID and Client Secret You'll now be prompted to add the Client ID and Client Secret. 1. To find the Client ID and Client Secret, Sign in to your PayPal account. !['Sign in to Paypal'](https://docs-assets.truto.one/Login-paypal.jpg) 2. Click on the `developer` button at the top right. !['Click on developer button in Paypal'](https://docs-assets.truto.one/Developer-button-paypal.png) 3. Under `my apps & credentials`, choose `live` and then the `create app` option. !['Click on live and create app'](https://docs-assets.truto.one/switchtolive-paypal.jpg) 4. Enter an app name (such as PayPal API for Truto) and select `merchant`. !['Enter App name'](https://docs-assets.truto.one/App-name-Merchant-paypal.jpg) 5. After completing this process, copy your Client ID and Client Secret and paste them into the relevant fields in Truto and click `Connect`. !['Copy Client ID and Client Secret'](https://docs-assets.truto.one/Client-ID-secret-paypal.jpg) !['Paypal Client ID and Client Secret'](https://docs-assets.truto.one/details-paypal.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Paypal Integrated Account'](https://docs-assets.truto.one/account-paypal.png) ## Uninstalling the Paypal integration To uninstall the Paypal integration from your Truto account, select the Paypal [integration](https://app.truto.one/integrations/installed?search=paypal) from the Integrations tab. Click on the `Settings` tab in Paypal Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Paypal integrated accounts from your Truto account. !['Uninstall Paypal'](https://docs-assets.truto.one/uninstall-paypal.png) --- # GetResponse > Source: https://truto.one/docs/integration-guides/getresponse/ ## Install GetResponse integration The GetResponse integration can be found [here](https://app.truto.one/integrations/available/4b67d401-9b40-4cd7-a687-0c5334a1fd5e). Please install it in your environments before proceeding with the steps below. ## Connecting a GetResponse account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their GetResponse account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select GetResponse ![Select GetResponse](https://docs-assets.truto.one/select-getresponse.png) 5. You'll now be asked to log in to your GetResponse account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new GetResponse integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Workable > Source: https://truto.one/docs/integration-guides/workable/ ## Install Workable integration The Workable integration can be found [here](https://app.truto.one/integrations/available/fd705c63-01f0-4a05-9039-06391a586cea). Please install it in your environments before proceeding with the steps below. ## Connecting a Workable account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Workable account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Workable ![Select Workable](https://docs-assets.truto.one/select-workable.png) 5. You'll now be asked to key-in in your Workable API Access Token and the subdomain to allow access to Truto. Go through the following steps. ![Enter Workable API Access Token](https://docs-assets.truto.one/workable-api-access-token.png) ## Generating a Workable API Access Token :::callout{type="warning"} - It's recommended that an administrator of your Workable account generates the API Access Token. ::: Refer the official Workable documentation to [generate the API Access token](https://workable.readme.io/reference/generate-an-access-token). The scopes required for the Workable integration are: - For ATS related functionality - `r_jobs` - `r_requisitions` - `r_offers` - `r_candidates` - For HRIS related functionality - `r_employees` - `r_account` If write functionality needs to be added, then add the corresponding write scopes as well, which start with `w_`. 6. Key in the API Access Token and the subdomain and click on **Connect** ![Enter Workable API Access Token](https://docs-assets.truto.one/enter-workable-api-access-token.png) 7. _Voila!_ You should now see a connection successful message. You can now close this tab. 8. Go to your Truto account, and you should see the new Workable integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Microsoft Dynamics 365 Sales > Source: https://truto.one/docs/integration-guides/dynamics365sales/ ## Install Microsoft Dynamics 365 Sales integration The Microsoft Dynamics 365 Sales integration can be found [here](https://app.truto.one/integrations/available/d973b1ac-83bf-4afc-86a0-bcf30c9ee553). Please install it in your environments before proceeding with the steps below. ## Connecting a Microsoft Dynamics 365 Sales account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Microsoft Dynamics 365 Sales account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Microsoft Dynamics 365 Sales ![Select Microsoft Dynamics 365 Sales](https://docs-assets.truto.one/select-d365sales.webp) 5. You'll now be asked for your 365 Sales **Account**. Fill in the details and click **Connect**. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Microsoft Dynamics 365 Sales integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Atlassian > Source: https://truto.one/docs/integration-guides/atlassian/ ## Install Atlassian integration The Atlassian integration can be found [here](https://app.truto.one/integrations/available/d47020bd-0c09-471a-b902-59cd0901a2e1). Please install it in your environments before proceeding with the steps below. ## Connecting an Atlassian account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Atlassian account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Atlassian !['Select Atlassian'](https://docs-assets.truto.one/select-atlassian.png) ### Finding your API Key and Organization ID --- ### Important Note - The [User Directory Activities API](https://truto.one/docs/api-reference/unified-user-directory-api/activities) resource will only work when `Atlassian Access` is enabled. - `Admin` role is required to use this API - To get data, you must verify a domain. Here is a [tutorial video link](https://www.youtube.com/watch?v=iLeOe2-7Cm4) on how to verify domains. --- You'll now be prompted to add the API Key and Organization ID. 1. To find the `API Key` and `Organization ID`. Sign in to your Atlassian account and go to `Settings`. !['Click on settings'](https://docs-assets.truto.one/atlassian-settings.png) 2. Under Settings, click on `API keys`. !['Click on api keys'](https://docs-assets.truto.one/atlassian-api-keys.png) 3. Now click on `Create API key` and enter `Name` and `Expires on` for API key. !['Click on Create API key'](https://docs-assets.truto.one/atlassian-api-key-button.png) 4. Now click on `Create`, copy `Organization ID` and `API key` values and paste it in Truto and click `Connect`. !['Click on Create API key'](https://docs-assets.truto.one/atlassian-create-key.png) !['Atlassian API Key and Organization ID'](https://docs-assets.truto.one/details-atlassian.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Integrated account'](https://docs-assets.truto.one/account-details-atlassian.png) ## Uninstalling the Atlassian integration To uninstall the Atlassian integration from your Truto account, select the Atlassian [integration](https://app.truto.one/integrations/installed?search=atlassian) from the Integrations tab. Click on the `Settings` tab in Atlassian Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Atlassian integrated accounts from your Truto account. !['Uninstall Atlassian'](https://docs-assets.truto.one/uninstall-atlassian.png) --- # Pipedrive > Source: https://truto.one/docs/integration-guides/pipedrive/ ## Install Pipedrive integration The Pipedrive integration can be found [here](https://app.truto.one/integrations/available/83c8d226-92fe-4240-adf6-93c8dfcffa8b). Please install it in your environments before proceeding with the steps below. ## Connecting a Pipedrive account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Pipedrive account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Pipedrive !['Select Pipedrive'](https://docs-assets.truto.one/select-pipedrive.webp) ## Finding your Pipedrive account You'll now be prompted to add your Pipedrive account details. Find the account from the URL in your browser as shown in the image below. Then click **Connect** !['Find the account from the URL'](https://docs-assets.truto.one/details-pipedrive-1.webp) !['Pipedrive API Key and Base URL'](https://docs-assets.truto.one/details-pipedrive.png) !['Pipedrive OAuth Screen'](https://docs-assets.truto.one/apikey-pipedrive.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the new integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. --- # BrowserStack > Source: https://truto.one/docs/integration-guides/browserstack/ ## Install BrowserStack integration The BrowserStack integration can be found [here](https://app.truto.one/integrations/available/05eaa0aa-488c-4ba7-af9a-e9bb626bc61e). Please install it in your environments before proceeding with the steps below. ## Connecting a BrowserStack account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their BrowserStack account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select BrowserStack. ![Select BrowserStack](https://docs-assets.truto.one/select-browserstack.png) 5. You'll now be asked for your BrowserStack Access Key and Username. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new BrowserStack integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # FreshBooks > Source: https://truto.one/docs/integration-guides/freshbooks/ ## Install FreshBooks integration The FreshBooks integration can be found [here](https://app.truto.one/integrations/available/155fb303-98d8-4f77-8a55-3cf82d1746af). Please install it in your environments before proceeding with the steps below. ## Connecting a FreshBooks account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their FreshBooks account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select FreshBooks ![Select FreshBooks](https://docs-assets.truto.one/select-freshbooks.png) 5. You'll now be asked to log in to your FreshBooks account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new FreshBooks integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # ActiveCampaign > Source: https://truto.one/docs/integration-guides/activecampaign/ ## Install ActiveCampaign integration The ActiveCampaign integration can be found [here](https://app.truto.one/integrations/available/ad4cce5f-b28e-463b-ae5f-82a4cf88d01a). Please install it in your environments before proceeding with the steps below. ## Connecting an ActiveCampaign account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their ActiveCampaign account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select ActiveCampaign !['Select ActiveCampaign'](https://docs-assets.truto.one/select-activecampaign.webp) ## Finding your Base URL and API Key You'll now be prompted to add the Base URL and API Key. To find the Base URL and API Key, go to your ActiveCampaign account. Click on `Settings > Developer`. Copy the `API Url` and `API Key` and paste them into the relevant fields in Truto and click `Connect` !['ActiveCampaign Get API Key'](https://docs-assets.truto.one/apikey-activecampaign.png) !['ActiveCampaign API Key and Base URL'](https://docs-assets.truto.one/details-activecampaign.webp) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. !['Connection successful'](https://docs-assets.truto.one/success-activecampaign.webp) 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['ActiveCampaign Integrated Account'](https://docs-assets.truto.one/account-activecampaign.webp) ## Uninstalling the ActiveCampaign integration To uninstall the ActiveCampaign integration from your Truto account, select the ActiveCampaign [integration](https://app.truto.one/integrations/installed?search=activecampaign) from the Integrations tab. Click on the `Settings` tab in ActiveCampaign Integration page And then click on Uninstall. Uninstalling the integration will also remove all the ActiveCampaign integrated accounts from your Truto account. !['Uninstall ActiveCampaign'](https://docs-assets.truto.one/uninstall-activecampaign.png) --- # Help Scout > Source: https://truto.one/docs/integration-guides/helpscout/ ## Install Help Scout integration The Help Scout integration can be found [here](https://app.truto.one/integrations/available/1fa47bf3-5f1f-4b65-bcd0-8d07ab455e15). Please install it in your environments before proceeding with the steps below. ## Connecting a Help Scout account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Help Scout account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Help Scout ![Select Help Scout](https://docs-assets.truto.one/select-help-scout.webp) 5. You'll now be asked to log in to your Help Scout account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Help Scout integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Notion > Source: https://truto.one/docs/integration-guides/notion/ ## Install Notion integration The Notion integration can be found [here](https://app.truto.one/integrations/available/3e1e62de-2157-4c0c-9273-b9e6a2d6105d). Please install it in your environments before proceeding with the steps below. ## Connecting a Notion account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Notion account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Notion ![Select Notion](https://docs-assets.truto.one/select-notion.webp) 5. You'll now be asked to log in to your Notion account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Notion integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zoho Analytics > Source: https://truto.one/docs/integration-guides/zohoanalytics/ ## Install Zoho Analytics integration The Zoho Analytics integration can be found [here](https://app.truto.one/integrations/available/b61e1bc4-183c-4b50-a30c-67a695f3f9f2). Please install it in your environments before proceeding with the steps below. ## Connecting a Zoho Analytics account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zoho Analytics account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zoho Analytics ![Select Zoho Analytics](https://docs-assets.truto.one/select-zoho-analytics.webp) ## Finding your Zoho Analytics Organization ID 5. You'll now be prompted to add the **Zoho Organization ID**'. Find the Zoho Organization ID from the Zoho Analytics website URL in your browser as shown in the images below. Then click **Connect** ![Zoho Analytics setting navigation screen](https://docs-assets.truto.one/zoho-analytics-details-1.webp) ![Find the orgnization ID from the URL](https://docs-assets.truto.one/zoho-analytics-details-2.webp) ![Key in the organization ID on the Truto dialog box](https://docs-assets.truto.one/zoho-analytics-details-3.webp) 6. Go through the login flow. Next click on **Accept** ![Zoho authorization screen](https://docs-assets.truto.one/zoho-analytics-details-4.webp) 7. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Zoho Analytics integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Azure DevOps > Source: https://truto.one/docs/integration-guides/azuredevops/ ## Install Azure DevOps integration The Azure DevOps integration can be found [here](https://app.truto.one/integrations/available/0540c61c-fa1f-44dd-b474-f55087184769). Please install it in your environments before proceeding with the steps below. ## Connecting an Azure DevOps account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Azure DevOps account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Azure DevOps ![Select Azure DevOps](https://docs-assets.truto.one/select-ado.png) ### Finding your Organization Name - When you Login to your Azure DevOps account, the URL will have the name of the organization as shown below. ![URL Azure DevOps](https://docs-assets.truto.one/url-ado.png) ### Prerequisites 1. Go to the following [link](https://dev.azure.com/) to enable the API Access from Azure DevOps and click on `Organization Settings` present in bottom-left as shown below. ![Organization Settings Azure DevOps](https://docs-assets.truto.one/org-ado.png) 2. Now enable `Third-party application access via OAuth` under `Policies` as shown below. ![Enable OAuth in Policies](https://docs-assets.truto.one/policies-ado.png) --- 5. You'll now be asked to log in to your Azure DevOps account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Azure DevOps integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Google Drive > Source: https://truto.one/docs/integration-guides/googledrive/ ## Install Google Drive integration The Google Drive integration can be found [here](https://app.truto.one/integrations/07a22ccf-a765-4ecd-92c1-83f899e98087). Please install it in your environments before proceeding with the steps below. ## Connecting a Google Drive account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Google Drive account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Google Drive ![Select Google Drive](https://docs-assets.truto.one/select-googledrive.png) 5. You'll now be asked to log in to your Google Drive account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Google Drive integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Linear > Source: https://truto.one/docs/integration-guides/linear/ ## Install Linear integration The Linear integration can be found [here](https://app.truto.one/integrations/available/83c8d226-92fe-4240-adf6-93c8dfcffa8b). Please install it in your environments before proceeding with the steps below. ## Connecting a Linear account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Linear account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Linear ![Select Linear](https://docs-assets.truto.one/select-linear.png) 5. You'll now be asked to log in to your Linear account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Linear integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # HR Cloud > Source: https://truto.one/docs/integration-guides/hrcloud/ ## Install HR Cloud integration The HR Cloud integration can be found [here](https://app.truto.one/integrations/4b7aae56-8581-4fcb-8a3f-930b772aa8b3). Please install it in your environments before proceeding with the steps below. ## Connecting a HR Cloud account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their HR Cloud account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select HR Cloud ![Select GitHub](https://docs-assets.truto.one/select-hrcloud.png) 5. You'll now be asked for your HR Cloud `Customer Key` and `Customer Secret`. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new HR Cloud integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Dropbox > Source: https://truto.one/docs/integration-guides/dropbox/ ## Install Dropbox integration The Dropbox integration can be found [here](https://app.truto.one/integrations/available/13d96651-3a61-46dd-9159-42df6817d8b1). Please install it in your environments before proceeding with the steps below. ## Creating a Dropbox app to use with Truto :::callout{type="warning"} This integration is built with Dropbox Business API in mind. So please make sure you connect a Dropbox Business account. ::: 1. Go to [Dropbox App Console](https://www.dropbox.com/developers/apps/create). 2. Select **Scoped access**, and then select **Full Dropbox** and finally enter a name for your app. Click on **Create app**. ![Create Dropbox app](https://docs-assets.truto.one/dropbox-create-oauth.png) 3. On the app details page, scroll down to OAuth 2 section and the Redirect URI. ![Dropbox redirect uri](https://docs-assets.truto.one/dropbox-redirect-uri.png) 4. Then move on to the Permissions tab and select the [permissions based on the Unified APIs](/docs/integration-guides/dropbox#unified-api-scopes) you want to use with this integration. [Refer the table below](/docs/integration-guides/dropbox#unified-api-scopes). ![Dropbox permissions](https://docs-assets.truto.one/dropbox-permissions-tab.png) 5. Go back to the **Settings** tab and copy the **App key** and **App secret** to enter into the Truto interface. ![Dropbox app key and secret](https://docs-assets.truto.one/dropbox-app-key-secret.png) ### Dropbox scopes to select based on the Unified APIs | Unified API | Scopes | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Unified User Directory API | account_info.read, team_info.read, team_data.member, members.read, groups.read | | Unified File Storage API | account_info.read, files.metadata.write, files.content.write, files.content.read, sharing.write, file_requests.write, contacts.write, team_info.read, team_data.member, team_data.team_space, files.team_metadata.write, files.team_metadata.read, members.read, groups.read | ## Connecting a Dropbox account :::callout{type="warning"} This integration is built with Dropbox Business API in mind. So please make sure you connect a Dropbox Business account. ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Dropbox account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Dropbox ![Select Dropbox](https://docs-assets.truto.one/select-dropbox.webp) 5. You'll now be asked to log in to your Dropbox account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Dropbox integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Airtable > Source: https://truto.one/docs/integration-guides/airtable/ ## Install Airtable integration The Airtable integration can be found [here](https://app.truto.one/integrations/available/2de25351-dbff-4c5e-896c-b47736120e12). Please install it in your environments before proceeding with the steps below. ## Connecting an Airtable account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Airtable account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Airtable ![Select Airtable](https://docs-assets.truto.one/select-airtable.webp) 5. You'll now be asked to log in to your Airtable account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Airtable integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Tailscale > Source: https://truto.one/docs/integration-guides/tailscale/ ## Install Tailscale integration The Tailscale integration can be found [here](https://app.truto.one/integrations/available/5bb26ecf-df98-46a7-b2e3-3adc575fd429). Please install it in your environments before proceeding with the steps below. ## Connecting a Tailscale account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Tailscale account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Tailscale !['Select Tailscale'](https://docs-assets.truto.one/select-tailscale.png) ### Finding your API Token and Tailnet You'll now be prompted to add the API Token and Tailnet. #### Tailnet 1. To find the Tailnet, Sign in to your Tailscale account. 2. You can find it in Header as shown below !['Header of Tailscale'](https://docs-assets.truto.one/tailnet-tailscale.png) #### API Token 1. To find the API Token, Sign in to your Tailscale account. 2. Click on the `Settings` button as shown below. !['Click on settings button'](https://docs-assets.truto.one/settings-tailscale.png) 3. Under `Settings`, click on `Keys`. !['Click on Keys under settings'](https://docs-assets.truto.one/keys-tailscale.png) 4. Under `API access tokens`, click on `Generate access token`. !['Click on generate access token'](https://docs-assets.truto.one/generate-token-tailscale.png) 5. Enter `Description` and click on `Generate access token`, You will find your API Token. !['Enter description and press on Generate access token'](https://docs-assets.truto.one/token-tailscale.png) 6. Enter your `API Token` and `Tailent`. Click on `Connect`. !['Tailscale API Token and Tailnet'](https://docs-assets.truto.one/details-tailscale.png) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Tailscale Integrated Account'](https://docs-assets.truto.one/account-tailscale.png) ## Uninstalling the Tailscale integration To uninstall the Tailscale integration from your Truto account, select the Tailscale [integration](https://app.truto.one/integrations/installed?search=tailscale) from the Integrations tab. Click on the `Settings` tab in Tailscale Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Tailscale integrated accounts from your Truto account. !['Uninstall Sentry'](https://docs-assets.truto.one/uninstall-tailscale.png) --- # Gorgias > Source: https://truto.one/docs/integration-guides/gorgias/ ## Install Gorgias integration You can start from the Gorgias App Store or from your Truto account. **From the Gorgias App Store** 1. In your Gorgias account, go to `Settings` → `App Store` → `All Apps`. 2. Find **Truto** in the list. 3. Select the app and click `Authorize`. 4. Log in to Truto, then follow the steps in [Connecting a Gorgias account](#connecting-a-gorgias-account) below. **From your Truto account** The Gorgias integration can be found [here](https://app.truto.one/integrations/available/83c8d226-92fe-4240-adf6-93c8dfcffa8b). Please install it in your environments before proceeding with the steps below. ## Connecting a Gorgias account 1. In your Truto account, go to `Integrated Accounts` and click `Connect Account`. ![Integrated accounts page with the Connect Account button](/images/docs/integration-guides/gorgias/01-connect-account.webp) *The `Connect Account` button is at the top right of the Integrated accounts page.* 2. Enter a Tenant ID, choose the Environment and Region, then click `Get connection link`. ![Connect an account modal](/images/docs/integration-guides/gorgias/02-connect-account-modal.webp) *The Tenant ID can be any ID of your choosing. You can also pick an existing tenant from the dropdown above it. For Region, pick where this integrated account should live: Western North America, Eastern North America, European Union or Asia Pacific.* 3. A connection link is generated. Click the open-in-new-tab icon next to the link. You can also copy the link and share it with your customers so they can connect their own Gorgias account. ![Generated connection link](/images/docs/integration-guides/gorgias/04-connection-link.webp) *Use the icon next to the link to open it in a new tab, or `Copy` to share it.* 4. Click `Get Started`. ![Get Started screen](/images/docs/integration-guides/gorgias/05-get-started.webp) *This screen explains how Truto keeps the connection secure.* 5. Search for Gorgias and select it. ![Select Gorgias from the integrations list](/images/docs/integration-guides/gorgias/06-select-gorgias.webp) *Type "gorgias" in the search box to find it quickly.* 6. Enter your Gorgias subdomain and click `Connect`. ![Enter your Gorgias subdomain](/images/docs/integration-guides/gorgias/07-enter-subdomain.webp) *Your subdomain is in your helpdesk URL. If the URL starts with `acme.gorgias.com`, enter `acme`.* 7. You'll now be asked to log in to your Gorgias account and allow access to Truto. Go through the steps. 8. _Voila!_ You should now see a connection successful message. You can now close this tab. 9. Go to your Truto account and you should see the new Gorgias integration under `Integrated Accounts`. Click on the `Account ID` to start calling the API. For example, you can enter a Gorgias ticket ID and pull that ticket's details in Truto. ## What to expect in Gorgias Connecting Truto does not create an HTTP integration in Gorgias, so the integration won't be visible in Gorgias. --- # Cloudflare > Source: https://truto.one/docs/integration-guides/cloudflare/ ## Install Cloudflare integration The Cloudflare integration can be found [here](https://app.truto.one/integrations/available/f1021931-e7ce-4198-8c2d-15a40e4b994a). Please install it in your environments before proceeding with the steps below. ## Connecting a Cloudflare account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Cloudflare account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Cloudflare !['Select Cloudflare'](https://docs-assets.truto.one/select-cloudflare.png) ### Finding your API Key You'll now be prompted to add the API Key. 1. To find the Token, Sign in to your Cloudflare account. 2. Click [here](https://dash.cloudflare.com/profile/api-tokens) and then click on `Create Token`. !['Click on create token'](https://docs-assets.truto.one/create-token-cloudflare.png) 3. After this go to Custom token and click on `Get started`. !['Click on get started under custom token'](https://docs-assets.truto.one/custom-token-cloudflare.png) 4. Enter `Name` of the API token. !['Enter name'](https://docs-assets.truto.one/token-name-cloudflare.png) 5. Give Permissions exactly as shown below. !['Give the permission account → account settings → read'](https://docs-assets.truto.one/permission-cloudflare.png) 6. Select account to be included after selecting required permissions. !['Select an account'](https://docs-assets.truto.one/select-account-cloudflare.png) :::warning Please do not leave it as `Include: All accounts`. If account is not selected then API might not work properly. ::: 7. Now, click on `Continue to summary` and Copy your `API Key`. !['Copy the access token'](https://docs-assets.truto.one/continue-cloudflare.png) !['Cloudflare API Key'](https://docs-assets.truto.one/details-cloudflare.png) 5. Enter your `API Key`. Click on `Connect`. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Cloudflare Integrated Account'](https://docs-assets.truto.one/account-cloudflare.png) ## Uninstalling the Cloudflare integration To uninstall the Cloudflare integration from your Truto account, select the Cloudflare [integration](https://app.truto.one/integrations/installed?search=cloudflare) from the Integrations tab. Click on the `Settings` tab in Cloudflare Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Cloudflare integrated accounts from your Truto account. !['Uninstall Cloudflare'](https://docs-assets.truto.one/uninstall-cloudflare.png) --- # Adobe Sign > Source: https://truto.one/docs/integration-guides/adobesign/ ## Install Adobe Sign integration The Adobe Sign integration can be found [here](https://app.truto.one/integrations/available/df564709-17f2-479e-bc7e-82d37cbd6443). Please install it in your environments before proceeding with the steps below. ## Connecting an Adobe Sign account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Adobe Sign account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Adobe Sign ![Select Adobe Sign](https://docs-assets.truto.one/select-adobesign.png) 5. You'll now be asked to log in to your Adobe Sign account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Adobe Sign integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zoom > Source: https://truto.one/docs/integration-guides/zoom/ ## Install Zoom integration The Zoom integration can be found [here](https://app.truto.one/integrations/available/a59d8d7a-939a-4baa-b167-2977225cfeb1). Please install it in your environments before proceeding with the steps below. ## Registering your OAuth App :::callout{type="warning"} - `Administrator` role is required to use this API ::: 1. Log in to your Zoom Developer account. 2. Navigate to the App Marketplace > Develop > Build App. ![Click build app](https://docs-assets.truto.one/build-app-zoom.png) 3. Choose `OAuth` App. ![Add OAuth app](https://docs-assets.truto.one/create-oauth-zoom.png) 4. Fill in the required details for your app (name) as shown below. ![Add name for OAuth app](https://docs-assets.truto.one/name-oauth-zoom.png) 5. Click on `Create`. ## Add details to your OAuth App 1. Go to `Information` tab. 2. Add the descriptions. 3. Add company name, contact name and email. 4. You can add more details in information for the application. ## Add Scopes to your OAuth App 1. Go to `Scopes`. 2. Click on `Add Scopes` button. 3. Select the scopes as per requirement and Click on `Done`. 4. Add Descriptions for the scopes which will help them get verified for public use. ### Scopes required to get data in Truto - To read [Users](https://truto.one/docs/api-reference/unified-user-directory-api/users) in Unified User Directory API > `user:read:admin` - To manage [Users](https://truto.one/docs/api-reference/unified-user-directory-api/users) in Unified User Directory API > `user:write:admin` - To read [Roles](https://truto.one/docs/api-reference/unified-user-directory-api/roles) in Unified User Directory API > `role:read:admin` - To read [Activities](https://truto.one/docs/api-reference/unified-user-directory-api/activities) and [Utilisation](https://truto.one/docs/api-reference/unified-user-directory-api/utilisation) in Unified User Directory API > `report:read:admin` - To read [Billing](https://truto.one/docs/api-reference/unified-user-directory-api/billing) in Unified User Directory API > `report:master` ## Obtaining Access Credentials 1. In the `App Credentials` section, find your `Client ID` and `Client Secret` and Add them to Truto by overriding the [OAuth Credentials](https://truto.one/docs/guides/integrations/overriding-oauth-credentials). 2. Enter `Redirect URL for OAuth` as shown below. ![Add redirect url and copy client id and secret](https://docs-assets.truto.one/credentials-zoom.png) - Redirect URL ``` https://api.truto.one/connect/zoom/callback ``` 4. Add the same Redirect URL to `Add Allow List` under `OAuth Allow List`. ![Add redirect url to allow list](https://docs-assets.truto.one/allowlist-zoom.png) ## Publishing the OAuth App 1. Add details in `Technical Design`. 2. Go to `Submit`. 3. If details are missing. You will be able to check them here and you can add it. 4. After adding all the details, click on `Submit`. 5. After the OAuth App gets published, it will be available for all users. ## Connecting a Zoom account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zoom account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zoom ![Select Zoom](https://docs-assets.truto.one/select-zoom.webp) 5. You'll now be asked to log in to your Zoom account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Zoom integration under **Integrated Accounts**. Click on the **Account ID** to view the details and initiate API calls. ## Making your first request Select the Zoom integrated account from the [Integrated Accounts](https://app.truto.one/integrated-accounts?search=zoom) tab. ![Select the Zoom integrated account](https://docs-assets.truto.one/zoom-details-1.webp) Click on the "Proxy API" tab ![Navigate to Proxy API](https://docs-assets.truto.one/zoom-details-2.webp) You can then try out any of the APIs that Truto currently supports for Zoom. ![Try out the Users Proxy API which lists the users in your Zoom account](https://docs-assets.truto.one/zoom-details-3.webp) ![Just click Call API button to make the network call. You can also call the Proxy API programatically](https://docs-assets.truto.one/zoom-details-4.webp) ## Uninstalling the Zoom integration To uninstall the Zoom integration from your Truto account, select the Zoom integration from the [Integrations](https://app.truto.one/integrations/installed?search=zoom) tab. ![Select the Zoom integration](https://docs-assets.truto.one/zoom-details-5.webp) Click on the Settings tab ![Click on Settings tab](https://docs-assets.truto.one/zoom-details-6.webp) And then click on Uninstall. Uninstalling the integration will also remove all the Zoom integrated accounts from your Truto account. ![Click Uninstall to remove the Zoom integration](https://docs-assets.truto.one/zoom-details-7.webp) On uninstallation, the access tokens generated for any connected Zoom accounts will be revoked. ## Support If you face any issues using the Zoom integration provided by Truto, please mail to support@truto.one ## Working hours Monday - Friday, 2:30AM - 4:30PM EDT ## First Response SLA 24 - 48 hours --- # Freshdesk > Source: https://truto.one/docs/integration-guides/freshdesk/ ## Install Freshdesk integration The Freshdesk integration can be found [here](https://app.truto.one/integrations/available/19daf592-d2b0-4d8c-af87-51280ae4b5ba). Please install it in your environments before proceeding with the steps below. ## Connecting a Freshdesk account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Freshdesk account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Freshdesk ![Select Freshdesk](https://docs-assets.truto.one/select-freshdesk.webp) 5. You'll now be asked to log in to your Freshdesk account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Freshdesk integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Grafana > Source: https://truto.one/docs/integration-guides/grafana/ ## Install Grafana integration The Grafana integration can be found [here](https://app.truto.one/integrations/available/44b3ced1-3e84-40fa-9ef1-1f81f7cc7af7). Please install it in your environments before proceeding with the steps below. ## Connecting a Grafana account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Grafana account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Grafana !['Select Grafana'](https://docs-assets.truto.one/select-grafana.png) ### Finding your API Key and Grafana Endpoint URL You'll now be prompted to add the API Key and Grafana Endpoint URL. #### Grafana Endpoint URL 1. To find the Endpoint URL, Sign in to your Grafana account. 2. You can find it from the URL as shown below !['URL in browser'](https://docs-assets.truto.one/grafana-url.png) #### API Key 1. To find the API Key, Sign in to your Grafana account. 2. Click on the `Administration` button at the left Navigation Panel. 3. Under `Administration`, click on `Service accounts`. !['Click on service account under administration in left menu'](https://docs-assets.truto.one/service-account-grafana.png) 4. Now click on `Add service account` as shown below. !['Click on add service account'](https://docs-assets.truto.one/add-account-grafana.png) 5. Enter `Name` and give Roles as shown below. !['Add roles in Grafana as Organization user reader'](https://docs-assets.truto.one/roles-grafana.png) 6. Click on `Apply` after selecting required Roles. !['Click on apply'](https://docs-assets.truto.one/apply-grafana.png) 7. Now click on `Create` as shown below. !['Click on Create'](https://docs-assets.truto.one/create-account-grafana.png) 8. Click on `Add service account token` and Enter `Name` for token. !['Click on Add service account token and enter name'](https://docs-assets.truto.one/add-service-account-grafana.png) 9. After clicking on `Generate token`, You will find your API Key. !['Click on generate token and copy API token'](https://docs-assets.truto.one/generate-token-grafana.png) !['Grafana API Key and Grafana Endpoint URL'](https://docs-assets.truto.one/details-grafana.png) 5. Enter your `API Key` and `Grafana Endpoint URL`. Click on `Connect`. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Grafana Integrated Account'](https://docs-assets.truto.one/account-grafana.png) ## Uninstalling the Grafana integration To uninstall the Grafana integration from your Truto account, select the Grafana [integration](https://app.truto.one/integrations/installed?search=grafana) from the Integrations tab. Click on the `Settings` tab in Grafana Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Grafana integrated accounts from your Truto account. !['Uninstall Sentry'](https://docs-assets.truto.one/uninstall-grafana.png) --- # Breezy HR > Source: https://truto.one/docs/integration-guides/breezyhr/ ## Install Breezy HR integration The Breezy HR integration can be found [here](https://app.truto.one/integrations/available/93204fd3-0f43-43bd-9a80-c226cf225b52). Please install it in your environments before proceeding with the steps below. ## Connecting an Breezy HR account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Breezy HR account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Breezy HR. ![Select Breezy HR](https://docs-assets.truto.one/select-breezyhr.png) 5. You'll now be asked for your Breezy HR Email and Password. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Breezy HR integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Keka > Source: https://truto.one/docs/integration-guides/keka/ ## Install Keka integration The Keka integration can be found [here](https://app.truto.one/integrations/available/ea877158-309a-47d6-897c-82900ab53e1a). Please install it in your environments before proceeding with the steps below. ## Connecting a Keka account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Keka account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Keka ![Select Keka](https://docs-assets.truto.one/select-keka.webp) ## Finding your Keka Subdomain, API Key and Client ID 5. You'll now be prompted to add the **Keka Subdomain**, **API Key**, **Client ID** and **Client Secret**. Get these from your Keka account. ![Keka details](https://docs-assets.truto.one/keka-details-1.png) **Keka Subdomain** - find it from the URL as shown below ![Keka subdomain](https://docs-assets.truto.one/keka-details-2.webp) Get the other details by going to **Settings > Integrations and Automation > API Access > Create New Key** ![Keka setting screen](https://docs-assets.truto.one/keka-details-3.webp) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Keka integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zoho CRM > Source: https://truto.one/docs/integration-guides/zohocrm/ ## Install Zoho CRM integration The Zoho CRM integration can be found [here](https://app.truto.one/integrations/available/6910a585-96d0-4d5b-9224-02de6f7f17ac). Please install it in your environments before proceeding with the steps below. ## Connecting a Zoho CRM account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zoho CRM account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zoho CRM ![Select Zoho CRM](https://docs-assets.truto.one/select-zohocrm.png) 5. You'll now be asked to log in to your Zoho CRM account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Zoho CRM integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Sage Business Cloud Accounting > Source: https://truto.one/docs/integration-guides/sagebusinesscloudaccounting/ ## Install Sage Business Cloud Accounting integration The Sage Business Cloud Accounting integration can be found [here](https://app.truto.one/integrations/available/abd4db53-8fa8-4de1-800a-1e0458801a1d). Please install it in your environments before proceeding with the steps below. ## Connecting a Sage Business Cloud Accounting account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Sage Business Cloud Accounting account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Sage Business Cloud Accounting ![Select Sage Business Cloud Accounting](https://docs-assets.truto.one/select-sagebusinesscloudaccounting.png) 5. You'll now be asked to log in to your Sage Business Cloud Accounting account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Sage Business Cloud Accounting integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Wix > Source: https://truto.one/docs/integration-guides/wix/ ## Install Wix integration The Wix integration can be found [here](https://app.truto.one/integrations/available/d7fcf44f-2bb7-43b7-93bc-cef08279d036). Please install it in your environments before proceeding with the steps below. ## Connecting a Wix account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Wix account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Wix ![Select Wix](https://docs-assets.truto.one/select-wix.png) 5. You'll now be asked to log in to your Wix account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Wix integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Gong > Source: https://truto.one/docs/integration-guides/gong/ ## Install Gong integration The Gong integration can be found [here](https://app.truto.one/integrations/available/46bb4b0f-faf9-4b81-87d6-9f4caf984ec9). Please install it in your environments before proceeding with the steps below. ## Connecting a Gong account 1. Click on **Gong Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Gong account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Gong ![Select Gong](https://docs-assets.truto.one/select-gong.png) 5. You'll now be asked to log in to your Gong account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Gong integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Trello > Source: https://truto.one/docs/integration-guides/trello/ ## Install Trello integration The Trello integration can be found [here](https://app.truto.one/integrations/available/1e3eeb57-7e83-45b5-8958-867e0f521467). Please install it in your environments before proceeding with the steps below. ## Connecting a Trello account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Trello account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Trello !['Select Trello'](https://docs-assets.truto.one/select-trello.png) ### Finding your Token and API Key :::callout{type="warning"} `Admin` role is required to use this API ::: You'll now be prompted to add the Token and API Key. 1. To find the Token and API Key. Sign in to your Trello account. 2. Go to the following [link](https://trello.com/power-ups/admin) for Power-Ups. 3. On top right, click on `New` button to create integration. !['Click on New button'](https://docs-assets.truto.one/new-trello.png) 4. Enter the details, no need to enter anything in Iframe connector URL field. Click on `Create`. !['Click on Create'](https://docs-assets.truto.one/create-trello.png) 5. Now, under the `API key` Section of your Power-Up, copy the `API Key` and paste it in the API Key field in Truto connect interface. !['Copy API Key'](https://docs-assets.truto.one/api-key-trello.png) 6. Then, click the Token link to generate a token. In the subsequent page, click on `Allow` to generate the token. And finally copy the token from the last page and paste it in the Token field in Truto connect interface. !['Generate Token'](https://docs-assets.truto.one/generate-token-trello.png) !['Allow consent'](https://docs-assets.truto.one/consent-trello.png) !['Copy Token'](https://docs-assets.truto.one/token-trello.png) !['Trello Token and API key'](https://docs-assets.truto.one/details-trello.png) 7_Voila!_ You should now see a connection successful message. You can now close this tab. 8. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Trello Integrated Account'](https://docs-assets.truto.one/account-trello.png) ## Uninstalling the Trello integration To uninstall the Trello integration from your Truto account, select the Trello [integration](https://app.truto.one/integrations/installed?search=trello) from the Integrations tab. Click on the `Settings` tab in Trello Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Trello integrated accounts from your Truto account. !['Uninstall Trello'](https://docs-assets.truto.one/uninstall-trello.png) --- # Microsoft Dynamics 365 Business Central > Source: https://truto.one/docs/integration-guides/dynamics365businesscentral/ ## Install Microsoft Dynamics 365 Business Central integration The Microsoft Dynamics 365 Business Central integration can be found [here](https://app.truto.one/integrations/available/846273a1-d9c5-421f-b0e5-ec9441f9f184). Please install it in your environments before proceeding with the steps below. ## Connecting a Microsoft Dynamics 365 Business Central account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Microsoft Dynamics 365 Business Central account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Microsoft Dynamics 365 Business Central ![Select Microsoft Dynamics 365 Business Central](https://docs-assets.truto.one/select-dynamics-365-bc.png) 5. You'll now be asked for your **Business Environment**. Fill in the details and click **Connect**. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Microsoft Dynamics 365 Business Central integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # HiBob > Source: https://truto.one/docs/integration-guides/hibob/ ## Install HiBob integration The HiBob integration can be found [here](https://app.truto.one/integrations/available/ba8ff697-f340-4dad-9bff-370b039f551f). Please install it in your environments before proceeding with the steps below. ## Connecting a HiBob account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their HiBob account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select HiBob ![Select HiBob](https://docs-assets.truto.one/select-hibob.png) 5. You'll now be asked for your HiBob API Token and ID. ## Generating HiBob Token and ID :::callout{type="warning"} You need to be an Administrator to follow the steps below ::: 1. Login to your HiBob account and click **Settings** on the sidebar, and then click **Integrations** under the **Account** section. ![HiBob integrations](https://docs-assets.truto.one/hibob-integrations.png) 2. Search for "service users" and click on **Manage**. ![HiBob service users](https://docs-assets.truto.one/hibob-service-user.png) 3. Click on **New Service User**. ![HiBob new service user](https://docs-assets.truto.one/hibob-new-service-user.png) 4. Enter the Service User Name and Display Name. Click **Next**. ![HiBob service user details](https://docs-assets.truto.one/hibob-service-user-details.png) 5. Copy the ID and Token to be entered into Truto interface later. ![HiBob service user id and token](https://docs-assets.truto.one/hibob-service-user-credentials.png) 6. Go to [Permission Groups](https://app.hibob.com/settings/permissions) in HiBob and click on **Create Group**. ![HiBob permission groups](https://docs-assets.truto.one/hibob-create-permission-group.png) 7. Enter a **Group Name** and choose **Select people by condition** in the Group members section. Click on **Edit**. ![HiBob create permission group](https://docs-assets.truto.one/hibob-permission-group-details.png) 8. Remove any conditions if present, and select the Service User you created in Step 4 by clicking the **Add Specific Employees** dropdown. Click **Apply** and then Click **Create**. ![HiBob permission group members](https://docs-assets.truto.one/hibob-permission-group-add-member-2.png) 9. You'll be taken to the Group details page. Click **Edit permissions** and then select all permissions from **People** and **Timeoff** category in the **Features** tab. ![HiBob permission group permissions](https://docs-assets.truto.one/hibob-permissions-people.png) ![HiBob permission group permissions timeoff](https://docs-assets.truto.one/hibob-permissions-timeoff.png) 10. Then move on to **People's data** tab and click **Edit**. ![HiBob permission group people data](https://docs-assets.truto.one/hibob-permission-people-data.png) 11. Select all the **Lifecycle statuses** and click **Apply**. ![HiBob permission group people data lifecycle statuses](https://docs-assets.truto.one/hibob-permission-people-data-add.png) 12. Click **Save** to save the permission changes. ![HiBob permission group people data lifecycle statuses](https://docs-assets.truto.one/hibob-permission-save.png) 13. Now go back to the Truto Link interface and enter in the ID and Token you copied from step 5. ![HiBob enter id and token](https://docs-assets.truto.one/hibob-enter-id-token.png) 14. _Voila!_ You should now see a connection successful message. You can now close this tab. Go to your Truto account, and you should see the new HiBob integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # HubSpot > Source: https://truto.one/docs/integration-guides/hubspot/ ## Install HubSpot integration The HubSpot integration can be found [here](https://app.truto.one/integrations/available/83c8d226-92fe-4240-adf6-93c8dfcffa8b). Please install it in your environments before proceeding with the steps below. ## Connecting a HubSpot account :::callout{type="warning"} - `Administrator` role is required to use this API - `Role` information is only available in `Enterprise` plan ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their HubSpot account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select HubSpot ![Select HubSpot](https://docs-assets.truto.one/select-hubspot.webp) 5. You'll now be asked to log in to your HubSpot account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new HubSpot integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. ## Setting up Unified Webhooks for HubSpot :::callout{type="info"} Needs to be done only once per environment ::: ### Setting up Webhooks in Truto 1. Login to https://app.truto.one/ and navigate to **Webhooks** tab 2. Click on the **Create Webhook** button and modal shows up. 3. Enter your endpoint URL in the `Endpoint` input to which you would like to get the webhook events posted. 4. Set the webhook to **Active** to start listening to the events. 5. Choose `record:created`, `record:updated`, `record:deleted` to only get the events related to the Unified Webhooks or select “all” to receive all the events. 6. Click on **Create Webhook** to save the webhook. ![Truto Webhooks Modal](https://docs-assets.truto.one/truto%20webhooks.png) ### Connecting Webhooks from HubSpot to Truto 1. Go to your HubSpot Developer account and navigate to the OAuth app for which you would like to setup Unified Webhooks. 2. Click on the **Webhooks** tab under the **Features** section. 3. Enter the target URL in the following format - `api.truto.one/environment-integration-webhook/` 1. You can find the `environment_integration_id` from the Truto UI by navigating to the following URL and select the environment for which you are setting up webhooks - https://app.truto.one/integrations/installed?search=hubspot 2. You can also refer to the following GIF to find the `environment_integration_id` - ![Find environment_integration_id](https://docs-assets.truto.one/Environment%20integration%20id%20copy.gif) 4. Once the Target URL is added, Click on **Create Subscription** 5. Select the object types for which you would like to receive webhooks. Currently, `Contact`, `Company`, `Deal` are supported. 6. Select the events for which you would like to receive webhooks. 7. If you see below shown warning, click on **Add these required scopes** and select the scopes and Click on **Update**. ![Add required scopes](https://docs-assets.truto.one/hubspot%20webhook%20scopes.png) 9. Once the required scopes are added, come back to Webhook section and select object types and events again and click on **Subscribe**. 10. You should now see the webhook subscription created successfully. 11. Select all the Event subscriptions and Click on **Activate** ![Activate HubSpot Event Subscriptions](https://docs-assets.truto.one/activate%20hubspot%20event%20subscriptions.png) Voila!! You should now start receiving the Unified Webhook events to your endpoint URL . --- # Wingman > Source: https://truto.one/docs/integration-guides/wingman/ ## Install Wingman integration The Wingman integration can be found [here](https://app.truto.one/integrations/available/0da06ea0-67a3-4533-ba2f-e97f8410fbdd). Please install it in your environments before proceeding with the steps below. ## Connecting a Wingman account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Wingman account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Wingman ![Select Wingman](https://docs-assets.truto.one/select-wingman.webp) 5. You'll now be asked to log in to your Wingman account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Wingman integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Teamleader > Source: https://truto.one/docs/integration-guides/teamleader/ ## Install Teamleader integration The Teamleader integration can be found [here](https://app.truto.one/integrations/available/332e4e16-b6c9-4f2a-88d6-2a3602dd1d8a). Please install it in your environments before proceeding with the steps below. ## Connecting a Teamleader account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Teamleader account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Teamleader ![Select Teamleader](https://docs-assets.truto.one/select-teamleader.png) 5. You'll now be asked to log in to your Teamleader account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Teamleader integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Travis CI > Source: https://truto.one/docs/integration-guides/travisci/ ## Install Travis CI integration The Travis CI integration can be found [here](https://app.truto.one/integrations/available/e8bf8e2a-f64f-441a-ae1d-04fbf70c8828). Please install it in your environments before proceeding with the steps below. ## Connecting a Travis CI account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Travis CI account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Travis CI ![Select Travis CI](https://docs-assets.truto.one/select-travisci.webp) 5. You'll now be asked for your Travis CI API key. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Travis CI integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Google Analytics > Source: https://truto.one/docs/integration-guides/googleanalytics/ ## Install Google Analytics integration The Google Analytics integration can be found [here](https://app.truto.one/integrations/available/2833e602-bd23-49d2-a54c-29e52bac4563). Please install it in your environments before proceeding with the steps below. ## Connecting a Google Analytics account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Google Analytics account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Google Analytics ![Select Google Analytics](https://docs-assets.truto.one/select-googleanalytics.png) 5. You'll now be asked to log in to your Google Analytics account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Google Analytics integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Webex > Source: https://truto.one/docs/integration-guides/webex/ ## Install Webex integration The Webex integration can be found [here](https://app.truto.one/integrations/available/9be773d5-1822-4f5b-b49a-d03a472abe43). Please install it in your environments before proceeding with the steps below. ## Connecting a Webex account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Webex account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Webex ![Select Webex](https://docs-assets.truto.one/select-webex.png) 5. You'll now be asked to log in to your Webex account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Webex integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Snowflake > Source: https://truto.one/docs/integration-guides/snowflake/ Truto connects to Snowflake in one of two ways: - **Key pair (service user)**: Truto creates a key pair for the connection and shows you its public key. A Snowflake admin adds that public key to a Snowflake service user by running SQL that the connect screen writes for you. Nobody signs in, and there is no OAuth app or password to look after. Choose this when your Snowflake policies do not allow OAuth, or when the connection should not depend on one person's account. - **OAuth**: a person signs in to Snowflake and allows access, through an OAuth security integration you create in Snowflake. ## Install Snowflake integration The Snowflake integration can be found [here](https://app.truto.one/integrations/available/60fabe44-0c0a-4647-8ffa-c5c3f0e09952). Please install it in your environments before proceeding with the steps below. ## Connecting a Snowflake account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Snowflake account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Snowflake !['Select Snowflake'](https://docs-assets.truto.one/select-snowflake.png) 5. Choose how to connect: **Key pair (service user)** or **OAuth 2.0**. Then follow the matching section below. ## Connect with a key pair (service user) ### Before you start - **A Snowflake admin with `ACCOUNTADMIN` runs the SQL.** The SQL grants a database role from Snowflake's own `SNOWFLAKE` database, and only `ACCOUNTADMIN` can grant those. - **Does your Snowflake account restrict IP addresses?** If it has a network policy, Truto's requests must come from fixed IP addresses. Use Truto's Static Gate and allow its IPs for the service user; see [Optional: allow the user only from Truto's Static Gate](#optional-allow-the-user-only-from-trutos-static-gate). Without a static gate, Truto's requests come from addresses that change. - **Use a new service user for Truto.** Let the SQL create a dedicated user. Truto signs in with the user's login name (`LOGIN_NAME`). For a user the SQL creates, the login name and the user name are the same. Using an existing user whose login name differs from its name is not covered yet. ### Steps 1. On the connect screen, choose **Key pair (service user)**. 2. Fill in the fields: - **Snowflake Account URL**, for example `https://myorg-myaccount.snowflakecomputing.com`. Snowsight URLs (`app.snowflake.com`), PrivateLink URLs and `.global` connection URLs are not supported. - **Service user login name** (default `TRUTO_SVC`): the user Truto signs in as. - **Warehouse** (default `COMPUTE_WH`): the warehouse Truto runs its queries on. - **Role** (default `TRUTO_ROLE`): the role Truto uses. The SQL on the screen fills in these values as you type. 3. Copy the SQL with the **Copy** button and run all of it in a Snowsight SQL worksheet as `ACCOUNTADMIN`. 4. Click **Connect**. Connecting does not call Snowflake, so it succeeds even if the key or a grant is wrong. Check the connection with one request through Truto, for example listing warehouses. A problem with the key, the grants or a network policy shows up there. :::callout{type="warning"} Keep the connect window open until you click **Connect**. The key on the screen belongs to that connection link. If you close the window and your app opens the connect screen again with a new link, you get a new key, and you need to run the SQL again. Running it again is safe. If the key changed before you clicked Connect, the screen says so and shows the current key. ::: ### What the SQL does The connect screen shows this SQL with your values and the connection's own key filled in. Here it is with the default values: ```sql USE ROLE ACCOUNTADMIN; -- SNOWFLAKE database roles can only be granted by their owner -- Role Truto uses CREATE ROLE IF NOT EXISTS TRUTO_ROLE; GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE TRUTO_ROLE; GRANT DATABASE ROLE SNOWFLAKE.SECURITY_VIEWER TO ROLE TRUTO_ROLE; -- Service user (service users cannot use passwords or SSO) CREATE USER IF NOT EXISTS TRUTO_SVC TYPE = SERVICE DEFAULT_ROLE = TRUTO_ROLE; GRANT ROLE TRUTO_ROLE TO USER TRUTO_SVC; -- This user may only sign in with a key pair (policies live in a schema) CREATE DATABASE IF NOT EXISTS TRUTO_ADMIN; CREATE SCHEMA IF NOT EXISTS TRUTO_ADMIN.POLICIES; CREATE AUTHENTICATION POLICY IF NOT EXISTS TRUTO_ADMIN.POLICIES.TRUTO_KEYPAIR_ONLY AUTHENTICATION_METHODS = ('KEYPAIR'); ALTER USER TRUTO_SVC SET AUTHENTICATION POLICY TRUTO_ADMIN.POLICIES.TRUTO_KEYPAIR_ONLY FORCE; -- Truto's key for this connection (last: fails if already added, which is safe) ALTER USER TRUTO_SVC ADD KEY PAIR TRUTO_ PUBLIC_KEY = ''; ``` To check the result afterwards, for example when asking Truto support for help, run this separately. It lists the user's key pairs and shows the account identifier: ```sql SHOW USER KEY PAIRS FOR USER TRUTO_SVC; SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() AS account_identifier, CURRENT_ACCOUNT() AS locator; ``` In plain words: - **Role.** `TRUTO_ROLE` can use the warehouse and read Snowflake's account usage data through the `SNOWFLAKE.SECURITY_VIEWER` database role. It gets nothing else. - **Service user.** A `SERVICE` user cannot sign in with a password or with SSO, so it can only be used by software that holds its key. - **Authentication policy.** The user can sign in only with a key pair. `FORCE` replaces a policy the user may already have. - **The key.** The public key is added under a name of its own: `TRUTO_` and the key's `key_id_short`, the first 8 characters of its ID in upper case. Each connection's key has a different name, so running the SQL again adds the new key instead of clashing with an old one. The private key never leaves Truto. The SQL is safe to run more than once: every statement that creates something uses `IF NOT EXISTS`, and the key statement comes last. A Snowflake user can hold at most 10 key pairs. To remove keys you no longer use, list them and remove them by name: ```sql SHOW USER KEY PAIRS FOR USER TRUTO_SVC; ALTER USER TRUTO_SVC REMOVE KEY PAIR TRUTO_; ``` A connection's `key_id_short` is in its context, under `context.snowflake_key.key_id_short`, and it is the end of the key's name in the SQL the connect screen showed. ### Optional: allow the user only from Truto's Static Gate Do this if your Snowflake account restricts IP addresses, or if you want the service user usable only from Truto. Truto's Static Gate sends the connection's requests from two fixed IP addresses: `134.199.136.185` and `143.244.208.28`. 1. Make the connection link with a static gate: under **Advanced settings → Static gate** in the dashboard's **Get connection link** dialog, or with `truto_static_gate_id` when you [create the link token](/docs/api-reference/admin/link-token/create) through the API. If your environment has no static gate yet, ask Truto to set one up for it. 2. As well as the SQL from the connect screen, run this as `ACCOUNTADMIN`: ```sql CREATE NETWORK POLICY IF NOT EXISTS TRUTO_NETWORK_POLICY ALLOWED_IP_LIST = ('134.199.136.185', '143.244.208.28'); ALTER USER TRUTO_SVC SET NETWORK_POLICY = TRUTO_NETWORK_POLICY; ``` A network policy set on a user takes the place of the account's own policy for that user, so this works even if your account allows only your own networks. These IPs are shared by every Truto customer's static gate: the policy keeps the internet at large out, and the key pair is what ties the user to your connection. Set the user's network policy only on a connection that goes through a static gate. Without one, Snowflake refuses every request Truto makes. ### Replace the key Truto does not rotate a connection's key yet, and a reconnect keeps the key the connection already has. To move to a new key, connect a new account with a new connection link and run its SQL, then delete the old account in Truto and remove its key from the service user. The new account has a new ID, and the old account's synced data goes with it when it is deleted. ### Connecting through the API If you create the integrated account with `POST /integrated-account` instead of the connect screen: 1. If you [allow the user only from Truto's Static Gate](#optional-allow-the-user-only-from-trutos-static-gate), put your static gate's `truto_static_gate_id` in the account's `context`. 2. Truto creates the key when it creates the account. The public key is in the response, under `context.snowflake_key.public_key`, and the key's name suffix under `context.snowflake_key.key_id_short`. 3. Run the SQL above with that key. Truto signs nothing with the key until it needs to, so creating the account does not need the key in Snowflake yet, but requests fail until it is there. 4. Call `POST /integrated-account/run-post-install-actions` with the account's `id`. It finishes the connection the way the connect screen does. Truto waits for this call, because those steps need the key to be in Snowflake. ### Troubleshooting - **The key is not accepted.** Snowflake does not have the key Truto signs with. Run the SQL from the connect screen again, for the same user, and check that the user is the one you entered. - **"Role … is not granted to this user".** The role in Truto is not granted to the service user. Run `GRANT ROLE TRUTO_ROLE TO USER TRUTO_SVC;` with your role and user. - **"You must specify the warehouse…".** Snowflake gives this when the warehouse does not exist, or when the role has no `USAGE` on it. Check the name, then run `GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE TRUTO_ROLE;` with your warehouse and role. - **The IP address is not allowed.** Your account or the service user has a network policy, and the request did not come from an IP it allows. Connect through a static gate and allow both Static Gate IPs for the user; see [Optional: allow the user only from Truto's Static Gate](#optional-allow-the-user-only-from-trutos-static-gate). ## Connect with OAuth ### Before you start :::callout{type="warning"} You need to be an `ACCOUNTADMIN` to create an OAuth application in Snowflake, and to grant the `SNOWFLAKE.SECURITY_VIEWER` database role below. ::: You'll be asked for these fields in Truto: Snowflake Account URL, Account Locator, Warehouse, Role, Client ID and Client Secret. ### Find your Account URL and Account Locator 1. Sign in to your Snowflake Account. 2. In the left navigation bar at bottom, you will find your `Account URL` and `Account Locator` as shown below. !['Account URL and Account Locator'](https://docs-assets.truto.one/account-url-snowflake.png) 3. Copy and enter it in Truto interface. ### Create the role Truto uses 1. Go to `Worksheets` from left navigation bar. !['Snowflake worksheet'](https://docs-assets.truto.one/worksheet-snowflake.png) 2. Click on the `Add` button and select `SQL Worksheet` as shown below. !['Add SQL worksheet'](https://docs-assets.truto.one/add-worksheet-snowflake.png) 3. Make sure that the `Database` is `Snowflake` and the `Schema` is `Account_Usage`. !['Select DataBase and Schema'](https://docs-assets.truto.one/select-db-snowflake.png) 4. Run the commands below. They create the role, let it use your warehouse, and let it read account usage data. ```sql CREATE ROLE IF NOT EXISTS TRUTO_ROLE; GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE TRUTO_ROLE; GRANT DATABASE ROLE SNOWFLAKE.SECURITY_VIEWER TO ROLE TRUTO_ROLE; ``` :::callout{type="tip"} You can use any role and warehouse names in place of `TRUTO_ROLE` and `COMPUTE_WH`. Use the same names in all the commands below and in Truto's **Role** and **Warehouse** fields. ::: ### Create the OAuth application 1. Run the command below in the worksheet to create your OAuth application. ```sql CREATE SECURITY INTEGRATION Truto TYPE = OAUTH OAUTH_CLIENT = CUSTOM OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' OAUTH_REDIRECT_URI = 'https://api.truto.one/connect/snowflake/callback' ENABLED = TRUE PRE_AUTHORIZED_ROLES_LIST = ( 'TRUTO_ROLE' ) OAUTH_ISSUE_REFRESH_TOKENS = TRUE OAUTH_REFRESH_TOKEN_VALIDITY = 7776000 ``` :::callout{type="warning"} `OAUTH_REFRESH_TOKEN_VALIDITY` can be set to maximum value of 7776000 seconds (90 Days). After this the integration should be re-authenticated. ::: If you need to raise the maximum value for Refresh Token's validity upto one year, refer to this [link](https://community.snowflake.com/s/article/FAQs-Snowflake-OAuth#:~:text=Could%C2%A0the%20Refresh%20Tokens%27%20validity%20be%C2%A0increased%20beyond%20the%20Maximum%20limit%20in%20special%20circumstances%3F). 2. To view `Client ID` and `Client Secret` run the below command in worksheet. ```sql SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('TRUTO'); ``` 3. Copy your `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` and enter it in Truto interface as `Client ID` and `Client Secret` respectively. !['Client ID and Client Secret in Snowflake'](https://docs-assets.truto.one/worksheet-credential-snowflake.png) ### Give the role to the person who connects The person who clicks **Connect** signs in to Snowflake and allows access. Truto does not ask Snowflake for a particular role, so the connection gets that person's **default role**. It must be the role you enter in Truto's **Role** field. Snowflake also blocks OAuth for admin roles such as `ACCOUNTADMIN` and `SECURITYADMIN` by default, so the person's default role cannot be one of those. Grant the role to that person and make it their default, replacing `` with their Snowflake user name: ```sql GRANT ROLE TRUTO_ROLE TO USER ; ALTER USER SET DEFAULT_ROLE = TRUTO_ROLE; ``` You can also do this in Snowsight, under **Governance & security » Users & roles**. ### Connect 1. Fill in the fields in Truto and click on `Connect`. You'll now be asked to log in to your Snowflake account and allow access to Truto. Go through the steps. !['Enter details in Truto and connect'](https://docs-assets.truto.one/details-snowflake.png) 2. _Voila!_ You should now see a connection successful message. You can now close this tab. 3. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Snowflake Integrated Account'](https://docs-assets.truto.one/account-snowflake.png) ## Optional: full user and role details Two kinds of data need more than the grants above: user details (from `SHOW USERS`) and the full list of roles (from `SHOW ROLES`). Without `MANAGE GRANTS ON ACCOUNT`, Snowflake leaves most user details empty and lists only the roles `TRUTO_ROLE` has privileges on. `MANAGE GRANTS` lets a role grant and revoke any privilege in the account, so many security teams do not allow it for an outside service. Add it only if you need that data: ```sql GRANT MANAGE GRANTS ON ACCOUNT TO ROLE TRUTO_ROLE; ``` ## Uninstalling the Snowflake integration To uninstall the Snowflake integration from your Truto account, select the Snowflake [integration](https://app.truto.one/integrations/installed?search=Snowflake) from the Integrations tab. Click on the `Settings` tab in Snowflake Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Snowflake integrated accounts from your Truto account. !['Uninstall Snowflake'](https://docs-assets.truto.one/uninstall-snowflake.png) --- # DocuSign > Source: https://truto.one/docs/integration-guides/docusign/ ## Install DocuSign integration The DocuSign integration can be found [here](https://app.truto.one/integrations/available/27e4634d-4ed0-4705-b6e0-d303e8044105). Please install it in your environments before proceeding with the steps below. ## Connecting a DocuSign account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their DocuSign account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select DocuSign ![Select DocuSign](https://docs-assets.truto.one/select-docusign.webp) 5. Click **Connect** and go through the login flow. 6. Voila! You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new DocuSign integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Miro > Source: https://truto.one/docs/integration-guides/miro/ ## Install Miro integration The Miro integration can be found [here](https://app.truto.one/integrations/available/5e5a5f42-3ad0-4ee6-8074-431cbe996b93). Please install it in your environments before proceeding with the steps below. ## Connecting a Miro account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Miro account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Miro !['Select Miro'](https://docs-assets.truto.one/select-miro.png) ### Finding your Client ID and Client Secret #### Prerequisites for Miro Integration - `Enterprise Plan` is required for connecting this integration. - You need to be an `Administrator` for connecting this integration. You'll now be prompted to add the Client ID and Client Secret. #### Create your Client ID and Client Secret 1. To find the Client ID and Client Secret, Sign in to your Miro [Developer](https://developers.miro.com/) Platform. 2. Click on the `Your apps` button as shown below. 3. Under `Your apps`, click on `Create a new app`. !['Click on Create APP'](https://docs-assets.truto.one/create-app-miro.png) 4. Enter `Name` for the App and click on `Create app`. !['Enter Name and Create APP'](https://docs-assets.truto.one/new-app-miro.png) 5. Enter `Redirect URI for OAuth2.0` and click on `Add` as shown below. - Redirect URI ``` https://api.truto.one/connect/miro/callback ``` !['Enter redirect uri'](https://docs-assets.truto.one/redirect-uri-miro.png) 6. Under permissions, Select `organizations:read`. Click on `Connect`. !['Add permissions'](https://docs-assets.truto.one/permissions-miro.png) ::: warning `organizations:read` permission will only be visible to Enterprise Users. ::: 7. Now copy `Client ID` and `Client Secret` from `APP Credentials` and Enter your `Client ID` and `Client Secret`. Click on `Connect`. !['Miro Client ID and Client Secret'](https://docs-assets.truto.one/credential-miro.png) 8. You'll now be asked to log in to your Miro account and allow access to Truto. Go through the steps. !['Sentry Token and Organization Slug'](https://docs-assets.truto.one/details-miro.png) !['Miro API Token and Tailnet'](https://docs-assets.truto.one/flow-miro.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Miro Integrated Account'](https://docs-assets.truto.one/account-miro.png) ## Uninstalling the Miro integration To uninstall the Miro integration from your Truto account, select the Miro [integration](https://app.truto.one/integrations/installed?search=miro) from the Integrations tab. Click on the `Settings` tab in Miro Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Miro integrated accounts from your Truto account. !['Uninstall Miro'](https://docs-assets.truto.one/uninstall-miro.png) --- # GitHub > Source: https://truto.one/docs/integration-guides/github/ ## Install GitHub integration The GitHub integration can be found [here](https://app.truto.one/integrations/available/1ec69175-0b60-465f-b606-d04b87bef0c6). Please install it in your environments before proceeding with the steps below. ## Connecting a GitHub account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their GitHub account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select GitHub ![Select GitHub](https://docs-assets.truto.one/select-github.webp) 5. You'll now be asked to log in to your GitHub account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new GitHub integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Xero > Source: https://truto.one/docs/integration-guides/xero/ ## Install Xero integration The Xero integration can be found [here](https://app.truto.one/integrations/available/3d324589-7034-4131-8c44-a69ce781fb53). Please install it in your environments before proceeding with the steps below. ## Connecting a Xero account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Xero account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Xero ![Select Xero](https://docs-assets.truto.one/select-xero.webp) 5. You'll now be asked to log in to your Xero account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Xero integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zoho People > Source: https://truto.one/docs/integration-guides/zohopeople/ ## Install Zoho People integration The Zoho People integration can be found [here](https://app.truto.one/integrations/available/d608fe66-5d1f-46d5-a05c-e7cbad36d741). Please install it in your environments before proceeding with the steps below. ## Connecting a Zoho People account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zoho People account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zoho People ![Select Zoho People](https://docs-assets.truto.one/select-zoho-people.png) 5. You'll now be asked to log in to your Zoho People account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Zoho People integration under **Integrated Accounts**. Click on the **Account ID** to start calling the API. --- # Constant Contact > Source: https://truto.one/docs/integration-guides/constantcontact/ ## Install Constant Contact integration The Constant Contact integration can be found [here](https://app.truto.one/integrations/available/b67f97e1-367a-42f5-a40b-9c52aa2f4c41). Please install it in your environments before proceeding with the steps below. ## Connecting a Constant Contact account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Constant Contact account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Constant Contact ![Select Constant Contact](https://docs-assets.truto.one/select-constantcontact.png) 5. You'll now be asked to log in to your Constant Contact account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Constant Contact integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # SendGrid > Source: https://truto.one/docs/integration-guides/sendgrid/ ## Install SendGrid integration The SendGrid integration can be found [here](https://app.truto.one/integrations/available/f2340e5e-4a07-4915-b28a-9cf8de1b91dd). Please install it in your environments before proceeding with the steps below. ## Connecting a SendGrid account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their SendGrid account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select SendGrid ![Select SendGrid](https://docs-assets.truto.one/select-sendgrid.webp) ## Getting your Sendgrid API Key 1. You'll now be asked for your SendGrid API key. Navigate to https://app.sendgrid.com/settings/api_keys. 2. Click on **Create API Key**. ![Sendgrid create api key](https://docs-assets.truto.one/sendgrid-create-api-key.png) 3. Enter an API Key Name, select Restricted Access and Select User Account Read Access. Click **Create and View**. ![Sendgrid create api key details](https://docs-assets.truto.one/sendgrid-create-api-key-details.png) ![Sendgrid create api key details 2](https://docs-assets.truto.one/sendgrid-create-api-key-details-2.png) 4. Copy the API Key and store it somewhere safe for entering into the Truto interface later. ![Sendgrid create api key](https://docs-assets.truto.one/sendgrid-api-key.png) 5. Because Sendgrid doesn't have the necessary user interface to grant the **teammates.read** scope to the API Key, we'll have to do that using their API. So generate a similar API token that you did just now but with **Full Access** to modify the API Key we generated in the previous steps. 6. Then make a note of the API Key ID you generated in step 7. ![Sendgrid create api key id](https://docs-assets.truto.one/sendgrid-api-key-id.png) 7. Run the following cURL command to modify the scopes of the API Key, ```bash curl --location --request PUT 'https://api.sendgrid.com/v3/api_keys/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "name": "Truto Demo", "scopes": ["teammates.read"] }' ``` In the command above, `truto_demo_api_key_id` is the ID of the API Key generated in step 7, `full_access_api_token` is the API Key with Full Access. 8. Now enter the API Key you stored in step 8 into the Truto Link interface. 9. _Voila!_ You should now see a connection successful message. You can now close this tab. 10. Go to your Truto account, and you should see the new SendGrid integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Calendly > Source: https://truto.one/docs/integration-guides/calendly/ ## Install Calendly integration The Calendly integration can be found [here](https://app.truto.one/integrations/available/d6882355-f512-499c-a7ba-24ec2034f8a5). Please install it in your environments before proceeding with the steps below. ## Connecting a Calendly account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Calendly account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Calendly ![Select Calendly](https://docs-assets.truto.one/select-calendly.webp) 5. You'll now be asked to log in to your Calendly account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Calendly integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Supabase > Source: https://truto.one/docs/integration-guides/supabase/ ## Install Supabase integration The Supabase integration can be found [here](https://app.truto.one/catalog/integrations/available/b2652326-19a9-4df9-9ec5-5345cb61d583). Please install it in your environments before proceeding with the steps below. ## Connecting Supabase account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Supabase account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Supabase ![Select Supabase](https://docs-assets.truto.one/select-supabase1.png) 5. You'll now be asked to log in to your Supabase account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Supabase integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Google Workspace > Source: https://truto.one/docs/integration-guides/googleworkspace/ ## Install Google Workspace integration The Google Workspace integration can be found [here](https://app.truto.one/integrations/available/2bc38d0e-3ac9-4f4b-95ea-c7be56524dd7). Please install it in your environments before proceeding with the steps below. ## Connecting a Google Workspace account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Google Workspace account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Google Workspace ![Select Google Workspace](https://docs-assets.truto.one/select-google.webp) 5. You'll now be asked to log in to your Google Workspace account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Google Workspace integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Pivotal Tracker > Source: https://truto.one/docs/integration-guides/pivotaltracker/ ## Install Pivotal Tracker integration The Pivotal Tracker integration can be found [here](https://app.truto.one/integrations/available/6d93e612-196d-47a1-b32f-f1142c26d15f). Please install it in your environments before proceeding with the steps below. ## Connecting a Pivotal Tracker account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Pivotal Tracker account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Pivotal Tracker ![Select Pivotal Tracker](https://docs-assets.truto.one/select-pivotaltracker.png) ## Finding your API Key on Pivotal Tracker 5. You'll now be asked for your Pivotal Tracker API key. To find your API Key go to your profile on Pivotal Tracker (https://www.pivotaltracker.com/profile) and click on 'Create New Token'. ![API token on Pivotal Tracker](https://docs-assets.truto.one/pivotal-tracker-details-1.webp) Copy the token and paste it in the field below and click **Connect** ![Truto screen for Pivotal Tracker API Key](https://docs-assets.truto.one/pivotal-tracker-details-2.webp) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Pivotal Tracker integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Datadog > Source: https://truto.one/docs/integration-guides/datadog/ ## Install Datadog integration The Datadog integration can be found [here](https://app.truto.one/integrations/available/99d979e4-b87c-4f11-9f9d-2476271501ac). Please install it in your environments before proceeding with the steps below. ## Connecting a Datadog account --- :::callout{type="warning"} - `Admin` role is required to use this API ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Datadog account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Datadog ![Select Datadog](https://docs-assets.truto.one/select-datadog.png) ### Finding your Datadog API Key and Application Key 1. You'll now be prompted to select the `Datadog Region` and. add the `API Key` and `Application Key`. 2. To find your Datadog Region/Site, refer this official [Datadog documentation](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site) 3. To find API Key, Sign in to your Datadog organization as a `Admin` user. Navigate to `Organization Settings` > `Application Keys`. Click `New Key` and enter the `Application Key` in Truto. 4. Navigate to Organization settings, then click the `API keys` tab. 5. Click the `New Key` button. 6. Enter a name for your key. 7. Click `Create API key`. 8. Now copy the `API key` and enter it in Truto. Click `Connect`. --- 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Datadog integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Humaans > Source: https://truto.one/docs/integration-guides/humaans/ ## Install Humaans integration The Humaans integration can be found [here](https://app.truto.one/integrations/available/4bf7d0f5-d95e-4c9b-8d3b-5b1ad359e8e2). Please install it in your environments before proceeding with the steps below. ## Connecting a Humaans account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Humaans account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Humaans ![Select Humaans](https://docs-assets.truto.one/select-humaans.png) ## Finding your API Key on Humaans 5. You'll now be asked for your Humaans API key. You'll now be asked for your Humaans API key. To find your API key, follow the steps below: ![API token on Humaans](https://docs-assets.truto.one/humaans-details-1.webp) ![Generate token on Humaans](https://docs-assets.truto.one/humaans-details-2.png) Choose the scopes based on what data you want to give access to. For most cases, we only need the 'View public data' scope. ![Select scopes](https://docs-assets.truto.one/humaans-details-3.webp) ![Copy token](https://docs-assets.truto.one/humaans-details-4.png) Paste the new token in the API Key field created in the previous step and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Humaans integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Asana > Source: https://truto.one/docs/integration-guides/asana/ ## Install Asana integration The Asana integration can be found [here](https://app.truto.one/integrations/available/91dcffb7-d9db-4c70-9ac8-91c71578f9a0). Please install it in your environments before proceeding with the steps below. ## Connecting an Asana account --- ### Important Note The [User Directory Activities API](https://truto.one/docs/api-reference/unified-user-directory-api/activities) resource will only work when authentication is done using API Key. To generate a Service Account API Key follow this [Asana guide](https://asana.com/guide/help/premium/service-accounts). --- 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Asana account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Asana ![Select Asana](https://docs-assets.truto.one/select-asana.webp) 5. You'll now be asked to log in to your Asana account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Asana integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Monday.com > Source: https://truto.one/docs/integration-guides/mondaycom/ ## Install Monday.com integration The Monday.com integration can be found [here](https://app.truto.one/integrations/available/e9112b90-825d-439f-873e-5a088731fd96). Please install it in your environments before proceeding with the steps below. ## Connecting a Monday.com account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Monday account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Monday.com !['Select Monday.com'](https://docs-assets.truto.one/select-mondaycom.png) ### Finding your Client ID and Client Secret 1. To find the Client ID and Client Secret, Sign in to your Monday.com account. !['Sign in to Monday'](https://docs-assets.truto.one/mondaycom-0.png) 2. Click on the `developer` button at the top right menu. !['Click on developer button in Monday.com'](https://docs-assets.truto.one/developers-mondaycom.png) 3. In `Monday Developer Center`, choose `Build App` option and configure your app. !['Click on live and create app'](https://docs-assets.truto.one/buildApp-mondaycom.png) 4. After completing this process, copy your Client ID and Client Secret and paste them into the relevant fields in Truto. !['Client Id and Secret'](https://docs-assets.truto.one/clientID-mondaycom.png) ## Uninstalling the Monday.com integration 1. To uninstall the Monday.com integration from your Truto account, select the Monday.com [integration](https://app.truto.one/integrations/installed?search=mondaycom) from the Integrations tab. 2. Click on the `Settings` tab in Monday.com Integration page 3. And then click on Uninstall. Uninstalling the integration will also remove all the Monday.com integrated accounts from your Truto account. !['Uninstall Monday.com'](https://docs-assets.truto.one/uninstall-mondaycom.png) ## Setting up Unified Webhooks for Monday.com :::callout{type="info"} Currently, Monday.com only supports Unified Webhooks for their [App life cycle events](https://developer.monday.com/apps/docs/webhooks). ::: ### Setting up Webhooks in Truto 1. Login to https://app.truto.one/ and navigate to Webhooks tab 2. Click on the Create Webhook button and modal shows up. 3. Enter your endpoint URL in the Endpoint input to which you would like to get the webhook events posted. 4. Set the webhook to Active to start listening to the events. 5. Choose `record:meta` only get the events related to the Unified Webhooks for Monday.com or select “all” to receive all the events. 6. Click on Create Webhook to save the webhook. !['Webhook Modal'](https://frontsite-logos.truto.one/record_meta_webhook_event.png) ### Connecting Webhooks from Monday.com to Truto 1. Go to your Monday.com account and click on the `Developers` button at the top right User Profile menu. 2. In the `Monday Developer Center`, choose the application for which you would like to set up webhooks. 3. Click on the `Webhooks` tab under the `Manage` section. !['Monday.com Webhooks'](https://frontsite-logos.truto.one/mondaycom_webhooks.png) 4. Enter the target URL in the following format - `https://api.truto.one/environment-integration-webhook/` 1. You can find the `environment_integration_id` from the Truto UI by navigating to the following URL and select the environment for which you are setting up webhooks - https://app.truto.one/integrations/installed?search=mondaycom 2. You can also refer to the following GIF to find the `environment_integration_id` - !['Find environment_integration_id'](https://docs-assets.truto.one/Environment%20integration%20id%20copy.gif) 5. Once the API URL is added, save the changes and publish the Monday.com app to Live. --- # PagerDuty > Source: https://truto.one/docs/integration-guides/pagerduty/ ## Install PagerDuty integration The PagerDuty integration can be found [here](https://app.truto.one/integrations/available/69ea1fe8-32dc-41bf-bb73-1b737b23389d). Please install it in your environments before proceeding with the steps below. ## Connecting a PagerDuty account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their PagerDuty account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select PagerDuty ![Select PagerDuty](https://docs-assets.truto.one/select-pagerduty.png) 5. You'll now be asked to log in to your PagerDuty account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new PagerDuty integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # QuickBooks > Source: https://truto.one/docs/integration-guides/quickbooks/ This article will take you through the steps to set up a QuickBooks integration and connect your first Quickbooks account. Truto provides a ready-to-use OAuth application for QuickBooks, but in case you want to use your own OAuth app, please follow the steps below or feel free to skip to the **Connecting A QuickBooks Account** section. ## Setup your own QuickBooks OAuth Integration in Truto > You can skip this step if you want to use Truto's QuickBooks OAuth application 1. Create an OAuth application in QuickBooks and note down the client_id and client_secret for your OAuth application. The redirect URL you have to use is https://api.truto.one/connect/quickbooks/callback 2. Open up the [QuickBooks](https://app.truto.one/integrations/available/444f54fa-439b-412c-80ce-c3d02eacd78e) integration in Truto. 3. Click on the **Clone** button in the integration details page. ![QuickBooks integration page in Truto](https://docs-assets.truto.one/quickbooks-details-1.png) 4. Scroll down to the **Authentication** section and key in the Client ID and Client Secret into the form fields.quickbooks-details-2 ![Enter your application's Client ID and Client Secret in the authentication section](https://docs-assets.truto.one/quickbooks-details-2.webp) 5. Scroll to the top of the page and click **Save** and then **Install** to install the integration. ![Save the integration and install it](https://docs-assets.truto.one/quickbooks-details-3.webp) ## Connecting a QuickBooks account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their QuickBooks account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select QuickBooks ![Select QuickBooks](https://docs-assets.truto.one/select-quickbooks.webp) 5. You'll now be asked to log in to your QuickBooks account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new QuickBooks integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Outreach > Source: https://truto.one/docs/integration-guides/outreach/ ## Install Outreach integration The Outreach integration can be found [here](https://app.truto.one/integrations/available/d48afc72-b0c4-464b-9dd2-6b596e39214b). Please install it in your environments before proceeding with the steps below. ## Connecting an Outreach account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Outreach account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Outreach ![Select Outreach](https://docs-assets.truto.one/select-outreach.webp) 5. You'll now be asked to log in to your Outreach account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Outreach integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Adobe Marketo Engage > Source: https://truto.one/docs/integration-guides/adobemarketoengage/ ## Install Adobe Marketo Engage integration The Adobe Marketo Engage integration can be found [here](https://app.truto.one/integrations/available/cc2a2b64-47b9-4cdd-9552-9a54eba60185). Please install it in your environments before proceeding with the steps below. ## Connecting an Adobe Marketo Engage account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Adobe Marketo Engage account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Adobe Marketo Engage !['Select Adobe Marketo Engage'](https://docs-assets.truto.one/select-adobe-me.png) ### Finding your Client ID, Client Secret, Identity URL and Endpoint :::callout{type="warning"} `Admin` role is required to use this API ::: You'll now be prompted to add the Client ID, Client Secret, Identity URL and Endpoint. 1. To find the `Client ID` and `Client Secret`. Sign in to your Adobe Marketo Engage account and go to `LaunchPoint` under `Admin` from the left navigation bar. 2. Under LaunchPoint, click on `New` and make sure that the type is `Custom`. Now click on `View Details`. !['Click on view details'](https://docs-assets.truto.one/view-details-adobe-me.png) 3. Copy your `Client ID` and `Client Secret` and paste it into Truto. !['Copy Adobe Marketo Client ID and Client Secret'](https://docs-assets.truto.one/credentials-adobe-me.png) 4. To find the Identity URL and Endpoint, go to `Web Services` under `Admin` from the left navigation bar. 5. Now, under the `REST API` Section, you will find the `Identity URL` and `Endpoint`, copy them and paste it in Truto and click `Connect`. !['Adobe Marketo Engage Client ID and Client Secret'](https://docs-assets.truto.one/details-adobe-me.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. ## Uninstalling the Adobe Marketo Engage integration To uninstall the Adobe Marketo Engage integration from your Truto account, select the Adobe Marketo Engage [integration](https://app.truto.one/integrations/installed?search=adobemarketoengage) from the Integrations tab. Click on the `Settings` tab in Adobe Marketo Engage Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Adobe Marketo Engage integrated accounts from your Truto account. !['Uninstall Adobe Marketo Engage'](https://docs-assets.truto.one/uninstall-adobe-me.png) --- # Moneybird > Source: https://truto.one/docs/integration-guides/moneybird/ ## Install Moneybird integration The Moneybird integration can be found [here](https://app.truto.one/integrations/available/60db6d41-fb85-4b97-89bd-4f49fe7f5877). Please install it in your environments before proceeding with the steps below. ## Connecting a Moneybird account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Moneybird account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Moneybird ![Select Moneybird](https://docs-assets.truto.one/select-moneybird.png) 5. You'll now be asked to log in to your Moneybird account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Moneybird integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # GitLab > Source: https://truto.one/docs/integration-guides/gitlab/ ## Install GitLab integration The GitLab integration can be found [here](https://app.truto.one/integrations/available/f25d1d3c-451f-46ef-aa80-134dc5353e8c). Please install it in your environments before proceeding with the steps below. ## Connecting a GitLab account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their GitLab account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select GitLab ![Select GitLab](https://docs-assets.truto.one/select-gitlab.png) 5. You'll now be asked to log in to your GitLab account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new GitLab integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Confluence > Source: https://truto.one/docs/integration-guides/confluence/ ## Install Confluence integration The Confluence integration can be found [here](https://app.truto.one/integrations/available/2330d45f-6a7e-4050-96c6-c59594dade6e). Please install it in your environments before proceeding with the steps below. ## Connecting a Confluence account --- ### Important Note The [User Directory Activities API](https://truto.one/docs/api-reference/unified-user-directory-api/activities) resource will only work on `Standard` and `Premium` plans. --- 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Confluence account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Confluence ![Select Confluence](https://docs-assets.truto.one/select-confluence.png) 5. You'll now be asked to log in to your Confluence account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Confluence integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Jetbrains > Source: https://truto.one/docs/integration-guides/jetbrains/ ## Install Jetbrains integration The Jetbrains integration can be found [here](https://app.truto.one/integrations/available/38fab044-84b0-4ba4-99bf-dbf03990c90b). Please install it in your environments before proceeding with the steps below. ## Connecting a Jetbrains account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Jetbrains account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Jetbrains. ![Select Jetbrains](https://docs-assets.truto.one/select-jetbrains.png) 5. You'll now be asked for your Jetbrains API key and Company Profile ID. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Travis CI integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Twingate > Source: https://truto.one/docs/integration-guides/twingate/ ## Install Twingate integration The Twingate integration can be found [here](https://app.truto.one/integrations/available/73f92a73-c4a2-424a-ba5d-d3e757bf5bcc). Please install it in your environments before proceeding with the steps below. ## Connecting a Twingate account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Twingate account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Twingate. ![Select Twingate](https://docs-assets.truto.one/select-twingate.png) 5. You'll now be asked for your Twingate `API Key` and `Subdomain`. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Twingate integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Wave > Source: https://truto.one/docs/integration-guides/wave/ ## Install Wave integration The Wave integration can be found [here](https://app.truto.one/integrations/available/9f2ede68-18f9-4908-8197-2709c38b92cf). Please install it in your environments before proceeding with the steps below. ## Connecting a Wave account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Wave account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Wave ![Select Wave](https://docs-assets.truto.one/select-wave.png) 5. You'll now be asked to log in to your Wave account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Wave integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Salesforce > Source: https://truto.one/docs/integration-guides/salesforce/ ## Install Salesforce integration The Salesforce integration can be found [here](https://app.truto.one/integrations/available/d9c21a25-3065-4d2b-a477-35742a7bd21d). Please install it in your environments before proceeding with the steps below. ## Connecting a Salesforce account --- :::callout{type="warning"} - `Admin` role is required to use this API ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Salesforce account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Salesforce ![Select Salesforce](https://docs-assets.truto.one/select-salesforce.png) ### Finding your Salesforce Subdomain - You'll now be prompted to add the `Salesforce Subdomain`. Find the Salesforce Subdomain by signing in to your Salesforce account in your browser as shown in the image below. Then click Connect ![Enter Subdomain from Salesforce](https://docs-assets.truto.one/url-salesforce.png) 5. You'll now be asked to log in to your Salesforce account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Salesforce integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Lever > Source: https://truto.one/docs/integration-guides/lever/ This article will take you through the steps to setup a Lever integration and connect your first Lever account. There are two ways of setting up a Lever integration in Truto. 1. **[RECOMMENDED]** Setup an OAuth application in Lever and use it in Truto. Please mention that you are going to use Truto as your integration provider in the [partnership interest form](https://www.lever.co/partnershipinterest/). 2. Use API Key based integration, where the end customer keys-in their API Key. Ideal for PoCs and supporting one or two customers. > Going with the OAuth application approach has added benefits >1. Customers can enable your integration in one-click. >2. No sensitive data transfer; no manual steps; and much less chance of error. >3. Official partnership opportunities are available to integrators who have built OAuth-based integrations to Lever. ## Setup Lever OAuth Integration in Truto (Recommended) 1. Create an OAuth application in Lever and note down the client_id and client_secret for your OAuth application. The redirect URL you have to use is https://api.truto.one/connect/lever/callback. 2. Open up the [Lever integration](https://app.truto.one/integrations/available/95c4655c-50f9-4781-b96e-93f025461162) in Truto. 3. Click on the **Clone** button in the integration details page. ![Lever integration page in Truto](https://docs-assets.truto.one/lever-details-1.webp) 4. Scroll down to the **Authentication** section and change it to **OAuth 2.0** ![Select OAuth 2.0 in the authentication section](https://docs-assets.truto.one/lever-details-2.webp) 5. Key in the following details
i. Client ID
ii. Client Secret
iii. Authorization Hoste (only the host part, e.g. https://api.lever.com)
iv. Token Host (only the host part, e.g. https://api.lever.com)
v. Scopes
vi. Authorization Path
vii. Token Path
viii. Audience (via the Add authorize URL params button)
![Enter the OAuth credentials for Lever](https://docs-assets.truto.one/lever-details-3.webp) 6. Scroll down to the **Authorization** section and select **Bearer Auth** in the Format dropdown and enter the following in the Bearer token field - **{{oauth.token.access_token}}.** ![Select Bearer Auth as the authorization format](https://docs-assets.truto.one/lever-details-4.png) 7. Scroll to the top of the page and click **Save** and then **Install** to install the integration. ![Save the integration and install it](https://docs-assets.truto.one/lever-details-5.png) ## API Key based integration > Ignore this if you have already setup an integration using the recommended OAuth based flow. This integration flow is recommended for PoCs and supporting one or two customers. You just have to install the [Lever integration](https://app.truto.one/integrations/available/95c4655c-50f9-4781-b96e-93f025461162) and proceed with the steps to connect Lever accounts below. ## Connecting a Lever account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Lever account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Lever ![Select Lever](https://docs-assets.truto.one/select-lever.png) 5. You'll now be asked to log in to your Lever account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Lever integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # ClickUp > Source: https://truto.one/docs/integration-guides/clickup/ ## Install ClickUp integration The ClickUp integration can be found [here](https://app.truto.one/integrations/available/af5f9b38-3d2d-4526-acc7-ebecab5fa74a). Please install it in your environments before proceeding with the steps below. ## Connecting a ClickUp account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their ClickUp account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select ClickUp ![Select ClickUp](https://docs-assets.truto.one/select-clickup.png) 5. You'll now be asked to log in to your ClickUp account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new ClickUp integration under **Integrated Accounts**. Click on the **Account ID** to see the details, and to start making API calls. --- # Keap > Source: https://truto.one/docs/integration-guides/keap/ ## Install Keap integration The Keap integration can be found [here](https://app.truto.one/integrations/available/e5c437c7-57ca-4666-8997-01fa6676c79d). Please install it in your environments before proceeding with the steps below. ## Connecting a Keap account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Keap account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Keap ![Select Keap](https://docs-assets.truto.one/select-keap.png) 5. You'll now be asked to log in to your Keap account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Keap integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Jira > Source: https://truto.one/docs/integration-guides/jira/ ## Install Jira integration The Jira integration can be found [here](https://app.truto.one/integrations/available/06f09d9c-7452-4add-aeed-f5564dacfa46). Please install it in your environments before proceeding with the steps below. ## Connecting a Jira account --- ### Important Note The [User Directory Activities API](https://truto.one/docs/api-reference/unified-user-directory-api/activities) resource will only work on `Standard` and `Premium` plans. --- 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Jira account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Jira ![Select Jira](https://docs-assets.truto.one/select-jira.png) 5. You'll now be asked to log in to your Jira account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Jira integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # BigCommerce > Source: https://truto.one/docs/integration-guides/bigcommerce/ ## Install BigCommerce integration The BigCommerce integration can be found [here](https://app.truto.one/integrations/available/cef71931-64b9-4968-8465-08e370d69d71). Please install it in your environments before proceeding with the steps below. ## Connecting a BigCommerce account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their BigCommerce account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select BigCommerce !['Select BigCommerce'](https://docs-assets.truto.one/select-bigcommerce.png) ## Finding your Store Hash and API Key You'll now be prompted to add the Store Hash and API Key. To find the Store Hash and API Key, go to your BigCommerce account. Click on `Settings > API Accounts`. In the top right corner, select the option to create an API account and Set the scopes for the API connection. As soon as you save these settings a box will pop up and a `txt` file will save, the `txt` file will have the credentials you require. Copy the `Store Hash` and `Access Token` and paste them into the relevant fields in Truto and click `Connect` !['BigCommerce Get API Key and Store Hash'](https://docs-assets.truto.one/apikey-bigcommerce.png) !['BigCommerce Enter API Key and Store Hash'](https://docs-assets.truto.one/details-bigcommerce.png) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. !['Connection successful'](https://docs-assets.truto.one/success-bigcommerce.png) 6. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['BigCommerce Integrated Account'](https://docs-assets.truto.one/account-bigcommerce.png) ## Uninstalling the BigCommerce integration To uninstall the BigCommerce integration from your Truto account, select the BigCommerce [integration](https://app.truto.one/integrations/installed?search=bigcommerce) from the Integrations tab. Click on the `Settings` tab in BigCommerce Integration page And then click on Uninstall. Uninstalling the integration will also remove all the BigCommerce integrated accounts from your Truto account. !['Uninstall BigCommerce'](https://docs-assets.truto.one/uninstall-bigcommerce.png) --- # Capsule > Source: https://truto.one/docs/integration-guides/capsule/ ## Install Capsule integration The Capsule integration can be found [here](https://app.truto.one/integrations/available/f9e7897b-2b60-475c-be8a-30ca7c4b1e3c). Please install it in your environments before proceeding with the steps below. ## Connecting a Capsule account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Capsule account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Capsule ![Select Capsule](https://docs-assets.truto.one/select-capsule.png) 5. You'll now be asked to log in to your Capsule account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Capsule integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Integration Guides > Source: https://truto.one/docs/integration-guides/ - [ActiveCampaign](/docs/integration-guides/activecampaign) - [Adobe](/docs/integration-guides/adobe) - [Adobe Marketo Engage](/docs/integration-guides/adobemarketoengage) - [Adobe Sign](/docs/integration-guides/adobesign) - [Airtable](/docs/integration-guides/airtable) - [AlexisHR](/docs/integration-guides/alexishr) - [Asana](/docs/integration-guides/asana) - [Atlassian](/docs/integration-guides/atlassian) - [Azure DevOps](/docs/integration-guides/azuredevops) - [BambooHR](/docs/integration-guides/bamboohr) - [Basecamp](/docs/integration-guides/basecamp) - [BigCommerce](/docs/integration-guides/bigcommerce) - [Box](/docs/integration-guides/box) - [Breezy HR](/docs/integration-guides/breezyhr) - [BrowserStack](/docs/integration-guides/browserstack) - [Calendly](/docs/integration-guides/calendly) - [Capsule](/docs/integration-guides/capsule) - [Clay HR](/docs/integration-guides/clayhr) - [ClickUp](/docs/integration-guides/clickup) - [Cloudflare](/docs/integration-guides/cloudflare) - [Confluence](/docs/integration-guides/confluence) - [Constant Contact](/docs/integration-guides/constantcontact) - [Copper](/docs/integration-guides/copper) - [Customer.io](/docs/integration-guides/customerio/registering-webhooks) - [Datadog](/docs/integration-guides/datadog) - [DocuSign](/docs/integration-guides/docusign) - [Dropbox](/docs/integration-guides/dropbox) - [FreeAgent](/docs/integration-guides/freeagent) - [FreshBooks](/docs/integration-guides/freshbooks) - [Freshdesk](/docs/integration-guides/freshdesk) - [Front](/docs/integration-guides/front) - [GetResponse](/docs/integration-guides/getresponse) - [GitHub](/docs/integration-guides/github) - [GitLab](/docs/integration-guides/gitlab) - [Gong](/docs/integration-guides/gong) - [Google Analytics](/docs/integration-guides/googleanalytics) - [Google Drive](/docs/integration-guides/googledrive.md) - [Google Workspace](/docs/integration-guides/googleworkspace) - [Gorgias](/docs/integration-guides/gorgias) - [Grafana](/docs/integration-guides/grafana) - [GreytHR](/docs/integration-guides/greythr) - [Help Scout](/docs/integration-guides/helpscout) - [HiBob](/docs/integration-guides/hibob) - [HR Cloud](/docs/integration-guides/helpscout) - [HubSpot](/docs/integration-guides/hubspot) - [Humaans](/docs/integration-guides/humaans) - [Intercom](/docs/integration-guides/intercom) - [Jenkins](/docs/integration-guides/jenkins) - [Jetbrains](/docs/integration-guides/jetbrains) - [Jira](/docs/integration-guides/jira) - [Keap](/docs/integration-guides/keap) - [Keka](/docs/integration-guides/keka) - [Lever](/docs/integration-guides/lever) - [Linear](/docs/integration-guides/linear) - [Mailchimp](/docs/integration-guides/mailchimp) - [Microsoft Dynamics 365 Business Central](/docs/integration-guides/dynamics365businesscentral) - [Microsoft Dynamics 365 Sales](/docs/integration-guides/dynamics365sales) - [Miro](/docs/integration-guides/miro) - [Monday.com](/docs/integration-guides/mondaycom) - [Moneybird](/docs/integration-guides/moneybird) - [Notion](/docs/integration-guides/notion) - [Okta](/docs/integration-guides/okta) - [Outreach](/docs/integration-guides/outreach) - [PagerDuty](/docs/integration-guides/pagerduty) - [Paypal](/docs/integration-guides/paypal) - [Pipedrive](/docs/integration-guides/pipedrive) - [Pivotal Tracker](/docs/integration-guides/pivotaltracker) - [QuickBooks](/docs/integration-guides/quickbooks) - [Sage Business Cloud Accounting](/docs/integration-guides/sagebusinesscloudaccounting) - [Salesforce](/docs/integration-guides/salesforce) - [SendGrid](/docs/integration-guides/sendgrid) - [Sentry](/docs/integration-guides/sentry) - [Slack](/docs/integration-guides/slack) - [Snowflake](/docs/integration-guides/snowflake) - [Supabase](/docs/integration-guides/supabase) - [Tailscale](/docs/integration-guides/tailscale) - [Teamleader](/docs/integration-guides/teamleader) - [Travis CI](/docs/integration-guides/travisci) - [Trello](/docs/integration-guides/trello) - [Twingate](/docs/integration-guides/twingate) - [Wave](/docs/integration-guides/wave) - [Webex](/docs/integration-guides/webex) - [Wingman](/docs/integration-guides/wingman) - [Wix](/docs/integration-guides/wix) - [Workable](/docs/integration-guides/workable) - [Xero](/docs/integration-guides/xero) - [Zendesk](/docs/integration-guides/zendesk) - [Zendesk Sell](/docs/integration-guides/zendesksell) - [Zoho Analytics](/docs/integration-guides/zohoanalytics) - [Zoho CRM](/docs/integration-guides/zohocrm) - [Zoho People](/docs/integration-guides/zohopeople) - [Zoom](/docs/integration-guides/zoom) --- # Mailchimp > Source: https://truto.one/docs/integration-guides/mailchimp/ ## Install Mailchimp integration The Mailchimp integration can be found [here](https://app.truto.one/integrations/available/5b400b57-f658-407d-ad92-6310caa998e4). Please install it in your environments before proceeding with the steps below. ## Connecting a Mailchimp account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Mailchimp account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Mailchimp ![Select Mailchimp](https://docs-assets.truto.one/select-mailchimp.webp) You'll now be asked for your Mailchimp account prefix ## Finding your Mailchimp account prefix Find your Mailchimp account prefix from the URL on your browser ![Finding the Mailchimp account prefix](https://docs-assets.truto.one/mailchimp-details-1.webp) On clicking **Connect** you'll be directed to log in to your Mailchimp account. Once logged in, click on **Allow** ![Mailchimp authorization screen](https://docs-assets.truto.one/mailchimp-details-2.webp) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Mailchimp integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zendesk > Source: https://truto.one/docs/integration-guides/zendesk/ ## Install Zendesk integration The Zendesk integration can be found [here](https://app.truto.one/integrations/available/18e4ce34-de79-41a5-9096-2dd789efb5d6). Please install it in your environments before proceeding with the steps below. ## Connecting a Zendesk account :::callout{type="warning"} - `Administartor` or `Agent` role is required to use this API ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zendesk account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zendesk ![Select Zendesk](https://docs-assets.truto.one/select-zendesk.png) ## Finding your Zendesk Subdomain 5. You'll now be asked for your Zendesk Subdomain (for instructions on how to find your Zendesk Subdomain, visit this [link](https://support.zendesk.com/hc/en-us/articles/4409381383578-Where-can-I-find-my-Zendesk-subdomain-)). Fill in the details and click Connect. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account and you should see the new Zendesk integration under **Integrated Accounts**. Click on the **Account ID** to view the details and initiate API calls. --- # Okta > Source: https://truto.one/docs/integration-guides/okta/ ## Install Okta integration The Okta integration can be found [here](https://app.truto.one/integrations/available/3d3b8b94-df11-4a75-85b5-153255a3a467). Please install it in your environments before proceeding with the steps below. ## Connecting a Okta account --- :::callout{type="warning"} - `Admin` or `Super Admin` role is required to use this API ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Okta account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Okta ![Select Okta](https://docs-assets.truto.one/select-okta.png) ### Finding your Okta Subdomain and API Key 1. You'll now be prompted to add the `Okta Subdomain`. Find the Okta Subdomain by signing in to your Okta account in your browser as shown in the image below. ![Enter Subdomain from Okta](https://docs-assets.truto.one/url-okta.png) 2. To find API Key, Sign in to your Okta organization as a user with administrator privileges. 3. In the `Admin Console`, select `Security` > `API` from the menu and then select the `Tokens` tab. 4. Click `Create Token`. 5. Name your token and click `Create Token`. 6. Now copy the `Token` and enter it in Truto. Click `Connect`. --- 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Okta integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Copper > Source: https://truto.one/docs/integration-guides/copper/ ## Install Copper integration The Copper integration can be found [here](https://app.truto.one/integrations/available/72c5965f-2f6a-4407-b225-ab3de7b13fad). Please install it in your environments before proceeding with the steps below. ## Connecting a Copper account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Copper account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Copper !['Select Copper'](https://docs-assets.truto.one/select-copper.webp) ## Finding your API Key You'll now be prompted to add the API Key and email. To generate an API Key, go to your Copper account. Click on `Settings > Integrations > API Keys > Generate API Key`. Copy/paste the API Key in the relevant field and fill in your email. Click `Connect` !['Copper Get API Key'](https://docs-assets.truto.one/apikey-copper.webp) !['Copper API Key and Base URL'](https://docs-assets.truto.one/details-copper.webp) 5. _Voila!_ You should now see a connection successful message. You can now close this tab. 6. Go to your Truto account and you should see the new integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. --- # AlexisHR > Source: https://truto.one/docs/integration-guides/alexishr/ ## Install the AlexisHR integration The AlexisHR integration can be found [here](https://app.truto.one/integrations/available/d54529bb-f948-4c26-b2f2-1f2e58a0702d). Please install it in your environments before proceeding with the steps below. ## Connecting an AlexisHR account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their AlexisHR account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select AlexisHR ![Select AlexisHR](https://docs-assets.truto.one/alexis-select-integration.png) 5. You'll now be asked to key-in in your AlexisHR API Access Token and the subdomain to allow access to Truto. Go through the following steps. ![Enter AlexisHR API Access Token](https://docs-assets.truto.one/alexis-api-access-token.png) ## Generating an AlexisHR API Access Token :::callout{type="warning"} - It's recommended that an administrator of your AlexisHR account generates the API Access Token. ::: 1. Head on over to https://app.alexishr.com/access-tokens. 2. Enter the name, description and set the type to All. 3. Click on Save. 4. Copy the generated API Access Token. 5. Key in the API Access Token and click on **Connect** ![Enter AlexisHR API Access Token](https://docs-assets.truto.one/enter-alexis-api-access-token.png) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new AlexisHR integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Adobe > Source: https://truto.one/docs/integration-guides/adobe/ ## Install Adobe integration The Adobe integration can be found [here](https://app.truto.one/integrations/available/11321826-e271-432f-9886-7866d8e4bafb). Please install it in your environments before proceeding with the steps below. ## Connecting an Adobe account :::callout{type="warning"} - `Admin` role is required to use this API - `Enterprise Plan` is required to use this API ::: 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Adobe account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Adobe. ![Select Adobe](https://docs-assets.truto.one/select-adobe.png) 5. You'll now be asked for your Adobe Client ID and Client Secret. Fill in the details and click **Connect.** 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Adobe integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Front > Source: https://truto.one/docs/integration-guides/front/ ## Install Front integration The Front integration can be found [here](https://app.truto.one/integrations/available/a4ec07d5-c7c1-4f10-8fc7-57942af4d09a). Please install it in your environments before proceeding with the steps below. ## Connecting a Front account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Front account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Front ![Select Front](https://docs-assets.truto.one/select-front.png) 5. You'll now be asked to log in to your Front account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Front integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Zendesk Sell > Source: https://truto.one/docs/integration-guides/zendesksell/ ## Install Zendesk Sell integration The Zendesk Sell integration can be found [here](https://app.truto.one/integrations/available/87f8e1c9-c47f-471c-8c17-2be18fa3c874). Please install it in your environments before proceeding with the steps below. ## Connecting a Zendesk Sell account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Zendesk Sell account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Zendesk Sell ![Select Zendesk Sell](https://docs-assets.truto.one/select-zendesk-sell.png) 5. You'll now be asked to log in to your Zendesk Sell account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Zendesk Sell integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Basecamp > Source: https://truto.one/docs/integration-guides/basecamp/ ## Install Basecamp integration The Basecamp integration can be found [here](https://app.truto.one/integrations/available/1d4d50fa-684b-4619-b888-6ebb40686891). Please install it in your environments before proceeding with the steps below. ## Connecting a Basecamp account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Basecamp account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Basecamp ![Select Basecamp](https://docs-assets.truto.one/select-basecamp.png) 5. You'll now be asked to log in to your Basecamp account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Basecamp integration under **Integrate Accounts**. Click on the Account ID to view the details and initiate API calls. --- # BambooHR > Source: https://truto.one/docs/integration-guides/bamboohr/ ## Install BambooHR integration The BambooHR integration can be found [here](https://app.truto.one/integrations/available/7d69de13-dafb-4524-9854-b5c9f66d2443). Please install it in your environments before proceeding with the steps below. ## Connecting a BambooHR account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their BambooHR account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select BambooHR ![Select BambooHR](https://docs-assets.truto.one/select-bamboohr.webp) 5. You'll now be asked to log in to your BambooHR account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new BambooHR integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Slack > Source: https://truto.one/docs/integration-guides/slack/ ## Install Slack integration The Slack integration can be found [here](https://app.truto.one/integrations/available/c24d3ca0-8f49-432d-84bb-f3d65d5cd835). Please install it in your environments before proceeding with the steps below. ## Connecting a Slack account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their Slack account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Slack ![Select Slack](https://docs-assets.truto.one/select-slack.webp) 5. You'll now be asked to log in to your Slack account and allow access to Truto. Go through the steps. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new Slack integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # greytHR > Source: https://truto.one/docs/integration-guides/greythr/ ## Install greytHR integration The greytHR integration can be found [here](https://app.truto.one/integrations/available/60f018d6-8ebb-473f-95d3-2d227483bd00). Please install it in your environments before proceeding with the steps below. ## Connecting a greytHR account 1. Click on **Connect Account** ![Click connect account](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be any ID of your choosing. And then click on **Get connection link** ![Get connection link](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their greytHR account. ![Share connection link](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select greytHR ![Select greytHR](https://docs-assets.truto.one/select-greythr.webp) ## Finding your greytHR account 5. You'll now be prompted to add the 'greytHR Subdomain, API Username and User Password'. Find the account from the URL in greytHR login page as shown in the image below. For API Username and User Password, contact greytHR. Then click **Connect** ![Find your greytHR account details](https://docs-assets.truto.one/greythr-details-1.webp) ![Find your greytHR account details](https://docs-assets.truto.one/greythr-details-2.webp) 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account, and you should see the new greytHR integration under **Integrated Accounts**. Click on the Account ID to view the details and initiate API calls. --- # Sentry > Source: https://truto.one/docs/integration-guides/sentry/ ## Install Sentry integration The Sentry integration can be found [here](https://app.truto.one/integrations/available/baa03b4c-8531-4c17-b8da-0e87c62913bd). Please install it in your environments before proceeding with the steps below. ## Connecting a Sentry account 1. Click on `Connect Account` !['Click connect account'](https://docs-assets.truto.one/truto-connect-account.png) 2. Type in a value for the Tenant ID. This can be an ID of your choosing. And then click on `Get connection link` !['Get connection link'](https://docs-assets.truto.one/truto-connect-account-modal.png) 3. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too and they will be able to connect their Sentry account. !['Share connection link'](https://docs-assets.truto.one/truto-connect-account-link.png) 4. Select Sentry !['Select Sentry'](https://docs-assets.truto.one/select-sentry.png) ### Finding your Token and Organization Slug You'll now be prompted to add the Token and Organization Slug. #### Organization Slug 1. To find the Organization Slug, Sign in to your Sentry account. 2. Click on the `Settings` button at the left Navigation Panel. !['Click on settings button in left menu'](https://docs-assets.truto.one/setting-button-sentry.png) 3. Under `General Settings`, you will get your Organization Slug !['Organization Slug in General Settings'](https://docs-assets.truto.one/organization-slug-sentry.png) #### Token 1. To find the Token, Sign in to your Sentry account. 2. Click on the `Settings` button at the left Navigation Panel. !['Click on settings button in left menu'](https://docs-assets.truto.one/setting-button-sentry.png) 3. Under `Developer Settings`, click on `Create New Integration`. !['Click on developer settings and create new integration'](https://docs-assets.truto.one/create-integration-sentry.png) 4. Select `Internal Integration` and click on `Next`. !['Click on Internal integration and next'](https://docs-assets.truto.one/internal-integration-sentry.png) 5. Enter `Name` and give Permissions as shown below. !['Select permissions and click on Save Changes'](https://docs-assets.truto.one/permissions-sentry.png) 6. Click on `Save Changes` after selecting required permissions. !['Click on integration'](https://docs-assets.truto.one/select-integration-sentry.png) 7. Now, in `Developer Settings` in `Internal Integration` you wil find your Integration. Click on it and inside it you will find your `Token` at the bottom. !['Copy the access token'](https://docs-assets.truto.one/token-sentry.png) !['Sentry Token and Organization Slug'](https://docs-assets.truto.one/details-sentry.png) 5. Enter your `Token` and `Organization Slug`. Click on `Connect`. 6. _Voila!_ You should now see a connection successful message. You can now close this tab. 7. Go to your Truto account and you should see the integration under Integrated Accounts. Click on the Account ID to change or edit the integration to suit your needs. !['Sentry Integrated Account'](https://docs-assets.truto.one/account-sentry.png) ## Uninstalling the Sentry integration To uninstall the Sentry integration from your Truto account, select the Sentry [integration](https://app.truto.one/integrations/installed?search=sentry) from the Integrations tab. Click on the `Settings` tab in Sentry Integration page And then click on Uninstall. Uninstalling the integration will also remove all the Sentry integrated accounts from your Truto account. !['Uninstall Sentry'](https://docs-assets.truto.one/uninstall-sentry.png) --- # Registering webhooks in Truto for Customer.io > Source: https://truto.one/docs/integration-guides/customerio/registering-webhooks/ 1. If you have not already, register a webhook in Truto. Follow this [guide](https://truto.one/docs/guides/webhooks/creating-a-webhook) to create a webhook in Truto. Please make sure it is subscribed to the following events - `record:created` - `record:updated` - `record:deleted` ![Truto webhook setup](https://docs-assets.truto.one/customerio-truto-webhook-setup.png) 2. Please make a note of the integrated account ID of the Customer.io account you'd like to register the webhook for. Next, head on over to the Customer.io interface to create a webhook. You can find it under `Journeys > Data & Integrations > Reporting webhooks`. Click the `Add reporting webhook` button. ![New webhook](https://docs-assets.truto.one/customerio-new-webhook.png) 3. Enter a name for the webhook and paste the following URL into the `Webhook URL` field. Replace `{{INTEGRATED_ACCOUNT_ID}}` with the integrated account ID you noted in step 2. ``` https://api.truto.one/integrated-account-webhook/{{INTEGRATED_ACCOUNT_ID}} ``` 4. Select the events you'd like to receive notifications for. ![Enter webhook url](https://docs-assets.truto.one/customerio-enter-webhook-url.png) 5. Save the webhook. 6. In the webhook list screen, click the 3-dots icon for the webhook you just registered and click `Copy signing key`. ![Copy signing key](https://docs-assets.truto.one/customerio-copy-signing-key.png) 7. Head on over to the integrated account details page in Truto and click `Edit varaibles` button in the Variables section of the Details tab. Click `Add variable` and enter `webhook_secret` under the `Name` field and paste the signing key you copied in step 6 under the `Value` field. Click `Save`. ![Click edit variables](https://docs-assets.truto.one/customerio-click-edit-variables.png) ![Enter webhook secret](https://docs-assets.truto.one/customerio-enter-webhook-secret.png) 8. You're all set! Truto will now send notifications to the webhook URL you registered in Customer.io whenever a record is created, updated, or deleted in the integrated account. ## Example webhook event ```json { "id": "64fbf363-7ba3-4745-8c7b-730c0fdbf40d", "event": "record:created", "payload": { "resource": "customerio/events", "records": [ { "data": { "action_id": 42, "campaign_id": 23, "content": "Welcome to the club, we are with you.", "customer_id": "user-123", "delivery_id": "RAECAAFwnUSneIa0ZXkmq8EdkAM==", "headers": { "Custom-Header": [ "custom-value" ] }, "identifiers": { "id": "user-123" }, "recipient": "test@example.com", "subject": "Thanks for signing up" }, "event_id": "01E2EMRMM6TZ12TF9WGZN0WJQT", "metric": "sent", "object_type": "email", "timestamp": "2024-02-16T14:27:36.000Z" } ], "integrated_account_id": "37440f42-0e20-442e-a98d-04b2766247cc", "raw_event_type": "email.sent", "raw_payload": { "data": { "action_id": 42, "campaign_id": 23, "content": "Welcome to the club, we are with you.", "customer_id": "user-123", "delivery_id": "RAECAAFwnUSneIa0ZXkmq8EdkAM==", "headers": { "Custom-Header": [ "custom-value" ] }, "identifiers": { "id": "user-123" }, "recipient": "test@example.com", "subject": "Thanks for signing up" }, "event_id": "01E2EMRMM6TZ12TF9WGZN0WJQT", "metric": "sent", "object_type": "email", "timestamp": 1708093656 } }, "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c177", "created_at": "2024-02-16T14:27:36.805Z", "webhook_id": "15d12ab3-64a8-450e-a185-ead081cee0e4" } ``` --- # Link SDK > Source: https://truto.one/docs/sdks/link-sdk/ `@truto/truto-link-sdk` is a browser SDK for connecting your customer's accounts to Truto. It provides the Truto Connect UI for account linking and RapidForm for post-connection data selection. > **Try it live:** The [Truto Link SDK Playground](https://playground.truto.one/) lets you try Connect, File Picker, and RapidForm flows interactively — no setup required. ## Installation ```bash npm install @truto/truto-link-sdk ``` ## Truto Connect To show the Truto Connect UI, generate a `link-token` via the Truto API from your backend server. See [Create Link Token](/docs/api-reference/admin/link-token/create). ```javascript import authenticate from '@truto/truto-link-sdk'; const linkToken = 'link-token-uuid'; authenticate(linkToken, {}) .then((response) => { console.log(response); // { result: 'success', integration: 'copper', integrated_account_id: '...', post_connect_form: '{}' } }) .catch((error) => { console.log(error); }); ``` ## RapidForm To show the RapidForm, generate an `integrated-account-token` via the API. See [Create Integrated Account Token](/docs/api-reference/admin/integrated-accounts/create-token). ```javascript import { rapidForm } from '@truto/truto-link-sdk'; const integratedAccountToken = 'integrated-account-token-uuid'; rapidForm(integratedAccountToken, {}) .then((response) => { console.log(response); // { result: 'success', integration: 'copper', integrated_account_id: '...', post_connect_form: '{}' } }) .catch((error) => { console.log(error); }); ``` ## Options Both `authenticate` and `rapidForm` accept these options as the second argument: | Option | Type | Description | |--------|------|-------------| | `integration` | `string` | Pre-select an integration, skipping the selection screen | | `iframe` | `boolean` | Show the UI in a full-screen iframe overlay on your page (default: `true`). Set to `false` to open a popup window instead | | `sameWindow` | `boolean` | Navigate the current window to the Truto UI instead of opening an overlay or popup (default: `false`). The function then returns nothing, so there is no promise to await: the result arrives as query parameters on the link token's `redirect_uri` | | `width` | `number` | Popup window width in pixels when `iframe` is `false` (default: `700`) | | `height` | `number` | Popup window height in pixels when `iframe` is `false` (default: `800`) | | `baseUrl` | `string` | Origin serving the Truto UI, for self-hosted or staging deployments (default: `https://app.truto.one`). Must be an absolute `http(s)` URL | `authenticate` also accepts: | Option | Type | Description | |--------|------|-------------| | `noBack` | `boolean` | Hide the "Back" button on the connection screen | | `authFormat` | `string` | Authentication format: `api_key`, `oauth2`, `oauth2_client_credentials`, `keka_oauth` | | `skipRapidForm` | `boolean` | Skip the RapidForm UI after account connection | | `integrations` | `string[]` | Limit which integrations are shown | `rapidForm` also accepts: | Option | Type | Description | |--------|------|-------------| | `additionalContext` | `object` | Stored under the `context` attribute of the integrated account | | `preventDeselect` | `object` | Prevent deselection of multi-select values in RapidForm | | `disabledFields` | `object` | Disable specific fields in RapidForm | ## Error Handling Errors follow this structure: ```json { "result": "error", "error": "string describing the error", "error_type": "invalid_token | invalid_integration | connection_error | app_credentials_not_configured | post_install_error | validation_error | rapid_form_error", "integration": "integration name", "integrated_account_id": "integrated account id, when one exists" } ``` `integrated_account_id` is present only when the failure concerns an account that already exists: a re-authorization that was refused or failed, and `post_install_error` or `validation_error` after the account was created. A first connection that fails before the account exists, such as the user cancelling on the provider's consent screen, carries no `integrated_account_id` key at all. The same applies to the query parameters appended to a link token's `redirect_uri`. | Error Type | Description | |------------|-------------| | `invalid_token` | The link token is invalid or expired | | `invalid_integration` | Invalid or uninstalled integration name | | `connection_error` | Error during the connection flow. When the provider refuses authorization, for example the user cancels on the consent screen, `error` carries the provider's own reason (`error_description` when the provider sends one, otherwise its error code, such as `access_denied`), truncated to 300 characters. | | `app_credentials_not_configured` | The integration cannot be connected yet: its app credentials (your own OAuth app, or AWS STS signing credentials) are not configured in the environment. `error` carries the same string. In full-page mode the end user is shown who to contact; in iframe and popup modes the dialog closes, so show your own message. An admin fixes it under the integration's **Configuration** tab (see [Overriding OAuth credentials](/docs/guides/integrations/overriding-oauth-credentials)). | | `post_install_error` | Post-install steps failed after account creation | | `validation_error` | Validation requests failed after account creation | | `rapid_form_error` | Error opening or processing RapidForm | When the user closes the overlay or popup without finishing, the promise rejects with the string `"closed"` instead of an object. When the browser blocks the popup (`iframe: false`), it rejects with the string `"blocked"`. ## Native File Pickers Show vendor-native file picker UIs for cloud storage integrations. `showFilePicker` accepts `sharepoint`, `onedrive`, `googledrive` (or `google`), `box`, `dropbox` and `dropboxpersonal` as the integration name. The pickers always talk to `https://api.truto.one` and do not read `baseUrl`. ### SharePoint / OneDrive ```javascript import { showFilePicker } from '@truto/truto-link-sdk'; const integratedAccountToken = 'integrated-account-token-uuid'; showFilePicker('sharepoint', integratedAccountToken, {}) .then((response) => { console.log(response); }); ``` ### Google Drive ```javascript import { showFilePicker } from '@truto/truto-link-sdk'; showFilePicker('googledrive', integratedAccountToken, { appId: '1234567890', title: 'Choose Files', maxItems: 5, views: [ { viewId: 'DOCS', includeFolders: true, selectFolderEnabled: true }, { enableDrives: true, includeFolders: true }, ], }).then((response) => { console.log(response); }); ``` ### Box > Add your site's domain to the CORS Allowed Domains in your Box Developer Console. ```javascript showFilePicker('box', integratedAccountToken, {}) .then((response) => console.log(response)); ``` ### Dropbox > Add your site's domain to the Allowed Domains in your Dropbox Developer Console. Use `dropboxpersonal` instead of `dropbox` for Dropbox personal accounts. ```javascript showFilePicker('dropbox', integratedAccountToken, { appKey: 'your-dropbox-app-key', }).then((response) => console.log(response)); ``` ## File Picker Transforms Use `trutoExpression` (a [JSONata](https://jsonata.org/) expression) to transform picked items before they are stored: ```javascript showFilePicker('onedrive', integratedAccountToken, { trutoExpression: "$.($merge([{'selected_at': $now()}, $]))", }).then((response) => { console.log(response); }); ``` Set `truto_upsert_drive_items: true` to merge new selections with existing items instead of replacing them: ```javascript showFilePicker('onedrive', integratedAccountToken, { truto_upsert_drive_items: true, }).then((response) => { console.log(response); }); ``` For SharePoint and OneDrive, set `truto_preselect_drive_items: true` to open the picker with the items already stored on the integrated account selected: ```javascript showFilePicker('sharepoint', integratedAccountToken, { truto_preselect_drive_items: true, }).then((response) => { console.log(response); }); ``` --- # Python SDK > Source: https://truto.one/docs/sdks/python/ `truto-python-sdk` is an async Python client for the Truto API. It covers the Unified, Proxy, and Custom APIs, MCP, and the Admin API endpoints in the [Truto API Reference](/docs/api-reference/overview/introduction). Package: [pypi.org/project/truto-python-sdk](https://pypi.org/project/truto-python-sdk/). The methods on this page require version 0.2.0 or later. ## Requirements Python 3.12+ ## Installation ```bash pip install "truto-python-sdk>=0.2.0" ``` ## Quick start Create an [API token](/docs/guides/api-tokens/creating-api-tokens), then: ```python import asyncio from truto_python_sdk import TrutoApi truto_api = TrutoApi(token="") async def main(): # Installed integrations in the environment async for integration in truto_api.environment_integrations.list(): print(integration) # Integrated accounts for a tenant accounts = await truto_api.integrated_accounts.list(tenant_id="acme-1").to_array() # A Unified API call async for contact in truto_api.unified_api.list( "crm", "contacts", {"integrated_account_id": accounts[0]["id"]} ): print(contact) asyncio.run(main()) ``` ## How the client works - **Async.** Every method returns a coroutine you `await`, except `list()`, which returns a paginated cursor (see [Pagination](#pagination)). - **Resources.** Each Admin API resource is an attribute of `TrutoApi`, such as `truto_api.tenants` or `truto_api.sync_jobs`. Most expose `list`, `get`, `create`, `update`, and `delete`. - **Request bodies** are plain `dict`s, matching the JSON bodies in the API reference. - **Query parameters** are keyword arguments on Admin API methods (`truto_api.tenants.list(environment_id="...")`), and a `query_params` dict on the Unified and Proxy APIs. - **Errors.** A non-2xx response raises `aiohttp.ClientResponseError`, with the HTTP status on `.status`. - **Base URL.** It defaults to `https://api.truto.one`. Pass `base_url` to `TrutoApi` to use a different one. ```python import aiohttp try: await truto_api.integrated_accounts.get("missing-id") except aiohttp.ClientResponseError as error: print(error.status) # 404 ``` ## Pagination `list()` returns a cursor that follows `next_cursor` for you. Iterate it with `async for`: ```python async for ticket in truto_api.unified_api.list( "ticketing", "tickets", {"integrated_account_id": "766cc1ee-..."} ): print(ticket) ``` Collect every page with `to_array()`: ```python tickets = await truto_api.unified_api.list( "ticketing", "tickets", {"integrated_account_id": "766cc1ee-..."} ).to_array() ``` Or fetch one page at a time with `next_page()`. Stop when the cursor's `next_cursor` is `None`; calling `next_page()` after the last page returns the last page again. ```python cursor = truto_api.tenants.list(limit=50) while True: page = await cursor.next_page() print(page) if cursor.next_cursor is None: break ``` ## Unified API Accessible via `truto_api.unified_api`. Pass `integrated_account_id` in `query_params`. See the [Unified API reference](/docs/api-reference/overview/introduction) for the models and resources available. ```python query = {"integrated_account_id": "766cc1ee-..."} contacts = truto_api.unified_api.list("crm", "contacts", query) contact = await truto_api.unified_api.get("crm", "contacts", "123", query) created = await truto_api.unified_api.create("crm", "contacts", {"first_name": "Ada"}, query) await truto_api.unified_api.update("crm", "contacts", "123", {"first_name": "Grace"}, query) await truto_api.unified_api.delete("crm", "contacts", "123", query) # Custom methods: POST /unified/{model}/{resource}/{method} results = await truto_api.unified_api.custom_method("crm", "contacts", "search", {"query": "acme"}, query) ``` | Method | Endpoint | |---|---| | `list(model, resource, query_params=None)` | `GET /unified/{model}/{resource}` | | `get(model, resource, id, query_params=None)` | `GET /unified/{model}/{resource}/{id}` | | `create(model, resource, data, query_params=None)` | `POST /unified/{model}/{resource}` | | `update(model, resource, id, data, query_params=None)` | `PATCH /unified/{model}/{resource}/{id}` | | `delete(model, resource, id, query_params=None)` | `DELETE /unified/{model}/{resource}/{id}` | | `custom_method(model, resource, method, data, query_params=None)` | `POST /unified/{model}/{resource}/{method}` | | `meta(model, resource, integration_name, method)` | `GET /unified/{model}/{resource}/{integration_name}/meta/{method}` | | `model_meta(model, integration_name)` | `GET /unified/meta/{model}/{integration_name}` | `meta` returns an integration's mapping metadata (schema and supported parameters) for one unified method. `model_meta` returns the resources and methods of a unified model that an integration supports. ```python meta = await truto_api.unified_api.meta("crm", "contacts", "hubspot", "list") crm_on_hubspot = await truto_api.unified_api.model_meta("crm", "hubspot") ``` ## Proxy API Accessible via `truto_api.proxy_api`. Calls go to the integration's own API through Truto, with resource names as defined on the integration. ```python query = {"integrated_account_id": "766cc1ee-..."} tickets = truto_api.proxy_api.list("tickets", query) ticket = await truto_api.proxy_api.get("tickets", "123", query) await truto_api.proxy_api.create("tickets", {"subject": "Help"}, query) await truto_api.proxy_api.update("tickets", "123", {"status": "closed"}, query) await truto_api.proxy_api.delete("tickets", "123", query) await truto_api.proxy_api.custom_method("tickets", "merge", {"ids": ["1", "2"]}, query) ``` | Method | Endpoint | |---|---| | `list(resource, query_params=None)` | `GET /proxy/{resource}` | | `get(resource, id, query_params=None)` | `GET /proxy/{resource}/{id}` | | `create(resource, data, query_params=None)` | `POST /proxy/{resource}` | | `update(resource, id, data, query_params=None)` | `PATCH /proxy/{resource}/{id}` | | `delete(resource, id, query_params=None)` | `DELETE /proxy/{resource}/{id}` | | `custom_method(resource, method, data, query_params=None)` | `POST /proxy/{resource}/{method}` | ## Custom API Accessible via `truto_api.custom_api`. Sends an arbitrary request to the integration's API through Truto, at `/custom/{path}`. Query parameters are keyword arguments. ```python result = await truto_api.custom_api.get("my/custom/path", integrated_account_id="766cc1ee-...") await truto_api.custom_api.post("my/custom/path", {"key": "value"}, integrated_account_id="766cc1ee-...") ``` | Method | Endpoint | |---|---| | `get(path, **query_params)` | `GET /custom/{path}` | | `post(path, data=None, **query_params)` | `POST /custom/{path}` | | `put(path, data=None, **query_params)` | `PUT /custom/{path}` | | `patch(path, data=None, **query_params)` | `PATCH /custom/{path}` | | `delete(path, **query_params)` | `DELETE /custom/{path}` | ## MCP Accessible via `truto_api.mcp`. Talks to an integrated account's MCP server, using the token from [Create MCP server](#mcp-servers). ```python mcp_token = "your-mcp-token" await truto_api.mcp.initialize(mcp_token, "my-client", "1.0.0") tools = await truto_api.mcp.list_tools(mcp_token) result = await truto_api.mcp.call_tool(mcp_token, "list_tickets", {"status": "open"}) # Any other JSON-RPC message await truto_api.mcp.call(mcp_token, {"method": "tools/list", "id": 3}) ``` | Method | Description | |---|---| | `initialize(token, client_name, client_version)` | Sends `initialize` | | `list_tools(token)` | Sends `tools/list` | | `call_tool(token, name, args)` | Sends `tools/call` | | `call(token, payload)` | Sends a raw JSON-RPC payload to `POST /mcp/{token}` | ## Integrated accounts Accessible via `truto_api.integrated_accounts`. [API reference](/docs/api-reference/admin/integrated-accounts). ```python accounts = truto_api.integrated_accounts.list(tenant_id="acme-1") account = await truto_api.integrated_accounts.get("ia-id") await truto_api.integrated_accounts.update_credentials("ia-id", {"api_key": "new-key"}) await truto_api.integrated_accounts.validate("ia-id") await truto_api.integrated_accounts.bulk_delete({"tenant_id": "acme-1"}) capabilities = await truto_api.integrated_accounts.capabilities("ia-id") ``` | Method | Endpoint | |---|---| | `list(**query_params)` | `GET /integrated-account` | | `get(id)` | `GET /integrated-account/{id}` | | `create(data)` | `POST /integrated-account` (import an account with existing credentials) | | `update(id, data)` | `PATCH /integrated-account/{id}` | | `delete(id)` | `DELETE /integrated-account/{id}` | | `update_credentials(id, data)` | `PATCH /integrated-account/{id}/credentials` | | `bulk_delete(data)` | `POST /integrated-account/bulk-delete` (by `ids` or `tenant_id`) | | `create_integrated_account_token(id)` | `POST /integrated-account/token` | | `refresh_credentials(id)` | `POST /integrated-account/refresh-credentials` | | `refresh_mapping_cache(data=None)` | `POST /integrated-account/refresh-mapping-cache` | | `create_form_token(id)` | `POST /integrated-account/form-token` | | `run_post_install_actions(id)` | `POST /integrated-account/run-post-install-actions` | | `validate(id)` | `POST /integrated-account/{id}/validate` | | `capabilities(id)` | `GET /integrated-account/{id}/capabilities` | | `tools(id)` | `GET /integrated-account/{id}/tools` (deprecated; use `capabilities`) | ### MCP servers Each integrated account can have MCP servers. [API reference](/docs/api-reference/admin/mcp). ```python server = await truto_api.integrated_accounts.create_mcp_server( "ia-id", {"name": "Support agent", "config": {"methods": ["list", "get"]}} ) servers = await truto_api.integrated_accounts.list_mcp_servers("ia-id") ``` | Method | Endpoint | |---|---| | `list_mcp_servers(ia_id)` | `GET /integrated-account/{ia_id}/mcp` | | `create_mcp_server(ia_id, data)` | `POST /integrated-account/{ia_id}/mcp` | | `get_mcp_server(ia_id, id)` | `GET /integrated-account/{ia_id}/mcp/{id}` | | `update_mcp_server(ia_id, id, data)` | `PATCH /integrated-account/{ia_id}/mcp/{id}` | | `delete_mcp_server(ia_id, id)` | `DELETE /integrated-account/{ia_id}/mcp/{id}` | ## Link tokens Accessible via `truto_api.link_tokens`. [API reference](/docs/api-reference/admin/link-token). ```python link_token = await truto_api.link_tokens.create({"tenant_id": "acme-1"}) ``` | Method | Endpoint | |---|---| | `create(data)` | `POST /link-token` | ## Tenants Accessible via `truto_api.tenants`. [API reference](/docs/api-reference/admin/tenants). ```python await truto_api.tenants.create({"id": "acme-1", "name": "Acme"}) await truto_api.tenants.bulk_create({"mode": "upsert", "tenants": [{"id": "acme-2", "name": "Acme 2"}]}) ``` | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/tenant`, `/tenant/{id}` | | `bulk_create(data)` | `POST /tenant/bulk` | ## Integrations Accessible via `truto_api.integrations`. [API reference](/docs/api-reference/admin/integrations). ```python integration = await truto_api.integrations.get("integration-id") capabilities = await truto_api.integrations.capabilities("hubspot") # ID or name await truto_api.integrations.install("integration-id") await truto_api.integrations.uninstall("integration-id") ``` | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/integration`, `/integration/{id}` | | `capabilities(id_or_name)` | `GET /integration/{id}/capabilities` | | `tools(id_or_name)` | `GET /integration/{id}/tools` (deprecated; use `capabilities`) | | `unified_apis(id_or_name)` | `GET /integration/{id}/unified-apis` (deprecated; use `capabilities`) | | `install(integration_id, is_enabled=True)` | `POST /environment-integration` | | `uninstall(integration_id)` | Finds the integration's environment integration and deletes it | ## Environment integrations Integrations installed in your environment. Accessible via `truto_api.environment_integrations`. [API reference](/docs/api-reference/admin/installed-integrations-environment-integrations). | Method | Endpoint | |---|---| | `list(**query_params)` | `GET /environment-integration` | | `get(id)` | `GET /environment-integration/{id}` | | `create(data)` | `POST /environment-integration` | | `update(id, data)` | `PATCH /environment-integration/{id}` | | `delete(id)` | `DELETE /environment-integration/{id}` | ## Unified models Accessible via `truto_api.unified_models`. [API reference](/docs/api-reference/admin/unified-models). | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/unified-model`, `/unified-model/{id}` | | `install(unified_model_id)` | `POST /environment-unified-model` | | `uninstall(unified_model_id)` | Finds the model's environment unified model and deletes it | ## Environment unified models Unified models installed in your environment. Accessible via `truto_api.environment_unified_models`. [API reference](/docs/api-reference/admin/installed-unified-models-environment-unified-models). | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/environment-unified-model`, `/environment-unified-model/{id}` | ## Unified model mappings How a unified model's resource methods map to an integration. Both resources expose `list`, `get`, `create`, `update`, and `delete`. | Attribute | Endpoint | Reference | |---|---|---| | `truto_api.unified_model_resource_methods` | `/unified-model-resource-method` | [Unified model mappings](/docs/api-reference/admin/unified-model-mappings) | | `truto_api.environment_unified_model_resource_methods` | `/environment-unified-model-resource-method` | [Environment unified model mappings](/docs/api-reference/admin/installed-unified-models-environment-unified-model-mappings) | ```python overrides = truto_api.environment_unified_model_resource_methods.list( environment_unified_model_id="..." ) async for override in overrides: print(override) ``` ## Sync jobs Each resource below exposes `list`, `get`, `create`, `update`, and `delete`. | Attribute | Endpoint | Extra methods | Reference | |---|---|---|---| | `truto_api.sync_jobs` | `/sync-job` | | [Sync jobs](/docs/api-reference/admin/sync-jobs) | | `truto_api.sync_job_runs` | `/sync-job-run` | | [Sync job runs](/docs/api-reference/admin/sync-job-runs) | | `truto_api.sync_job_cron_triggers` | `/sync-job-cron-trigger` | `schedule(id)`: `POST /sync-job-cron-trigger/{id}/schedule` | [Sync job cron triggers](/docs/api-reference/admin/sync-job-cron-triggers) | | `truto_api.sync_job_templates` | `/sync-job-template` | | [Sync job templates](/docs/api-reference/admin/sync-job-templates) | | `truto_api.sync_job_run_states` | `/sync-job-run-state` | | [Sync job run state](/docs/api-reference/admin/sync-job-run-state) | ```python run = await truto_api.sync_job_runs.create({ "sync_job_id": "sync-job-id", "integrated_account_id": "766cc1ee-...", }) await truto_api.sync_job_runs.delete(run["id"]) # stops the run ``` ## Webhooks Accessible via `truto_api.webhooks`. [API reference](/docs/api-reference/admin/webhooks). ```python webhook = await truto_api.webhooks.create({"target_url": "https://example.com/truto"}) await truto_api.webhooks.test(webhook["id"], event_type="integrated_account:created") ``` | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/webhook`, `/webhook/{id}` | | `test(id, event_type=None, integrated_account_id=None)` | `POST /webhook/test` | ## Workflows Accessible via `truto_api.workflows` and `truto_api.workflow_runs`. API reference: [Workflows](/docs/api-reference/admin/workflows), [Workflow runs](/docs/api-reference/admin/workflowruns). ```python workflow = await truto_api.workflows.create({ "trigger_name": "integrated_account:active", "config": { "steps": [ { "type": "run", "action": "run_sync_job", "config": '{"sync_job_id": "sync-job-id", "integrated_account_id": integrated_account_id}', } ] }, }) async for run in truto_api.workflow_runs.list(workflow_id=workflow["id"]): print(run.get("status")) ``` | Attribute | Methods | Endpoint | |---|---|---| | `truto_api.workflows` | `list`, `get`, `create`, `update`, `delete` | `/workflow`, `/workflow/{id}` | | `truto_api.workflow_runs` | `list`, `get`, `create`, `update`, `delete` | `/workflow-run`, `/workflow-run/{id}` | ## Datastores Accessible via `truto_api.datastores`. [API reference](/docs/api-reference/admin/datastores). | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/datastore`, `/datastore/{id}` | | `test(id, method, body=None)` | `POST /datastore/{id}/test/{method}` | ## Static gates Accessible via `truto_api.static_gates`. [API reference](/docs/api-reference/admin/static-gates). | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/static-gate`, `/static-gate/{id}` | ## Observability destinations Accessible via `truto_api.observability_destinations`. [API reference](/docs/api-reference/admin/observability-destinations). ```python await truto_api.observability_destinations.test("observability-destination-id") ``` | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/observability-destination`, `/observability-destination/{id}` | | `test(id)` | `POST /observability-destination/{id}/test` | ## Documentation Accessible via `truto_api.documentations`. [API reference](/docs/api-reference/admin/documentation). | Method | Endpoint | |---|---| | `list`, `get`, `create`, `update`, `delete` | `/documentation`, `/documentation/{id}` | ## Batch requests Accessible via `truto_api.batch_requests`. [API reference](/docs/api-reference/admin/batch-requests). | Method | Endpoint | |---|---| | `create(data)` | `POST /batch-request` | ## Analytics Accessible via `truto_api.analytics`. [API reference](/docs/api-reference/admin/analytics). Query parameters are keyword arguments. For names that aren't valid Python identifiers, such as `from`, pass a dict as the first argument. ```python dashboard = await truto_api.analytics.dashboard(range="7d") series = await truto_api.analytics.timeseries( {"from": "2026-10-01", "to": "2026-10-08"}, environment_id="environment-id", metric="api_calls", ) by_integration = await truto_api.analytics.breakdown( environment_id="environment-id", metric="api_calls", dimension="integration" ) ``` | Method | Endpoint | |---|---| | `status(...)` | `GET /analytics/status` | | `metrics(...)` | `GET /analytics/metrics` | | `dashboard(...)` | `GET /analytics/dashboard` | | `timeseries(...)` | `GET /analytics/timeseries` | | `breakdown(...)` | `GET /analytics/breakdown` | ## Environments, API tokens, categories, and logs | Attribute | Methods | Endpoint | Reference | |---|---|---|---| | `truto_api.environments` | `list`, `get` | `/environment` | [Environments](/docs/api-reference/admin/environments) | | `truto_api.api_tokens` | `list`, `get` | `/api-token` | [API tokens](/docs/api-reference/admin/api-tokens) | | `truto_api.categories` | `list` | `/category` | [Categories](/docs/api-reference/admin/categories) | | `truto_api.logs` | `list` | `/log` | [Logs](/docs/api-reference/admin/logs) | `truto_api.ping()` calls `GET /ping` to check that your token works. ## Other resources These resources are in the SDK but not in the public API reference. | Attribute | Methods | Endpoint | |---|---|---| | `truto_api.users` | `list`, `get` | `/user`, `/user/{id}` | | `truto_api.teams` | `list`, `get` | `/team`, `/team/{id}` | | `truto_api.daemons` | `list`, `get`, `create`, `update`, `delete` | `/daemon`, `/daemon/{id}` | | `truto_api.daemon_jobs` | `list`, `get`, `create`, `update`, `delete` | `/daemon-job`, `/daemon-job/{id}` | | `truto_api.daemon_job_runs` | `list`, `get`, `create`, `update`, `delete` | `/daemon-job-run`, `/daemon-job-run/{id}` | | `truto_api.daemon_job_cron_triggers` | `list`, `get`, `create`, `update`, `delete`, `schedule` | `/daemon-job-cron-trigger`, `/daemon-job-cron-trigger/{id}` | | `truto_api.sandbox_integrated_accounts` | `list`, `get`, `create`, `delete` | `/sandbox-integrated-account`, `/sandbox-integrated-account/{id}` | | `truto_api.alarms` | `list`, `get`, `create`, `update`, `delete` | `/alarm`, `/alarm/{id}` | | `truto_api.integrated_account_webhooks` | `process(integrated_account_id, payload)` | `POST /integrated-account-webhook/{id}` | | `truto_api.environment_integration_webhooks` | `process(environment_integration_id, payload)` | `POST /environment-integration-webhook/{id}` | --- # TypeScript SDK > Source: https://truto.one/docs/sdks/typescript/ `@truto/truto-ts-sdk` is a TypeScript/JavaScript library to interact with the Truto API. The SDK mirrors the Unified, Proxy, Custom, and core Admin API endpoints of the Truto REST API, which are documented in the [Truto API Reference](/docs/api-reference/overview/introduction). It does not wrap every endpoint; call the REST API directly for anything it does not expose. ## Requirements Node.js 18+ (the library uses `fetch`) ## Installation ```bash npm install @truto/truto-ts-sdk ``` or via yarn: ```bash yarn add @truto/truto-ts-sdk ``` ## Usage ### ESM Import ```javascript import TrutoApi from '@truto/truto-ts-sdk' ``` ### CommonJS Import ```javascript const { default: TrutoApi } = require('@truto/truto-ts-sdk'); ``` ### Initializing the client ```javascript const trutoApi = new TrutoApi({ token: process.env.TRUTO_API_TOKEN, }) ``` ### Calling the APIs ```javascript // Fetch all installed integrations const installedIntegrations = trutoApi.environmentIntegration.list() for await (const installedIntegration of installedIntegrations) { console.log(installedIntegration) } // Fetch integrated accounts for a tenant const integratedAccounts = trutoApi.integratedAccount.list({ tenant_id: 'acme-1', }) console.log(await integratedAccounts.toArray()) // To fetch all // Install an integration to the environment the API token is associated with await trutoApi.integration.install('32b122db-ad24-400f-8ee7-0be21edc12ef') // Make a request to the unified API const unifiedApiCursor = trutoApi.unifiedApi.list({ unified_model: 'accounting', resource: 'accounts', integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', created_at: '2023-05-01T00:00:00.000Z', }) for await (const unifiedApiResource of unifiedApiCursor) { console.log(unifiedApiResource) } const unifiedApiResource = await trutoApi.unifiedApi.get('1', { unified_model: 'accounting', resource: 'accounts', integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', }) console.log(unifiedApiResource) ``` ## Available Tools The SDK provides a way to discover available tools and their schemas for each integrated account. This is particularly useful when building LLM-powered applications: ```javascript // Get available tools for an integrated account const tools = await trutoApi.integratedAccount.tools( '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', ['list', 'get'] ) console.log(tools) // Get all tools without filtering by method const allTools = await trutoApi.integratedAccount.tools( '766cc1ee-6637-4aa1-a73e-a0c89ccc867c' ) ``` Each tool in the response includes: - `resource` — The resource name (e.g., `tickets`, `accounts`) - `method` — The available method (e.g., `list`, `get`, `create`) - `name` — A human-readable name for the tool - `description` — A description of what the tool does - `query_schema` — JSON schema for query parameters - `body_schema` — JSON schema for request body (if applicable) - `required` — Array of required parameter names Truto provides a toolset for [Langchain.js](https://github.com/trutohq/truto-langchainjs-toolset) as well. ## Retry Options The SDK provides built-in retry mechanisms to handle rate limits and transient failures: ```javascript const result = await trutoApi.unifiedApi.list({ unified_model: 'accounting', resource: 'accounts', integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', }, { retryStatusCodes: [429, 503], defaultRetryAfter: 5, maxRetries: 5, timeout: 60, onRetry: (retryCount, statusCode) => { console.log(`Retry attempt ${retryCount} due to status code ${statusCode}`); }, onRateLimited: (retryAfter, retryCount) => { console.log(`Rate limited, waiting ${retryAfter}s before retry ${retryCount + 1}`); } }).toArray(); ``` | Option | Default | Description | |--------|---------|-------------| | `noRetry` | `false` | Disable retries for this request. When `true`, the other retry options have no effect | | `retryStatusCodes` | `[408, 409, 425, 429, 502, 503, 504]` | Extra HTTP status codes to retry on. They are added to the defaults, so the defaults are always retried | | `defaultRetryAfter` | `10` | Seconds to wait before retrying a `429` response that has no `Retry-After` header. Other retryable status codes are retried immediately | | `maxRetries` | `3` | Maximum number of retries | | `timeout` | `30` | Timeout in seconds for each attempt. A timed-out attempt throws an error with status code `408` and is not retried | | `onRetry` | — | Callback notified on retries | | `onRateLimited` | — | Callback notified on 429 responses | Numeric options set to `0` fall back to their defaults. ## Request Queue For high-volume API requests with rate limiting, the SDK provides a request queue: ```javascript import TrutoApi, { RequestQueue } from '@truto/truto-ts-sdk' const truto = new TrutoApi({ token: process.env.TRUTO_API_TOKEN, baseUrl: process.env.TRUTO_API_BASE_URL, }) const queue = new RequestQueue(truto, { concurrency: 5, interval: 1000, }) const response = await queue.proxyApi .list({ integrated_account_id: '820b732c-bd4d-4b98-b33e-fda752a368ff', resource: 'tickets', limit: 10, }) .toArray() ``` ## File Uploads The SDK supports file uploads using `FormData`: ```javascript const formData = new FormData(); formData.append('file', fileObject); formData.append('name', 'example.pdf'); await trutoApi.unifiedApi.create(formData, { unified_model: 'file-storage', resource: 'drive-items', integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', }); // With body passthrough (sends FormData directly to integration) await trutoApi.unifiedApi.create(formData, { unified_model: 'file-storage', resource: 'drive-items', integrated_account_id: '766cc1ee-6637-4aa1-a73e-a0c89ccc867c', truto_body_passthrough: true, }); ``` --- # AI-powered build > Source: https://truto.one/docs/cli/integrations-build/ `truto integrations build` discovers API documentation, runs an **agentic** build, and writes a local **IntegrationFile** JSON (for example `acme.integration.json`). Nothing is pushed to Truto until you run [`truto integrations apply`](/docs/cli/integrations#apply). ```bash # Create a new integration from docs truto integrations build https://docs.example.com/openapi.json # Improve an existing integration (slug loads live config from your environment) truto integrations build https://docs.example.com/openapi.json acme # Push when you are satisfied truto integrations apply acme.integration.json ``` You can pass **multiple source URLs** in any order; the CLI picks the highest-fidelity source as primary and indexes the rest. URLs must start with `http://`, `https://`, `file://`, `/`, or `./`. Any other positional argument is treated as the integration slug. ```bash truto integrations build \ https://docs.example.com/guides/rest-api/ \ https://docs.example.com/static/openapi.json \ acme ``` ## Prerequisites | Requirement | Notes | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Anthropic API key** | Required for the default LLM provider. Flag → `$ANTHROPIC_API_KEY` → `truto profiles set-key anthropic` → interactive prompt. | | **Fireworks API key** | Required only when you pick `--llm-provider fireworks`. Flag → `$FIREWORKS_API_KEY` → `truto profiles set-key fireworks` → interactive prompt. | | **Firecrawl API key** | Generic docs sites that need crawling, **and** `web_search` / `web_fetch` under the Fireworks provider. Flag → `$FIRECRAWL_API_KEY` → `truto profiles set-key firecrawl` → interactive prompt. | | **Truto login** | Required when improving an existing slug (`acme`) so the CLI can load live config and categories. | The CLI prompts for the LLM provider interactively when `--llm-provider` is omitted on a TTY (defaults to `anthropic` in CI / non-TTY). Pick **Fireworks AI** for Fireworks-hosted Kimi, DeepSeek, GLM, MiniMax, or Qwen models. ## What happens during a build The default flow (no flags) is **agentic**. An older **12-section orchestrator** still exists behind `--legacy-flow` for parity testing; it is not what new users should follow. ### 1. Pre-flight - Resolve the LLM provider (Anthropic by default, or Fireworks via `--llm-provider fireworks`) and its API key. Resolve Firecrawl when crawling is needed (and for Fireworks `web_search` / `web_fetch`). - Optional prompt: **general build instructions** (press Enter to skip). Skip non-interactively with `--instructions "…"`. - Load the pattern catalog and exemplars used by audit and the agent. ### 2. Discovery The CLI extracts and indexes your source(s): OpenAPI, Postman collections, GraphQL, `llms-full.txt`, Mintlify/Readme tricks, Firecrawl crawl, and related tiers. Pin behavior with `--source-tier` when auto-detection picks the wrong tier. By default the CLI uses **agentic discovery**; pass `--legacy-discovery` to force the older deterministic tier ladder (GraphQL sources always use legacy discovery). For OpenAPI or GraphQL specs, the CLI can also crawl companion human-readable doc pages unless you pass `--no-companion-docs`. Pass explicit roots with `--companion-docs ` (repeatable). ### 3. Audit (informational) The CLI compares discovered docs, live config (on update), and catalog patterns, then prints **audit findings** to stderr (severity, section, resource/method, message). On the agentic path these are **not** a menu you must complete — the agent uses them as context. On `--legacy-flow`, findings drive a multiselect of which sections to build. ### 4. Phase A — autonomous build The agent works through the integration file in a **working copy** next to your output path (for example `.acme.integration.json.working`). It calls tools (read source docs, search the index, read corpus examples, validate patches) and applies **cascade patches** without per-section yes/no prompts. Phase A ends when the agent signals completion or hits its turn budget (you can still refine in Phase B). ### 5. Editor (optional) Unless you pass `--no-editor`, the CLI opens the working file in your editor (`$VISUAL` / `$EDITOR`, `--editor`, or profile). Fix anything by hand before refinement. ### 6. Phase B — refinement loop You drive changes with **free-form instructions**: ```text Refinement instruction (e.g. "website_id should be a credential, not a query param" — leave empty to finish): ``` For each instruction the agent proposes a patch. You review the diff and choose: | Choice | Meaning | | ---------------------------------- | --------------------------------------------- | | **[a] accept and continue** | Apply the patch to the working file | | **[s] skip this section** | Decline this patch | | **[c] chat (refine via feedback)** | Explain what to change; the agent re-proposes | Press **Enter** on an empty line to finish Phase B. Type **`:edit`** to open the working file in your editor again (with validate / discard). Accepted refinements can be saved as **learnings** for future builds (`~/.truto/build-learnings.jsonl`; Windows: `%USERPROFILE%\.truto\build-learnings.jsonl`). ### 7. Documentation generation After Phase B, the CLI generates **per-method documentation rows** in the background (`description`, `query_schema`, `body_schema`, `response_schema`) from the final config and source index. This runs automatically; you do not step through 12 sections manually. ### 8. Output The final file is written to `--out` or `.integration.json`, with a reminder to run `truto integrations apply`. :::callout{type="info"} **Resume:** If a working file already exists with substantial content, Phase A is skipped and you go straight to Phase B refinement. **Only missing methods:** On an existing integration slug, pass `--only-missing` to add API methods that appear in the source but are not yet on the live integration — without changing existing methods, auth, or pagination. Incompatible with `--legacy-flow` and `--docs-only`. Phase B refinement is skipped in this mode. ::: ## Integration file shape The output follows the **IntegrationFile** schema: `name`, `config` (auth, pagination, `resources`, webhooks, etc.), optional `documentation` rows, `audit_notes`, and `_refinements` from Phase B. The agent still reasons about the same conceptual areas (basic details, base URL, auth, resources, webhooks, …) but as patches on one JSON document, not a fixed **[a]/[b]/[c]** menu per section. ## LLM providers The build loop supports two LLM providers. Pick interactively when `--llm-provider` is omitted on a TTY; the default is `anthropic` in CI / non-TTY. | Provider | Flag | Models | Web tools | Notes | |----------|------|--------|-----------|-------| | **Anthropic** (default) | `--llm-provider anthropic` | Tiered Claude: `claude-opus-4-6` (agent), `claude-sonnet-4-6` (extraction/docs), `claude-haiku-4-5` (classification) | Anthropic **server-side** `web_search` / `web_fetch` | Adaptive thinking, `cache_control` blocks, container metadata | | **Fireworks AI** | `--llm-provider fireworks` | One shared **workhorse** model for agent + extraction, plus a cheap **classification** model | **Client-side** `web_search` / `web_fetch` via Firecrawl (requires `FIRECRAWL_API_KEY`) | No adaptive thinking, no Anthropic server tools, no `cache_control`; Fireworks prompt caching is automatic (CLI sends `x-session-affinity`) | ### Picking Fireworks ```bash # Interactive — the CLI prompts for the LLM provider when --llm-provider is omitted on a TTY truto integrations build https://docs.example.com acme # Non-interactive — pin Fireworks and a workhorse model export FIREWORKS_API_KEY=... truto integrations build https://docs.example.com acme \ --llm-provider fireworks \ --llm-model kimi-k2p7 ``` ### Fireworks model presets Fireworks uses a **shared workhorse model** for agent + extraction, plus a separate cheap **classification** model. Naming a model — with `--llm-model`, its aliases `--llm-agent-model` / `--llm-extraction-model`, or the interactive picker — pins all three tiers to it. Add `--llm-classification-model` to route classification to a different model. The defaults below apply only when no model is named (non-interactive runs). | Tier | Claude default | Fireworks default | Used for | |------|----------------|-------------------|----------| | Agent + extraction | Opus + Sonnet | `glm-5p2` (one model for both) | Discovery agent, build loop, docs, schemas | | Classification | `claude-haiku-4-5` | `deepseek-v4p1-flash` | Page classification, routing | **Workhorse presets** (pick one; it also runs classification unless `--llm-classification-model` is set): | Preset | Fireworks model | Notes | |--------|-----------------|-------| | `glm-5p2` | `accounts/fireworks/models/glm-5p2` | 1M context flagship agent (default) | | `glm-5p3-flash` | `accounts/fireworks/models/glm-5p3-flash` | 1M context, lower-cost agent | | `kimi-k2p7` | `accounts/fireworks/models/kimi-k2p7-code` | Coding specialist, MCP workflows | | `minimax-m3` | `accounts/fireworks/models/minimax-m3` | K2.7-class agent, 512k context | | `qwen3p7-plus` | `accounts/fireworks/models/qwen3p7-plus` | Strong structured JSON for docs/schemas | | `deepseek-v4-pro` | `accounts/fireworks/models/deepseek-v4-pro` | 1M context reasoning | **Classification presets:** `deepseek-v4p1-flash` (default) or `gpt-oss-20b`. Raw `accounts/.../models/...` IDs also work on any tier flag. :::callout{type="warning"} Don't mix `--anthropic-model` with `--llm-provider fireworks` (or `--llm-model` with `--llm-provider anthropic`) — the CLI hard-errors. Use `--llm-model` (or `--llm-agent-model` / `--llm-extraction-model` / `--llm-classification-model`) for Fireworks, and `--anthropic-model` for Anthropic. ::: ### Embedding provider Hybrid source search (BM25 + cosine) defaults to a **local ONNX** model (`all-MiniLM-L6-v2`, ~35 MB, no API key). To use Fireworks-hosted embeddings instead: ```bash truto integrations build https://docs.example.com acme \ --embedding-provider fireworks \ --embedding-model qwen3-embedding-8b ``` `--embedding-provider fireworks` requires `FIREWORKS_API_KEY`. Supported `--embedding-model` presets: `local-minilm`, `qwen3-embedding-8b` (and aliases `qwen3`, `best`). The default for `--embedding-provider fireworks` is `qwen3-embedding-8b`. ### Web tools and Firecrawl `web_search` / `web_fetch` are always exposed to the agent, but the backend depends on the LLM provider: | | Anthropic (default) | Fireworks | |---|---------------------|-----------| | `web_search` / `web_fetch` | Anthropic server tools | Firecrawl-backed **client-side** tools | | Required keys | `ANTHROPIC_API_KEY` | `FIREWORKS_API_KEY` **and** `FIRECRAWL_API_KEY` | | Per-run budgets (build / discovery) | 10 search / 20 fetch | 10 search / 20 fetch | | OpenAPI spec hunt (`find_openapi_spec`) | 5 search / 5 fetch per invocation | 5 search / 5 fetch per invocation | Without a Firecrawl key, **Fireworks builds still run** but cannot use `web_search` or `web_fetch`. Doc crawling via `map_doc_site` / `scrape_pages` also requires Firecrawl. Use `--no-firecrawl` only when you accept a docs-only path without live web tools. ## Useful flags | Flag | Purpose | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--out ` | Output path (default `.integration.json`) | | `--instructions ` | Skip the build-instructions prompt | | `--source-tier ` | Pin doc extraction (`auto`, `openapi-only`, `postman`, `llms-full`, `graphql-introspection`, … — run `truto integrations build --help` for the full list) | | `--legacy-discovery` | Force legacy deterministic discovery instead of the agentic loop (default) | | `--no-spec-web-search` | Skip web search when hunting for an OpenAPI spec URL | | `--companion-docs ` / `--no-companion-docs` | Crawl extra doc-site roots alongside OpenAPI/GraphQL (`--companion-docs` is repeatable) | | `--max-pages ` | Cap doc pages walked during discovery (default `200`) | | `--only-missing` | UPDATE mode: add missing methods only; requires existing integration slug | | `--integration-config-dir ` | Local integration corpus for pattern matching (`$TRUTO_INTEGRATION_CONFIG_DIR` or profile `integrationConfigDir`) | | `--no-firecrawl` | Skip Firecrawl; use cheaper extraction only. Also disables `web_search` / `web_fetch` under `--llm-provider fireworks` | | `--firecrawl-ignore-robots-txt` | Pass `ignoreRobotsTxt: true` to Firecrawl (enterprise plans only) | | `--refresh-firecrawl-cache` / `--no-llm-cache` / `--refresh-llm-cache` | Control local caches under `~/.truto/cache/` (Windows: `%USERPROFILE%\.truto\cache\`) — `--no-llm-cache` / `--refresh-llm-cache` apply to both LLM providers | | `--no-editor` | Skip opening the editor between Phase A and B | | `--editor ` | Editor command (`cursor`, `code`, …) | | `--llm-provider ` | `anthropic` (default) or `fireworks`. Prompts interactively when omitted on a TTY | | `--anthropic-api-key ` | Override Anthropic API key (flag → `$ANTHROPIC_API_KEY` → profile → prompt) | | `--anthropic-model ` | Override Claude model for all tasks (Anthropic provider only; tiered defaults: `claude-opus-4-6` / `claude-sonnet-4-6` / `claude-haiku-4-5`) | | `--fireworks-api-key ` | Override Fireworks API key (required for `--llm-provider fireworks`) | | `--llm-model ` | Pin all Fireworks tiers (agent, extraction, classification) to one model. Presets: `glm-5p2`, `glm-5p3-flash`, `kimi-k2p7`, `minimax-m3`, `qwen3p7-plus`, `deepseek-v4-pro`, or a raw `accounts/.../models/...` ID | | `--llm-agent-model ` / `--llm-extraction-model ` | Aliases for `--llm-model` (also pin classification) | | `--llm-classification-model ` | Fireworks classification-tier model. Presets: `deepseek-v4p1-flash`, `gpt-oss-20b` | | `--embedding-provider ` | `local` (default, MiniLM ONNX) or `fireworks` (Qwen3, requires `FIREWORKS_API_KEY`) | | `--embedding-model ` | Embedding model preset: `local-minilm`, `qwen3-embedding-8b` (and aliases `qwen3`, `best`) | | `--no-embeddings` | Skip embedding the source index for this build (BM25-only search). Cached embeddings still survive for future runs | | `--legacy-flow` | Use the old 12-section orchestrator (`[a]` Accept, `[s]` Skip, `[w]` Seems wrong per section) | | `--docs-only ` | Skip build; regenerate documentation rows only | | `--resource ` | With `--docs-only`, limit which resources get new doc rows | | `--debug-log ` / `--no-debug-log` | JSONL transcript of the build (default on under `~/.truto/logs/`; Windows: `%USERPROFILE%\.truto\logs\`) | Deprecated flags from older builds (for example `--resources`, `--yes`, `--dry-run` on **build**, `--include-low-confidence`, `--plan-out`, `--report-out`, `--category`, `--label`, `--base-url`, `--no-bootstrap`, `--no-basic-details`, `--no-query-schema`, `--no-body-schema`, `--descriptions-only`, `--rewrite-bad-descriptions`, `--no-llm-canonicalize`, `--no-llm-regroup`, `--no-llm-split-buckets`, `--strict`, `--no-validate`, `--keep-inline-docs`) exit with an error (`2`) before any LLM key resolution or crawling runs, and point you at the new flow plus `truto integrations apply`. ## Bring-your-own keys | Key | Required when | | ------------------- | ---------------------------------------------- | | `ANTHROPIC_API_KEY` | Default build (`--llm-provider anthropic`) | | `FIREWORKS_API_KEY` | `--llm-provider fireworks` or `--embedding-provider fireworks` | | `FIRECRAWL_API_KEY` | Generic doc sites that need crawling, **and** `web_search` / `web_fetch` under `--llm-provider fireworks` | Resolution order for each: CLI flag → environment variable → `truto profiles set-key` → interactive prompt on a TTY. Keys are stored under the active profile, so `truto profiles use staging` and `truto profiles use prod` can hold different `anthropicApiKey` / `fireworksApiKey` / `firecrawlApiKey` values. > **Note:** Hybrid search (BM25 + cosine) is now powered by a local ONNX model (`all-MiniLM-L6-v2`) downloaded automatically on first use (~35 MB). No external API key is required. To use Fireworks-hosted `qwen3-embedding-8b` embeddings instead, pass `--embedding-provider fireworks` (requires `FIREWORKS_API_KEY`). ## Doc-discovery and caches The discovery pipeline tries cheap sources before Firecrawl (OpenAPI direct, `llms.txt` / `llms-full.txt`, markdown siblings, then scoped Firecrawl). See `truto integrations build --help` for `--source-tier` values. | Cache | Location | TTL | Bypass | | --------- | -------------------------------------------------------------------------------- | --- | --------------------------------------- | | Firecrawl | `~/.truto/cache/firecrawl/` (`%USERPROFILE%\.truto\cache\firecrawl\` on Windows) | 24h | `--refresh-firecrawl-cache` | | LLM | `~/.truto/cache/anthropic/` (`%USERPROFILE%\.truto\cache\anthropic\` on Windows) | 7d | `--no-llm-cache`, `--refresh-llm-cache` | The LLM cache is keyed by (provider + model + system prompt + messages hash) and is **shared by both Anthropic and Fireworks** — Fireworks calls go through the same Anthropic-compatible adapter, so the on-disk path is the same despite the `anthropic/` directory name. Switching models or providers invalidates automatically. ## After the build Push the file with [Managing integrations — Apply](/docs/cli/integrations#apply). Validate structure first with [Lint](/docs/cli/integrations#lint). To add a **single** method when you already know the HTTP verb and path (no LLM), use [Add method](/docs/cli/integrations-add-method) instead of a full build. ## Next steps - [Managing integrations](/docs/cli/integrations) — CRUD, `init`, `validate`, `apply`, `lint` - [Add method](/docs/cli/integrations-add-method) — mechanical one-method PATCH - [Examples](/docs/cli/examples) — end-to-end workflows --- # Examples > Source: https://truto.one/docs/cli/examples/ Worked examples for common CLI workflows. Assumes you have run `truto login` and have at least one integrated account. ## Orientation ```bash truto whoami truto whoami -o json truto whoami -p staging truto profiles list truto team get -o json ``` ## Discover integrations ```bash truto integrations list truto integrations list --name hubspot truto integrations unified-apis truto integrations tools ``` ## Manage tenants ```bash # List tenants in this environment truto tenants list # Pre-create a tenant with metadata before the customer connects # --metadata '{"tier":"enterprise"}' also works; the flag value is parsed as JSON. truto tenants create -b '{"id":"acme-1","name":"Acme Corp","metadata":{"tier":"enterprise","region":"wnam"}}' # Bulk create up to 1000 tenants from a JSON file or stdin # Default mode is insert (skips existing ids). Use --mode upsert to update them. truto tenants create-bulk -b '[{"id":"acme-1","name":"Acme Corp"}]' truto tenants create-bulk --mode upsert -b '[{"id":"acme-1","name":"Acme Corp","metadata":{"tier":"gold"}}]' cat tenants.json | truto tenants create-bulk --stdin # Inspect one tenant truto tenants get acme-1 # Delete a tenant (fails with 409 if it still has connected accounts) truto tenants delete acme-1 # Open the tenants page in your browser truto open tenants truto open tenants acme-1 ``` ## Discover what an account can do ```bash ACCOUNT= truto accounts tools $ACCOUNT truto accounts identify $ACCOUNT truto accounts tools $ACCOUNT --methods list truto accounts tools $ACCOUNT --methods list,get --tags contacts,deals truto capabilities $ACCOUNT --type proxy ``` :::callout{type="tip"} For coding agents, `accounts tools` is the best starting point when you do not know which resources an account supports. ::: ## Proxy API ```bash ACCOUNT= truto proxy contacts -a $ACCOUNT truto proxy contacts 1 -m get -a $ACCOUNT -o json truto proxy contacts -m create -a $ACCOUNT -b '{"properties":{"email":"jane@example.com"}}' ``` ## Unified API ```bash ACCOUNT= truto unified crm contacts -a $ACCOUNT truto unified crm contacts -m get -a $ACCOUNT -o json truto unified crm contacts -m create -a $ACCOUNT -b '{"first_name":"Jane","last_name":"Doe"}' ``` ## Test a response mapping ```bash # Evaluate a mapping against a saved raw API response (no live call) truto unified test-mapping \ --model crm --resource contacts --integration hubspot \ --input sample-list-response.json # Or pass the JSONata expression directly truto unified test-mapping \ --mapping '$map(results, function($r) { $r })' \ --input sample-list-response.json ``` ## Export and analyze ```bash ACCOUNT= truto export crm/contacts -a $ACCOUNT -o ndjson --out contacts.ndjson truto export crm/contacts -a $ACCOUNT -o ndjson | jq -r '.email' | sort -u wc -l < contacts.ndjson ``` ## Profiles and staging ```bash truto login --token $STAGING_TOKEN --profile-name staging truto use staging truto integrations list truto use default ``` ## Integration build workflow ```bash export ANTHROPIC_API_KEY=sk-ant-... # Agentic build → working file → refinement (press Enter when done) → my-vendor.integration.json truto integrations build https://docs.vendor.com/openapi.json my-vendor # Add only endpoints missing from the live integration truto integrations build https://docs.vendor.com/openapi.json my-vendor --only-missing truto integrations lint my-vendor.integration.json truto integrations apply my-vendor.integration.json ``` ### Build on Fireworks AI instead of Anthropic ```bash export FIREWORKS_API_KEY=... export FIRECRAWL_API_KEY=... # required for web_search / web_fetch under Fireworks # Default workhorse (glm-5p2) for agent + extraction, deepseek-v4p1-flash for classification (non-interactive) truto integrations build https://docs.vendor.com/openapi.json my-vendor \ --llm-provider fireworks # Pin a different workhorse (Kimi K2.7 Code) and a cheaper classifier truto integrations build https://docs.vendor.com/openapi.json my-vendor \ --llm-provider fireworks \ --llm-model kimi-k2p7 \ --llm-classification-model gpt-oss-20b # Use Fireworks-hosted Qwen3 embeddings instead of the local ONNX default truto integrations build https://docs.vendor.com/openapi.json my-vendor \ --llm-provider fireworks \ --embedding-provider fireworks \ --embedding-model qwen3-embedding-8b ``` See [AI-powered build — LLM providers](/docs/cli/integrations-build#llm-providers) for the full preset table and the `--anthropic-model` / `--llm-model` exclusivity rule. To add a single endpoint when you already have the HTTP verb and path, use `truto integrations add-method` — see [Add method](/docs/cli/integrations-add-method). ## Unified mappings build workflow ```bash export ANTHROPIC_API_KEY=sk-ant-... ACCOUNT= # Agentic build → JSONata mapping rows grounded on live samples → my-vendor.crm.mappings.json truto unified-mappings build my-vendor crm --account $ACCOUNT # Audit, then push to the base mapping rows truto unified-mappings validate my-vendor.crm.mappings.json truto unified-mappings apply my-vendor.crm.mappings.json --target base ``` See [Unified mappings build](/docs/cli/unified-mappings) for the sample ladder, flags, and the MappingFile shape. ## Verbose debugging ```bash truto proxy contacts -a $ACCOUNT -v # stderr shows → GET ... and ← status ``` ## Piping between commands ```bash # Create multiple integrations from a file cat integrations.ndjson | truto integrations create --stdin # Chain export into proxy create on another account (--stdin takes one JSON body per call) truto export crm/contacts -a $ACCOUNT_A -o ndjson | \ head -5 | \ while IFS= read -r record; do printf '%s' "$record" | truto proxy contacts -m create -a $ACCOUNT_B --stdin done ``` ## More help - [Data plane](/docs/cli/data-plane) — unified vs proxy - [Power features](/docs/cli/power-features) — export, diff, JSONata - [AI-powered build](/docs/cli/integrations-build) — full build options - Run `truto context` for an LLM-oriented reference (`truto context --full` for the full tree) --- # Data plane > Source: https://truto.one/docs/cli/data-plane/ Data-plane commands call third-party services **through** Truto using credentials on an integrated account. Every call requires an account ID via `-a, --account` (except `capabilities` when targeting an integration). ## Unified API Normalized resources across integrations (consistent field names). ```bash # List CRM contacts truto unified crm contacts -a # Get one record truto unified crm contacts -m get -a # Create truto unified crm contacts -m create -a -b '{"first_name":"Jane"}' # Query params (comma-separated key=value, or JSON object) truto unified crm contacts -a -q "limit=10,status=active" truto unified crm contacts -a --query-json '{"limit":10}' # Stdin body echo '{"first_name":"Test"}' | truto unified crm contacts -m create -a --stdin ``` **Arguments:** `` (e.g. `crm`, `ats`), `` (e.g. `contacts`), optional `[id]` :::callout{type="info"} Use **unified** when you want Truto's normalized schema across vendors. Use **proxy** for integration-specific fields or APIs not in the unified model. ::: ## Proxy API Raw integration resources without normalization. ```bash truto proxy tickets -a truto proxy tickets T-42 -m get -a truto proxy tickets -m create -a -b '{"subject":"Bug report"}' # Custom method → POST /proxy/tickets/custom-action truto proxy tickets -m custom-action -a -b '{"key":"value"}' ``` ## Custom API User-defined custom endpoints on Truto: ```bash truto custom /my-endpoint -a truto custom /my-endpoint -m POST -a -b '{"key":"value"}' truto custom /my-endpoint -a -H "X-Custom-Header=value" ``` ## Batch Multiple operations in one request (same resource format as sync jobs): ```bash truto batch requests.json truto batch -b '{"integrated_account_id":"","resources":[ {"resource":"contacts","method":"list"}, {"resource":"companies","method":"list"} ]}' cat batch.json | truto batch --stdin ``` Each entry: `resource`, `method`, optional `query`, `body`, `id`, `persist` (set `persist: true` on proxy resources to include results in the response). ## Test mapping locally Evaluate a `response_mapping` JSONata expression against a sample raw API response — no integrated account or third-party call: ```bash # Inline mapping + sample file truto unified test-mapping \ --mapping '$map(results, function($r) { $merge([$r, {"id": $string($r.id)}]) })' \ --input sample-response.json # Fetch mapping from the platform, then evaluate truto unified test-mapping \ --model crm --resource contacts --integration salesforce \ --method list \ --input sample-response.json # Overlay environment-specific overrides truto unified test-mapping \ --model crm --resource contacts --integration salesforce \ --with-overrides \ --input sample-response.json \ --show-mapping cat sample-response.json | truto unified test-mapping \ --mapping-file expr.jsonata --stdin ``` Pass query context into the mapping as `$query` / `$rawQuery` with `-q`, `--query-json`, or `--query-file` (same as live unified calls). Operator-based mappings cannot be evaluated locally yet — the CLI prints the resolved mapping for inspection. ## Capabilities Discover proxy and unified methods for an integration or account: ```bash truto capabilities hubspot truto capabilities --methods list,get --resource contacts truto capabilities hubspot --has-description ``` See [Admin resources — Capabilities](/docs/cli/admin-resources#capabilities) for `--type`, `--target`, and AI readiness details. ## Discovering methods on an account Before calling unified or proxy, list what an account supports: ```bash truto accounts tools truto accounts tools --methods list --tags contacts,deals ``` ## Next steps - [Power features](/docs/cli/power-features) — bulk `export`, `diff` - [Examples](/docs/cli/examples) — proxy and unified walkthroughs --- # Overview > Source: https://truto.one/docs/cli/overview/ The Truto CLI is the command-line interface for the Truto unified API platform. Use it to manage platform resources (integrations, accounts, sync jobs, webhooks, and more), call unified and proxy APIs against live connections, bulk-export data, and scaffold integrations with AI-assisted builds. ## What you can do | Area | Examples | | ---------------------- | -------------------------------------------------------------------------------- | | **Authentication** | `truto login`, profiles for staging vs production | | **Integrations** | List, create, update; AI-powered `integrations build`; push configs with `apply` | | **Unified mappings** | AI-powered `unified-mappings build` of JSONata mapping rows; `validate` and `apply` | | **Connected accounts** | `truto accounts list`, refresh OAuth, mint scoped tokens | | **Tenants** | `truto tenants list/create`, `truto tenants create-bulk`, `truto open tenants` | | **Automation** | Sync jobs, workflows, webhooks, daemon jobs | | **Data plane** | `truto unified`, `truto proxy`, `truto custom`, `truto batch`, `unified test-mapping` | | **Power tools** | `export`, `diff`, `jsonata eval`, open resources in the dashboard | ## Before you begin You need three things before the CLI can talk to Truto: | Requirement | What it is | How to get it | | ----------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Truto account** | Access to the dashboard and your team | [Sign in](https://app.truto.one) or ask your team admin for an invite | | **API token** | A secret Bearer credential scoped to one environment | Create one in the dashboard — see [Creating API tokens](/docs/guides/api-tokens/creating-api-tokens) | :::callout{type="info"} Each API token belongs to a **single environment**. Commands only see integrations, accounts, and other resources in that environment. Use separate [CLI profiles](/docs/cli/authentication#profiles) if you work across staging and production. ::: ## Quick start ### 1. Install the CLI **Linux / macOS:** ```bash curl -fsSL https://cli.truto.one/install.sh | bash ``` The installer places `truto` in `~/.truto/bin`. If `truto` is not found, add that directory to your `PATH` (the install script usually prints the exact line to run), then open a new terminal tab. **Windows (PowerShell):** ```powershell irm https://cli.truto.one/install.ps1 | iex ``` Installs to `%USERPROFILE%\.truto\bin\truto.exe`. Open a new terminal after install. See [Installation](/docs/cli/installation) for version pinning, custom install directories, and upgrades. ### 2. Log in **Interactive** — the CLI prompts for profile name, API URL, and token: ```bash truto login ``` **Non-interactive** — pass the token you copied from the dashboard: ```bash export TRUTO_API_TOKEN="" truto login --token "$TRUTO_API_TOKEN" ``` Leave the API URL at the default (`https://api.truto.one`) unless your team uses a custom instance. Details: [Authentication](/docs/cli/authentication). ### 3. Verify ```bash truto whoami ``` You should see your **profile**, **API URL**, and **team name**. `whoami` reads the saved profile (`-p ` or the active one); it does not pick up `--token` or `TRUTO_API_TOKEN`. ### 4. Explore your environment ```bash # Integrations installed in this environment (not the global catalog) truto integrations list # API tokens you can inspect (create/delete still requires the dashboard) truto api-tokens list ``` **Next commands to try:** ```bash truto accounts list # connected customer accounts truto tenants list # tenants in this environment truto integrations list --name hubspot # filter by slug truto open tenants # open the tenants page in your browser ``` For a full product walkthrough (Link, webhooks, first unified call), continue with [Getting started](/docs/getting-started). ## Documentation map | Topic | Page | | ----------------------------------- | ------------------------------------------------ | | Install and upgrade | [Installation](/docs/cli/installation) | | Login, profiles, tokens | [Authentication](/docs/cli/authentication) | | Flags and output formats | [Global options](/docs/cli/global-options) | | Integrations (CRUD, apply, lint) | [Managing integrations](/docs/cli/integrations) | | AI build from docs | [AI-powered build](/docs/cli/integrations-build) | | Add one method (you supply details) | [Add method](/docs/cli/integrations-add-method) | | AI build of unified mapping rows | [Unified mappings build](/docs/cli/unified-mappings) | | Accounts, sync jobs, webhooks, etc. | [Admin resources](/docs/cli/admin-resources) | | Unified, proxy, custom, batch | [Data plane](/docs/cli/data-plane) | | Export, diff, JSONata, open | [Power features](/docs/cli/power-features) | | Guided wizard | [Interactive mode](/docs/cli/interactive-mode) | | Full command list | [Command reference](/docs/cli/command-reference) | | Cookbook examples | [Examples](/docs/cli/examples) | ## Related resources - [Getting Started](/docs/getting-started) — first API call and dashboard setup - [Guides](/docs/guides/how-truto-works/overview) — platform concepts - [API Reference](/docs/api-reference/overview/introduction) — REST endpoints the CLI wraps - [TypeScript SDK](/docs/sdks/typescript) — programmatic alternative to the CLI :::callout{type="tip"} Coding agents can run `truto context` for a single-shot reference of every command, flag, and entity. Add `--full` for the auto-generated command tree. ::: --- # Global options > Source: https://truto.one/docs/cli/global-options/ Every command accepts these flags. They can appear anywhere on the command line (before or after the subcommand). | Flag | Description | Default | | --- | --- | --- | | `-p, --profile ` | Use a specific profile | Active profile | | `--api-url ` | Override API URL | Profile URL or `https://api.truto.one` | | `--token ` | Override API token | Profile token | | `-o, --output ` | `json`, `table`, `yaml`, `csv`, `ndjson` | `table` | | `-v, --verbose` | Print request/response details to stderr | Off | | `--no-color` | Disable colored output | Off | | `--no-help-on-error` | Suppress automatic `--help` on errors (for piping) | Off | **Format shortcuts:** `--json`, `--yaml`, `--csv`, and `--ndjson` are shorthand for `-o json`, `-o yaml`, and so on. **Flag aliases:** Snake_case and camelCase variants work on most flags (for example `--tenant-id`, `--tenant_id`, and `--tenantId` are equivalent). Dotted API field names become kebab-case flags (`integration.name` → `--integration-name`). :::callout{type="tip"} When `-o` is `json`, `yaml`, `csv`, or `ndjson`, decorative status messages are suppressed on stdout so only structured data is emitted. Errors always go to stderr. ::: ## Transient errors and retries Every API call the CLI makes retries on its own when the failure is one that a moment later usually fixes: - **429 Too Many Requests** on any method. The API rejected the request before running it (this is what an overloaded database returns), so replaying it is always safe. - **502 / 503 / 504** and **network errors** (connection reset, DNS, TLS) on `GET`, `HEAD`, `OPTIONS`, `PUT` and `DELETE` only. A `POST` or `PATCH` that reached the server before the connection dropped may already have been applied, so those surface the error instead. A `500` is never retried. The default budget is 3 retries with exponential backoff (0.5s, 1s, 2s, with jitter), capped at 10s per wait. A `Retry-After` header from the server replaces the computed delay, subject to the same 10s cap. On a terminal, or with `--verbose`, each retry prints a dim line to stderr: ``` ⟳ 429 Too Many Requests on GET /integration/865df83b-… — retrying in 1.0s (1/3) ``` When stderr is a pipe the retries are silent, so a scripted run still sees exactly one error envelope. Set `TRUTO_MAX_RETRIES` to change the budget. `TRUTO_MAX_RETRIES=0` turns retrying off, which is what a CI job that wants fail-fast behaviour should set. ## Output formats | Format | Best for | Notes | | --- | --- | --- | | `table` | Interactive inspection | Default. Truncates long values; up to 8 columns. | | `json` | Piping to `jq`, saving files | Pretty-printed, 2-space indent. | | `ndjson` | Streaming, log processing | One JSON object per line. Ideal for `export`. | | `csv` | Spreadsheets | Columns from first record. | | `yaml` | Human-readable nested data | | Some commands override the default: | Command | Default output | | --- | --- | | Admin commands, including `get` | `table` | | `export` | `json` (unless `-o` is set) | | `custom` | `json` | ## Pagination List commands return 25 results by default: ```bash truto integrations list --limit 10 # Output shows: Next page: --next-cursor abc123... truto integrations list --limit 10 --next-cursor abc123 ``` For exhaustive pagination across data-plane resources, use [`truto export`](/docs/cli/power-features) instead. ## Shared resource flags Most admin resource commands support: | Flag | Operation | Description | | --- | --- | --- | | `--next-cursor ` | `list` | Next page | | `--limit ` | `list` | Results per page (default 25) | | `--stdin` | `create`, `update` | Body from stdin (JSON array or NDJSON) | | `-i, --interactive` | `update` | Pre-fill fields from current record | | `-f, --force` | `delete` | Skip confirmation | | `--select ` | `list`, `get` | Comma-separated fields to return (supports dotted paths) | | `--brief` | `get` | Omit nested objects from output | | `--like ` | `list` | Case-sensitive `LIKE` filter on a column, `%` / `_` wildcards (repeatable) | | `--ilike ` | `list` | Case-insensitive `ILIKE` filter on a column (repeatable, where supported) | On `unified`, `proxy`, `custom`, and `unified test-mapping`, pass query params with `-q key=value` (repeatable), `--query-json '{"limit":10}'`, or `--query-file params.json`. ## Filtering List commands accept `--` filters. Check per-command help: ```bash truto integrations list --help truto accounts list --tenant-id truto sync-jobs list --integration_name hubspot ``` ## Scripting examples ```bash # IDs as JSON truto integrations list -o json | jq '.[].id' # Count exported records truto export crm/contacts -a -o ndjson | wc -l # Debug HTTP truto integrations list -v # stderr: → GET https://api.truto.one/integration?limit=25 # ← 200 OK ``` ## Stdin and `--body` On `create` and `update` (admin resources), `unified`, `proxy`, `custom`, and `batch`: - **Admin `create`:** Input starting with `[` → JSON array (bulk create); otherwise NDJSON (one object per line). - **Admin `update`:** Same parsing; each object is sent as a separate update to the given ID. - **Data plane / batch:** Stdin is always a **single** JSON body. - `--stdin` and `-b` are mutually exclusive. For data-plane commands, `-b` wins; for admin `create` and `update`, `--stdin` wins. See [Power features](/docs/cli/power-features) for full stdin examples. --- # Interactive mode > Source: https://truto.one/docs/cli/interactive-mode/ A guided wizard for exploring the API without memorizing commands: ```bash truto interactive truto i # alias ``` The wizard walks you through: 1. Pick a resource type 2. Choose an operation (list, get, create, update, delete) 3. Enter required parameters 4. View results :::callout{type="info"} **When to use:** Learning the API, exploring field names, or quick one-off inspection. **When not to use:** Scripting or automation — use subcommands directly for full filter/query support and stable output formats. ::: ## Next steps - [Command reference](/docs/cli/command-reference) — full command list - [Examples](/docs/cli/examples) — scripted workflows --- # Power features > Source: https://truto.one/docs/cli/power-features/ ## Export Bulk export with auto-pagination (unified or proxy): ```bash # Unified: path contains / truto export crm/contacts -a -o ndjson --out contacts.ndjson truto export crm/contacts -a -o csv --out contacts.csv # Proxy: no slash in path truto export tickets -a -o csv --out tickets.csv # Pipe to jq truto export crm/contacts -a -o ndjson | jq '.email' ``` | Format | Behavior | | --- | --- | | `ndjson` | Streams one record per line — best for large datasets | | `csv` | Header from first page; columns locked from first record | | `json` / `yaml` | Buffers all pages in memory — avoid for huge exports | Default format for `export` is **`json`** (not `table`). ## Diff Compare two records field-by-field: ```bash truto diff crm/contacts -a truto diff crm/contacts -a --account2 # cross-account truto diff crm/contacts -a -o json ``` Resource path convention matches `export`: `crm/contacts` → unified; `tickets` → proxy. With `--account2`, `[id2]` is optional and defaults to `id1`. ## JSONata Evaluate [Truto JSONata](/docs/guides/unified-apis/mapping-bindings) locally (no API call): ```bash truto jsonata eval --expression '$map(items, function($v) { $v.id })' --input context.json cat context.json | truto jsonata eval --expression-file expr.txt --stdin ``` Uses `@truto/truto-jsonata` with Truto's custom functions. ## Open dashboard ```bash truto open truto open integrations truto open accounts truto open tenants # tenants page truto open tenants acme-corp # specific tenant detail truto open sync-jobs truto open logs ``` Resources that open a dashboard page: `integrations`, `accounts` (or `integrated-accounts`), `tenants`, `sync-jobs`, `webhooks`, and `logs`. Pass an ID with `integrations`, `accounts`, `tenants`, or `sync-jobs` to open that record's detail page. Any other name is appended to `https://app.truto.one/` as-is. Uses `open` on macOS, `xdg-open` on Linux, and the system default browser on Windows. ## Stdin piping ```bash # Bulk admin create from NDJSON cat contacts.ndjson | truto accounts create --stdin # Bulk admin create from JSON array echo '[{"name":"a"},{"name":"b"}]' | truto integrations create --stdin # Data plane (single JSON body) echo '{"first_name":"Jane"}' | truto unified crm contacts -m create -a --stdin cat batch.json | truto batch --stdin ``` ## Upgrade ```bash truto upgrade --check truto upgrade --force ``` See [Installation](/docs/cli/installation). --- # Authentication > Source: https://truto.one/docs/cli/authentication/ The CLI uses **API tokens** exclusively — not your dashboard email and password. Each token is a Bearer credential scoped to **one** Truto environment (`development`, `staging`, or `production`). ## Get an API token Create a token in the dashboard before running `truto login`: 1. Sign in to [app.truto.one](https://app.truto.one). 2. Go to **Settings → API Tokens**. 3. Click **Create API Token**. 4. Enter a name (for example `cli-macbook` or `ci-staging`) and select the **environment** the token should access. 5. Click **Create API Token**, then **copy the token immediately** — Truto only shows the full secret once. 6. Check **I have copied my API Token** and click **Done**. ![Go to API tokens in Settings](https://docs-assets.truto.one/create-api-token.png) ![Copy API Token](/images/docs/api-tokens/api-token-generated.png) Store the token in a password manager or export it to your shell for non-interactive login: ```bash export TRUTO_API_TOKEN="" ``` :::callout{type="warning"} Treat API tokens like passwords. Anyone with the token can call Truto Admin and data-plane APIs as your team in that environment. Do not commit tokens to git or paste them in public channels. ::: **Environment matters:** A `staging` token cannot list production accounts or integrations. Pick the environment you intend to work in when creating the token. Read more in [Environments overview](/docs/guides/environments/overview). **CLI vs dashboard:** You can **list** and **view** tokens with `truto api-tokens list` and `truto api-tokens get `, but **creating and deleting** tokens must be done in the dashboard (or via the Admin API from your own backend). ## Interactive login ```bash truto login ``` You are prompted for: 1. **Profile name** (default: `default`) — a local label so you can switch between staging and production profiles later 2. **API base URL** (default: `https://api.truto.one`) — leave as-is unless your team gave you a different API host 3. **API token** (masked input) — paste the token you copied from **Settings → API Tokens** The token is verified against the API before saving. If a profile with the same name already exists, you are asked to confirm overwriting it (use `-f` to skip). ## Non-interactive login ```bash truto login --token # Custom API URL truto login --token --api-url https://your-instance.truto.one # Named profile truto login --token --profile-name staging # Overwrite without confirmation truto login --token --profile-name staging -f ``` :::callout{type="info"} When using `--token`, interactive prompts are skipped and existing profiles are overwritten without confirmation (same as `-f`). ::: ## Logout and verify ```bash # Remove credentials (default profile) truto logout # Remove a specific profile truto logout --profile-name staging -f # Verify the credentials saved in a profile truto whoami truto whoami -p staging -o json ``` ## Profiles Credentials are stored in `~/.truto/config.json` on macOS and Linux (`%USERPROFILE%\.truto\config.json` on Windows). File permissions are restricted on POSIX systems (`0600`). Manage multiple profiles for staging, production, or different teams: ```bash truto profiles list truto profiles use staging truto use staging # shortcut for profiles use truto profiles set api-url https://custom.truto.one truto profiles set default-integrated-account truto profiles get api-url ``` Store bring-your-own keys for `truto integrations build` and `truto unified-mappings build` (Anthropic by default; Fireworks optional with `--llm-provider fireworks`; Firecrawl when crawling docs): ```bash truto profiles set-key anthropic # interactive, masked (default LLM provider) truto profiles set-key fireworks # interactive, masked (optional — --llm-provider fireworks / --embedding-provider fireworks) truto profiles set-key firecrawl sk-... # non-interactive (web crawl + Fireworks web tools) ``` See [AI-powered build](/docs/cli/integrations-build) for how BYOK keys are used. ### Allowed profile keys | Key | Aliases | | -------------------------- | ---------------------------------------------------------- | | `apiUrl` | `api_url`, `api-url` | | `defaultIntegratedAccount` | `default_integrated_account`, `default-integrated-account` | | `anthropicApiKey` | `anthropic_api_key`, `anthropic-api-key` | | `fireworksApiKey` | `fireworks_api_key`, `fireworks-api-key` | | `firecrawlApiKey` | `firecrawl_api_key`, `firecrawl-api-key` | | `integrationConfigDir` | `integration_config_dir`, `integration-config-dir` | | `unifiedMappingDir` | `unified_mapping_dir`, `unified-mapping-dir` | ## Resolution order **Token:** 1. `--token` flag (highest priority) 2. `TRUTO_API_TOKEN` environment variable 3. The selected profile's `apiToken` (`-p `, otherwise the active profile) 4. Error if none found **API URL:** 1. `--api-url` flag 2. `TRUTO_API_URL` environment variable 3. The selected profile's `apiUrl` 4. `https://api.truto.one` (default) :::callout{type="warning"} An exported `TRUTO_API_TOKEN` or `TRUTO_API_URL` wins over every profile — `-p staging` and `truto use staging` have no effect on the token or URL while it is set. Unset it before switching profiles. ::: Your API token is scoped to a single **environment**. You never pass `environment_id` on commands — all resources are automatically filtered to that environment. ## Next steps - [Global options](/docs/cli/global-options) — `-p`, `--token`, output formats - [Managing integrations](/docs/cli/integrations) — first admin commands after login --- # Installation > Source: https://truto.one/docs/cli/installation/ ## Linux / macOS ```bash curl -fsSL https://cli.truto.one/install.sh | bash ``` The installer detects your OS and architecture, downloads the correct binary, and installs it to `~/.truto/bin/truto`. Add `~/.truto/bin` to your `PATH` if the installer does not do so automatically. ### Install options (Linux / macOS) ```bash # Install a specific version curl -fsSL https://cli.truto.one/install.sh | TRUTO_VERSION=1.0.36 bash # Install to a custom directory curl -fsSL https://cli.truto.one/install.sh | TRUTO_INSTALL_DIR=/usr/local/bin bash ``` Set the variables on `bash`, not on `curl` — the installer reads them from its own environment. Every download is checked against the release's `SHA256SUMS` manifest, and the installer refuses to continue if the manifest can't be fetched or the digest doesn't match. For an old pinned release that has no manifest, add `TRUTO_SKIP_CHECKSUM=1` alongside `TRUTO_VERSION` to install it unverified. ## Windows (PowerShell) ```powershell irm https://cli.truto.one/install.ps1 | iex ``` Installs to `%USERPROFILE%\.truto\bin\truto.exe` and adds that directory to your user `PATH`. Open a new terminal after install so the updated `PATH` is picked up. :::callout{type="info"} **Windows on ARM:** The installer downloads the x64 binary, which runs under Windows' x64 emulation layer. WSL users can use the Linux install script (`install.sh`) inside their distro instead. ::: ### Install options (Windows) ```powershell # Install a specific version $env:TRUTO_VERSION='1.0.36'; irm https://cli.truto.one/install.ps1 | iex # Install to a custom directory $env:TRUTO_INSTALL_DIR='C:\Tools\truto'; irm https://cli.truto.one/install.ps1 | iex ``` ## Upgrading ```bash # Check if a newer version is available truto upgrade --check # Upgrade to the latest version truto upgrade # Re-download even if already on the latest version truto upgrade --force ``` The `upgrade` command fetches the latest release from `cli.truto.one`, downloads the platform-specific binary, and replaces the currently running binary in place. :::callout{type="info"} On Linux and macOS, if the CLI was installed to a system directory (for example `/usr/local/bin`), you may need to run `sudo truto upgrade`. On Windows, run PowerShell as administrator only if you installed to a protected directory. ::: :::callout{type="tip"} Run `truto upgrade --check` periodically to see if a new version is available without installing it. ::: ## Next steps 1. [Create an API token](/docs/guides/api-tokens/creating-api-tokens) in the dashboard (Settings → API Tokens). 2. [Authenticate](/docs/cli/authentication) with `truto login` or `truto login --token "$TRUTO_API_TOKEN"`. 3. Follow the [CLI overview](/docs/cli/overview) quick start to verify with `truto whoami` and explore your environment. --- # Command reference > Source: https://truto.one/docs/cli/command-reference/ Run `truto --help` for flags and filters on any command. ## Authentication and profiles | Command | Description | | ------------------------ | ------------------------------------------------ | | `truto login` | Authenticate interactively or with `--token` | | `truto logout` | Remove stored credentials | | `truto whoami` | Show current user and team | | `truto profiles` | List, switch, get, and set profile values | | `truto use ` | Shortcut for `profiles use` | | `truto profiles set-key` | Store Anthropic/Fireworks/Firecrawl keys for builds | ## Integrations | Command | Description | | --------------------------------- | -------------------------------------- | | `truto integrations` | CRUD integration definitions | | `truto integrations init` | Scaffold a starter integration | | `truto integrations validate` | Validate config against OpenAPI schema | | `truto integrations tools` | List tools/methods for an integration | | `truto integrations unified-apis` | List unified APIs for an integration | | `truto integrations build` | AI-powered build → local JSON file | | `truto integrations apply` | Push IntegrationFile JSON to Truto | | `truto integrations lint` | Static audit of integration config | | `truto integrations add-method` | Add one method to a resource | | `truto categories` | List integration categories | ## Unified mappings | Command | Description | | --------------------------------- | ---------------------------------------------------------- | | `truto unified-mappings build` | AI-powered build of unified mapping rows → local JSON file | | `truto unified-mappings validate` | Audit a MappingFile (deterministic, no writes) | | `truto unified-mappings apply` | Push mapping rows to base or env override tables | ## Admin resources | Command | Description | | ---------------------------------- | ----------------------------------------------------------------- | | `truto accounts` | Integrated accounts (connections) | | `truto accounts identify` | Quick summary of one connected account | | `truto tenants` | Manage tenants (external identities that own integrated accounts) | | `truto tenants create-bulk` | Create or upsert up to 1000 tenants (`--mode insert|upsert`) | | `truto environments` | Environments (list, get, update) | | `truto environment-integrations` | Per-environment integration installs | | `truto api-tokens` | API tokens (list, get) | | `truto sync-jobs` | Sync job definitions | | `truto sync-job-runs` | Sync job execution records | | `truto sync-job-triggers` | Cron triggers for sync jobs | | `truto sync-job-templates` | Reusable sync templates | | `truto sync-job-run-states` | Key-value state for sync runs | | `truto workflows` | Event-triggered automations | | `truto workflow-runs` | Workflow execution records | | `truto webhooks` | Outbound webhooks | | `truto notification-destinations` | Slack/email alert targets | | `truto mcp-tokens` | MCP tokens (per account) | | `truto unified-models` | Unified model definitions | | `truto unified-model-mappings` | Base unified model mapping rows | | `truto env-unified-models` | Environment unified model installs | | `truto env-unified-model-mappings` | Per-environment mapping overrides | | `truto datastores` | S3, GCS, MongoDB, Qdrant connections | | `truto daemons` | Background worker identities | | `truto daemon-jobs` | Daemon job definitions | | `truto daemon-job-runs` | Daemon job runs | | `truto daemon-job-triggers` | Daemon cron triggers | | `truto users` | Team members (list, get) | | `truto team` | Team settings | | `truto gates` | Static IP egress proxies | | `truto docs` | Integration/model documentation rows | | `truto link-tokens` | Truto Link connect tokens (create) | | `truto logs` | Query platform logs | | `truto schema` | Download OpenAPI schema | | `truto files` | Upload files to Truto-hosted URLs | ## Data plane | Command | Description | | ---------------------------- | -------------------------------------------------------- | | `truto unified` | Normalized unified API calls | | `truto unified test-mapping` | Evaluate response mappings locally (no third-party call) | | `truto proxy` | Raw proxy API calls | | `truto custom` | Custom API paths | | `truto batch` | Batch multiple operations | | `truto capabilities` | Discover methods for integration or account | ## Power features | Command | Description | | ------------------- | ------------------------------ | | `truto export` | Bulk export with pagination | | `truto diff` | Compare two records | | `truto jsonata` | Evaluate JSONata locally | | `truto open` | Open dashboard in browser | | `truto upgrade` | Upgrade CLI binary | | `truto interactive` | Launch interactive wizard | | `truto context` | LLM-oriented command reference | ## Gotchas 1. **`accounts` vs `integrated-accounts`:** CLI uses `accounts`; API path is `integrated-account`. 2. **`gates` vs `static-gates`:** CLI uses `gates`; API path is `static-gate`. 3. **`export` / `diff` paths:** Slash → unified (`crm/contacts`); no slash → proxy (`tickets`). Not for admin resources. 4. **MCP tokens:** Account ID is the first positional argument, not `-a`. 5. **Optimistic locking:** `integrations update` and `unified-models update` require the record's current `version` from a prior `get` — pass it as `--lock-version ` or as `"version"` in `-b`. 6. **Schema output:** `truto schema` returns YAML; use `truto schema --out file.yml`. 7. **Environment scope:** Your token scopes all commands to one environment automatically. 8. **Mapping command names:** CLI uses `unified-model-mappings` and `env-unified-model-mappings`; API paths use `unified-model-resource-method` and `environment-unified-model-resource-method`. --- # Admin resources > Source: https://truto.one/docs/cli/admin-resources/ Admin commands manage Truto platform resources. All follow the same pattern: ```bash truto [args] [options] ``` Operations: `list`, `get`, `create`, `update`, `delete` (where supported). See [Global options](/docs/cli/global-options) for shared flags. ## Integrated accounts (`accounts`) Live tenant connections to integrations. ```bash truto accounts list truto accounts list --integration-name hubspot --status active truto accounts get truto accounts create -b '{"environment_integration_id":"...","tenant_id":"...","context":{},"authentication_method":"oauth2"}' truto accounts update -b '{"status":"inactive"}' truto accounts refresh-credentials truto accounts create-token # short-lived scoped token truto accounts identify # integration, tenant, status in one call truto accounts tools --methods list,get ``` :::callout{type="warning"} The command is **`accounts`**, not `integrated-accounts` (shorter alias for the `integrated-account` API path). ::: **Filters:** `--tenant-id`, `--is-sandbox`, `--integration-name`, `--status`, `--features-super-query`, `--created-at`, `--updated-at` **Status values:** `active`, `connecting`, `post_install_error`, `validation_error`, `needs_reauth` **Bulk delete** — delete every account for a tenant, or a specific list of accounts, in a single request: ```bash # Delete every account for a tenant (capped at 1000 per request; repeat until matched_count < 1000) curl -X POST https://api.truto.one/integrated-account/bulk-delete \ -H 'Authorization: Bearer ' -H 'Content-Type: application/json' \ -d '{"tenant_id":"acme-corp"}' # Or delete a specific list of account UUIDs (max 99 per request because of D1's parameter limit) curl -X POST https://api.truto.one/integrated-account/bulk-delete \ -H 'Authorization: Bearer ' -H 'Content-Type: application/json' \ -d '{"ids":["79a39d69-e27e-49cb-b9a9-79f5eea7aa26","0c74a4ad-7b8e-4f3a-9c1d-2e4f5a6b7c8d"]}' ``` ## Tenants External identities that own integrated accounts. One tenant, many connected accounts. ```bash truto tenants list truto tenants list --name acme truto tenants get truto tenants create -b '{"id":"acme-corp","name":"Acme Corp","metadata":{"tier":"gold"}}' truto tenants update -b '{"name":"Acme Corp","metadata":{"tier":"platinum"}}' truto tenants delete # Create or upsert up to 1000 tenants in a single request (POST /tenant/bulk) truto tenants create-bulk -b '[{"id":"acme"},{"id":"globex"}]' truto tenants create-bulk --mode upsert -b '[{"id":"acme","name":"Acme Corp"}]' cat tenants.ndjson | truto tenants create-bulk --stdin ``` **Filters:** `--id`, `--name` **Create fields:** `id` (required — any characters up to 255, except control characters, leading or trailing whitespace, or an id that is exactly `.` or `..`), `name` (optional; defaults to `id`), `metadata` (optional JSON object) **Bulk import:** `--mode insert` (default) skips existing ids; `--mode upsert` updates `name`/`metadata` on existing ids. Only `id`, `name`, and `metadata` are allowed per row. **Update fields:** `name`, `metadata` (`PATCH` replaces the whole metadata object; merge client-side for partial updates) :::callout{type="warning"} `truto tenants delete ` returns `409 Conflict` if the tenant still has connected accounts. List them with `truto accounts list --tenant-id ` (or bulk-delete via the endpoint shown above — capped at 1000 accounts per request), then retry. ::: See [Tenants overview](/docs/guides/tenants/overview) for concepts and [Bulk import](/docs/guides/tenants/bulk-import) for the CSV/JSON upload flow. ## Environments ```bash truto environments list truto environments get truto environments update -b '{"name":"Production"}' ``` :::callout{type="info"} Creating and deleting environments requires the dashboard. The CLI supports list, get, and update only. ::: ## Environment integrations ```bash truto environment-integrations list --integration_id truto environment-integrations create -b '{"integration_id":"...","override":{...}}' truto environment-integrations update -b '{"is_enabled":false}' truto environment-integrations delete ``` ## API tokens ```bash truto api-tokens list --name ci-token truto api-tokens get ``` Create and delete tokens require the dashboard. ## Sync jobs and runs ```bash truto sync-jobs list --integration_name hubspot truto sync-jobs create -b '{"label":"Sync Contacts","integration_name":"hubspot","resources":{...}}' truto sync-job-runs list --sync_job_id truto sync-job-runs create -b '{"sync_job_id":"...","integrated_account_id":"..."}' truto sync-job-triggers list --integrated_account_id truto sync-job-triggers create -b '{"sync_job_id":"...","cron_expression":"0 */6 * * *"}' truto sync-job-triggers schedule truto sync-job-templates list truto sync-job-templates create -b '{"label":"CRM Sync","resources":{...},"default_runtime_version":2}' ``` **Sync job run state** (key-value checkpoint data keyed by `state_key` from the sync job definition): ```bash truto sync-job-run-states list --state-key truto sync-job-run-states get --state-key truto sync-job-run-states create --state-key --key cursor --value "..." truto sync-job-run-states update --state-key --value "..." truto sync-job-run-states delete --state-key -f ``` ## Workflows ```bash truto workflows list truto workflows create -b '{"trigger_name":"on_new_contact","config":{...}}' truto workflow-runs list --workflow_id --status completed ``` Workflow runs cannot be created via CLI — they are triggered by the workflow. ## Webhooks and notifications ```bash truto webhooks create -b '{"target_url":"https://example.com/hook"}' truto webhooks test --id truto notification-destinations create -b '{"type":"slack","config":{...},"label":"Eng Alerts"}' truto notification-destinations test --id ``` ## MCP tokens Scoped to an integrated account. The **account ID is the first positional argument**: ```bash truto mcp-tokens list truto mcp-tokens create --name "my-mcp-token" truto mcp-tokens delete -f ``` ## Unified models and environment overrides ```bash truto unified-models list truto unified-models create -b '{"name":"crm","category":"crm","description":"CRM model","resources":{...}}' truto unified-models update -b '{"description":"Updated","version":1}' truto unified-model-mappings list --integration-name hubspot --resource-name contacts truto env-unified-models list truto env-unified-model-mappings list ``` `version` is required on unified model updates — fetch with `get` first. ## Datastores, daemons, team ```bash truto datastores create -b '{"label":"my-bucket","type":"s3","config":{...}}' truto datastores test truto daemons create -b '{"label":"My Daemon"}' truto daemon-jobs list truto daemon-job-runs create -b '{"daemon_job_id":"...","daemon_id":"..."}' truto daemon-job-triggers schedule truto team get truto team update -b '{"name":"New Team Name"}' truto users list ``` ## Gates, docs, link tokens, logs, files, schema ```bash # Static IP egress proxies (command: gates, API: static-gate) truto gates create -b '{"name":"us-west-proxy","domain":"api.example.com"}' # User-authored integration/model documentation truto docs list --integration_id # at least one filter required truto docs create -b '{"content":"...","type":"readme","integration_id":"..."}' truto link-tokens create --tenant-id truto link-tokens create --tenant-id --integrated-account-id truto logs --log-type unified_proxy_api --integrated-account-id --limit 50 truto files upload /path/to/file.csv truto schema --out openapi.yml # YAML output; --out not -o ``` **Log types and filters** vary by type — run `truto logs --help`. `--log-type` is required. **Link token refusal.** `link-tokens create --integrated-account-id ` is refused with `400` and `truto_error_code: app_credentials_not_configured` when the account's integration has no usable authentication method left — every method it has is a bring-your-own-app one (an OAuth 2.0 client id or an AWS STS access key) with no app credentials configured in the environment. Reauthorization may switch method, so an integration that still has a working method is not refused. Add the credentials in the integration's **Configuration** tab (**Use your own OAuth settings** for OAuth 2.0, **Use your own signing credentials** for AWS STS), then retry. A `--tenant-id`-only token is never refused for this reason. ## Capabilities Show what an integration or account can do — proxy methods, unified resources, auth surfaces, and **AI readiness** scoring: ```bash truto capabilities hubspot truto capabilities --type proxy truto capabilities acme-crm --resource contacts --methods list,get truto capabilities hubspot --has-description # only methods with descriptions truto capabilities hubspot --target integration # force integration (not account) lookup ``` UUID-shaped targets are treated as integrated accounts; otherwise integration slug/ID. Override that guess with `--target integration` or `--target account`. --- # Add method > Source: https://truto.one/docs/cli/integrations-add-method/ `truto integrations add-method` lands **one method** on an existing integration resource. You supply the HTTP details (or paste a curl example); the CLI merges them into `config.resources` and PATCHes the integration. There are **no LLM calls** and no doc crawl. Use this when you already know what to add. For building or reshaping a whole integration from API docs, use [AI-powered build](/docs/cli/integrations-build) instead. ## Command shape ```bash truto integrations add-method \ --http-method \ --path ``` **Arguments:** | Argument | Description | | --- | --- | | `slug-or-id` | Integration slug (e.g. `hubspot`) or UUID | | `resource` | Resource name (e.g. `contacts`). Created empty if missing unless `--no-create-resource` | | `method-name` | Method key (e.g. `list`, `get`, `archive`). Not overwritten unless `--force` | ## Examples ```bash # Archive a contact truto integrations add-method hubspot contacts archive \ --http-method POST \ --path /crm/v3/objects/contacts/{{id}}/archive # List with cursor pagination (auto-creates resource if needed) truto integrations add-method acme-crm deals list \ --http-method GET \ --path /deals \ --pagination cursor \ --response-path results # Dry-run: print patched config, no API call truto integrations add-method hubspot contacts archive \ --http-method POST \ --path /contacts/{{id}}/archive \ --print # Write patched config to a file for review truto integrations add-method hubspot contacts archive \ --http-method POST \ --path /contacts/{{id}}/archive \ --out patched.json ``` ## From curl (`--from-curl`) Paste a curl block from provider docs; verb, path, body, and `body_format` are extracted mechanically. File uploads are recognized: `-F name=@file` becomes a `multipart` body with `name` as a binary field, and `-T file` or `--data-binary @file` becomes a `raw` body with a single binary `file` field (content type from a `-H Content-Type` header, else `application/octet-stream`). Other headers are ignored (auth lives on the integration's `authorization` block, not per-method): ```bash truto integrations add-method acme-crm contacts create \ --from-curl 'curl -X POST "https://api.acme.test/v1/contacts" \ -H "Authorization: Bearer $TOKEN" \ -d "{\"name\":\"jane\"}"' \ --print ``` Explicit flags override curl-derived values: ```bash truto integrations add-method hubspot contacts archive \ --from-curl 'curl -X POST "https://api.hubapi.com/crm/v3/objects/contacts/12345/archive"' \ --path '/crm/v3/objects/contacts/{{id}}/archive' ``` The CLI warns (does not fail) when the curl URL host disagrees with the integration's `base_url`. ## Common options | Flag | Description | | --- | --- | | `--http-method` | `GET`, `POST`, `PATCH`, `PUT`, `DELETE`, … | | `--path` | Upstream path; may use `{{id}}`, `{{body.field}}`, `{{query.field}}` | | `--from-curl` | Parse verb/path/body from curl text | | `--response-path` | JSONata path to unwrap list/object in responses (e.g. `results`) | | `--mcp-annotations` | MCP tool hints as JSON booleans: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` (e.g. `'{"readOnlyHint":true}'`) | | `--body` / `--body-file` / `--body-format` | Default request body for the method | | `--pagination` | `cursor`, `offset`, `page`, or `none` | | `--force` | Replace an existing method with the same name | | `--no-create-resource` | Fail if the resource does not exist | | `--no-validate` | Skip pre-PATCH schema validation (escape hatch) | | `--print` | Print merged config to stdout instead of PATCHing | | `--out` | Write merged config to a file (no API call) | ## Behavior notes - Reads the live integration `version` for optimistic-locking PATCH. - Validates the merged config against `IntegrationConfig` (issues touching only the edited method block the push unless `--no-validate`). - Writes no per-method **documentation** (`description`, query or response schemas), with one exception: a file upload parsed from `--from-curl` gets a `body_schema` documentation row that marks the file field as binary, merged into any existing row. For full documentation, use [AI-powered build](/docs/cli/integrations-build) or `truto integrations apply` after adding docs to an IntegrationFile. ## Next steps - [Managing integrations](/docs/cli/integrations) — list/get/update integrations - [AI-powered build](/docs/cli/integrations-build) — full integration from docs --- # Unified mappings build > Source: https://truto.one/docs/cli/unified-mappings/ `truto unified-mappings build` authors the **JSONata mapping rows** that connect one integration's proxy API to a [unified model](/docs/guides/unified-apis/what-are-unified-apis) (for example `crm`, `ats`, `hris`). It runs an **agentic** build, writes a local **MappingFile** JSON (for example `acme.crm.mappings.json`), and pushes nothing to Truto until you run `truto unified-mappings apply`. ```bash # Build mappings for an integration against a unified model truto unified-mappings build acme crm # Audit the result without pushing truto unified-mappings validate acme.crm.mappings.json # Push when you are satisfied truto unified-mappings apply acme.crm.mappings.json --target base ``` For each unified **resource + method** (for example `contacts.list`, `accounts.get`, `deals.create`) the build generates the JSONata that transforms the integration's raw proxy response into the unified schema shape — plus `query_mapping`, `request_body_mapping`, and `error_mapping` where the proxy method needs them. This is the mapping-side companion to [`truto integrations build`](/docs/cli/integrations-build): build the integration first (so it has proxy resources), then build its unified mappings. ## Prerequisites | Requirement | Notes | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | **LLM API key** | Anthropic by default (flag → `$ANTHROPIC_API_KEY` → `truto profiles set-key anthropic` → interactive prompt), or Fireworks with `--llm-provider fireworks`. | | **Truto login** | The build loads the integration config, the unified model schema, and any existing mapping rows from your environment. | | **An installed integration** | The integration must already exist with proxy resources (build it with [`truto integrations build`](/docs/cli/integrations-build)). | | **Account or docs (required)** | Pass `--account` for live proxy samples, **or** at least one `--source-url` (URL or local file). Both may be combined. Without either, the build exits with an error. | | **Firecrawl API key** | Only when you pass a `--source-url` docs site that needs crawling (not raw OpenAPI / local files). | | **Local ONNX model** | Automatically downloaded on first use (~35 MB). Powers hybrid BM25 + cosine search over the `--source-url` index. | :::callout{type="info"} **LLM provider:** `truto unified-mappings build` runs on **Anthropic Claude** by default (tiered: Opus for the agentic loop, Sonnet for the `--structured` pipeline) or on **Fireworks AI** with `--llm-provider fireworks`. On a TTY the CLI prompts for the provider when the flag is omitted; non-interactive runs use Anthropic. Model selection works as in [`truto integrations build`](/docs/cli/integrations-build#fireworks-model-presets): `--anthropic-model` overrides all Claude tiers, and `--llm-model` / `--llm-classification-model` pick Fireworks models. ::: ## What happens during a build The default flow (no flags) is **agentic**: Claude (Opus) orchestrates the build through tools, routing each unified resource/method to a proxy endpoint, sampling it, generating JSONata, validating, and committing the cell. A fixed per-cell pipeline still exists behind `--structured` for parity and cheaper runs — it still uses the LLM (Sonnet) to route and generate each mapping; only the orchestration is fixed, not the JSONata output. ### 1. Pre-flight - Resolve the LLM provider and its key (and Firecrawl when a `--source-url` is crawled). - Fetch the integration config (`config.resources`), the unified model schema (env override merged when `--environment-id` is set), and any existing mapping rows. - Inventory the proxy resources/methods and **plan the cells** — the unified resource × method pairs that a proxy endpoint can serve. - Load the mapping **corpus** (exemplars from other integrations) used for cribbing and leak detection. ### 2. Routing The agent routes each unified resource/method to a proxy resource/method — including cross-name routes (unified `accounts` → proxy `companies`), multi-proxy-resource routes, and conditional (when-guarded) routes. Routing decisions are recorded so later steps and resumes stay consistent. ### 3. Ground the sample Per cell, the build grounds generation on the richest sample it can find, in order: 1. **Live proxy** (`fetch_proxy_sample`) when an `--account` is connected. Sampling is **read-only** — it only issues a `GET` for `list`/`get` and never runs create/update/delete against the connected account. 2. **DB documentation** examples (`read_doc_response_example`). 3. The **`--source-url` index** (one or more URLs/paths, merged) (`search_source_docs`), and as a last resort a single-page scrape (`scrape_doc_page`, needs Firecrawl). Write cells (`create` / `update` / `delete`) are built from the proxy's documented request body even without a response example — the cell does its job through `request_body_mapping`. ### 4. Generate and validate `generateMappingField` produces each field's JSONata; `validate_mapping_output` compiles it, evaluates it against the sample, and checks the result against the unified JSON Schema. A deterministic pass fixes proxy array paths, `get`→`list` aliases, and list wrappers, and rejects cross-integration leaks (verbatim copies of another integration's expressions). ### 5. Refinement loop (interactive) In an interactive terminal the build ends in a **refinement loop**. Type a free-form instruction (for example `engagements.create: strip the trailing Z from start times`) and the agent re-builds the affected cell. Type `:show` to print the full per-cell review in the terminal. Press **Enter** on an empty line to finish. The loop is skipped with `--no-refine`, `--yes`, `--only-missing`, or when output is piped. ### 6. Output The final MappingFile is written to `--out` or `..mappings.json`, with a **build summary** printed to the terminal and embedded in the file. The summary reports built / skipped / flagged counts and the next `validate` / `apply` commands. :::callout{type="info"} **Resume:** If the final MappingFile at `--out` (default `..mappings.json`) already exists, the build resumes from it — existing cells are kept and failed/empty cells are retried. It also carries forward mappings already applied on the platform (local cells win on conflict). Pass `--fresh` to ignore existing seeds and start from scratch. **Only missing cells:** With `--only-missing`, only cells absent from the existing file are built — existing cells and skipped cells are untouched, failures are not retried. ::: ## MappingFile shape The output is a **MappingFile**: integration + unified-model identifiers, a `write_target`, the generated `cells[]`, and a `build_summary`. | Field | Purpose | | ---------------------- | --------------------------------------------------------------------------------------------------------------- | | `integration_name` / `unified_model_name` | What this file maps, by slug. | | `write_target` | `base` (team-owned rows) or `env` (per-environment override rows). | | `cells[]` | One entry per unified resource/method, each with a `config` (the mapping fields) and `db_info` (apply action). | | `build_summary` | `status`, `counts` (planned / built / skipped / flagged), `built`, `skipped` (with reasons), `unbuilt_routed`, and `warnings`. | Each cell's `config` carries the relevant mapping fields: `response_mapping`, and for read/write methods `query_mapping`, `request_body_schema` + `request_body_mapping` (required fields are marked), and `error_mapping`. The `build_summary` is built for human review — it explains every gap. `skipped` cells list **why** no mapping was produced (for example "no proxy endpoint serves this method"), and `warnings` flag cells worth a second look (hardcoded `custom_fields`, create/update transform drift, single-key guards) grouped by cell and kind. ## Useful flags | Flag | Purpose | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `-a, --account ` | Integrated account ID for **live proxy samples** (read-only GET). | | `--source-url ` | API docs URL or local file path (repeatable, comma-separated; URLs and local OpenAPI/Postman/markdown files are merged into one source index). Supports glob patterns (e.g. `'./specs/*.json'`). | | `--yes` | Non-interactive mode: skip account/docs prompts. Requires `--account` and/or `--source-url`. | | `--anthropic-api-key ` | Override Anthropic API key (flag → `$ANTHROPIC_API_KEY` → profile → prompt). | | `--firecrawl-api-key ` | Override Firecrawl API key (flag → `$FIRECRAWL_API_KEY` → profile → prompt). | | `--no-firecrawl` | Skip Firecrawl; use cheaper extraction only for doc sites. | | `--resources ` | Comma-separated unified resources to build (default: all planned). | | `--methods ` | Comma-separated methods (`list,get,create,update,delete,…`). | | `--structured` | Run a fixed per-cell pipeline instead of the agentic loop (still LLM-generated; only the orchestration is fixed). | | `--no-web-search` | Disable the `web_search` / `web_fetch` tools and the source-sample web-search rung (no outbound web calls). | | `--fresh` | Ignore an existing working/final MappingFile and start from scratch. | | `--only-missing` | Build only cells absent from the existing file; do not retry failures or modify existing cells. | | `--no-refine` | Skip the interactive post-build refinement loop. | | `--fail-fast` | Stop on the first cell error (default: skip failed cells and continue). | | `--environment-id ` | Resolve schema overrides and target env override rows. | | `--target ` | Write-target hint recorded in the file for `apply` (default `base`). | | `--out ` | Output path (default `..mappings.json`). | | `--unified-mapping-dir ` | Corpus of unified mapping exemplars (`$TRUTO_UNIFIED_MAPPING_DIR` or profile `unifiedMappingDir`). | | `--integration-config-dir ` | Local proxy-config corpus for exemplars. | | `--debug-log ` / `--no-debug-log` | JSONL transcript of the build (default on, under `~/.truto/logs/`). | | `--anthropic-model ` | Override the model for all LLM tiers (Anthropic only). | | `--llm-provider ` | `anthropic` (default) or `fireworks`. | | `--fireworks-api-key ` | Override Fireworks API key (flag → `$FIREWORKS_API_KEY` → profile → prompt). | | `--llm-model ` | Pin all Fireworks tiers to one preset or `accounts/.../models/...` ID. | | `--llm-classification-model ` | Fireworks classification-tier model. | | `--agent` | Deprecated no-op — the agentic loop is already the default. | Run `truto unified-mappings build --help` for the complete list. ## Bring-your-own keys | Key | Required when | | ------------------- | --------------------------------------------------------- | | `ANTHROPIC_API_KEY` | `--llm-provider anthropic` (the default) | | `FIREWORKS_API_KEY` | `--llm-provider fireworks` | | `FIRECRAWL_API_KEY` | A `--source-url` docs site needs crawling | Resolution order for each: CLI flag → environment variable → `truto profiles set-key` → interactive prompt on a TTY. > **Note:** Hybrid search (BM25 + cosine) is now powered by a local ONNX model downloaded automatically on first use. No external API key is required. ## Web tools By default the agent can call the Anthropic-side `web_search` / `web_fetch` server tools to ground a low-confidence route or an undocumented field against the provider's official docs (capped by `max_uses`). Pass `--no-web-search` to disable both those tools and the source-index web-search rung — useful for builds where you want no outbound web calls beyond the proxy and Truto APIs. ## Validate Audit a MappingFile without applying — deterministic, no LLM, no writes: ```bash truto unified-mappings validate acme.crm.mappings.json truto unified-mappings validate acme.crm.mappings.json -v # list advisory warnings ``` Validation re-checks every cell's JSONata and schema conformance and exits non-zero on errors. Advisory warnings (the per-cell review flags from `build_summary.warnings`) never fail validation; they are summarized by default and listed in full with `-v`. Pass `--environment-id` to resolve env schema overrides. ## Apply Push the reviewed MappingFile to the platform: ```bash # Preview the payloads without writing truto unified-mappings apply acme.crm.mappings.json --dry-run # Apply to base rows (or env override rows) truto unified-mappings apply acme.crm.mappings.json --target base truto unified-mappings apply acme.crm.mappings.json --target env ``` Apply upserts each cell as a `unified_model_resource_method` row (or the `environment_unified_model_resource_method` override when `--target env`), using the `db_info` action recorded per cell (create / update / skip). `--target env` only works on a file built with `--environment-id`; otherwise apply stops with an error before writing anything. | Flag | Effect | | ---------------- | ------------------------------------------------- | | `--target ` | Write base rows or per-environment overrides | | `--dry-run` | Validate and print payloads; no API calls | | `--yes` | Skip confirmation prompts | ## Examples ```bash # Live-grounded build for a connected account, then validate + apply export ANTHROPIC_API_KEY=sk-ant-... ACCOUNT= truto unified-mappings build acme crm --account $ACCOUNT truto unified-mappings validate acme.crm.mappings.json truto unified-mappings apply acme.crm.mappings.json --target base # Doc-grounded build with a source URL (no account) truto unified-mappings build acme crm \ --source-url https://docs.acme.com/openapi.json --yes # Multiple sources: remote URL + local files + glob truto unified-mappings build acme crm \ --source-url https://docs.acme.com/api \ --source-url ./specs/acme-openapi.json \ --source-url './notes/*.md' --yes # Only build the cells you are missing, just for two resources truto unified-mappings build acme crm --resources contacts,accounts --only-missing # Fixed pipeline, no web calls truto unified-mappings build acme crm --structured --no-web-search ``` ## Next steps - [Managing integrations](/docs/cli/integrations) — build the integration first so it has proxy resources - [AI-powered integration build](/docs/cli/integrations-build) — the integration-side companion flow - [What are Unified APIs?](/docs/guides/unified-apis/what-are-unified-apis) — the models you are mapping to - [JSONata Binding Reference](/docs/guides/unified-apis/mapping-bindings) — the expression language used in every mapping field - [Data plane](/docs/cli/data-plane) — `unified test-mapping` to iterate on a single `response_mapping` locally --- # Managing integrations > Source: https://truto.one/docs/cli/integrations/ Integration definitions are third-party app connectors in Truto. The CLI exposes full CRUD plus helpers to scaffold, validate, and inspect integrations. ## Quick reference ```bash truto integrations list truto integrations get -o json truto integrations create -b '{"name":"my-app","config":{"label":"My App","base_url":"https://api.example.com"}}' truto integrations update -b '{"category":"crm"}' --lock-version 1 truto integrations delete -f ``` ## Scaffold a new integration (`init`) Interactively create a starter config and POST it to Truto: ```bash truto integrations init acme-crm truto integrations init --label "Acme CRM" --auth oauth2 --base-url https://api.acme.com truto integrations init acme-crm --print # print config only, no API call truto integrations init acme-crm --out acme.json # write to file ``` ## Validate config (`validate`) Validate against the `IntegrationConfig` schema before pushing: ```bash truto integrations validate truto integrations validate -f ./config.json cat config.json | truto integrations validate --stdin ``` ## Discovery helpers ```bash # Tools/methods exposed by an integration truto integrations tools # Unified APIs mapped to an integration truto integrations unified-apis ``` ## CRUD details **List filter:** `--name` **Create fields:** `name` (required), `config` (JSON, required), `category` **Update fields:** `category`, `config` (JSON), `--lock-version` (required — optimistic locking; the record's current `version` from `get`, or `"version"` in `-b`) The server replaces the whole stored `config` on update. Before sending, the CLI compares your `config` with the live one and refuses an update that would drop top-level keys, resources, or methods. Choose how to send a partial or shrinking config: | Flag | Effect | | --- | --- | | `--merge-config` | Merge your partial `config` over the live one (top-level keys replaced whole, `resources` merged per resource) and send the result | | `--replace-config` | Send `config` as given, replacing the stored config — needed to remove keys, resources, or methods on purpose | | `--dry-run` | Print the plan and the config key diff; send nothing | `truto integrations get --at-version ` reads a stored older version of the record. ```bash # Create interactively truto integrations create # Pipe from stdin echo '{"name":"test","config":{"label":"Test"}}' | truto integrations create --stdin ``` ## Apply Push an `IntegrationFile` JSON (typically from `integrations build`) to your Truto environment. Non-interactive — no LLM calls. ```bash truto integrations apply acme.integration.json truto integrations apply acme.integration.json --dry-run # validate + show plan only truto integrations apply acme.integration.json --docs-only # push documentation rows only (integration must exist) truto integrations apply acme.integration.json --slug-override renamed-slug # override slug on CREATE ``` - Validates the file against the IntegrationFile schema before any API call. - Creates or updates the integration from the file's `id` / `name`. - Diffs and syncs per-method documentation rows and integration-wide doc types. - Prints a summary of created, updated, and unchanged resources. ## Lint Static audit of integration config — no LLM, no network beyond an optional slug lookup: ```bash truto integrations lint ./acme.integration.json truto integrations lint acme-crm # audit live integration by slug truto integrations lint ./acme.integration.json --ignore-warnings truto integrations lint acme-crm --integration-config-dir ./corpus ``` Exit codes: `0` clean, `1` warn- or error-level findings remain, `2` input error. Info-level findings never change the exit code. `--ignore-warnings` lowers the exit-`1` bar to error-level findings only; `--ignore-info` hides info-level findings from the table output (`-o json`, `yaml`, `ndjson`, and `csv` always include every finding). ## Related commands | Command | Purpose | | --- | --- | | [`integrations build`](/docs/cli/integrations-build) | Agentic build from API docs → local JSON file | | [`integrations add-method`](/docs/cli/integrations-add-method) | Add one method when you supply HTTP details (no LLM) | ## Categories List integration categories (verticals such as `crm`, `ats`, `helpdesk`): ```bash truto categories list truto categories list --name crm ``` --- # SDKs for Truto API > Source: https://truto.one/docs/api-reference/overview/sdk/ Three official libraries cover the most-used endpoints in this reference. Pick the one that matches your runtime. ## TypeScript SDK `@truto/truto-ts-sdk` — server-side TypeScript / JavaScript client for the Truto API. Resources are typed; list endpoints return an async iterator. ```bash npm install @truto/truto-ts-sdk ``` [Full TypeScript SDK guide →](/docs/sdks/typescript) ## Python SDK `truto-python-sdk` — async Python client for the Unified, Proxy, Custom, and Admin APIs in this reference. ```bash pip install truto-python-sdk ``` [Full Python SDK guide →](/docs/sdks/python) ## Link SDK `@truto/truto-link-sdk` — browser SDK for the Connect UI, RapidForms, and the Google Drive / Dropbox / OneDrive file pickers. Use it on the frontend; pair it with the TypeScript or Python SDK on the backend. ```bash npm install @truto/truto-link-sdk ``` [Full Link SDK guide →](/docs/sdks/link-sdk) ## Other languages Email [support@truto.one](mailto:support@truto.one) if you need a client for another language. --- # Introduction > Source: https://truto.one/docs/api-reference/overview/introduction/ Welcome to the Truto API documentation. This API allows you to interact with various Unified APIs provided by the Truto platform, including the Admin API. ## Base URL The base URL for all the API endpoints is: ```http https://api.truto.one ``` The use of HTTPS is mandatory when making requests to this API. ## Headers The default response content type for this API is `application/json` and it also accepts `application/json`. To ensure correct response handling, please set the `Content-Type` and `Accept` headers of your requests to `application/json`. ## API Token To authenticate with the Truto API, you will need an API token. Detailed instructions on how to generate an API token can be found in the following guide: [Creating API Tokens](https://truto.one/docs/guides/api-tokens/creating-api-tokens) --- # Pagination > Source: https://truto.one/docs/api-reference/overview/pagination/ Truto's API uses cursor-based pagination for all list endpoints. This is a way to handle large sets of data effectively and efficiently. Instead of relying on traditional offset-based pagination, cursor pagination provides smoother navigation through the listed items. ## Understanding the Response Each call to a list endpoint returns an object containing two main attributes: - `result`: This attribute contains the list of resources returned by the current request. - `next_cursor`: This attribute is a cursor that points to the start of the next page of results. If `next_cursor` is null, then there are no more pages to retrieve. Unified and Proxy API list calls can also carry: - `prev_cursor`: a cursor to the previous page, when the provider supports paging backwards. - `result_count`: the number of records in `result`. - `is_partial_response`: `true` when the integration's list call returns records with only some of their fields, so fetching a record by ID can return more (Unified APIs only). ## Using the Cursors To fetch the next page of results, use the `next_cursor` value from the previous response. This should be included as a query parameter in your next request. For instance, if the `next_cursor` from the last response was `abc123`, you would fetch the next page of results by appending `?next_cursor=abc123` to the URL. ## Limiting the Results You can limit the number of records returned in a single request by using the `limit` query parameter. The `limit` parameter defines the maximum number of records to return. For example, `?limit=10` will return up to 10 records from the list. On Unified and Proxy APIs, `limit` is capped at the largest page size the integration allows — 100 unless the integration sets a different maximum — so a larger value returns at most that many records. ## Example Here's an example of a response from a list call: ```json { "result": [ { "id": 1, "name": "Resource 1", ... }, { "id": 2, "name": "Resource 2", ... }, ... ], "next_cursor": "abc123" } ``` In this example, result is an array of resources, and `next_cursor` is the cursor you would use to fetch the next page of results. --- # Authentication > Source: https://truto.one/docs/api-reference/overview/authentication/ Truto API uses Bearer authorization. This form of authentication should be included in the header of every API request. ## Generating API Token Before you can authenticate your requests, you will first need to generate an API token. Follow the instructions outlined in our guide on creating API tokens: [Creating API Tokens](https://truto.one/docs/guides/api-tokens/creating-api-tokens) After generating your API token, keep it safe and do not share it. This token is used to authenticate your requests and can provide access to your account if it is compromised. ## Using the API Token Once you have generated an API token, you can use it to authenticate your requests. The token should be included in the `Authorization` header with the `Bearer` keyword, like so: ```http Authorization: Bearer ``` Replace `` with your actual API token. Remember, all API requests must be made over HTTPS. Non-secure requests will fail. --- # Querying in Truto API > Source: https://truto.one/docs/api-reference/overview/querying/ This doc walks you through the various query parameter formats and conventions used in Truto API, both Admin and Unified APIs. ## Unified, Admin and SuperQuery APIs The following query parameter formats and operators can be used in the Unified, Admin and SuperQuery APIs. ### Strings If you are specifying a query parameter which accepts a string, then use the parameter name as is. For example, if you are specifying a query parameter `name` with value `foo`, then the query parameters will be, ```http request name=foo ``` ```json { "name": "foo" } ``` ### Numbers If you are specifying a query parameter which accepts a number, then use the parameter name as is. For example, if you are specifying a query parameter `limit` with value `10`, then the query parameters will be, ```http request limit=10 ``` ```json { "limit": 10 } ``` ### Booleans If you are specifying a query parameter which accepts a boolean, then use the parameter name as is. For example, if you are specifying a query parameter `is_active` with value `true`, then the query parameters will be, ```http request is_active=true ``` ```json { "is_active": true } ``` ### Objects If you are specifying a query parameter which accepts an object, then use `[]` brackets to specify the attributes. Assuming the following query in JSON, ```json { "foo": { "bar": "baz", "bar1": { "bar2": "baz2" } } } ``` The equivalent query parameters in HTTP request will be, ```http request foo[bar]=baz&foo[bar1][bar2]=baz2 ``` ### Arrays If you are specifying a query parameter which accepts an array, then use empty `[]` brackets to specify the items. Assuming the following query in JSON, ```json { "foo": [ "bar", { "bar1": "baz1" } ] } ``` The equivalent query parameters in HTTP will be, ```http request foo[]=bar&foo[][bar1]=baz1 ``` ### Date and Time Date and time query parameters are specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format regardless of the format the underlying third party API accepts. Truto handles the translation between the ISO 8601 format and the third party API format. In all the Unified APIs we'll have the `created_at` and `updated_at` query parameters which can also use the `gt`, `gte`, `lt`, `lte` operators wherever the underlying API supports it. :::callout{type="warning"} The operators you can use are dependent on the underlying API and if the underlying API doesn't support the operator, then Truto will ignore it. ::: For example, assuming you want to filter resources by `created_at` between `2021-01-01` and `2021-01-31`, the query parameters will be, ```http request created_at[gte]=2021-01-01T00:00:00Z&created_at[lte]=2021-01-31T23:59:59Z ``` ```json { "created_at": { "gte": "2021-01-01T00:00:00Z", "lte": "2021-01-31T23:59:59Z" } } ``` ### Sort by If you want to sort the resources by a specific attribute, then use the `sort_by` query parameter. :::callout{type="warning"} In case of Unified APIs, sorting will only work if the underlying API supports it and the attributes you can sort by is limited based on the underlying API. ::: For example, if you want to sort the resources by `created_at` in ascending order, the query parameters will be, ```http request sort_by[created_at]=asc ``` ```json { "sort_by": { "created_at": "asc" } } ``` You can also sort by multiple attributes by specifying the `sort_by` query parameter multiple times. For example, if you want to sort the resources by `created_at` in ascending order and then by `updated_at` in descending order, the query parameters will be, ```http request sort_by[created_at]=asc&sort_by[updated_at]=desc ``` ```json { "sort_by": { "created_at": "asc", "updated_at": "desc" } } ``` ## Additional query operators in Admin and SuperQuery APIs In the Admin and SuperQuery APIs, you can use the following additional query operators -- ### ne The `ne` operator is used to filter resources where the attribute is not equal to the specified value. For example, if you want to filter resources where the `status` attribute is not equal to `closed`, the query parameters will be, ```http request status[ne]=closed ``` ```json { "status": { "ne": "closed" } } ``` ### eq The `eq` operator is used to filter resources where the attribute is equal to the specified value. For example, if you want to filter resources where the `status` attribute is equal to `open`, the query parameters will be, ```http request status[eq]=open ``` ```json { "status": { "eq": "open" } } ``` ### in The `in` operator is used to filter resources where the attribute is in the specified list of values. For example, if you want to filter resources where the `status` attribute is either `open` or `closed`, the query parameters will be, ```http request status[in][]=open&status[in][]=closed ``` ```json { "status": { "in": ["open", "closed"] } } ``` ### nin The `nin` operator is used to filter resources where the attribute is not in the specified list of values. For example, if you want to filter resources where the `status` attribute is neither `open` nor `closed`, the query parameters will be, ```http request status[nin][]=open&status[nin][]=closed ``` ```json { "status": { "nin": ["open", "closed"] } } ``` ### like The `like` operator is used to filter resources where the attribute matches the specified pattern. For example, if you want to filter resources where the `name` attribute starts with `foo`, the query parameters will be, ```http request name[like]=foo% ``` ```json { "name": { "like": "foo%" } } ``` ### nlike The `nlike` operator is used to filter resources where the attribute does not match the specified pattern. For example, if you want to filter resources where the `name` attribute does not start with `foo`, the query parameters will be, ```http request name[nlike]=foo% ``` ```json { "name": { "nlike": "foo%" } } ``` ### gt, gte, lt, lte The `gt`, `gte`, `lt`, `lte` operators are used to filter resources where the attribute is greater than, greater than or equal to, less than, and less than or equal to the specified value respectively. For example, if you want to filter resources where the `created_at` attribute is greater than `2021-01-01` and lesser than `2021-01-31`, the query parameters will be, ```http request created_at[gt]=2021-01-01T00:00:00Z&created_at[lt]=2021-01-31T23:59:59Z ``` ```json { "created_at": { "gt": "2021-01-01T00:00:00Z", "lt": "2021-01-31T23:59:59Z" } } ``` ### or & and The `or` and `and` operators are used to combine multiple query parameters. For example, if you want to filter resources where the `status` attribute is `open` or `name` matches a pattern and the `created_at` attribute is greater than `2021-01-01`, the query parameters will be, ```http request or[0][status]=open&or[1][and][0][name][like]=foo%&or[1][and][1][created_at][gt]=2021-01-01T00:00:00Z ``` ```json { "or": [ { "status": "open" }, { "and": [ { "name": { "like": "foo%" } }, { "created_at": { "gt": "2021-01-01T00:00:00Z" } } ] } ] } ``` ## In RapidBridge Sync Jobs In RapidBridge Sync Jobs, query parameters can be specified in the `query` attribute of the `resources` array. ```json { "resources": [ { "resource": "knowledge-base/page-content", "method": "list", "depends_on": "knowledge-base/pages", "query": { "foo": { "bar": "baz" }, "baz": ["foo", "bar"], "created_at": { "gt": "2021-01-01T00:00:00Z" }, "page_id": "{{resources.knowledge-base.pages.id}}" } } ] } ``` You can use the object format to specify the query parameters in RapidBridge Sync Jobs. In the example above, the query parameters sent to the `knowledge-base/page-content` endpoint will be, ```http request foo[bar]=baz&baz[]=foo&baz[]=bar&created_at[gt]=2021-01-01T00:00:00Z&page_id=123 ``` You can also use the placeholders to refer to the values of other resources in the Sync Job. In the example above, the `page_id` query parameter refers to the `id` attribute of the `knowledge-base/pages` resource. ## Remote Query Parameters In Unified APIs, there are cases where you may need to pass query parameters to the underlying third-party API directly. In such cases, you can use the `remote_query` query parameter. The `remote_query` parameter is an object that contains the query parameters to be passed to the underlying third-party API. You can use this parameter with any other unified query parameters and they will merged together with remote query parameters taking precedence. Imagine a scenario where you want to pass the query parameters `foo=bar` and `baz=foo` to the underlying third-party API. The query parameters will be, ```http request remote_query[foo]=bar&remote_query[baz]=foo ``` ```json { "remote_query": { "foo": "bar", "baz": "foo" }, //...any other unified query parameters } ``` To specify this in the Truto Dashboards Try Unified API Modal, please check the `Use code editor for query parameters` checkbox and specify the query parameters in the code editor. ![Remote Query Parameters](https://docs-assets.truto.one/remote_query_parameters_truto_ui.png) --- # Rate limits in Truto API > Source: https://truto.one/docs/api-reference/overview/rate-limits/ We standardize and expose rate limit information from various underlying APIs to ensure consistent and predictable usage tracking for our consumers. We normalize the following headers across all endpoints: - **`ratelimit-limit`** — Indicates the maximum number of requests allowed within the current rate limit window. It represents the total quota allocated by the API you are interacting with. - **`ratelimit-remaining`** — Reflects the number of requests remaining within the current rate limit window. This header updates after each API call, helping you track your remaining quota in real-time. - **`ratelimit-reset`** — Reflects the number of seconds when the current rate limit window will reset. After this time, your request quota will be refreshed, and the `ratelimit-remaining` will return to its maximum value. By normalizing the rate limit information with these headers, we ensure that regardless of the API provider's native rate-limiting policies, you always receive a standardized rate limit response. This allows for easier integration and rate limit management, ensuring you can efficiently monitor and control your API consumption while avoiding unexpected rate limit breaches and service interruptions. ## Example Here's an example of how these headers are returned in the response when the Unified API is called for the HubSpot integration: ```json { "ratelimit-limit": "110;w=10", "ratelimit-remaining": 109, "ratelimit-reset": 60 } ``` - `ratelimit-limit`: This indicates that the maximum number of requests allowed within the current rate limit window is 110, with a rate limit window duration of 10 seconds (w=10). - `ratelimit-remaining`: This shows that 109 requests are still available within the current rate limit window. - `ratelimit-reset`: This indicates that the current rate limit window will reset in 60 seconds. > Note: Rate limit headers are included in the response only when the integration is configured to read the provider's rate-limit headers. For integrations without that configuration, these headers are absent even if the provider enforces rate limits. Additionally, the rate limit window (w=10) is specific to certain APIs and may not be available depending on the rate limit configurations of the underlying API provider. Truto's rate limiting mechanism has been implemented based on this archive [RateLimit Header Fields for HTTP](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#section-3) --- # Errors > Source: https://truto.one/docs/api-reference/overview/errors/ Every Truto error comes back with the right HTTP status, a JSON body shaped the same way regardless of route, and — for Unified and Proxy APIs — extra fields that tell you whether the failure happened at Truto's edge or inside the provider you're calling. ## Response shape Successful responses are documented per endpoint. Error responses always look like this: ```json { "statusCode": 400, "error": "Bad Request", "message": "name is required" } ``` Three fields are guaranteed: - **`statusCode`** — the same number as the HTTP status. Mirrors the response status line. - **`error`** — the canonical name for that status, e.g. `Bad Request`, `Unauthorized`, `Not Found`, `Too Many Requests`, `Internal Server Error`. - **`message`** — a human-readable description. For provider-originated errors this is extracted from the provider's body (see below). Errors raised by Truto's own validation, auth, and routing layers (admin endpoints, Unified API parameter checks, missing `integrated_account_id`, malformed request bodies, etc.) usually stop here; a few refusals add a `truto_error_code` and a handful of named fields (see [Refusals](#refusals--truto_error_code) below). Errors from the underlying provider — anything you hit through `/unified/*` or `/proxy/*` — carry several extra fields. ## Distinguishing Truto errors from provider errors When a Unified or Proxy API call fails because the underlying provider returned a non-2xx, the response gains: - **`truto_is_remote_error: true`** — set on every error that originated outside Truto. - **`raw_response`** — the provider's response body, parsed as JSON if possible, otherwise the raw text. - Rate-limit headers, when they apply: `ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset` if the integration defines how to read them from the provider's response, and `Retry-After` when the provider rate-limited the call. Other provider response headers are not forwarded on errors — see [Rate limits](/docs/api-reference/overview/rate-limits). ```json { "statusCode": 422, "error": "Unprocessable Entity", "message": "Email is invalid", "truto_is_remote_error": true, "raw_response": { "errors": [ { "field": "email", "code": "invalid", "message": "Email is invalid" } ] } } ``` The `message` is normalized by walking the provider body for the usual error fields (`message`, `msg`, `errorMessage`, `description`, `detail`, `summary`, `error_description`, and a long list of variants). When that lookup finds nothing, `message` is empty and you should fall back to `raw_response`. If the field is missing, the error came from Truto itself — almost always a 4xx for input you sent (missing `integrated_account_id`, malformed body, expired token), or a 5xx that means we couldn't reach the provider at all. ## Refusals — `truto_error_code` Some errors raised by Truto itself carry a `truto_error_code`: a stable, machine-readable name for *why* the request was refused, so you can branch on it without parsing `message`. Codes are additive — a response either has one or has none — and the other fields stay as documented above. ```json { "statusCode": 400, "error": "Bad Request", "message": "Google Sheets cannot be re-authorized: its OAuth 2.0 app credentials are no longer configured in this environment. Add them back in Integration Settings.", "truto_error_code": "app_credentials_not_configured", "integration": "googlesheets", "environment_integration_id": "…", "authentication_methods": ["oauth2"] } ``` The codes you can see: - **`app_credentials_not_configured`** — from `POST /link-token` when reauthorizing an account (`integrated_account_id`) whose integration has no usable authentication method left: every method it has is a bring-your-own-app one — OAuth 2.0 or AWS STS — with no app credentials configured in this environment. `authentication_methods` lists the methods that need them. Reauthorization may switch method, so an integration with a working API key beside an unconfigured OAuth app is not refused. [Add the credentials](/docs/guides/integrations/overriding-oauth-credentials) — the message calls this *Integration Settings*; in the dashboard it is the integration's **Configuration** tab, toggle **Use your own OAuth settings** for OAuth 2.0 or **Use your own signing credentials** for AWS STS — then retry. A token minted with `tenant_id` alone is never refused for this reason; the connect UI leaves such integrations out instead. See [Reauthorizing connections](/docs/guides/integrated-accounts/reauthorizing-connections#when-the-token-is-refused). - **`cron_triggers_would_stop`** — a 400 from editing a sync job or daemon job, or one of its cron triggers, when the change would make the job's cron triggers fail every run. `cron_triggers` names the affected triggers. Change or delete the triggers first, then retry the edit. - **`sync_job_run_not_completed`** — a 400 from starting a sync job run while an earlier run of the same job, for the same integrated account or mutex key, has not finished. `running_sync_job_runs` lists the runs still in progress. It can also appear on a cron trigger's error when a scheduled run was skipped for this reason. - **`sync_job_no_resources`** — a 400 from starting a run of a sync job that has no resources. Add at least one resource to the job. - **`integrated_account_needs_reauth`** — the error a sync job run fails with, carried on `sync_job_run:failed`, when every integrated account the run calls is in `needs_reauth`. It is a 401 with `truto_is_remote_error: true`. Reconnect the account; the next run syncs again. ## Insights — `truto_error_insight` Unified API errors come with a `truto_error_insight` block that tells you, in machine-readable form, what to change. Each key is independent; you may see one, several, or none. ```json { "statusCode": 400, "error": "Bad Request", "message": "name is required", "truto_error_insight": { "missing_required_body_fields": { "description": "These body fields are required and are missing in the request", "value": ["name"] } } } ``` The keys you can see: - **`missing_required_query_parameters`** — `value` is an array of query parameter names you didn't send but the unified model requires. - **`missing_required_body_fields`** — same, for body fields. - **`conditionally_required_query_parameters`** — `value` is an object keyed by parameter name, with the rule that triggers the requirement (e.g. "required when `type` is `lead`"). - **`conditionally_required_body_fields`** — same, for body fields. - **`rate_limit_error`** — present on a 429 from the provider. Pair with the `Retry-After` header. - **`remote_error`** — present whenever `truto_is_remote_error` is `true`. The hint is intentionally short — read `raw_response` and `message` for the actual content. - **`forbidden_error`** — present on a 403 from the provider. Not every 403 is a scope problem, so `value` states what Truto worked out and, where it could not work anything out, why not. `value.refusal_basis` is always present and states what Truto can say the refusal rests on. There are five values, and each one implies a different remedy — which is the point of reading it rather than reading a list of scopes: | `refusal_basis` | Will a reconnect help? | What it means | |---|---|---| | `scopes_missing` | Yes | The scopes in `value.missing_scopes` are absent from the grant. Drive a re-consent flow. | | `scopes_satisfied` | No | Every declared scope is granted, so the refusal has another cause. Read what the provider said. | | `non_scope_requirement` | No | The requirement is a role or an API-key permission, named in `value.required_permissions`, and granted inside the provider rather than by reconnecting. | | `no_scope_concept` | No | This connection authenticates with an API key or OAuth 1.0a, which have no scopes — there is nothing to grant. | | `not_determined` | Maybe | No comparison ran and Truto cannot name a basis. Read `description` for which reason applied, and `raw_response` for the provider's own account. | `not_determined` covers three situations that differ only in *why* Truto has no answer — no requirement recorded for this resource and method, the provider never echoed which scopes it granted, or the granted string could not be split with confidence. They are one value because the remedy is identical in all three, and on this API `description` still names which one applied. Do not rely on `description` to recover the reason on **every** surface, though. The end-user connect widget is deliberately sent no Truto prose, so it reads the reason structurally instead: the first situation is Truto's own missing catalogue entry, and it is the only one of the three that carries no `required_permissions` — because having no recorded requirement is what defines it. The other two always carry the requirement, since a comparison was attempted against one. So `not_determined` **with** `required_permissions` means the provider's grant was unreadable or undisclosed, and `not_determined` **without** it means Truto has nothing recorded for that resource and method. **Treat this as an open set.** The read path deliberately accepts a value it does not recognise, so a newly shipped state cannot break a client. Generate a permissive type and keep a default branch. `value.missing_scopes` appears only for `scopes_missing` and `scopes_satisfied`, and only ever means "these declared scopes are not in the grant". Do not default an absent `missing_scopes` to `[]` — absent means no comparison happened, which is not the same statement as "nothing is missing". `value.missing_any_of_scopes` is separate, for requirements where holding any one alternative is enough; folding the two together would tell a reader to grant every alternative. `value.required_permissions`, its any-of counterpart `value.required_any_of_permissions`, and `value.permission_vocabulary` (`oauth_scope` / `api_key_permission` / `role_label`) state what the call needs whether or not a comparison was possible — the vocabulary decides the remedy, and only `oauth_scope` is fixed by reconnecting. All three are withheld for `no_scope_concept`, where the declared permissions belong to an authentication method this connection does not use, so naming them would send you looking for a setting that does not exist. Everything above is Truto's own reading, inferred from integration configuration. What the **provider** said travels beside it on the 403 response itself, and it is the authoritative account: `raw_response` is the error body verbatim, and `message` is the human text pulled out of it. `raw_response` is on every remote 403. Truto deliberately does **not** summarise that body — there is no field carrying "the provider's error code" or "the provider's documentation link". Which key in an arbitrary provider's error shape is the important one has no correct general answer, and a confidently wrong pick placed above a correct body is worse than no pick at all. Read `raw_response` yourself, or, if you want one integration's code lifted into a stable field, do it per integration with an `error_expression` or `error_mapping` written against that provider's actual shape. Note that `message` is **unbounded**: the extractor's last candidate is the payload itself when the payload is a string, so for a plain-text or HTML body it is the whole body. Cap it before you display it. Both of those are on the **response** only. The durable `last_forbidden_error` on the integrated account keeps Truto's own reading — `refusal_basis`, `description`, `missing_scopes`, `missing_any_of_scopes`, `required_permissions`, `required_any_of_permissions` and `permission_vocabulary` — plus one capped copy of the provider's body as `raw_response_excerpt`, so a connection page opened days later still shows what the provider said and not only what Truto inferred. That excerpt is capped at 2,048 bytes including its trailing `… truncated` marker, and a truncated one is a byte prefix of a serialized body, so `JSON.parse` on it throws. What the row does **not** keep is `message`, so re-run the call to see that. **If you read `missing_scopes` today**, note which states no longer carry it. It appears only for `scopes_missing` and `scopes_satisfied`. The condition, rather than a list of names that goes stale the moment an integration is added: **any connection whose declared requirement is not an OAuth scope** now reports `non_scope_requirement`, runs no scope diff, and carries `required_permissions` with `permission_vocabulary` set to `api_key_permission` or `role_label` instead. Read those two for the names and the remedy — only `oauth_scope` is fixed by reconnecting — and `refusal_basis` for whether a comparison happened at all. Which vocabulary an integration uses is worked out from its own configuration, so every integration is classified without anyone labelling it. An integration author can also declare it outright with `permission_vocabulary` at `config.resources..`, which wins where it is set; that exists to correct the rare integration the derivation reads wrongly, and you should not need to care which case you are looking at. Three things about the override are worth knowing if you set one: - **An unrecognised value is ignored, not rejected at read time.** `"banana"`, `42`, `null` and `[]` all fall back to the derived answer rather than describing a 403 with `undefined` — so a typo shows you a plausible result and no signal that it was ignored. On a write through the API the closed set is enforced, so the typo is caught there. - **A declared `oauth_scope` is ignored when that same method's permission list contains whitespace.** RFC 6749 makes the space the delimiter *between* scope tokens, so a token containing one cannot be a scope; the declaration and the list contradict each other, and the list wins. This is the only case where a declaration does not take effect. - **It can be overridden per environment**, alongside `scopes` and `scopes_any_of`, on the environment integration's `override.resources..` — so one environment can be corrected without touching the base integration. Of those, the ones that actually **lose** a field they used to send are the OAuth-authenticating ones, because an API-key connection never had a scope grant to diff and so never carried `missing_scopes` in the first place. In the public catalogue that is `haloitsm` and `jamf`, both `oauth2_client_credentials`, both declaring console role names like `Read - Users`. They previously emitted those names under `missing_scopes`, which told a reader to reconnect and grant a permission reconnecting cannot grant. Your own environment's set depends on which integrations it has enabled — derive it from `permission_vocabulary` rather than from a name list. One more change to the durable record: `missing_scopes` is now stored in the order the integration declares it, matching the live response, where it was previously sorted. That is the only list with a previous state — the others beside it are new fields in this change and were never stored sorted. Nothing depends on the order; it is noted because a row written before this differs from one written after. Proxy API errors carry `truto_is_remote_error`, `raw_response`, forwarded headers, and — on 403s, including one an integration's own `error_expression` maps to 403 — a `truto_error_insight.forbidden_error`. The Proxy API has no unified schema to compare your request against, so the missing-parameter, rate-limit, and remote-error insights aren't added. ```json { "statusCode": 403, "error": "Forbidden", "message": "Insufficient permissions", "truto_is_remote_error": true, "raw_response": { "error": "insufficient_scope", "error_description": "Token does not have crm.objects.contacts.write scope" }, "truto_error_insight": { "forbidden_error": { "description": "Access forbidden. This connection does not hold every scope this resource and method requires — reconnect and grant the scopes listed alongside this error.", "resource": "contacts", "method": "create", "value": { "refusal_basis": "scopes_missing", "missing_scopes": ["crm.objects.contacts.write"], "required_permissions": ["crm.objects.contacts.write"], "permission_vocabulary": "oauth_scope" } } } } ``` ## Status codes The numbers below are what you'll actually see; the meaning given is what they mean inside Truto. ### 2xx - **`200 OK`** — request succeeded. Body contains the requested resource. - **`201 Created`** — `POST` succeeded and a new resource was created. - **`204 No Content`** — request succeeded with no body. Common for `DELETE`. ### 4xx - **`400 Bad Request`** — Truto rejected the request before it left our edge. On Unified APIs this is also where missing-required-field errors land; check `truto_error_insight`. - **`401 Unauthorized`** — without `truto_is_remote_error`, your API token is missing, expired, or wrong. With `truto_is_remote_error: true`, the provider rejected the connection's credentials — Truto flips the integrated account to `needs_reauth`, sets `last_error` on it, and fires the [`integrated_account:authentication_error`](/docs/guides/webhooks/list-webhook-events) webhook. The connection will keep returning 401 until the end user [reconnects](/docs/guides/integrated-accounts/reauthorizing-connections). - **`403 Forbidden`** — the caller is authenticated but not allowed. On Unified and Proxy APIs read `raw_response` and `message` first — the provider is the system that refused, so its own words are the authoritative account — then `truto_error_insight.forbidden_error.value.refusal_basis` for Truto's reading. Only `refusal_basis: "scopes_missing"` means a reconnect with the right scopes will fix it. `non_scope_requirement` points at a role or API-key permission granted inside the provider, and the rest are licensing, plan, admin-permission or configuration problems that a re-consent flow will not touch. - **`404 Not Found`** — the resource doesn't exist, or the integrated account / environment isn't visible to your token. - **`405 Method Not Allowed`** — the HTTP method isn't supported on that route. Sandbox accounts return this on `POST` / `PATCH` / `DELETE` calls because they're read-only. - **`409 Conflict`** — with `truto_is_remote_error: true`, the provider rejected a create or update because of a uniqueness constraint; check `raw_response` for the specific field. Without it, Truto refused the request itself: for example, creating a tenant whose ID already exists in the environment, deleting a tenant that still has connected accounts, or connecting an integration the tenant has already connected. - **`422 Unprocessable Entity`** — payload is well-formed but the provider rejected it (validation error inside the provider). - **`429 Too Many Requests`** — see [Rate limits](#rate-limits) below. Truto also returns a 429 with `Retry-After` when its own database is briefly overloaded; back off and retry. - **`503 Service Unavailable`** — the integrated account has been blocked (contact `support@truto.one`), the database is switching over (`Retry-After: 2`; retry after a few seconds), or the endpoint is paused for scheduled maintenance. ### 5xx - **`500 Internal Server Error`** — Truto failed to process the request. Retry with backoff; if it persists, capture the response and contact support. - **`502 Bad Gateway`** / **`504 Gateway Timeout`** — Truto reached the provider but the provider didn't respond cleanly. Safe to retry. ## Rate limits Truto enforces these limits in front of requests. Each returns a 429 with a `Retry-After` header. | Scope | Limit | `Retry-After` | Triggered by | | --- | --- | --- | --- | | Per API token | 100 requests / 1s and 500 requests / 10s | `1` or `10` | The API token in `Authorization` | | Per dashboard session | 500 requests / 10s | `10` | The session cookie, for calls made from the Truto dashboard | | Per integrated account | 50 requests / 10s | `10` | The `integrated_account_id` query parameter (Unified, Proxy and Custom APIs) | | Per source IP | 2000 requests / 10s | `10` | Every request from one address, authenticated or not | `POST /link-token` and incoming provider webhooks are exempt from the per-token and per-session limits. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Too many requests. You can make 50 requests every 10 seconds per integrated account." } ``` When the underlying provider rate-limits you, the response is a 429 with `truto_is_remote_error: true` and the provider's `Retry-After` (or our normalized equivalent) in the headers. On Unified API routes you'll also get `truto_error_insight.rate_limit_error`. See [Rate limits](/docs/api-reference/overview/rate-limits) for the full set of headers Truto normalizes. ## Retry strategy - **Retry on**: 429 (after `Retry-After`), 502, 503 (not when the integrated account is blocked), 504, and 5xx that don't carry `truto_is_remote_error`. - **Don't retry on**: 400, 401, 403, 404, 409, 422 — fix the request, the token, or the connection first. - **Watch `truto_is_remote_error`**: a 5xx with `truto_is_remote_error: true` is the provider failing, not Truto. Retry policy should be the same as for any flaky upstream — exponential backoff, capped attempts. --- # Connection flow for an Integrated account > Source: https://truto.one/docs/guides/integrated-accounts/connection-flow/ This document describes the flow of events that happen when an integrated account is connected. This is useful for understanding the different steps involved in the connection process and for debugging any issues that may arise during the connection process. `end-user` refers to the user who is connecting their account. 1. **Integrated account is created**: When an integrated account is created, Truto will send an `integrated_account:created` webhook event. This event will contain the integrated account as the payload. When an existing account is reauthorized, Truto sends `integrated_account:updated` instead, and the remaining steps run in the same order. 2. **Post install steps run**: Post install steps are requests, transformations and other steps that are defined on the integration to make the Unified and Proxy APIs work properly. These steps are run after the integrated account is created. If any of these steps fail, Truto will send an `integrated_account:post_install_error` webhook event. This event will contain the integrated account as the payload, the end-user will be notified on the connection screen and Truto Link SDK will throw an error. Post install steps are not defined on all the integrations. 3. **Connection validation steps run**: Connection validation steps are Unified and Proxy API requests that are defined on the integration to make sure that the connection is valid and has the necessary permissions required for making the API calls. They run only if the post install steps succeeded; when post install fails, validation is skipped. If any of these steps fail, Truto will send an `integrated_account:validation_error` webhook event. This event will contain the integrated account as the payload, the end-user will be notified on the connection screen and Truto Link SDK will throw an error. Connection validation steps are not defined by Truto and can be configured by you in the installed integration details page. 4. **Integrated account is activated**: The integrated account is now ready to use -- Unified and Proxy API calls be made against this integrated account, Truto will send an `integrated_account:active` webhook event. This event will contain the integrated account as the payload. This event is sent only after the post install and connection validation steps succeed. If either fails, the account keeps its `post_install_error` or `validation_error` status and no `integrated_account:active` event is sent. 5. **Post connect form (RapidForm) submitted**: If a post connect form ([RapidForm](/docs/guides/rapid-form/overview)) is defined on the installed integration, Truto will send an `integrated_account:post_connect_form_submitted` webhook event when the user submits the RapidForm on the connection screen. This event will contain the integrated account as the payload. This event is sent after the integrated account is activated. :::callout{type="warning"} If the post install steps or connection validation steps fail, the integrated account is not deleted automatically. Once the cause is fixed, recover it without reconnecting: `POST /integrated-account/run-post-install-actions` with `{ "id": "" }` reruns post install and validation, and `POST /integrated-account//validate` reruns validation alone. On success the account returns to `active` and Truto sends `integrated_account:active`. You can also delete the integrated account. ::: --- # Adding/Editing Context Variables in an Integrated Account > Source: https://truto.one/docs/guides/integrated-accounts/adding-editing-context-variables/ In Truto, you can add or edit 'Variables' within an Integrated Account. But what does this mean and why would you want to do it? Let's break it down. ## What are Variables? 'Variables' in Truto are bits of information needed for an integration to work properly. They are specific details unique to your account that Truto uses when communicating with the integrated API. For instance, in an integration with Shopify, you might need to provide your Shopify subdomain. ## Add and Edit Variables 1. **Sign into Truto** and navigate to `Integrated Accounts` or click [here](https://app.truto.one/integrated-accounts). ![Select an Integrated account](/images/integrated-accounts/list-annotated.png) 2. **Select an Integrated Account**. You'll find a section labeled `Variables`. ![Edit variables](/images/integrated-accounts/edit-variables.png) 3. **Click on `Edit Variables`**. A new window will pop up where you can add new variables or edit existing ones. ![Save new variables](/images/integrated-accounts/save-variables.png) 4. **Save your changes**. After you're done, make sure to hit the `Save` button. ## How to Use Variables? Once you've set up your variables, you can use them in other sections by referencing them with: ``` {{ variable_name }} ``` **Important note:** After updating or adding new variables, you may be required to reauthorize your connection to ensure the updated variables are recognized and used correctly. And there you have it! Now you know how to add and edit context variables in an Integrated Account in Truto. It's an easy and efficient way to customize and manage your API integrations. --- # Uninstalling/Deleting an Integrated Account > Source: https://truto.one/docs/guides/integrated-accounts/uninstalling/ If you no longer need an integrated account in Truto, you have the option to uninstall or delete it. Uninstalling an integrated account removes the account from your list and deletes its stored credentials and context variables. For OAuth connections, Truto also asks the provider to revoke the access token, where the provider supports it. Truto then sends an `integrated_account:deleted` webhook event. ## Uninstall/Delete an Integrated Account 1. **Sign into Truto** and navigate to the `Integrated Accounts` section or click [here](https://app.truto.one/integrated-accounts). ![Select an Integrated account](/images/integrated-accounts/list-annotated.png) 2. **Select the Integrated Account** you want to uninstall/delete. 3. **Click on `Delete integrated account` button**. You will be prompted to confirm this action because this process is irreversible. ![Select Delete integrated account](/images/integrated-accounts/delete-integrated-account.png) 4. **Click on `Delete` button**. ![Select Delete button](/images/integrated-accounts/delete-integrated-account-warn.png) 5. **Voila!** You will now be redirected to `Integrated Accounts` section and integrated account has been successfully uninstalled/deleted from the environment. > Note: Please make sure you're certain about this action. Uninstalling/deleting an integrated account is a permanent action and cannot be undone. The account's credentials and context variables are permanently deleted. --- # Making API Calls to Unified and Proxy APIs in Truto > Source: https://truto.one/docs/guides/integrated-accounts/making-api-calls/ Truto provides you two ways to access your integrated account's data: the 'Unified API' and the 'Proxy API'. Both options allow you to fetch data from the underlying APIs, but they present this data in different ways. ## Unified API The Unified API transforms the data into a common format, making it easier to work with if you're using multiple different integrations. ## Proxy API The Proxy API gives you the data exactly as it comes from the original source, without any transformations. It's more of a direct line to the underlying API. ## Making API Calls via Truto interface 1. **Sign into Truto** and go to the `Integrated Accounts` section or click [here](https://app.truto.one/integrated-accounts). ![Select an Integrated account](/images/integrated-accounts/list-annotated.png) 2. **Select an Integrated Account**. The detail page shows **Unified API** and **Proxy API** sections. ![Unified API and Proxy API sections](/images/integrated-accounts/unified-proxy-api-chooser.png) 3. **Select either Unified API or Proxy API** based on your requirements. ![Select Unified API or Proxy API](/images/integrated-accounts/integrated-account-resources.png) 4. **Select a Resource** to call from that API, then click the method you want to call (for example `list`). A dialog opens with the request. ![Click on Call API](/images/misc/resources-call-api.png) 5. **Click on `Call API`** ![Click on Call API](/images/misc/call-api.png) ## Querying Data Both APIs allow you to limit the number of results you get in one go by using the `limit` parameter. You can also use the `next_cursor` parameter to navigate through pages of results. In some cases, you might need to use specific query parameters like `id` to retrieve specific data. In the Unified API, you'll find an option called `Show remote_data`. If this is enabled, you'll see both the transformed data and the original data from the underlying API. If it's disabled, you'll only see the transformed data. ## Writing Data using Unified APIs Writing data back into the integrations using Unified APIs is inherently a hard problem to solve. The remote APIs usually have their own set of required fields while creating or updating data. And certain fields which are required for writing data don't get sent in the responses. Truto tries to solve this by 1. Using the same fields you receive in the response of Unified APIs as the fields of the request body while writing data. 2. Providing a `/meta` API for each Unified API resource to help you generate the requests programmatically. ### Structure of request body in the Unified API Let's take an example of [creating a CRM Contact](/docs/api-reference/unified-crm-api/contacts/create) using the Unified API. A CRM Contact object has the following Unified fields, - first_name - last_name - email_addresses - [and many more](/docs/api-reference/unified-crm-api/contacts) We'll use the same set of Unified fields to create a CRM Contact irrespective of the underlying API integration. So with these things in mind, a request body to create or update a Contact in Hubspot with the Unified API would like, ```json // POST https://api.truto.one/unified/crm/contacts // example of a Hubspot Contact create request { // set of unified API fields, "first_name": "John", "last_name": "Doe", // an object which gets passed as it to the underlying API. "remote_data": { "properties": { "hs_some_hubspot_specific_property": "from_truto" } } } ``` In the example above, the `first_name` and `last_name` Unified API fields get transformed according to the [Hubspot API rules](https://developers.hubspot.com/docs/api/crm/contacts) and the object in the `remote_data` gets merged into the transformed object. This is how the final request object would look like after all the transformations are applied by Truto, ```json { // notice how first_name and last_name get added to the properties object. "properties": { "firstname": "John", "lastname": "Doe", "hs_some_hubspot_specific_property": "from_truto" } } ``` `first_name` becomes `properties.firstname` and `last_name` becomes `properties.lastname`. The way Hubspot expects the request body to be. ### `/meta` route to get request body schema In the Hubspot example above, we had to refer to the Hubspot documentation to figure out the required fields to create a Contact. But we don't want to do that for every single CRM, so Truto provides a solution where you can query the fields required to create or update an entity using Unified API resource by calling the `/meta` route. Taking the Hubspot example from above, you can call the following route to fetch the fields required to create a Contact in Hubspot, :::code-tabs ```http label="create" GET /unified/crm/contacts/meta/create?integrated_account_id= ``` ```http label="update" GET /unified/crm/contacts/meta/update?integrated_account_id= ``` ```http label="list" GET /unified/crm/contacts/meta/list?integrated_account_id= ``` ```http label="get" GET /unified/crm/contacts/meta/get?integrated_account_id= ``` ::: Note the segment order: `meta` always comes **before** the method name. A path like `/unified/crm/contacts/create/meta` does not exist and returns a plaintext `404`. Two forms of the route are supported: - `GET /unified/{model}/{resource}/{integration}/meta/{method}` — the integration is named in the path, and the environment is taken from your API token. No `integrated_account_id` needed. For example, `GET /unified/crm/contacts/hubspot/meta/list`. - `GET /unified/{model}/{resource}/meta/{method}?integrated_account_id=…` — the integration and the environment are both derived from the integrated account. When you authenticate with an integrated account token, the `integrated_account_id` query parameter is optional. It should return a response with `request_body_schema` attribute which contains the fields required to make the request. ```json {10-99} { "method": "create", "schema": { // JSON schema of the response }, "query_schema": { // JSON schema of the query parameters you need to pass }, // The request body fields "request_body_schema": { "first_name": { "type": "string", "description": "The contact's first name", "required": true, "mapping": "first_name" }, "last_name": { "type": "string", "description": "The contact's last name", "mapping": "last_name" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "street_1": { "type": "string", "description": "Line 1 of the street address" }, "street_2": { "type": "string", "description": "Line 2 of the street address" }, "city": { "type": "string", "description": "The city" }, "state": { "type": "string", "description": "The state" }, "postal_code": { "type": "string", "description": "The postal code" }, "country": { "type": "string", "description": "The country" }, "type": { "type": "string", "description": "The address type" } } }, "mapping": "addresses" }, "email_addresses": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address" }, "type": { "type": "string", "description": "The email address type" } } }, "required": true, "mapping": "email_addresses" }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string", "description": "The phone number" }, "type": { "type": "string", "description": "The phone number type" } } }, "mapping": "phone_numbers" }, "custom_fields": { "type": "object", "description": "Custom fields to be set on the contact", "mapping": "custom_fields" } }, "default_query": {} } ``` The two forms of the route return slightly different payloads. The `integrated_account_id` form shown above also returns `documentation_link`, `response_mapping`, `default_query` and `default_body`. The `{integration}` form returns `response_schema` in addition, and nests the query and request-body schemas one level deeper, under `properties`: ```json { "query_schema": { "type": "object", "properties": { // JSON schema of the query parameters you need to pass } }, "request_body_schema": { "type": "object", "properties": { // The request body fields } } } ``` --- # Reauthorizing Connections in an Integrated Account > Source: https://truto.one/docs/guides/integrated-accounts/reauthorizing-connections/ Sometimes, you may need to refresh your connection to an integration in Truto. This could be because of changes to your integration settings or updates in the integration itself. Reauthorizing your connection will allow the integration to continue to work properly with the updated information. ## Getting notified about reauthorization In case of OAuth integrations, when an end-user revokes access for the OAuth app, Truto will not be able to refresh the access tokens. In such cases, when Truto fails to refresh the access token, it marks the integrated account `needs_reauth` and sends an `integrated_account:authentication_error` event with the integrated account as the payload. The event is sent once, when the account moves into `needs_reauth`; further failures while it stays in that state send nothing. When the account recovers, Truto sets it back to `active` and sends `integrated_account:reactivated`. You can use this event to notify the end-user about the issue and ask them to re-authorize the connection. For OAuth with refresh token functionality, the account moves to `needs_reauth` (and the `integrated_account:authentication_error` event is sent) when there is an issue with refreshing the access token for an integrated account regardless of what the underlying issue is. For other authentication methods and OAuth without refresh token functionality, the account moves to `needs_reauth` when an underlying API call to the integration fails with a 401 response status code. This can happen when proxy and unified APIs are called, or when Sync Jobs are run. > [Webhooks Guide](/docs/guides/webhooks/overview) ## Reauthorize Connections via Truto interface Follow these simple steps: 1. **Sign into Truto** and go to the `Integrated Accounts` section or click [here](https://app.truto.one/integrated-accounts). ![Select an Integrated account](/images/integrated-accounts/list-annotated.png) 2. **Select an Integrated Account**. On the account detail page, click **Re-authorize connection**. ![Re-authorize connection](/images/integrated-accounts/reauthorize-integrated-account.png) 3. In the dialog, click **Get connection link**. ![Get connection link](/images/integrated-accounts/reauthorize-connection.png) 4. Open the **Magic Link** to complete re-authorization. You can share this link with your customer instead. ![Complete re-authorization](/images/integrated-accounts/reauthorize-link.png) ### What happens next? After clicking on the Magic Link, you will be redirected to your account on the integrated platform. You will have to log in and allow access to Truto. Follow the steps for authentication, and upon successful completion, you will see a 'Connection successful' message. You can then close the tab. ## Reauthorizing an account via API Use the following cURL command to generate a link-token. Truto uses Bearer authorization, replace the `` in the command below with your API token. > [Create Link Token API Reference](/docs/api-reference/admin/link-token/create#reauthorizing-an-integrated-account) ```bash curl --location 'https://api.truto.one/link-token' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "integrated_account_id": "" }' ``` Response: ```json { "link_token": "e73c7b9b-2e4d-47d1-b5d2-83441fd24e4c" } ``` Use the following URL, to launch Truto's connection UI. Remember to replace `` with the actual link token received from the API request. ```http https://app.truto.one/connect-account?link_token= ``` ### When the token is refused Reauthorization may switch sign-in method: the connection UI offers whatever methods the integration still has, and the account's `authentication_method` is updated when the end user picks a different one. So the token is refused only when *nothing* on the integration can connect — every method it has is a bring-your-own-app one (OAuth 2.0 or AWS STS) whose app credentials have been removed from this environment since the account connected. Then no token is created and the API answers `400` with `truto_error_code: "app_credentials_not_configured"`; the body also carries `integration`, `environment_integration_id` and `authentication_methods`. [Add the credentials back](/docs/guides/integrations/overriding-oauth-credentials) (or enable another method) and retry; nothing the end user does can complete the reauthorization until then. An account on an integration that still has a working method — an API key beside an unconfigured OAuth app, say — gets its token as usual and reconnects with that method. ### Embedding the linking flow within your app You can also use our Frontend Link SDK to embed the connection flow within your UI. More details [here](/docs/guides/link-sdk/how-to-embed). With this, your Re-authorization process is complete! You've now ensured that your Truto integration will continue to work properly, even with the updated information. --- # Integrated Accounts in Truto > Source: https://truto.one/docs/guides/integrated-accounts/connecting-an-account/ Truto's "Integrated Accounts" feature is a powerful tool that helps you manage your connections to various APIs. Here's what it means and how it works: ## What are Integrated Accounts? "Integrated Accounts" are essentially your connections to various APIs. Once you've connected your account from an API, an 'Integrated Account' is created in Truto. ## How to Access Integrated Accounts? 1. Sign into your Truto account. 2. Navigate to 'Integrated Accounts' from the menu or simply click [here](https://app.truto.one/integrated-accounts). Here, you'll see a list of all your connected accounts. ## What Information is Displayed? Each integrated account listed here will display some important details: - **Account ID**: A unique identifier for the account. - **Tenant ID**: The [tenant](/docs/guides/tenants/overview) that owns this account. One tenant can own many accounts across different integrations. - **Integration**: The specific API or application that the account is connected to. - **Status**: The connection's current state, such as Active, Connecting, Needs re-auth, Validation error, Post install error, or Permission error. - **Connected On**: The date and time when the account was connected. ## What Can You Do Here? In the 'Integrated Accounts' section, you can: - **View Details**: Check the details of any integrated account by clicking on it. - **Access APIs**: Use both Unified and Proxy APIs. - **Check API Logs**: Monitor the API's activities, identify any issues, and troubleshoot them. ## Connecting an account via API Use the following cURL command to generate a link-token. Truto uses Bearer authorization, replace the `` in the command below with your API token. > [Create Link Token API Reference](/docs/api-reference/admin/link-token/create) ```bash curl --location 'https://api.truto.one/link-token' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "tenant_id": "acme-1" }' ``` Response: ```json { "link_token": "e73c7b9b-2e4d-47d1-b5d2-83441fd24e4c" } ``` Use the following URL, to launch Truto's connection UI. Remember to replace `` with the actual link token received from the API request. ```http https://app.truto.one/connect-account?link_token= ``` ### Integrations that are not ready yet A token minted with `tenant_id` is never refused for an integration's sake. If an installed integration's only sign-in methods are bring-your-own-app ones — OAuth 2.0 or AWS STS — and you have not yet [added your own app credentials](/docs/guides/integrations/overriding-oauth-credentials) for it, the connect UI simply leaves that integration out until you do. A deep link to it shows the end user that the integration is not ready yet and names your team. ### Embedding the linking flow within your app You can also use our Frontend Link SDK to embed the connection flow within your UI. More details [here](/docs/guides/link-sdk/how-to-embed). ## Connecting an account via Truto interface 1. Sign in to your Truto account. 2. Click on `Connect Account` ![Click connect account](/images/integrated-accounts/truto-connect-account.png) 3. Type in a value for the Tenant ID. This can be any ID of your choosing (up to 255 characters, with no control characters, no leading or trailing whitespace, and not `.` or `..`). If a [tenant](/docs/guides/tenants/overview) with that ID doesn't exist yet, Truto auto-creates one when the account connects. Then click on `Get connection link`. ![Get connection link](/images/integrated-accounts/connect-account-modal.png) 4. A new link will be generated. Clicking on the link will open a new tab with the list of integrations. You can share this link with your customers too, and they will be able to connect their account. ![Share connection link](/images/integrated-accounts/truto-connect-account-link.png) 5. Select integration from the list to be created ![Select integration](/images/getting-started/select-salesforce.png) 6. You'll now be asked to log in to your account and allow access to Truto. Go through the authentication steps. 7. _Voila!_ You should now see a connection successful message. You can now close this tab. 8. Go to your Truto account, and you should see the new integration under `Integrated Accounts`. Click on the Account ID to view the details and initiate API calls. --- # Overview > Source: https://truto.one/docs/guides/integrated-accounts/connection-validation/setting-up-connection-validation/ The Connection Validation feature in Truto ensures that API connections are configured correctly with valid credentials and required permissions. It is set up on the installed integration's **Configuration** tab. You can define specific API calls for validation by configuring relevant fields under the Connection Validation section. The Connection Validation steps run as described in the [Connection flow for an Integrated account](https://truto.one/docs/guides/integrated-accounts/connection-flow) during the connection of an integrated account to check that the connection is valid by making an API call after the customer or user is entering their API credentials. ## Getting Started Setting up the connection validation is important because if the integrated account connects without verifying it, users can connect their accounts, but further API calls fail with **403 Forbidden** error because of invalid API keys as shown in below screenshot. ![Integration Authentication Issue](/images/integrated-accounts/api_authentication_failure.png) This guide will walk you through enabling Connection Validation for an integration and selecting the necessary fields — using a **GuestPoint** integration as an example. ## Enable Connection Validation To begin using Connection Validation, enable it on the integration’s **Configuration** tab. 1. **Navigate to Integration Configuration**: Open the installed integration and go to the **Configuration** tab. Its fields are editable in place. ![Connection Validation on Configuration](/images/integrated-accounts/guestpoint_connection_validation_settings.png) 2. **Enable Connection Validation**: In the **Connection validation** section, turn on **Do connection validation**, then click **Add request** to add a validation step. Add more steps the same way; they run in order. ![Enable Connection Validation](/images/integrated-accounts/enable_connection_validation.png) ## Select Fields in Connection Validation After Connection Validation is enabled, you will need to select a few key fields to validate the connection. This example shows the fields to select to set up connection validation for **GuestPoint**. **Steps**: 1. **Set Data Source**: - **Request Type**: Choose **Unified API** or **Proxy API** based on your data fetching method. ![Select Request Type](/images/misc/select_request_type.png) - **Resource to fetch**: Specify the endpoint to fetch data from (e.g., `pings` for Proxy APIs). ![Select Resource](/images/misc/select_resource_to_fetch.png) - **Method to call**: Select **list** to retrieve the list of items. Any method defined on the selected resource can be used. ![Select Method](/images/misc/select_method_to_call.png) - **Query in JSON format**: Allows to filter the data retrieved from the selected API response. By specifying a query, you can fetch only the relevant data you need instead of retrieving the entire response. This is an optional field in this case. 2. **Click on Save** in the page header: Connection Validation has now been configured. ![Connection Validation Set Up](/images/integrated-accounts/guestpoint_connection_validation_set_up.png) 3. After Connection Validation is configured, the selected API call is made when connecting an integrated account. --- --- # Connecting an Integrated Account with Connection Validation > Source: https://truto.one/docs/guides/integrated-accounts/connection-validation/connecting-to-integrated-account-with-connection-validation/ ## Connecting an Integrated Account with Connection Validation You can connect an integrated account by following the steps available in [Integrated Accounts](https://truto.one/docs/guides/integrated-accounts/connecting-an-account#connecting-an-account-via-truto-interface). **Connection Validation Outcomes**: - **If Successful**: The test API call succeeds, the connection is validated, and the account shows as active. ![Connection Validation Successful](/images/integrated-accounts/guestpoint_connection_validation_successful.png) - **If Unsuccessful**: - The test API call returned an error because the provided authentication credentials are not correct. The integrated account is left in a validation error state. ![Connection Validation Unsuccessful](/images/integrated-accounts/guestpoint_connection_validation_unsuccessful.png) - A **Validation Error** label is added on the integrated accounts list, helping users understand the issue and fix it. This type of error label is not displayed for successful connections. ![Show Label When Connection Validation Failed](/images/integrated-accounts/connection_validation_label.png) **If using Truto Link SDK**: If you are using the [Truto Link SDK](https://www.npmjs.com/package/@truto/truto-link-sdk) to handle your integration flows, a [validation_error will be thrown](https://www.npmjs.com/package/@truto/truto-link-sdk#error-types) after the integrated account is created and while running the validation requests setup for the integration fail. This error informs you (and possibly your front-end application) that the credentials you provided could not be validated. --- # Platform MCP Server > Source: https://truto.one/docs/guides/assistant/platform-mcp-server/ The Truto **Platform MCP server** exposes a small, fixed set of meta-tools for discovering and calling the Truto **platform API**. It is scoped to your workspace — not per-integration proxy tools. Use it when you want an external AI assistant (Cursor, Claude Desktop, Claude Code, ChatGPT, and so on) to list integrations, inspect connected accounts, run sync jobs, or perform other platform operations on your behalf. You can find your workspace MCP endpoint on the **Settings → Assistant** page under **Platform MCP Server**. ## Endpoint The Platform MCP server is a JSON-RPC endpoint on the Truto API: ``` https://api.truto.one/platform/mcp ``` Replace the host if your team uses a different API base URL (for example, a dedicated deployment). The path is always `/platform/mcp`. ## Authentication Every request must include a Truto **API token** as a Bearer credential: ``` Authorization: Bearer ``` An API token is scoped to the environment it was created in, so the server only sees and changes that environment's resources. Create and manage tokens in the Truto app under **Settings → API Tokens**. See [Creating API tokens](/docs/guides/api-tokens/creating-api-tokens) for step-by-step instructions. Integrated-account tokens cannot access the Platform MCP server — use a team API token instead. ## Exposed tools The server advertises four tools via `tools/list`: | Tool | Purpose | | --- | --- | | `list_api_operations` | Discover REST operations from the Truto OpenAPI catalog (filter by tag, keyword, or path prefix). | | `describe_api_operation` | Get parameters and request-body schema for a specific operation (`method` + `path`). | | `call_platform_api` | Execute a platform API call as the authenticated user. Use `fields` or `jsonata` on the request to shape large list responses. | | `get_capabilities` | Show proxy and unified API surfaces for an integration slug/ID or integrated-account UUID. | The in-app assistant also exposes `read_platform_resource` and `query_tool_result`. Those tools are **not** available on the Platform MCP server. The server also supports standard MCP resources and a `platform-assistant` prompt for operator context. ## Client setup Pick your client and add the config. Substitute your API token and API base URL. Store tokens in environment variables or your client's secret handling — do not commit API tokens to version control. ### Cursor Cursor v0.48.0+ connects to **unauthenticated** remote MCP servers natively via a `url` field. The Platform MCP server requires a Bearer token on every request, so use the `mcp-remote` bridge (same transport Claude Desktop uses). Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally, or open **Cursor Settings → Tools & MCP → New MCP Server** to create the file: ```json { "mcpServers": { "truto": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.truto.one/platform/mcp", "--header", "Authorization:${TRUTO_AUTH_HEADER}" ], "env": { "TRUTO_AUTH_HEADER": "Bearer YOUR_API_TOKEN" } } } } ``` Use `Authorization:${TRUTO_AUTH_HEADER}` with no spaces around `:` — Cursor on Windows mangles spaces inside `args` when invoking `npx`. Put the full `Bearer …` value in `env` instead of splitting it across the argument. After saving: 1. Restart Cursor (or reload the window). 2. Open **Customize** in the sidebar and confirm **truto** is enabled under MCP servers. 3. If the server stays disconnected, open **Output → MCP Logs** (`Cmd+Shift+U` on macOS) and check for auth or connection errors. ### Claude Desktop Claude Desktop connects to remote MCP servers through an `npx` bridge. Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config): ```json { "mcpServers": { "truto": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.truto.one/platform/mcp", "--header", "Authorization:${TRUTO_AUTH_HEADER}" ], "env": { "TRUTO_AUTH_HEADER": "Bearer YOUR_API_TOKEN" } } } } ``` Fully quit and reopen Claude Desktop after saving. ### Claude Code ```bash claude mcp add --transport http truto https://api.truto.one/platform/mcp \ --header "Authorization: Bearer YOUR_API_TOKEN" ``` Add `--scope user` to make it available across all projects. ### ChatGPT ChatGPT connects to remote MCP servers over HTTPS (SSE or Streamable HTTP). Enable **Developer mode**, create an app pointing at your Platform MCP endpoint, then enable the app per chat before using it. **Plan requirements:** Developer Mode and custom MCP apps are available on ChatGPT Plus, Pro, Business, Enterprise, and Education plans. Business and Enterprise workspaces get full MCP support including write actions. Plus and Pro users can connect read-only custom MCP servers in Developer Mode. See [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta) and the [Developer mode guide](https://platform.openai.com/docs/guides/developer-mode) for current plan details. **Authentication note:** The Platform MCP server requires `Authorization: Bearer ` on every request, including `initialize` and `tools/list`. OpenAI documents OAuth, No Authentication, and Mixed Authentication for custom MCP apps — not static Bearer tokens in the ChatGPT web UI. If your **Create app** screen includes an API key or Bearer token field, paste your Truto API token there. If it only offers OAuth, use Cursor, Claude Desktop, or Claude Code instead, or call the server through the [OpenAI Responses API MCP tool](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) (see below). **Enable Developer Mode** - **Individual users:** **Settings → Apps → Advanced settings** → turn on **Developer mode**. - **Business admins:** enable Developer Mode under [workspace settings](https://chatgpt.com/admin/ca) (**Workspace Settings → Permissions & Roles → Connected Data → Developer mode**), then turn it on for your account under **Settings → Apps → Advanced settings**. - **Enterprise/Edu:** workspace admins enable Developer Mode via RBAC; authorized members toggle it under **Settings → Apps → Advanced settings**. **Create the app** 1. With Developer Mode on, go to **Settings → Apps → Create** (admins can also use **Workspace settings → Apps → Create**). 2. Set the MCP server URL to `https://api.truto.one/platform/mcp` (or your team's API base URL with path `/platform/mcp`). 3. Pick the authentication option that matches what the UI offers and what the server requires (see authentication note above). 4. Click **Scan Tools**, wait for the scan to finish, then click **Create**. The app appears as a draft under **Workspace settings → Apps → Drafts**. Admins publish it for the workspace; until then, you can test it from your own **Settings → Apps** list (marked **Dev**). **Use the app in a chat** A saved app is not active until you enable it in the conversation: 1. Start a new chat. 2. Click **+** in the composer → **More** → **Developer Mode** → **Add sources**. 3. Enable your Truto app, then ask a question that should call platform tools (for example, "List my connected accounts"). **OpenAI Responses API (Bearer token)** If the ChatGPT app UI does not accept a static token, pass your Truto API token in the MCP tool's `authorization` field when calling the [Responses API](https://developers.openai.com/api/docs/guides/tools-connectors-mcp): ```bash curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "tools": [{ "type": "mcp", "server_label": "truto", "server_url": "https://api.truto.one/platform/mcp", "authorization": "Bearer YOUR_TRUTO_API_TOKEN", "require_approval": "never" }], "input": "List my integrated accounts" }' ``` Send the Truto token on every Responses API request — the API does not store the `authorization` value between calls. Write actions through ChatGPT still require confirmation in the chat UI when using Developer Mode apps. Over Platform MCP, `call_platform_api` returns an `APPROVAL_REQUIRED` error for mutating requests — approve those writes in the **Truto Assistant** chat UI instead. ## Write approvals Read operations run immediately through MCP: `GET` and `HEAD` requests, plus `POST` requests to paths ending in `/test`, `/validate`, `/refresh-credentials`, or `/refresh-mapping-cache`. **Writes, deletes and sensitive reads require approval** when using the in-app Truto Assistant. Over Platform MCP, `call_platform_api` returns an `APPROVAL_REQUIRED` error for: - `POST`, `PUT`, and `PATCH` requests that mutate platform resources - All `DELETE` requests and bulk-delete operations - Calls that touch credentials or other sensitive configuration - `GET` and `HEAD` requests to sensitive paths — API tokens, SCIM tokens, secrets, OAuth tokens, and environment variables Some paths are never callable through `call_platform_api`, with or without approval: `/auth`, `/link-token`, `/session-token`, `/magic-link`, and `/assistant`. The call returns a `FORBIDDEN` error. Mint link tokens and session tokens from your own backend instead. Use MCP for discovery and read-only inspection, or approve destructive and write operations in the **Truto Assistant** chat UI instead. Treat API tokens like passwords — store them in your MCP client's secret handling (environment variables, OS keychain, or your team's secrets manager) rather than committing them to version control. --- # Truto Assistant > Source: https://truto.one/docs/guides/assistant/truto-assistant/ Truto Assistant is an AI-powered chat sidebar built into the Truto dashboard. It lets you explore your workspace, run platform operations, and get answers about integrations and connected accounts using natural language. ## Features - **Natural language queries** — ask about your integrations, connected accounts, sync jobs, unified APIs, and more without memorizing API paths or navigation. - **Platform operations** — list accounts, check sync job status, query data, and inspect integration configuration directly from chat. - **Deep links** — responses include links to relevant pages in the dashboard so you can jump straight to what you need. - **Tool approval** — write and destructive operations (create, update, delete) require explicit approval before executing. - **Workspace-aware** — the assistant knows about your team's integrations, connected accounts, and configuration. ## Setup 1. Navigate to **Settings → Assistant** (the **Truto Assistant** page). 2. Toggle **Enable Truto Assistant** on. 3. Enter your **Anthropic API key** — Truto uses BYOK (Bring Your Own Key), so usage is billed directly to your Anthropic account. 4. Click **Test key** to verify the key works. Only team admins can configure assistant settings. ![Assistant settings](/images/assistant/assistant-settings.png) ## Usage 1. Open **Truto Assistant** from the dashboard sidebar to open the chat panel. 2. Type a natural language question or command — for example, "List my connected HubSpot accounts" or "What sync jobs are failing?" 3. The assistant will call platform tools to gather information. Read operations execute immediately; write operations show an approval prompt first. 4. Use the model selector in the message composer to switch between models mid-conversation. 5. The context meter beside the model selector shows how much of the model's context window is in use. ## Available models | Model | Strengths | | --- | --- | | Claude Sonnet 5 | Latest balanced model | | Claude Sonnet 4.6 (default) | Balanced speed and capability — recommended for most tasks | | Claude Opus 4.6 | Most capable reasoning — best for complex multi-step operations | | Claude Haiku 4.5 | Fast and economical — good for simple lookups | You can switch models at any time using the selector in the message composer. ## Security - **BYOK** — your Anthropic API key is stored encrypted and never shared with other teams or used outside your workspace. - **Write approval** — any tool call that would create, update, or delete a resource requires you to click Approve before it executes. - **Workspace scope** — the assistant can only access data within your team's workspace. It cannot see other teams' resources. - **No training** — conversations are sent to Anthropic's API under their standard data policy (messages are not used to train models). ## Related - [Platform MCP Server](/docs/guides/assistant/platform-mcp-server) — connect external AI tools (Cursor, Claude Desktop) to your workspace via MCP. --- # Truto LLM Tools Overview > Source: https://truto.one/docs/guides/tools/overview/ Truto provides all the resources defined on an Integration as tools for your LLM frameworks to use. We currently support the following LLM frameworks: - Langchain.js - [truto-langchainjs-toolset](https://github.com/trutohq/truto-langchainjs-toolset) Please reach out to us at support@truto.one if you need support for additional frameworks. ## How it works Every integration on Truto is essentially a comprehensive JSON object that represents how an underlying product's API behaves. Think of it as a Swagger file, but built specifically with integrations in mind. Integrations have a concept of `Resources`, which map to the endpoints on the underlying product's API. Resources enable us to map any API into a REST-based CRUD API. > For example, you could have a `members` resource on the Cloudflare integration that maps to `/client/v4/accounts/:id/members` API on Cloudflare. Every Resource has `Methods` defined on them. These can be standard ones like List, Get, Create, Update, and Delete, as well as custom ones like "Send Email". > Taking the example further, we could define `GET /client/v4/accounts/:id/members` as a List method to retrieve all members in a Cloudflare account, and `POST /client/v4/accounts/:id/members` as a Create method to add a new member to a Cloudflare account. The `Methods` on the `Resources` are what we currently provide as Proxy APIs, where Truto handles all pagination, authentication, and query parameter processing. They always return data in a predefined format. They are the first level of abstraction that Truto provides. Unified APIs are built on top of these Proxy APIs with data transformation added to normalize the structure of the data into a common format across a product category. The second level of abstraction. > We could define a User Directory Unified API that calls the `members` resource for Cloudflare integration and might call the `users` resource for Hubspot. As a consumer of the Unified API, you simply need to call the `/user-directory/users` endpoint. Unified APIs are particularly helpful when building integrations programmatically. However, when solving problems agentically, Proxy APIs are sufficient because they can handle data normalization on their own using the raw data from the underlying product's APIs. Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the `Methods` defined on the `Resources` for an integration. We then call the [/integrated-account/:id/tools](/docs/api-reference/admin/integrated-accounts/tools) endpoint on the Truto API to return all of these Proxy APIs with their descriptions and schemas, creating Tools that LLM frameworks can use. ## Adding tools to an integration The Truto team provides basic tool definitions for each `Resource` and `Method` by default. **Following the true Truto ethos, all of this is customizable by anyone using Truto.** Let's walk through the steps of adding a tool definition for the Cloudflare integration: We'll add the tool definition for the List Members endpoint on the Cloudflare integration and then call the `/tools` endpoint to see the output of what we've added. 1. Go to the Cloudflare integration in your Truto account. ![Tools cloudflare integration](/images/tools/tools-cloudflare-integration.png) 2. Click the Edit integration button in the top right. ![Tools edit cloudflare integration](/images/tools/tools_edit_integration.png) 3. Scroll down to the Resources section, expand the `members` resource, and then expand the List method. ![Tools scroll down to resource cloudflare integration](/images/tools/tools_scroll_to_description.png) 4. Enter a description for the method, which will be used as the description for the tool. ![Tools add description cloudflare integration](/images/tools/tools_add_description.png) 5. Next, switch to the Query Schema tab where you can specify the query parameters that the API accepts. ![Tools add query schema cloudflare integration](/images/tools/tools_add_query_schema.png) 6. Scroll back to the top of the screen and click Save (Note: we're working on making this a sticky header). 7. Now connect a Cloudflare account using Truto and make a note of the integrated account ID. You can refer to our [guide on connecting accounts](https://truto.one/docs/guides/integrated-accounts/connecting-an-account#connecting-an-account-via-truto-interface). ![Connect a Cloudflare account](/images/tools/connect-account.png) 8. After you have the integrated account ID for a Cloudflare integration, you can call the following endpoint: `GET https://api.truto.one/integrated-account//tools` ([API Reference](/docs/api-reference/admin/integrated-accounts/tools)). ![Tools tools response cloudflare integration](/images/tools/tools_endpoint_response.png) You'll receive the List Members Proxy API as a tool in the response, which can now be used with LLM providers of your choice. Our LLM SDKs use this [/tools](/docs/api-reference/admin/integrated-accounts/tools) endpoint to register tools in the LLM framework. You can refer to our [Langchain SDK](https://github.com/trutohq/truto-langchainjs-toolset) to see how it works. These tool definitions update automatically as soon as you make changes in the Truto integration UI. For completeness, let's improve the tool description for the List Member endpoint. ![Tools update description cloudflare integration](/images/tools/tool_edit_description.png) And then call the [/tools](/docs/api-reference/admin/integrated-accounts/tools) endpoint again. ![Tools updated tools response cloudflare integration](/images/tools/tools_endpoint_response_2.png) You'll see that the description has been updated in real-time! ## Seeing it in action We've created an example file in the [Truto Langchain.js SDK repo](https://github.com/trutohq/truto-langchainjs-toolset). You can install Bun and run `bun run examples/index.ts` to see it in action. ![Tool calling](/images/tools/tool_calling.png) ## Tools API reference You can refer to the API reference for the tools endpoint [here](/docs/api-reference/admin/integrated-accounts/tools). The tools endpoint accepts the following query parameters to help you filter the tools based on your requirements: - `methods` - an array of strings to filter the tools based on the type of method. For example, if you just want read-only and custom tools, you can specify `methods[0]=read&methods[1]=custom`. This will return any non-write tools available on the integrated account. Accepted values are `read` (`get` and `list`), `write` (`create`, `update` and `delete`), `custom` (any other method), or an exact method name such as `search`. - `tags` - an array of strings. Only tools carrying at least one of these tags are returned, for example `tags[0]=contacts`. - `has_description` - tools without a description are left out by default. Pass `has_description=false` to include them. --- # Custom Validation > Source: https://truto.one/docs/guides/rapid-form/custom-validation/ RapidForm allows you to implement advanced validation logic using **JSONata expressions**, enabling you to enforce complex business rules that go beyond basic "required" conditions. This step comes after you have added the neccessary fields in your RapidForm. ## Enabling Custom Validation Custom validation is applied at the form level and is executed on the data entered by the user across multiple fields. Toggle the **Custom Validation** option to enable this feature. ![Custom Validation Toggle](/images/rapid-form/rapidForm-custom-validation-toggle.png) --- ## Configuring Custom Validation Custom validation once toggled would look like : ![Custom Validation Configuration](/images/rapid-form/rapidform-custom-validation.png) ### Validation Configuration Options #### 1. **Example Input Data (JSON)** - Provide sample JSON data to simulate and test your validation logic. - **Example**: ```json { "projects": [ { "value": "1" }, { "value": "2" }, { "value": "3" } ] } ``` #### 2. **Validation Expression (JSONata)** - Write a **JSONata** expression that evaluates the input data. - **Expected Output**: - An array of error objects with: - **field** (optional): The field to which the error message applies. Leave it out to show the message as an error for the whole form. - **message**: The error message to display. - Or `undefined` if no errors are found. - **Example Expression**: ```jsonata ($exists(projects) and $count(projects) >= 5) ? undefined : [{ "field": "projects", "message": "Select at least 5 projects" }] ``` - **Explanation**: - `$exists(projects)` checks if the `projects` field exists. - `$count(projects)` counts the number of items in the `projects` array. - If there are at least 5 items, the validation passes (returns `undefined`). - Otherwise, it returns an error targeting the `projects` field. #### 3. **Output** - View the results of your validation expression applied to the example input data. - For the above example, the output would look like: ```json [ { "field": "projects", "message": "Select at least 5 projects" } ] ``` --- Custom validation in RapidForm is a powerful feature that allows you to enforce precise business rules and ensure data accuracy before submission. By leveraging **JSONata expressions**, you can create dynamic, field-level validation that goes beyond basic requirements, enabling: - **Consistency**: Validate inputs against your specific criteria to ensure clean, standardized data. - **Flexibility**: Handle complex scenarios like interdependent fields or calculated requirements. - **User Guidance**: Provide clear and actionable error messages to improve user experience and minimize mistakes. By integrating custom validation into your RapidForm workflows, you enhance the reliability and usability of your forms, ensuring they meet both user and business requirements effectively. Let RapidForm handle the complexity so you can focus on delivering seamless integrations. --- # Overview > Source: https://truto.one/docs/guides/rapid-form/overview/ **RapidForm** is a powerful tool designed to collect input from end users as part of the [Integrated account connection flow](/docs/guides/integrated-accounts/connecting-an-account#connecting-an-account-via-truto-interface) It streamlines the process of gathering necessary data and preferences from users after they have connected their accounts, enabling more personalized and efficient integrations. ## Key Features - **Supports Unified and Proxy APIs**: RapidForm can fetch data using both [Unified APIs](/docs/guides/unified-apis/what-are-unified-apis) and Proxy APIs (directly proxying requests to the service's API), offering flexibility in how you access data. - **Dynamic Field Types**: Use various field types such as Single Select, Multi Select, Text, Password, Checkbox, and Hidden fields to collect different types of input. - **Dependency Management**: Fields can depend on the values of other fields, enabling dynamic form behavior (e.g., loading projects based on a selected workspace). - **Custom Validation and Transformation**: Implement custom validation logic and data transformations using [JSONata](https://docs.jsonata.org/overview.html) expressions to ensure data integrity and meet specific business rules. ## Use Cases Here are some scenarios where RapidForm can significantly enhance the integration experience: ### 1. Syncing Specific Tickets **Example**: **Syncing Tickets from Zendesk with Specific Tags** - **Scenario**: You want to allow users to sync only tickets that have certain tags from their Zendesk account. - **Solution with RapidForm**: - After the user connects their Zendesk account, RapidForm fetches the list of tags using Zendesk's API. - The form presents a **Multi Select** field populated with the user's tags. - The user selects the tags they are interested in. - The integration later on uses this selection to filter tickets. The selections are stores as variables in the Integrated Account. ### 2. Selecting Specific Workspaces or Projects **Example**: **Syncing Data from a Specific Workspace in Asana** - **Scenario**: Users may have multiple workspaces in Asana but only want to sync data from one. - **Solution with RapidForm**: - After connecting their Asana account, RapidForm fetches the list of workspaces via the Asana API. - A **Single Select** field displays the available workspaces. - The user selects the desired workspace. - Subsequent data synchronization is scoped to the selected the Projects corresponsing to the Workspace. --- # Transform Expressions > Source: https://truto.one/docs/guides/rapid-form/transform-expressions/ Transform expressions allow you to manipulate and compute form data before saving it to the integrated account. By using **JSONata expressions**, you can compute additional fields, modify existing data, or restructure the payload for storage or integration.This step comes after you have added the neccessary fields in your RapidForm ## Setting Up Transform Expressions Transform expressions are configured to preprocess form data before it is stored. This feature is useful for scenarios where fields need to be computed dynamically or existing fields require adjustments. Toggle the **Transform data before saving** option to enable this feature. ![Transform Toggle](/images/rapid-form/rapidform-transfrom-expression.png) ## Configuration Options ### 1. **Example Input Data (JSON)** - Provide sample JSON data to simulate and test your transformation logic. - **Example**: ```json { "projects": [ { "value": 1 }, { "value": 2 }, { "value": 3 } ] } ``` --- ### 2. **Transformation Expression (JSONata)** - Write a **JSONata** expression to transform the input data. - **Expected Output**: - A single JSON object representing the transformed data. - You can use the `$merge` function to merge computed fields with the original input. - **Example Expression**: ```jsonata $merge([ $, { "totalProjects": $count(projects), "timestamp": $now() } ]) ``` - **Explanation**: - `$merge` combines the original data (`$`) with computed fields. - `"totalProjects"` is computed using `$count(projects)`, which counts the number of items in the `projects` array. - `"timestamp"` adds the current date and time using `$now()`. --- ### 3. **Output** - Displays the result of applying the transformation expression to the example input data. - **For the Above Example**: **Output**: ```json { "projects": [ { "value": 1 }, { "value": 2 }, { "value": 3 } ], "totalProjects": 3, "timestamp": "2024-12-04T10:15:00.000Z" } ``` --- Transform expressions in RapidForm offer an efficient way to customize and preprocess form data before saving it to an integrated account. By leveraging **JSONata expressions**, you gain the flexibility to dynamically compute fields, modify existing data, or restructure the payload to match the requirements of your integration --- # RapidForm Fields > Source: https://truto.one/docs/guides/rapid-form/field-types/ You can add multiple fields to your RapidForm. Open the installed integration's **Configuration** tab to configure each field by `type`. The RapidForm fields are editable in place, and **Save** in the page header applies your changes. Each field type has its own options; the sections below walk through them with examples. ## Single Select ![Single Select Field](/images/rapid-form/rapidform_single_select.png) The **Single Select** field allows users to choose one option from a dropdown list. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `workspace_id` - This will be the name of the variable in the Variables section. - **Label** (required) - The name displayed to users on the form. - **Example**: `Workspace` - This will be the label of the field in the RapidForm. - **Type** (required) - Select **Single Select** for this field type. - **Help Text** - Additional guidance displayed under the field. - **Example**: `Select the workspace you want to sync` - **Disabled Help Text** - Guidance shown when the field is disabled. - Useful when the field depends on another field. - **Example**: `Please select an account first` - **Required** - Determines if the field is mandatory. - Options: **Enabled** or **Disabled** - **Request Type** (required) - Method used to fetch data for the options. - Options: - **Unified API** - **Proxy API** - **Example**: **Unified API** - **Resource to Fetch** (required) - The API endpoint or resource to fetch data from. - Select the resource corresponding to the **Request Type**. - **Example**: `ticketing/workspace` - **Method to Call** (required) - The API method used to fetch data. - Options: - **list**: Retrieves a list of items. - **get**: Retrieves a single item. - **Example**: **list** - **Query in JSON Format** - Additional query parameters in JSON format to refine the data fetched. - **Example**: ```json { "status": "active" } ``` - **Depends On** - Specifies fields this field depends on. - Enter field names separated by commas. - **Example**: `account_id` (if the workspace depends on the selected account) - **Reset Value on Parent Dependency Change** - Determines if the field should reset when a parent field changes. - Options: **Enabled** or **Disabled** - **Enable Auto Pagination** - Enables automatic loading of more items as the user scrolls. - **Warning**: Do not enable if the resource has a large number of items, as it may cause performance issues. - **Noun Used for the Field** - The singular noun used to describe the items. - Default: `item` - **Example**: `workspace` - **No Results Title** - Message displayed when no data is returned. - Default: `No results returned` - **Example**: `No Workspaces Found` - **No Results Subtext** - Additional message when no data is returned. - Default: `No results returned` - **Example**: `Please check your account selection.` - **Label Attribute for the Select Field** - The attribute in the API response to use as the label. - Default: `label` - **Example**: `name` (if the API returns `name` as the workspace name) - **Value Attribute for the Select Field** - The attribute in the API response to use as the value. - Default: `value` - **Example**: `id` (if the API returns `id` as the workspace identifier) - **Subtext Attribute for the Select Field** - An additional attribute to show as subtext. - Default: `subText` - **Example**: `description` (to display a brief description under each option) - **Parent Attribute for the Select Field** - The attribute in the response used for grouping options under a parent. - **Example**: `organization_name` (if workspaces are grouped by organization) - **Attribute in Parent to Match Value** - The attribute in the parent used to match values. - Default: `value` - **Example**: `organization_id` - **No Label Text** - Text displayed when the label attribute is empty. - Default: `No label` - **Example**: `Unnamed Workspace` - **Enable Search** - Allows users to search within the data. - Options: **Enabled** or **Disabled** ## Multi Select ![Multi Select Field](/images/rapid-form/rapidform_multi_select.png) The **Multi Select** field allows users to choose multiple options from a list. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `project_ids` - This will be the name of the variable in the Variables section. - **Label** (required) - The name displayed to users on the form. - **Example**: `Projects` - This will be the label of the field in the RapidForm. - **Type** (required) - Select **Multi Select** for this field type. - **Help Text** - Additional guidance displayed under the field. - **Example**: `Select the projects you want to sync` - **Disabled Help Text** - Guidance shown when the field is disabled. - **Example**: `Please select a workspace first` - **Required** - Determines if the field is mandatory. - Options: **Enabled** or **Disabled** - **Request Type** (required) - Method used to fetch data for the options. - Options: - **Unified API** - **Proxy API** - **Example**: **Unified API** - **Resource to Fetch** (required) - The API endpoint or resource to fetch data from. - **Example**: `ticketing/project` - **Method to Call** (required) - The API method used to fetch data. - Options: - **list** - **get** - **Example**: **list** - **Query in JSON Format** - Additional query parameters in JSON format. - **Example**: ```json { "workspace_id": "{{workspace_id.value}}" } ``` - *Note*: A select field stores the selected option as an object with `value`, `label` and `subText`. Using `{{workspace_id.value}}` pulls the selected ID from the `workspace_id` field. - **Depends On** - Fields this field depends on. - Enter field names separated by commas. - **Example**: `workspace_id` - **Reset Value on Parent Dependency Change** - Determines if the field should reset when a parent field changes. - Options: **Enabled** or **Disabled** - **Example**: **Enabled** - **Enable Auto Pagination** - Enables automatic loading of more items as the user scrolls. - **Example**: **Disabled** - **Noun Used for the Field** - Default: `item` - **Example**: `project` - **No Results Title** - Default: `No results returned` - **Example**: `No Projects Found` - **No Results Subtext** - Default: `No results returned` - **Example**: `Try selecting a different workspace.` - **Label Attribute for the Select Field** - Default: `label` - **Example**: `name` - **Value Attribute for the Select Field** - Default: `value` - **Example**: `id` - **Subtext Attribute for the Select Field** - Default: `subText` - **Example**: `description` - **Parent Attribute for the Select Field** - **Example**: `category` (if projects are grouped by category) - **Attribute in Parent to Match Value** - Default: `value` - **Example**: `category_id` - **No Label Text** - Default: `No label` - **Example**: `Unnamed Project` - **Allow Select All** - Enables users to select all options at once. - Options: **Enabled** or **Disabled** - **High Cardinality** - Tick this if the number of selected values will be large (1000+). - **Enable Search** - Allows users to search within the options. - Options: **Enabled** or **Disabled** - **Attribute to Use for Search** (required if search is enabled) - The query parameter name used for searching. - **Example**: `name` - **Label for Search Input Field** (if search is enabled) - **Example**: `Search Projects` - **Placeholder for Search Input Field** (if search is enabled) - **Example**: `Enter project name` - **Search on Frontend** (if search is enabled) - The search will happen on the loaded data with no additional API calls. - Options: **Enabled** or **Disabled** - **Example**: **Disabled** (search queries the API) - **Empty Search Result Message** - Default: `No options matched the search criteria` - **Example**: `No projects match your search` ## Text ![Text Field](/images/rapid-form/rapidform_text.png) The **Text** field allows users to enter a single line of text. It is useful for custom inputs from the user. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `user_name` - **Label** (required) - The name displayed to users on the form. - **Example**: `User Name` - **Type** (required) - Select **Text** for this field type. - **Help Text** - Additional guidance displayed under the field. - **Example**: `Enter your full name` - **Disabled Help Text** - Guidance shown when the field is disabled. - **Example**: `This field is not editable` - **Required** - Determines if the field is mandatory. - Options: **Enabled** or **Disabled** - **Depends On** - Fields this field depends on. - Enter field names separated by commas. - **Example**: `user_id` (if the name depends on a selected user ID) ## Password ![Password Field](/images/rapid-form/passowrd_rapidform.png) The **Password** field allows users to enter sensitive information securely. Useful for sensitive fields like passwords, API Keys etc. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `api_secret` - **Label** (required) - The name displayed to users on the form. - **Example**: `API Secret` - **Type** (required) - Select **Password** for this field type. - **Help Text** - Additional guidance displayed under the field. - **Example**: `Enter your API secret key` - **Disabled Help Text** - Guidance shown when the field is disabled. - **Example**: `Please complete previous steps` - **Required** - Determines if the field is mandatory. - Options: **Enabled** or **Disabled** - **Depends On** - Fields this field depends on. - Enter field names separated by commas. - **Example**: `api_key` (if the secret depends on an API key entered) ## Checkbox ![Checkbox Field](/images/rapid-form/checkbox-rapidform.png) The **Checkbox** field allows users to select or deselect an option, representing a simple yes/no or true/false choice. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `subscribe_newsletter` - **Label** (required) - The name displayed to users on the form. - **Example**: `Subscribe to Newsletter` - **Type** (required) - Select **Checkbox** for this field type. - **Help Text** - Additional guidance displayed under the field. - **Example**: `Receive updates and special offers` - **Disabled Help Text** - Guidance shown when the field is disabled. - **Example**: `Option not available at this time` - **Required** - Determines if the field must be checked before submission. - Options: **Enabled** or **Disabled** - **Depends On** - Fields this field depends on. - Enter field names separated by commas. - **Example**: `email` (if subscription depends on email being provided) ## Hidden ![Hidden Field](/images/rapid-form/hidden-rapidform.png) The **Hidden** field stores data without displaying it to the user. It's useful for passing data that doesn't require user input, such as default values, metadata, or values derived from other fields. ### Configuration Options - **Name** (required) - The unique identifier for this field used internally. - **Example**: `session_token` - **Type** (required) - Select **Hidden** for this field type. - **Request Type** (required) - Method used to fetch data for the hidden field. - Options: - **Unified API** - **Proxy API** - **Resource to Fetch** (required) - The API endpoint or resource to fetch data from. - **Example**: `auth/session` - **Method to Call** (required) - The API method used to fetch data. - Options: - **list** - **get** - **Query in JSON Format** - Additional query parameters in JSON format. - **Depends On** - Fields this field depends on. - Enter field names separated by commas. - **Example**: `user_id` - **Reset Value on Parent Dependency Change** - Determines if the field should reset when a parent field changes. - Options: **Enabled** or **Disabled** - **Enable Auto Pagination** - **Warning**: Typically not needed for hidden fields. Do not enable unless necessary. ## Reordering and Deleting Fields To adjust the order of fields in your form, use the arrows to reorder them. This allows you to easily adjust the flow of the form without needing to recreate the fields. Use the delete button if you want to delete a field from your form. ![Reorder Fields](/images/misc/rapidfrom-reorder.png) --- # Creating a RapidForm through API > Source: https://truto.one/docs/guides/rapid-form/creating-rapid-from-api/ Follow the steps below to create a RapidForm through the Truto API. ## Basic structure of a RapidForm Taking the example of an Asana RapidForm which asks the user to select a Workspace and its Projects, it can be defined like so, ```json { "type": "form", "config": { "fields": [ { "name": "workspace_id", "type": "single_select", "label": "Workspace", "help_text": "The workspace to sync", "placeholder": "Select a workspace", "required": true, "data_source": { "type": "unified", "resource": "ticketing/workspaces", "method": "list" }, "options": { "value": "id", "label": "name", "subText": "id" } }, { "name": "collections", "type": "multi_select", "label": "Projects", "depends_on": [ "workspace_id" ], "help_text": "The projects to sync", "required": true, "data_source": { "type": "unified", "resource": "ticketing/collections", "method": "list", "query": { "workspace_id": "{{workspace_id.value}}" } }, "disabled_text": "Please select a workspace", "options": { "value": "id", "label": "name", "subText": "id" } } ] } } ``` - `type` specifies that it's a `form`. - `config.fields` is an array containing all the form fields. The order of the array items dictates the order of the form fields in the UI. - `config.fields.name` is the variable name that is stored in the `context` object of an Integrated account. This is the name that will appear in the Variables section in the UI and will be used as a placeholder in the Sync Job configuration. - `config.fields.type` can be `single_select`, `multi_select`, `text`, `password`, `checkbox` or `hidden`. A single select field stores the selected option as an object with `value`, `label` and `subText`, and a multi select field stores an array of these objects. Use the `value` attribute to get the selected ID, like `{{workspace_id.value}}`. - `config.fields.label` is the Label of the field that appears in the UI to the end user. - `config.fields.help_text` is the help text that appears below the field to help the end user in selecting the values. - `config.fields.required` marks the field as required in the UI where the end user needs to select a value. - `config.fields.disabled_text` is used in `multi_select` fields when they are dependent on the value of another field. In the example above, Projects field requires a Workspace to be selected, so until a Workspace is selected the Projects field will show the `disabled_text`. - `config.fields.depends_on` is an array used to create dependency between the fields. In the example above, Projects is dependent on Workspace, so the `depends_on` has the value `workspace_id` (name of the field that Projects field depends on). Multiple dependencies can be specified. - `config.fields.data_source` specifies the data to be fetched from the Unified or Proxy API to populate the options in the single and multi select fields. - `type` can be `unified` for fetching Unified API data and `proxy` for fetching Proxy API data. - `resource` is the name of the resource endpoint to fetch the data from. For Unified API, the format is `unified_api_name/resource_name`. - `method` can be `list` or `get`. It can also be a custom method for Proxy API. - `query` is the query parameters to send to the resource endpoint. You can use placeholders to refer to the values of other fields in the form. In the example above, the query for Projects fields refers to the selected Workspace's ID through the field's `name` attribute - `{{workspace_id.value}}`. - `config.fields.options` is the mapping for showing the options in the single dropdown and multi select checkboxes. - `value` the attribute in the data_source to use as the value. - `label` the attribute in the data_source to show as the label in the selection dropdown. - `subText` the attribute in the data_source to show as the help text to make a better selection or to distinguish two options with the same `label` value. ## Get the installed integration To create the RapidForm defined above, we'll first need to get the `id` of the installed Asana integration. Use the following request to get it, ```bash curl --location 'https://api.truto.one/environment-integration?integration.name=asana' \ --header 'Authorization: Bearer ' \ { "result": [ { "id": "09b8d7dd-d7c1-42ba-8fae-d3c9278ade35", "integration_id": "91dcffb7-d9db-4c70-9ac8-91c71578f9a0", ... } } ], "next_cursor": null, "limit": 500 } ``` `integration.name` can be used to filter the integration based on its identifier. Use the `result.id` attribute in the steps going forward for the installed integration ID. ## Add RapidForm to the installed integration Now let's add the RapidForm defined above to the installed integration. To do this, issue a PATCH request on the installed integration with the request below. Use the id retrieved in the previous step. ```bash curl --location --request PATCH 'https://api.truto.one/environment-integration/09b8d7dd-d7c1-42ba-8fae-d3c9278ade35' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "override": { "actions": { "post_connect_user_form": { "steps": [ { "type": "form", "config": { "fields": [ { "name": "workspace_id", "type": "single_select", "label": "Workspace", "help_text": "The workspace to sync", "placeholder": "Select a workspace", "required": true, "data_source": { "type": "unified", "resource": "ticketing/workspaces", "method": "list" }, "options": { "value": "id", "label": "name", "subText": "id" } }, { "name": "collections", "type": "multi_select", "label": "Projects", "depends_on": [ "workspace_id" ], "help_text": "The projects to sync", "required": true, "data_source": { "type": "unified", "resource": "ticketing/collections", "method": "list", "query": { "workspace_id": "{{workspace_id.value}}" } }, "disabled_text": "Please select a workspace", "options": { "value": "id", "label": "name", "subText": "id" } } ] } } ] } } } }' ``` The form definition is added to the following path, `override.actions.post_connect_user_form.steps`. ## Accessing RapidForm values in Sync Job The values selected by the user in a RapidForm can be accessed using placeholders in a Sync Job like shown below. The example is of a Sync Job which fetches tasks in selected projects in Asana. [Learn more about Sync Jobs](/docs/guides/rapid-bridge/creating-rapid-bridge). ```json { "integration_name": "asana", "args_schema": {}, "resources": [ { "resource": "ticketing/collections", "method": "get", "loop_on": "collections", "id": "{{collections.value}}" }, { "resource": "ticketing/tickets", "method": "list", "depends_on": "ticketing/collections", "query": { "collection_id": "{{resources.ticketing.collections.id}}" } } ] } ``` In the example above, `loop_on` is set to `collections`, the `name` attribute of the Projects field in the RapidForm defined above, so a request is made for each selected project. Inside the loop, `collections` holds one selected option, and `{{collections.value}}` is that project's ID. --- # Getting Started > Source: https://truto.one/docs/guides/rapid-form/creating-rapid-form/ Setting up a RapidForm is straightforward and can be accomplished in a few simple steps. This guide will walk you through enabling RapidForm, defining the necessary fields, and setting up dynamic interactions—using an **Asana Integration** as an example. ## Enable RapidForm To begin using RapidForm, you need to enable it in your integration settings. 1. **Open Configuration on the installed integration**: Go to **Integrations → Installed**, select the integration, and open the **Configuration** tab. Its settings are editable in place. ![RapidForm on the Configuration tab](/images/rapid-form/asana_rapidform_settings.png) 2. **Enable RapidForm**: In the **RapidForm** section, turn on **Use RapidForm**. ![Enable RapidForm](/images/rapid-form/rapidform_enable.png) ## Create Fields in RapidForm With RapidForm enabled, you can start creating fields to gather information from users. In this example, we'll allow users to select a **Workspace** and its associated **Projects** to sync from **Asana**. ### Create a Field for Workspace **Purpose**: Let users select the Asana workspace they want to sync. **Steps**: 1. As soon as **Use RapidForm** is turned on, a new field is shown. Use this field to configure the Workspace 2. **Configure the Field**: - **Name**: Enter a unique identifier (e.g., `workspace_id`). - **Label**: Provide a user-friendly name (e.g., `Workspace`). - **Type**: Select **Single-Select**, as users can choose only one workspace. - **Help Text**: Add guidance (e.g., `Select the workspace you want to sync`). 3. **Set Data Source**: - **Request Type**: Choose **Unified API** or **Proxy API** based on your data fetching method. - **Resource**: Specify the endpoint to fetch data from (e.g., `ticketing/workspace` for Unified APIs). - **Method**: Select **list** to retrieve the list of workspaces. The supported methods include `list` and `get` 4. **Click Save** in the page header. Your Workspace field is now configured. ![RapidForm Asana Workspace](/images/rapid-form/asana-workspace-rapidform.png) --- ### Create a Field for Projects **Purpose**: Allow users to select multiple projects within the chosen workspace. **Steps**: 1. **Add Another Field**: Click **Add RapidForm field** to create a new form field. ![RapidForm Add Field](/images/rapid-form/add-rapidform-field.png) 2. **Configure the Field**: - **Name**: Enter a unique identifier (e.g., `projects`). - **Label**: Provide a user-friendly name (e.g., `Projects`). - **Type**: Select **Multi-Select**, as users can choose multiple projects. - **Help Text**: Add guidance (e.g., `Select the projects you want to sync`). 3. **Set Data Source**: - **Request Type**: Choose **Unified API** or **Proxy API**. - **Resource**: Specify the endpoint to fetch data from (e.g., `ticketing/project`). - **Method**: Select the appropriate method to retrieve projects. 4. **Add Query Parameters**: - Use the `workspace_id` from the previous field to fetch projects specific to the selected workspace. 5. **Set Field Dependency**: - **Depends On**: Specify that this field depends on `workspace_id`. - **Reset on Change**: Check the option to reset the field when `workspace_id` changes, ensuring the projects list updates accordingly. 6. **Click Save** in the page header. Your Projects field is now set up. ![RapidForm Asana Projects](/images/rapid-form/asana-projects-rapidform.png) ## How the configured RapidForm Appears to Users ### Dynamic Interaction Between Fields - **Initial State**: The Projects field remains empty until a workspace is selected. ![RapidForm - dependency between the fields](/images/rapid-form/rapid-form-1.png) ### After Selecting a Workspace - **Projects Populated**: Once a workspace is selected, the Projects field displays the first page of projects related to that workspace. - **Pagination Support**: Users can click "Load more" to fetch additional projects if there are more than can be displayed initially. ![RapidForm - pagination support](/images/rapid-form/rapid-form-2.png) ![RapidForm - after pagination](/images/rapid-form/rapid-form-3.png) ### Variables Captured - **Workspace ID and Projects**: The selected values are stored and can be accessed in the **Variables** section of the integrated account. - **Usage in Sync Job**: These variables (`workspace_id` and `projects`) can be used in your [Sync Job configuration](/docs/guides/rapid-bridge/overview) to customize the data synchronization process. ![RapidForm - variables](/images/rapid-form/asana_rapidform_integration.png) ## Next Steps By following these steps, you've created a user-friendly RapidForm that dynamically interacts with user input, enhancing the integration experience. If you need further assistance or want to explore more features, refer to the [Field Types](/docs/guides/rapid-form/field-types) for additional guidance. --- # Truto RapidBridge Overview > Source: https://truto.one/docs/guides/rapid-bridge/overview/ When developing integrations, it's common to pull data frequently from third-party APIs. This usually involves creating a scheduling system. **RapidBridge** simplifies this process. It manages the scheduling, retrieves data from the Unified and Proxy APIs, and forwards the results to a webhook endpoint in Truto, either on demand or based on a schedule. ## How it works ![Rapid Bridge](/images/misc/RapidBridge.png) Start by setting up a **Sync Job**. This is essentially your plan, specifying which data resources you aim to synchronize. Say you want to sync tickets, customers, and organizations from Zendesk; you lay out these specifications in the Sync Job. You can create and manage sync jobs from the dashboard under **Sync Jobs** in [app.truto.one](https://app.truto.one). See [Using the Sync Jobs UI](/docs/guides/sync-jobs/using-the-ui) for a walkthrough of the list, detail tabs, runs, schedules, and templates. Implementing this plan against an account is termed a **Sync Job Run**. To initiate a RapidBridge Sync Job Run, you'll need: - The Sync Job's ID - The target integrated account - The webhook endpoint's ID stored in Truto Here's the process in action: 1. Truto initiates with a `sync_job_run:started` message. 2. It begins to retrieve resources. For each fetched resource, it communicates with the API endpoint, sending the acquired data to the webhook, tagged as `sync_job_run:record`. 3. The webhook needs to respond with a 200 status code for Truto to proceed with the next resource or to continue the sync. After all data resources are synchronized, Truto sends a `sync_job_run:completed` notification. ## Webhook event sequence 1. **`sync_job_run:started`**: This event marks the initiation of the syncing process. Before any data is fetched, this event is triggered. The webhook endpoint should acknowledge receipt by responding with a 200 status code. If you want to run any validation and stop the sync process, you can respond with a 400 status code. 2. **`sync_job_run:record`**: This event is at the core of the data synchronization. Each time Truto fetches a resource, whether it's a single item or a batch, it sends the data to the webhook endpoint under this event label. To ensure smooth processing, the webhook endpoint should respond with a 200 status code. Once received, Truto proceeds to the next resource or batch. This process repeats until all designated resources are synchronized. 3. **`sync_job_run:record_error`**: Not all fetches are guaranteed to be smooth. In cases where an error arises during data retrieval, this event is sent to notify of the issue. The occurrence of this event largely depends on the `error_handling` setting. If set to its default value, `ignore`, this event is triggered. For Truto to continue with the sync or to move to the next resource, the webhook endpoint should send back a 200 status response. 4. **`sync_job_run:rate_limited`**: Sometimes, the rate of data requests may exceed the allowed limits of the underlying API. When this happens, Truto sends this event to indicate a rate limit scenario. The syncing process pauses temporarily during this period. Once the limitation period is over, Truto resumes the sync process, starting with the `sync_job_run:record` events. As with other events, the continuation relies on receiving a 200 status response from the webhook endpoint. 5. **`sync_job_run:completed`** or **`sync_job_run:failed`**: Every process has its end. Once all resources are fetched and synchronized (or if an unresolvable error occurs), one of these concluding events is sent. The `sync_job_run:completed` event indicates a successful synchronization. On the other hand, if a critical error halts the process, the `sync_job_run:failed` event is sent to signify an incomplete or unsuccessful sync. On runtime version 1, setting `error_handling` to `fail_fast` also ends the run with this event on the first error. --- # Creating a RapidBridge Sync Job > Source: https://truto.one/docs/guides/rapid-bridge/creating-rapid-bridge/ A RapidBridge Sync Job first needs a webhook endpoint to send data to. :::callout{type="info"} The Sync Job definitions in this guide use the resource format of sync job runtime versions 1 to 3. A Sync Job created through the API without `default_runtime_version` runs on version 3. ::: ## Creating a webhook Use the following request to create a webhook endpoint, ```bash curl --location 'https://api.truto.one/webhook' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "target_url": "https://webhook.site/6a7cc86e-9286-4be8-ba79-bcd8dfdbeee1", "is_active": true, "event_types": [ "sync_job_run:created", "sync_job_run:updated", "sync_job_run:started", "sync_job_run:completed", "sync_job_run:failed", "sync_job_run:deleted", "sync_job_run:record", "sync_job_run:record_error", "sync_job_run:rate_limited", "integrated_account:created", "integrated_account:active", "integrated_account:post_connect_form_submitted" ] }' ``` You can also follow our more detailed [guide into creating webhooks](/docs/guides/webhooks/creating-a-webhook-through-ui). ## Creating a Sync Job In this guide, we'll be syncing users, contacts, tickets and comments for each ticket from Zendesk using the [Unified API for Ticketing](/docs/api-reference/unified-ticketing-api). Use the following request to create a Sync Job, ```bash curl --location 'https://api.truto.one/sync-job' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "integration_name": "zendesk", "resources": [ { "resource": "ticketing/users", "method": "list" }, { "resource": "ticketing/contacts", "method": "list" }, { "resource": "ticketing/tickets", "method": "list" }, { "resource": "ticketing/comments", "method": "list", "depends_on": "ticketing/tickets", "query": { "ticket_id": "{{resources.ticketing.tickets.id}}" } } ] }' ``` In the request above, - `integration_name` is the identifier of the integration that the sync job is for. In this case Zendesk, so it's value is set to `zendesk`. - `resources` is the list of resources to fetch from Zendesk. Each item in the list has the following schema, - `resource` (required) is the name of the Unified API resource or the Proxy API resource. For Unified APIs, use the format `unified_api_name/resource_name` and for the Proxy APIs, just use `resource_name`. - `method` (required) can be `list` or `get` for Unified APIs. For Proxy APIs, it can be `list`, `get` or any other read-like custom method. - `depends_on` (optional) creates a dependency between this resource and some other resource in the `resources` list. In the example above, `ticketing/comments` resource needs a `ticket_id` query parameter to fetch the comments for, so we first fetch the list of `tickets` and then for each ticket, we fetch the `comments`. - `query` (optional) are the query parameters to be passed to each request. Placeholders can be used to populate the query parameters dynamically, like in the example above, `ticketing/comments` uses the `{{resources.ticketing.tickets.id}}` placeholder to refer to the `id` property of a Unified Ticket Resource and set it as the `ticket_id`. Refer the [placeholder reference](#placeholder-reference) section for more details on the placeholders that can be used. ## Running a Sync Job Now that we have created a Webhook and a Sync Job, we can execute the Sync Job, create a Sync Job Run. Make sure you have a Zendesk Integrated Account already created. Checkout our guide to connect an account. To create a Sync Job Run, execute the following request, ```bash curl --location 'https://api.truto.one/sync-job-run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "sync_job_id": "7279a917-b447-4629-9e46-a1eeb791ad6b", "integrated_account_id": "7ae7b0ab-c6a7-4f29-aec1-1f123517af5d", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c" }' ``` This should start executing the Sync Job and the Webhook endpoint should start receiving the events. In the request above, - `sync_job_id` is the `id` of the Sync Job we created in the previous step - `integrated_account_id` is the `id` of the Integrated Account connected to a Zendesk account - `webhook_id` is the `id` of the Webhook created in the first step. ## Error handling Truto by default ignores any errors that occur during a Sync Job Run and continues with the next resource, sending you `sync_job_run:record_error` webhook events for each error encountered. The `error_handling` attribute in the Sync Job Run request controls this. It accepts `ignore` (the default), `fail_fast`, and `batch`. - `fail_fast` makes the Sync Job Run fail as soon as an error occurs. It applies only to runtime version 1. On other runtime versions the run continues past errors, as with `ignore`. - `batch` holds back the `sync_job_run:record_error` events until the end of the run and then sends them together, up to 100 errors per event, with `error` and `meta` as arrays. It applies to runtime versions 2 and 3. On runtime version 1 it behaves like `ignore`. ```bash curl --location 'https://api.truto.one/sync-job-run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "sync_job_id": "7279a917-b447-4629-9e46-a1eeb791ad6b", "integrated_account_id": "7ae7b0ab-c6a7-4f29-aec1-1f123517af5d", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c", "error_handling": "fail_fast" }' ``` ## Incremental syncing of data By default, the Sync Job above will fetch all the objects for a resource in every Sync Job Run, i.e. all the tickets will be synced on every Sync Job Run. In most cases, an incremental way of syncing would be preferred, where only tickets that have changed from the time the previous Sync Job ran. To do this, `updated_at` query parameter of the `ticketing/tickets` Unified API resource can be used, bound to `previous_run_date`. The binding can be created like so, ```json { "resource": "ticketing/tickets", "method": "list", "query": { "updated_at": { "gt": "{{previous_run_date}}" } } } ``` `previous_run_date` is a special attribute tracked by Truto. It holds the start time of the latest Sync Job Run that completed successfully for the Sync Job and a particular Integrated Account. It's set to `'1970-01-01T00:00:00.000Z'` on the very first Sync Job Run. The previous Sync Job can be updated with the new resource binding. Send the full `resources` list, since it replaces the existing one, ```bash curl --location --request PATCH 'https://api.truto.one/sync-job/7279a917-b447-4629-9e46-a1eeb791ad6b' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "resources": [ { "resource": "ticketing/users", "method": "list" }, { "resource": "ticketing/contacts", "method": "list" }, { "resource": "ticketing/tickets", "method": "list", "query": { "updated_at": { "gt": "{{previous_run_date}}" } } }, { "resource": "ticketing/comments", "method": "list", "depends_on": "ticketing/tickets", "query": { "ticket_id": "{{resources.ticketing.tickets.id}}" } } ] }' ``` Now, everytime the Sync Job would execute, it will fetch only the tickets which have been changed from the last time a Sync Job Run ran. ### Doing a full sync on demand Sometimes you want to fully sync the data and just ignore the `previous_run_date`. It's possible to do it using `ignore_previous_run` attribute set to `true` in the Sync Job Run request. ```bash curl --location 'https://api.truto.one/sync-job-run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "sync_job_id": "7279a917-b447-4629-9e46-a1eeb791ad6b", "integrated_account_id": "7ae7b0ab-c6a7-4f29-aec1-1f123517af5d", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c", "ignore_previous_run": true }' ``` ## Running a Sync Job on schedule :::callout{type="tip"} The cron expression is in UTC timezone. Runs must be at least 5 minutes apart. ::: To run a Sync Job on a recurring schedule, a Sync Job Cron Trigger can be created. Use the following request to create one, ```bash curl --location 'https://api.truto.one/sync-job-cron-trigger' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "sync_job_id": "d7fd45d6-136a-4244-aeb9-b6439bfa8b71", "integrated_account_id": "6680c7ff-9f0e-45be-9915-a7334dc37f23", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c", "cron_expression": "0 */6 * * *" }' ``` The request schema is similar to Sync Job Run with an additional attribute - `cron_expression`. The Cron expression above will run the Sync Job every 6 hours. When the trigger is saved, Truto checks the gap between its next two runs. If the gap is under 5 minutes, as with `*/2 * * * *`, or the expression doesn't parse, the request is rejected with a `400` that says why, and no trigger is saved. ## Passing arguments to a Sync Job Arguments can be passed to a Sync Job Run to fetch data dynamically. Imagine if in the example above, we needed to fetch tickets incrementally based on the previous Sync Job Run date, but also based on a date of our choosing for the initial sync. To achieve this, first the schema of the arguments to be passed in the Sync Job Run needs to be added to the Sync Job. It's specified using `args_schema` attribute in the request body. ```json { "args_schema": { "ticket_sync_start_date": { "type": "string", "format": "date-time" } } } ``` Next, we use this argument in the `ticketing/tickets` resource like so, but instead of the normal variable binding, a JSONata expression is used for `query`. The [JSONata](https://docs.jsonata.org/overview) expression is like so, ```jsonata { 'updated_at': { 'gt': args.ticket_sync_start_date ? args.ticket_sync_start_date : previous_run_date } } ``` The expression above uses `ticket_sync_start_date` from the arguments if it's passed or falls back to `previous_run_date`. :::callout{type="info"} Update: We recently introduced conditional placeholders than can achieve the same result without the need for JSONata expressions. You'd still need JSONata expressions for more complex scenarios. ```json { "updated_at": "{{args.ticket_sync_start_date|previous_run_date}}" } ``` ::: The updated resource definition looks like so, ```json { "resource": "ticketing/tickets", "method": "list", "query": "{ 'updated_at': { 'gt': args.ticket_sync_start_date ? args.ticket_sync_start_date : previous_run_date } }" } ``` The final request to create a Sync Job with arguments, ```bash curl --location 'https://api.truto.one/sync-job' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "integration_name": "zendesk", "args_schema": { "ticket_sync_start_date": { "type": "string", "format": "date-time" } }, "resources": [ { "resource": "ticketing/users", "method": "list" }, { "resource": "ticketing/contacts", "method": "list" }, { "resource": "ticketing/tickets", "method": "list", "query": "{ '\''updated_at'\'': { '\''gt'\'': args.ticket_sync_start_date ? args.ticket_sync_start_date : previous_run_date } }" }, { "resource": "ticketing/comments", "method": "list", "depends_on": "ticketing/tickets", "query": { "ticket_id": "{{resources.ticketing.tickets.id}}" } } ] }' ``` To run a Sync Job with arguments, `args` attribute needs to be added to the request body, ```json { "args": { "ticket_sync_start_date": "2023-07-23T18:10:56.072Z" } } ``` The request would be, ```bash curl --location 'https://api.truto.one/sync-job-run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "args": { "ticket_sync_start_date": "2023-07-23T18:10:56.072Z" }, "sync_job_id": "7279a917-b447-4629-9e46-a1eeb791ad6b", "integrated_account_id": "7ae7b0ab-c6a7-4f29-aec1-1f123517af5d", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c" }' ``` ## Looping a request over an array Taking the arguments example forward, imagine a hypothetical scenario where we need to fetch a specific set of tickets based on a list of ticket ids. This can be achieved using the `loop_on` attribute in the Sync Job Run request. To create such a Sync Job, we first need to define the args_schema like so, ```json { "args_schema": { "ticket_ids": { "type": "array", "items": { "type": "string" } } } } ``` Then define the `ticketing/tickets` resource like so, ```json { "resource": "ticketing/tickets", "method": "get", "loop_on": "args.ticket_ids", "id": "{{args.ticket_ids}}" } ``` Here, the `loop_on` attribute specifies that for each element in the `ticket_ids` array, a request should be made. The `id` attribute specifies the placeholder to be used for the `id` of the ticket. Complete request to create a Sync Job with looping, ```bash curl --location 'https://api.truto.one/sync-job' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "integration_name": "zendesk", "args_schema": { "ticket_ids": { "type": "array", "items": { "type": "string" } } }, "resources": [ { "resource": "ticketing/tickets", "method": "get", "loop_on": "args.ticket_ids", "id": "{{args.ticket_ids}}" } ] }' ``` ## Recursively fetching data for the same resource There are cases where you might need to fetch data for the same resource, where the resources might have a parent-child relationship. For example, in drive-items for the Unified File Storage API, there could be drive items of the type `folder` which might have child drive items within them. To fetch such resources, you can use the `recurse` attribute in the Sync Job resource, ```json { "resource": "file-storage/drive-items", "method": "list", "recurse": { "if": "{{resources.file-storage.drive-items.has_children:bool}}", "config": { "query": { "parent": { "id": "{{resources.file-storage.drive-items.id}}" } } } } } ``` In the above example, we set the recurse condition in the `if` attribute. Most of the resources which follow this parent-child relation have an `has_children` attribute which is a boolean (you'll need to check the documentation to make sure). If the `has_children` attribute is true, then the `config` attribute will be used to fetch the child resources. The `query` attribute in the `config` specifies the query parameters to be passed to the request. The `parent.id` is set to the `id` of the parent resource. You can use placeholders to refer to the values of other fields. ## Transforming the data fetched by the resources Sometimes you might need to transform the data fetched by the resources before sending it to the webhook. This can be achieved using the `transform` notes in the Sync Job. Transform nodes accept a JSONata expression which should return the final result to be sent to the webhook. These nodes are always dependent on a resource node (using depends_on), so you can't have an independent transform node. Also, the resource node which the transform nodes depend on should have a `name` attribute and the transform node itself should have a `name` attribute. You can also have transform nodes dependent on another transform node, and resource nodes dependent on transform nodes. Some use cases where the transform nodes are especially helpful -- 1. Filtering out the data fetched by the resource -- When the underlying API doesn't support the filters you need, like updated_at, tags, etc., you can use the transform nodes to filter out the data. 2. Modifying the output of the resource without modifying the Unified mappings -- You might need to modify the output of the resource before sending it to the webhook, like adding a new field, modifying the existing fields, etc. This is the context object available for the JSONata expressions in the transform nodes, - `args` - The arguments passed to the Sync Job Run. - `resources.` - Contains the data fetched by the resource, keyed by its `resource` value split on `/`. For example, the data of `ticketing/contacts` is at `resources.ticketing.contacts`. - `previous_run_date` - Refers to the start time of the latest Sync Job Run that completed successfully for the Sync Job and an Integrated Account. It's set to '1970-01-01T00:00:00.000Z' on the very first Sync Job Run. - `resource` - Refers to the parent resource's attributes defined in the Sync Job with placeholders resolved. - `` - Refers to the context variables set in the Integrated Account. Taking the example from Zendesk, this Sync Job ignores the contacts NOT updated from the last time the sync job ran, ```json { "integration_name": "zendesk", "args_schema": {}, "resources": [ { // needs a name "name": "all-contacts", "resource": "ticketing/contacts", "method": "list", "persist": false }, { // needs a name "name": "filtered-contacts", "type": "transform", "config": { "expression": "resources.ticketing.contacts[updated_at >= %.%.%.previous_run_date]" }, // refer to the name "depends_on": "all-contacts", "persist": true } ] } ``` To make sure that you only get the filtered contacts on the webhook in the example above, `persist` has been set to `true` for the transform node and `false` for all the contacts. Transform nodes need to have the `persist` attribute set to `true` if you need their output to be sent to the webhook. By default, it's set to `false`. :::callout{type="tip"} If the resource name contains special characters apart from underscore `_`, like `-`, then in JSONata you need to refer to them using backticks. For example, if the resource name is `knowledge-base/page-content`, then you need to refer to it as ``` resources.`knowledge-base`.`page-content` ``` in JSONata. ::: ## Spooling data into a single webhook event Spool nodes allow you to paginate and fetch the complete resource and then send it in a single webhook event. One of the places where this is useful is in the Knowledge Base APIs where the page content might be split into multiple blocks and is provided through a paginated API. You can use the `spool` nodes to fetch all the blocks and then send them in a single webhook event. You can also have `transform` nodes dependent on `spool` nodes, which can transform the data fetched by the `spool` nodes. As with `transform` nodes, `spool` nodes can't be independent and should be dependent on a resource node. The resource node which the `spool` nodes depend on should have a `name` attribute and the `spool` node itself should have a `name` attribute. You can't have a `spool` node dependent on another `spool` node. Taking the example of a Notion integration, where we need the content of a Notion page as a markdown, ```json { "integration_name": "notion", "args_schema": { "page_id": { "type": "string", "required": true } }, "resources": [ { "name": "page-content", "resource": "knowledge-base/page-content", "method": "list", "query": { "page": { "id": "{{args.page_id}}" }, "truto_ignore_remote_data": true }, "recurse": { "if": "{{resources.knowledge-base.page-content.has_children:bool}}", "config": { "query": { "page_content_id": "{{resources.knowledge-base.page-content.id}}" } } }, "persist": false }, { "name": "remove-remote-data", "type": "transform", "config": { "expression": "[resources.`knowledge-base`.`page-content`.$sift(function($v, $k) {$k != 'remote_data'})]" }, "depends_on": "page-content" }, { "name": "all-page-content", "type": "spool", "depends_on": "remove-remote-data" }, { "name": "combine-page-content", "type": "transform", "config": { "expression": "$blob($reduce($sortNodes(resources.`knowledge-base`.`page-content`, 'id', 'parent.id'), function($acc, $v) { $acc & $v.body.content }, ''), { \"type\": \"text/markdown\" })" }, "depends_on": "all-page-content", "persist": true } ] } ``` In the example above, 1. We first fetch the page-content blocks for the page provided in the argument. 2. It then goes through the `remove-remote-data` transform node to remove the `remote_data` attribute from the fetched blocks. 3. The `all-page-content` spool node fetches all the blocks of the page content. 4. Then the `recurse` logic kicks in and fetches the child blocks for each block if any. 5. Finally, the `combine-page-content` transform node combines all the blocks fetched by the `all-page-content` spool node and sends it as a single webhook event. The data is converted into a Blob with the type `text/markdown`. In `spool` nodes, the data is stored temporarily on Truto's servers. Once the sync job run completes/fails, the data is deleted. #### Limitations The amount of data you can store in spool nodes is limited to 128KB, so make sure that the data you are fetching in each page falls within that limit. That is the reason why in the example above, we have a `remove-remote-data` transform node to remove the `remote_data` attribute from the fetched blocks, as it might contain a lot of data. ## Running Sync Job after an Integrated Account is connected To run a Sync Job after an Integrated Account is connected, listen to the `integrated_account:active` event. This event is sent when an Integrated Account is created and is ready to be used. If you have a RapidForm configured for the integration, then you'll need to listen to the `integrated_account:post_connect_form_submitted` event. An example webhook event for both is shown below, ```json { "id": "bed2145c-46d7-41fa-ad69-3e70cb5bb74d", "event": "integrated_account:active", "payload": { "id": "937fed13-712d-4647-dfe3-7613948b0348", "tenant_id": "acme-1", "environment_integration_id": "f7d82f6d-20f0-4bed-231c-d9c31e023710", // more data }, "environment_id": "ac15abdc-b38e-47d0-97a2-6f494017c177", "created_at": "2023-08-31T18:08:27.879Z", "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c" } ``` The Sync Job Run can be scheduled or executed immediately after receiving the webhook event by using the `payload.id` attribute as the `integrated_account_id` in the Sync Job Run request. ```bash curl --location 'https://api.truto.one/sync-job-run' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "sync_job_id": "7279a917-b447-4629-9e46-a1eeb791ad6b", "integrated_account_id": "937fed13-712d-4647-dfe3-7613948b0348", # from the webhook event "webhook_id": "a5b21886-3b4d-4fd0-9956-ffc0714d701c" }' ``` ## Placeholder Reference Placeholders can be used in the Sync Job `resources` to refer to the values of other fields in the Sync Job. The placeholders are enclosed in double curly braces {{}}. The placeholders available are, - {{args.<arg_name>}} - Refers to the value of the argument passed to the Sync Job Run. - {{resources.<resource_path>.<field_name>}} - Refers to the value of a field in a resource fetched in the Sync Job. The `resource_path` is the parent's `resource` value split on `/`, like {{resources.ticketing.tickets.id}} for `ticketing/tickets`. The `field_name` can be any field in the resource. This is only available when the resource is dependent on another resource using the `depends_on` attribute. - {{previous_run_date}} - Refers to the start time of the latest Sync Job Run that completed successfully for the Sync Job and an Integrated Account. It's set to `'1970-01-01T00:00:00.000Z'` on the very first Sync Job Run. - {{truto_parent_resource.<attribute>}} - If using `depends_on`, then the parent resource's attributes can be accessed using this placeholder. For example, you could use the queries used in the parent resource by using {{truto_parent_resource.query.<query_name>}}. This can be useful for [recurse](#recursively-fetching-data-for-the-same-resource) use cases. - {{truto_parent_resource.query.<parameter_name>}} - {{truto_parent_resource.method}} - {{truto_parent_resource.resource}} - {{truto_parent_resource.id}} - {{truto_parent_resource.body.<attribute_name>}} - {{<integrated_account_context_variable>}} - Refers to the value of a [context variable](/docs/guides/integrated-accounts/adding-editing-context-variables) set in the Integrated Account. For example, if you have a variable with name `foo` in the integrated account, you can refer to it using {{foo}}. ## Sync Job API Reference Refer [Sync Job API Reference](/docs/api-reference/admin/sync-jobs/list) for more details about the requests. --- # Overview > Source: https://truto.one/docs/guides/tenants/overview/ A tenant represents one of your end-users (or customers, or workspaces — whichever unit you connect integrations for) inside Truto. Every integrated account is owned by a tenant, and everything you send to third-party APIs through Truto is billed, logged, and rate-limited under the tenant that owns the account. ## What is a Tenant? A tenant is a lightweight, environment-scoped object that groups all the integrated accounts belonging to one of your end-users. You choose the ID — a string like `acme-corp`, `usr_1a2b3c`, or the UUID your own database uses — and Truto keeps that same ID with the tenant across every integration your user connects. One tenant can own many integrated accounts: your customer "Acme Corp" might connect HubSpot, Salesforce, and Slack, and each of those becomes an integrated account under the same tenant. Filtering `GET /integrated-account?tenant_id=acme-corp` returns all three. ## Tenants and Environments Tenants are scoped to an environment. The same `tenant_id` value can exist in `development`, `staging`, and `production` independently — three separate tenant rows with three separate sets of connected accounts. That's the same isolation model as [Environments](/docs/guides/environments/overview): what's in one environment isn't in the others. Because of that scope, the composite primary key of a tenant is `(id, environment_id)`. The dashboard handles environment scoping automatically; API tokens are bound to a single environment, so you don't need to pass `environment_id` manually in API calls. ## Tenant IDs You pick the ID. Truto accepts any string up to 255 characters, except control characters (newlines included), leading or trailing whitespace, and the IDs `.` and `..`. Slashes, spaces and other separators are allowed. When you put an ID in a URL path such as `/tenant/:id`, URL-encode it — `org/4567` becomes `/tenant/org%2F4567`. Common choices: - The primary key from your own users/organizations table (`user_1a2b3c`, `org-4567`). - A slug your customer will recognize (`acme-corp`). - The email domain, when you have one workspace per company (`acme.com`). Whatever you pick, treat it as immutable: it's referenced by every integrated account owned by that tenant, every link token created against it, every log line, and every webhook payload. ## Where Tenants come from There are three ways a tenant appears in Truto: - **You create it explicitly** — via the dashboard, the API (`POST /tenant`), the CLI (`truto tenants create`), or in bulk (`POST /tenant/bulk`). This is the recommended path when you're onboarding a new customer. - **Truto auto-creates it during a connection** — when an integrated account is created with a `tenant_id` that doesn't exist yet, and the ID matches the allowed pattern, Truto materializes the tenant row for you. Creating a link token alone does not create the tenant — your customer's first successful connection does. - **You bulk-import a batch** — from CSV or JSON. Useful when moving from another system or seeding staging with a known set of customers. See [Bulk import](/docs/guides/tenants/bulk-import). Explicitly creating tenants first gives you a place to attach metadata (tier, region, billing plan) before the customer connects anything. If you don't need that, letting Truto auto-create them is fine. ## Metadata Tenants carry a free-form JSON `metadata` field. Truto stores it as-is; nothing in it changes platform behaviour. Use it for anything your team wants alongside the tenant record: ```json { "tier": "gold", "region": "wnam", "signed_up_at": "2026-06-01", "billing_email": "billing@acme.com" } ``` Metadata is returned on every `GET /tenant` / `GET /tenant/:id`. ## Managing tenants - **Dashboard** — [Tenants](https://app.truto.one/tenants) — table view with per-tenant account counts, edit, delete, bulk import, and per-tenant detail with bulk-delete of connected accounts. - **API** — `POST /tenant`, `GET /tenant`, `GET /tenant/:id`, `PATCH /tenant/:id`, `DELETE /tenant/:id`, and `POST /tenant/bulk`. See [Creating tenants](/docs/guides/tenants/creating-tenants) and [Deleting tenants](/docs/guides/tenants/deleting-tenants). - **CLI** — [`truto tenants ...`](/docs/cli/admin-resources#tenants), including `truto tenants create-bulk` for batch imports. ## FAQ **Can the same `tenant_id` appear in multiple environments?** Yes. `acme-corp` in `development`, `staging`, and `production` are three separate tenants with three separate sets of accounts — that's the environment isolation model. **Do I have to create the tenant before my customer connects an account?** No. If you call `POST /link-token` (or create an integrated account directly) with a `tenant_id` that doesn't exist, Truto creates the tenant when the integrated account is created — as long as the ID matches the allowed pattern. Minting the link token alone does not materialize the tenant. Pre-creating gives you a place to attach metadata; auto-create is fine when you don't need that. **What if my legacy tenant IDs have characters like `/` in them?** They work. Slashes, spaces and other separators are valid in tenant IDs, and auto-create materializes a tenant for them; URL-encode the ID when you call `/tenant/:id`. Auto-create only skips IDs that can't be valid tenant IDs — longer than 255 characters, containing control characters, with leading or trailing whitespace, or exactly `.` or `..`. Those still work as strings on integrated accounts, but Truto won't materialize a tenant row for them. Migrate to a compatible ID (or create the tenant explicitly with a compatible ID and re-point the account) to get first-class tenant management. **Can I rename a tenant's ID?** No — the ID is the primary key. You can change the display `name` and `metadata` on `PATCH /tenant/:id`, but the ID is immutable. If you need a different ID, create a new tenant and migrate integrated accounts to it before deleting the old one. **Can I delete a tenant with connected accounts?** No — the API returns `409 Conflict`. Delete the accounts first (or `POST /integrated-account/bulk-delete` with `tenant_id`), then delete the tenant. See [Deleting tenants](/docs/guides/tenants/deleting-tenants). --- # Deleting tenants > Source: https://truto.one/docs/guides/tenants/deleting-tenants/ Deleting a tenant is permanent — the row is gone and can't be restored. Truto enforces one important guard: **a tenant with any connected integrated accounts can't be deleted.** Delete (or bulk-delete) its accounts first, then delete the tenant. ## The delete guard `DELETE /tenant/:id` returns `409 Conflict` with the message *"Can't delete tenant with connected accounts."* if any integrated account still references this tenant in this environment. This is a hard rule enforced by the API — the same guard runs whether you're calling from the dashboard, API, or CLI. The reason: integrated accounts and their credentials are the primary reason the tenant exists. Removing the tenant would orphan them (or, worse, silently break downstream sync jobs and webhooks that expect the tenant reference). Truto makes you deal with the accounts explicitly. ## From the dashboard 1. Open [Tenants](https://app.truto.one/tenants). 2. Click into the tenant you want to delete. The detail page lists every integrated account owned by this tenant. 3. If the tenant has connected accounts: - Select accounts individually with the checkbox column, or click the header checkbox to select all. - Click **Delete N selected accounts**, confirm in the modal. 4. Once no accounts remain, click the **⋮** menu on the tenant row (in the list) and choose **Delete**. Confirm in the modal. The tenant is gone from the list. This is an irreversible operation. ## From the API Delete a tenant that has no accounts: ```bash curl --location --request DELETE 'https://api.truto.one/tenant/acme-corp' \ --header 'Authorization: Bearer ' ``` Response (`200 OK`): ```json { "id": "acme-corp", "environment_id": "…", "name": "Acme Corp", "metadata": {…}, "created_at": "…", "updated_at": "…" } ``` If the tenant still has accounts (`409 Conflict`): ```json { "statusCode": 409, "error": "Conflict", "message": "Can't delete tenant with connected accounts." } ``` ## Bulk-deleting accounts first If the tenant has many accounts, delete them with `POST /integrated-account/bulk-delete` (capped at 1000 accounts per request — repeat until `matched_count < 1000`): ```bash curl --location 'https://api.truto.one/integrated-account/bulk-delete' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "tenant_id": "acme-corp" }' ``` Response: ```json { "deleted_count": 3, "matched_count": 3, "deleted_integrated_account_ids": ["79a39d69-e27e-49cb-b9a9-79f5eea7aa26", "…", "…"], "matched_integrated_account_ids": ["79a39d69-e27e-49cb-b9a9-79f5eea7aa26", "…", "…"] } ``` Or delete a subset by account UUIDs (max 99 per request due to D1's parameter limit): ```json { "ids": ["79a39d69-e27e-49cb-b9a9-79f5eea7aa26", "0c74a4ad-7b8e-4f3a-9c1d-2e4f5a6b7c8d"] } ``` Exactly one of `tenant_id` or `ids` must be supplied. The `tenant_id` branch is capped at **1000 accounts per request**; if the tenant has more, repeat the call until `matched_count` is less than 1000. Once all accounts are gone, `DELETE /tenant/:id` succeeds. ## From the CLI ```bash # List the accounts first truto accounts list --tenant-id acme-corp # Delete them via bulk-delete (curl; no CLI subcommand yet), then delete the tenant # curl -X POST https://api.truto.one/integrated-account/bulk-delete \ # -H 'Authorization: Bearer ' -H 'Content-Type: application/json' \ # -d '{"tenant_id":"acme-corp"}' truto tenants delete acme-corp ``` See [Admin resources — Tenants](/docs/cli/admin-resources#tenants). ## Recovery There is no undelete. If you delete a tenant and need it back, re-create it with the same `id`; you'll get a fresh row (new `created_at`, no metadata). Integrated accounts that referenced it are already gone — they don't come back with the tenant. --- # Bulk import > Source: https://truto.one/docs/guides/tenants/bulk-import/ When you're migrating from another platform, seeding staging with a known list of customers, or onboarding a batch of new tenants at once, use the bulk-import endpoint. It accepts up to 1000 tenants in a single request and reports per-row status. ## From the dashboard 1. Open [Tenants](https://app.truto.one/tenants) and click **Bulk import** in the top-right. ![Tenants list with Bulk import](/images/tenants/bulk-import.png) 2. Choose the format — **CSV** or **JSON**. 3. Choose the mode: - **Insert** (default) — create new tenants; existing ids are skipped. - **Upsert** — create new tenants and update `name` / `metadata` when the id already exists. 4. Either **click the upload area** (or drag-and-drop) a `.csv` / `.json` file (up to 5 MB), **or paste** the content directly into the editor below. 5. If you're using CSV, click **Download CSV template** for the expected header row. 6. Fix any validation errors (shown as a toast). **Import** stays disabled until the content is valid. 7. Click **Import** / **Upsert**. A toast reports how many tenants were created, updated, or skipped. ![Bulk import tenants modal](/images/tenants/bulk-import-modal.png) ### Allowed fields Each row may only include: | Field | Required | Rules | | --- | --- | --- | | `id` | Yes | 1–255 characters; no control characters, no leading or trailing whitespace, not `.` or `..`. Unique within the file. | | `name` | No | Non-empty string, max 255 characters. Defaults to `id` on insert when omitted. | | `metadata` | No | JSON **object** (not an array or primitive). Blank keys are rejected. | Unknown columns (CSV) or unknown keys (JSON) are rejected. CSV data rows may not have more values than the header defines. ### CSV format Headers required: `id`. Optional: `name`, `metadata`. Wrap `metadata` in double quotes — the JSON is what's stored: ```csv id,name,metadata acme-corp,Acme Corp,"{""tier"":""gold"",""region"":""wnam""}" globex-inc,Globex Inc,"{""tier"":""silver""}" initech,Initech, ``` ### JSON format A top-level array of tenant objects: ```json [ { "id": "acme-corp", "name": "Acme Corp", "metadata": { "tier": "gold" } }, { "id": "globex-inc", "name": "Globex Inc" }, { "id": "initech" } ] ``` ## From the API ```bash curl --location 'https://api.truto.one/tenant/bulk' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "mode": "insert", "tenants": [ { "id": "acme-corp", "name": "Acme Corp", "metadata": {"tier":"gold"} }, { "id": "globex-inc", "name": "Globex Inc" }, { "id": "initech" } ] }' ``` `mode` is optional and defaults to `insert`. Set `"mode": "upsert"` to update existing rows. ### Insert response ```json { "created": [ { "id": "acme-corp", "environment_id": "…", "name": "Acme Corp", "metadata": { "tier": "gold" }, "created_at": "…", "updated_at": "…" } ], "updated": [], "skipped": [ { "id": "globex-inc", "reason": "already_exists" } ] } ``` Rows in `skipped` collided on `(id, environment_id)`. Insert uses `INSERT ... ON CONFLICT DO NOTHING`, so the request never fails partway through. ### Upsert response ```json { "created": [{ "id": "initech", "name": "initech", "metadata": {}, "…": "…" }], "updated": [{ "id": "acme-corp", "name": "Acme Corp", "metadata": { "tier": "gold" }, "…": "…" }], "skipped": [] } ``` On upsert, omitted `name` / `metadata` keep the existing row's values. Newly created rows still default `name` to `id` and `metadata` to `{}` when omitted. **Caps:** at most 1000 tenants per request. Split larger inputs client-side and call `POST /tenant/bulk` multiple times. ## From the CLI ```bash # Insert (default) — skips existing ids truto tenants create-bulk -b '[{"id":"acme"},{"id":"globex"}]' # Upsert — updates name/metadata on existing ids truto tenants create-bulk --mode upsert -b '[{"id":"acme","name":"Acme Corp"}]' # From an NDJSON file (one JSON object per line) cat tenants.ndjson | truto tenants create-bulk --stdin # From a JSON array file truto tenants create-bulk -b "$(cat tenants.json)" ``` The CLI enforces the 1000-row cap client-side so you catch it before hitting the network. See [`truto tenants`](/docs/cli/admin-resources#tenants). ## Idempotency and re-runs **Insert:** re-running the same import is safe — existing ids come back in `skipped`, and only new ids appear in `created`. Useful as a "sync my customer list" cron that only adds missing tenants. **Upsert:** re-running applies the latest `name` / `metadata` from the file to matching ids and creates any missing ones. --- # Creating tenants > Source: https://truto.one/docs/guides/tenants/creating-tenants/ You can create tenants explicitly (recommended when you want metadata in place before the customer connects), or let Truto auto-create them on first connection. This page covers the explicit paths. ## From the dashboard 1. Sign in to your Truto account. 2. Navigate to **Tenants** from the sidebar, or open [`https://app.truto.one/tenants`](https://app.truto.one/tenants) directly. ![Tenants list](/images/tenants/tenants-list.png) 3. Click **Add Tenant** in the top-right. 4. Fill in the fields: - **Tenant ID** (required) — your identifier for this customer. Any string up to 255 characters, without control characters or leading/trailing whitespace, and not `.` or `..`. Immutable once set. - **Name** (optional) — a display name. Defaults to the ID if left blank. - **Metadata** (optional) — free-form JSON. Everything you'd want to see alongside the tenant record. ![Add tenant form](/images/tenants/add-tenant.png) 5. Click **Create**. The new tenant appears in the list. Click into it to see (or bulk-delete) all integrated accounts owned by that tenant. ## From the API Truto uses Bearer authentication — replace `` with an API token from your target environment. ```bash curl --location 'https://api.truto.one/tenant' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "id": "acme-corp", "name": "Acme Corp", "metadata": { "tier": "gold", "region": "wnam" } }' ``` Response (`201 Created`): ```json { "id": "acme-corp", "environment_id": "…", "name": "Acme Corp", "metadata": { "tier": "gold", "region": "wnam" }, "created_at": "2026-07-02T09:14:03.117Z", "updated_at": "2026-07-02T09:14:03.117Z" } ``` ### Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | Your identifier for the tenant. 1–255 characters; no control characters, no leading or trailing whitespace, not `.` or `..`. URL-encode it in `/tenant/:id` paths. Immutable. | | `name` | string | No | Display name. Defaults to `id`. | | `metadata` | object | No | Free-form JSON. Stored and returned verbatim. | `id` is unique within an environment. Attempting to create the same ID twice in the same environment returns `409 Conflict`. ## From the CLI ```bash truto tenants create -b '{"id":"acme-corp","name":"Acme Corp","metadata":{"tier":"gold"}}' truto tenants list truto tenants get acme-corp ``` See [Admin resources — Tenants](/docs/cli/admin-resources#tenants) for the full command surface, filters, and bulk create. ## Letting Truto auto-create If you skip the explicit create and just connect an account — via `POST /link-token` followed by a successful connection, or a direct `POST /integrated-account` — with a new `tenant_id`, Truto materializes the tenant row when the integrated account is created (not when the link token is minted), provided the ID matches the allowed pattern. The auto-created tenant has: - `id` = the value you passed - `name` = the same value - `metadata` = `{}` You can `PATCH` it later to add metadata or change the display name. Auto-create keeps the "no setup for the customer" flow but denies you a place to attach billing/tier fields ahead of time — pick based on what your onboarding needs. ## Updating a tenant Only `name` and `metadata` are updatable. The `id` is the primary key and can't be renamed. ```bash curl --location 'https://api.truto.one/tenant/acme-corp' \ --request PATCH \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "metadata": { "tier": "platinum" } }' ``` `metadata` on `PATCH` replaces the whole object; merge on the client side if you want partial updates. ## Next steps - [Bulk import](/docs/guides/tenants/bulk-import) — CSV / JSON / file upload for hundreds or thousands of tenants at once. - [Deleting tenants](/docs/guides/tenants/deleting-tenants) — including the delete guard that refuses tenants with connected accounts. - [Integrated Accounts](/docs/guides/integrated-accounts/connecting-an-account) — once a tenant exists, connect their first account. --- # Overview > Source: https://truto.one/docs/guides/daemon/overview/ --- # Using Daemon > Source: https://truto.one/docs/guides/daemon/using-daemon/ --- # Using the Sync Jobs UI > Source: https://truto.one/docs/guides/sync-jobs/using-the-ui/ Manage sync jobs from [app.truto.one](https://app.truto.one). Sign in, then choose **Sync Jobs** in the sidebar. This guide walks through each screen in the dashboard. For what sync jobs, runs, schedules, and templates mean, see the [Sync Jobs overview](/docs/guides/sync-jobs/overview). ## List jobs The **Jobs** tab lists every sync job in the selected environment. ![Sync Jobs list](/images/sync-jobs/list.png) 1. **Sync Jobs** in the sidebar opens this page. 2. **Jobs** and **Templates** switch between your job list and reusable blueprints. 3. **Create job** opens the form for a new sync job. 4. Search filters jobs by label, integration, or ID. 5. The environment selector limits the list to one environment. 6. Each row shows **Label**, **Integration**, **Version**, and **Updated**. Click the label to open the job. 7. The row menu offers **Edit**, **Trigger run**, and **Delete**. ## Open a job Click a job's label to open its detail page. ![Sync Job detail Overview](/images/sync-jobs/detail-overview.png) 1. **« Sync jobs** returns to the list. 2. The job **Label** and runtime version tag appear at the top. 3. **Trigger run** starts a new sync job run. 4. The menu next to **Trigger run** offers **Run with last args**, **View runs**, **Edit**, and **Delete**. 5. The job ID and integration name are shown below the title. 6. **Overview**, **Runs**, **Schedules**, **Run State**, and **Settings** switch between detail tabs. ## Overview The **Overview** tab is a read-only summary of the job definition. ![Sync Job detail Overview](/images/sync-jobs/detail-overview.png) 1. **Label**, **Integration**, **Runtime version**, and **Delay between requests (ms)** describe the job at a glance. 2. **Mutex key** and **State key** control concurrency and incremental sync state. 3. **Created** and **Updated** show when the job last changed. 4. **Resources** shows the pipeline definition (read-only JSON). 5. **Arguments schema** and **Arguments validation** appear when the job accepts runtime arguments. ## Runs The **Runs** tab lists every sync job run for this job. ![Sync Job detail Runs](/images/sync-jobs/detail-runs.png) 1. Filter by run ID, **Status**, or date range. 2. Each row shows **Run ID**, **Status**, **Started**, **Duration**, and **Records**. 3. Click a run ID to open the run detail page. 4. The row menu offers **View logs**, and **Stop** on active runs. 5. **Load more** fetches additional runs when the list is paginated. To start a run from the job header, click **Trigger run**. The modal title is **Trigger run ·** followed by the job label. Fill in the integrated account, destination, and any arguments required by the job, then confirm with **Trigger run**. ## Schedules The **Schedules** tab lists cron triggers that run this job automatically. ![Sync Job detail Schedules](/images/sync-jobs/detail-schedules.png) 1. The header notes that schedules use a UTC cron expression. 2. **Add schedule** opens the schedule form. 3. Each row shows **Cron expression** (with a UTC label), **Target** (integrated account and destination), and **Updated**. 4. The row menu offers **Edit** and **Delete**. 5. When no schedules exist, **Add schedule** is also shown in the empty state. Schedules run in UTC with a minimum five-minute interval. ## Settings The **Settings** tab is where you edit or delete a job. ![Sync Job detail Settings](/images/sync-jobs/detail-settings.png) 1. **Label** — a name to identify this sync job. 2. **Runtime version** — the runtime that powers this job. Version 4 is recommended for new jobs. 3. **Integration name** — the integration this job is associated with, if any. 4. **Resources** — the pipeline definition as JSON. 5. **Arguments schema** and **Arguments validation** — optional runtime arguments and validation rules. 6. **Mutex key** and **State key** — optional keys for concurrency and persistent state. 7. **Delay between requests (ms)** — optional throttle between API calls. 8. **Save changes** applies your edits. 9. **Delete sync job** permanently removes the job and its run history. ## Run detail Click a run ID on the **Runs** tab to inspect a single sync job run. ![Sync Job run detail](/images/sync-jobs/run-detail.png) 1. **« Runs** returns to the run list for this job. 2. The run **Status** tag reflects the current state (for example **Running**, **Completed**, or **Failed**). 3. **View logs** opens the log viewer for this run. 4. **Stop run** appears while the run is still active. 5. **Sync job** links back to the parent job. 6. **Runtime version**, **Error handling**, and destination fields (such as **Integrated account**, **Webhook**, or **Datastore**) show how this run was configured. 7. **Started**, **Finished**, **Duration**, and **Created** summarize timing. 8. **Records processed** breaks down persisted record counts per resource. 9. **Arguments** shows the JSON args passed when the run was triggered. ## Templates Switch to the **Templates** tab to browse reusable sync job blueprints. ![Sync Job Templates](/images/sync-jobs/templates.png) 1. **Create template** opens the template form. 2. Search filters templates by label, integration, description, or ID. 3. Each row shows **Label**, **Integration**, **Version**, **Description**, and **Owner** (**You** or **Shared**). 4. The row menu offers **Create job from template** for every template. **Edit** and **Delete** appear on templates you own. 5. **Create job from template** opens the job form pre-filled from the template so you can save it as a new sync job in your environment. --- # Sync Jobs overview > Source: https://truto.one/docs/guides/sync-jobs/overview/ A **sync job** is a reusable pipeline that pulls data from connected accounts and writes it to destinations such as webhooks, datastores, or SuperQuery tables. You define the job once in your environment, then run it many times — each execution is a **sync job run**. In [app.truto.one](https://app.truto.one), open **Sync Jobs** from the sidebar. The page has two tabs — **Jobs** and **Templates** — plus detail views for individual jobs, their runs, and their schedules. For a screen-by-screen walkthrough, see [Using the Sync Jobs UI](/docs/guides/sync-jobs/using-the-ui). To stream records to a webhook on a schedule, see the [RapidBridge overview](/docs/guides/rapid-bridge/overview). ## Sync Jobs A sync job holds the pipeline definition: which resources to fetch, how to transform them, and where to send the results. Each job has a **Label**, an optional **Integration**, a **Runtime version** (version 4 is recommended for new jobs), and a **Resources** JSON definition. From the **Jobs** tab you can search jobs, filter by environment, create a job, or open one to view its details. ![Sync Jobs list](/images/sync-jobs/list.png) ## Sync Job Runs A **sync job run** is one execution of a sync job for a specific integrated account (and optional runtime arguments such as a webhook or datastore). Runs move through statuses such as **Created**, **Running**, **Rate limited**, **Completed**, **Failed**, and **Stopped**. Trigger a run from a job's detail page with **Trigger run**, or let a schedule create runs automatically. Open the **Runs** tab on a job to filter by status or date, inspect duration and record counts, and drill into a single run. On runtime versions 3 and 4, a run ends **Failed** as soon as it starts when every one of its integrated accounts that still exists needs reauthentication (status `needs_reauth`). On version 4, those are the accounts in the run's arguments whose `args_schema` format is `integrated_account_id`. The run fetches nothing and leaves the job's incremental state where it was, so no data is skipped later. The `sync_job_run:failed` event carries a 401 error with `truto_error_code: integrated_account_needs_reauth`. Schedules keep running, and each scheduled run fails this way and sends its own `sync_job_run:failed` event until the account is [reauthorized](/docs/guides/integrated-accounts/reauthorizing-connections). The first run after that syncs again. Updating an account's credentials with `PATCH /integrated-account/{id}/credentials` does not change its status. Reauthorize the account, or set its `status` back to `active` with `PATCH /integrated-account/{id}`. ![Sync Job detail Runs](/images/sync-jobs/detail-runs.png) ## Schedules **Schedules** attach a UTC cron expression to a sync job so it runs automatically for a chosen integrated account and destination. From the **Schedules** tab on a job, click **Add schedule** to set the cron expression, target account, and default arguments. Schedules run in UTC with a minimum five-minute interval. ![Sync Job detail Schedules](/images/sync-jobs/detail-schedules.png) ## Templates **Templates** are reusable sync job blueprints. Use them to share a pipeline across environments or to scaffold a new job without copying JSON by hand. The **Templates** tab lists each template's label, integration, version, description, and owner (**You** for templates you created, **Shared** for templates shared with you). Create a template with **Create template**, or open the row menu and choose **Create job from template** to start a new job from an existing blueprint. ![Sync Job Templates](/images/sync-jobs/templates.png) ## Job detail views Click a job's label on the **Jobs** tab to open its detail page. Tabs along the top let you switch between: - **Overview** — read-only summary of label, integration, runtime version, mutex and state keys, and the resources definition. - **Runs** — execution history for this job. - **Schedules** — cron triggers for this job. - **Run State** — inspect and reset the incremental sync state this job keeps, when the job has a state key. - **Settings** — edit the job definition or delete the job. ![Sync Job detail Overview](/images/sync-jobs/detail-overview.png) ![Sync Job detail Settings](/images/sync-jobs/detail-settings.png) Click a run ID on the **Runs** tab to open the run detail page. There you can see status, timing, error handling, destination arguments, records processed per resource, and the arguments passed for that run. Active runs can be stopped with **Stop run**. ![Sync Job run detail](/images/sync-jobs/run-detail.png) --- # Why Truto > Source: https://truto.one/docs/guides/how-truto-works/what-makes-us-different/ Truto is a Unified-API platform with four opinions that put it on the opposite side of the line from most of the category. ## Pass-through, not a cache (by default) By default, every Unified API call is a live call to the vendor. Truto doesn't run a background sync to mirror your customer's data into our database, doesn't return data from a Truto-side copy, and doesn't pretend to know more about the vendor than the vendor does. The trade-off is honest: you share the vendor's rate limit, and your latency tracks the vendor's. In return you don't reconcile a stale mirror, and there's no Truto-shaped data residency surface to argue about with your customer. When you do want the cached experience that Merge, Finch, and other sync-first providers ship by default, the same Unified APIs are also available against a synced store — pick whichever side of the cache you want to own: - [**RapidBridge**](/docs/guides/rapid-bridge/overview) — schedule a sync job that pulls Unified API resources on your cadence and streams every record to your webhook, your datastore (S3, GCS, MongoDB, Qdrant), or a SuperQuery table. Use this when the data needs to land in your warehouse or your database. - **SuperQuery** — read from a Truto-managed synced store by hitting the same `/unified/...` endpoints with `?truto_super_query=apac|wnam`. Populated by RapidBridge sync jobs with a `superquery` destination. Use this when you want the Merge/Finch-style "we serve from cache" shape without standing up your own pipeline. See [Realtime data model](/docs/guides/how-truto-works/realtime-unified-apis-considerations). ## Declarative integrations and Unified APIs New integrations and Unified APIs are added by editing config — auth, base URL, resource list, mapping rules — not by writing platform code. The same surface customers use to add their own integration or override a Unified API mapping is the surface Truto uses to ship the catalog. [Learn why this is important](https://truto.one/blog/your-unified-apis-are-lying-to-you-the-hidden-cost-of-rigid-schemas/). See [Creating integrations](/docs/guides/integrations/creating-integrations) and [Creating Unified APIs](/docs/guides/unified-apis/creating-unified-apis). ## Admin-API complete Everything in `app.truto.one` is also a route. Installing an integration, minting a link token, listing integrated accounts, rotating an API token, registering a webhook, scheduling a sync — all of it is an HTTP call. Anything you can do as a human in the Dashboard you can also do from a script, a Workflow, or a coding agent. See [API reference](/docs/api-reference/overview/introduction). ## Coding-agent native The platform ships with a [skills pack](https://github.com/trutohq/truto-skills) and a [CLI](https://cli.truto.one) alongside the docs. An agent that supports the [Agent Skills](https://www.anthropic.com/news/skills) convention can wire a link-token route, a webhook handler, and the first Unified API call into your codebase from a single prompt — using the same routes documented here, not a sandboxed code generator. See [Setting up Truto with a coding agent](/docs/getting-started#setting-up-truto-with-a-coding-agent). --- # Realtime data model > Source: https://truto.one/docs/guides/how-truto-works/realtime-unified-apis-considerations/ Truto doesn't cache vendor data. Every Unified API call is a live call to the vendor API, on the request thread, returning the vendor's response shaped into Truto's unified envelope. That single design choice shapes how you think about rate limits, filtering, and latency. ## You share the vendor's rate limit Because Truto doesn't run a background sync, the rate-limit budget your customer has at the vendor is the budget your app has too. Truto adds its own limits in front: 50 requests every 10 seconds per integrated account, plus per-API-token limits — see [Rate limits](/docs/api-reference/overview/errors#rate-limits). When the integration is configured to read the vendor's rate-limit headers, Truto normalizes them into three standard response headers — `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset` — so your client can back off the same way regardless of which vendor it just called. The same normalization applies to both `/unified/...` and `/proxy/...` calls; `/proxy/...` is Truto's equivalent of what other Unified-API providers call pass-through. ```bash $ curl -i "https://api.truto.one/unified/crm/contacts?integrated_account_id=$ACCOUNT_ID" \ -H "Authorization: Bearer $TRUTO_API_TOKEN" HTTP/2 200 content-type: application/json; charset=utf-8 ratelimit-limit: 110;w=10 ratelimit-remaining: 109 ratelimit-reset: 60 { "result": [ /* ... */ ], "next_cursor": "..." } ``` `ratelimit-limit` carries the vendor's window in the `;w=` parameter when the vendor exposes one (HubSpot does; many don't). If the vendor doesn't return rate-limit information, or the integration isn't configured to read it, the headers are absent. If a call is rate-limited by the vendor, you get a `429` from Truto with a `Retry-After` header, plus the same three headers when the integration reads them — `ratelimit-reset` tells you how many seconds until the vendor's window opens again. For the header semantics and a longer worked example, see [Rate limits in Truto API](/docs/api-reference/overview/rate-limits). ## Filter availability is per integration The Unified API accepts the same query operators across vendors — `created_at[gt]`, `status[in]`, `sort_by`, `or`, `and`, and so on. What changes per vendor is which operators the underlying API actually supports. If the vendor doesn't support a filter, Truto silently drops it rather than fake it server-side; the cost of doing otherwise is fetching every record and filtering on the request thread, and that loses you the rate-limit budget above. Before relying on a filter, ask the integration what it supports. The meta endpoint returns the merged JSON schema for one method on one integration mapping — `query_schema` is the source of truth for which filters that vendor's `list` accepts: ```bash $ curl "https://api.truto.one/unified/crm/contacts/hubspot/meta/list" \ -H "Authorization: Bearer $TRUTO_API_TOKEN" { "method": "list", "documentation_link": "https://developers.hubspot.com/docs/api/crm/contacts", "query_schema": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email_addresses": { "type": "array", "items": { "type": "string" } }, "sort_by": { "type": "object" } } }, "default_query": { "limit": 50 } } ``` Anything not listed under `query_schema.properties` is silently dropped at call time — that's how you tell, before you ship a filter to production, whether HubSpot will honor `last_name[ilike]=*han` or quietly ignore it. For the full operator grammar see [Querying in Truto API](/docs/api-reference/overview/querying). ## Latency tracks the vendor A unified call is a vendor call plus a small Truto hop. Truto's hop is bounded; the vendor's isn't. p99 latency on `/unified/...` is roughly the vendor's p99 plus a few tens of milliseconds. That's fine for request-time use cases (pulling a contact when a user opens a record), and it's the wrong shape for jobs you'd otherwise run on a schedule against millions of records. For workloads where you need durable streaming, retries, pagination at scale, or the data landed in your warehouse, use [RapidBridge](/docs/guides/rapid-bridge/overview) — the same Unified API resources, executed as a background pipeline writing to a webhook, datastore, or SuperQuery destination. For "tell me when something changed at the vendor" use cases, use [Webhooks](/docs/guides/webhooks/overview). --- # Architecture > Source: https://truto.one/docs/guides/how-truto-works/overview/ Truto is middleware. Your app talks to one URL — `api.truto.one` — with one bearer token, and Truto holds every vendor credential and forwards each call to the right vendor. ```mermaid Truto middleware flowchart LR yourApp["Your app"] -->|"TRUTO_API_TOKEN"| trutoApi["Truto API
api.truto.one"] trutoApi -->|"vendor credentials"| vendor["Vendor API"] ``` Two consequences fall out of that: - **Truto handles vendor credentials for you.** Your customer connects through Truto Link — whether that's an OAuth handoff, an API key prompt, or whatever flow the integration needs. Truto stores the credentials securely, refreshes OAuth tokens when the vendor supports refresh, and uses the right credential when forwarding calls to the vendor. Your app keeps using the same `TRUTO_API_TOKEN`. - **Pass-through, not cache.** Each call hits the vendor live. Truto does not store the response. The trade-offs that follow — rate limits, latency, filter availability — are written up in [Realtime data model](/docs/guides/how-truto-works/realtime-unified-apis-considerations). ## The named entities These are the nouns you'll see in the API, the SDKs, and `app.truto.one`. Each one links to the page that owns it. | Entity | What it is | |--------|------------| | **Team** | Your Truto account. Owns environments, billing, and members. Manage at [Settings → Team Members](/docs/guides/team-members/adding-team-members). | | **[Environment](/docs/guides/environments/overview)** | A logical group of installed integrations, integrated accounts, API tokens, and webhooks. Production, staging, and development are usually separate environments. | | **[Integration](/docs/guides/integrations/overview)** | A vendor connector — `hubspot`, `salesforce`, `gmail`. Installed once per environment from the [catalog](https://app.truto.one/catalog/integrations). | | **[Integrated account](/docs/guides/integrated-accounts/connecting-an-account)** | One end-customer's connection to one integration in one environment. Has an `integrated_account_id` and belongs to a [tenant](/docs/guides/tenants/overview). Every data-plane call carries `?integrated_account_id=...`. | | **[Tenant](/docs/guides/tenants/overview)** | An environment-scoped external identity — your end-customer, workspace, or organisation — that owns one or more integrated accounts. You choose the `id` (any string up to 255 characters that fits your data model: `team:`, `user:`, `acme-corp`, whatever) and Truto keeps the same `id` across every account that tenant connects. Manage tenants explicitly via `POST /tenant` or `truto tenants ...`, or let Truto auto-materialise them on first connection. | | **[Unified API](/docs/guides/unified-apis/what-are-unified-apis)** | A category-level shape (CRM, ATS, ticketing) that one call can target across vendors. Sits at `/unified/{model}/{resource}`. | | **Proxy and Custom APIs** | The escape hatches at `/proxy/{resource}` (raw vendor shape) and `/custom/{resource}` (your own server-side handlers). Use when the unified shape doesn't carry a field you need. | | **[Link token](/docs/guides/integrated-accounts/connecting-an-account)** | Credential your backend mints and your frontend hands to Truto Link. Valid for 7 days, and used up once a connection completes with it. Created at `POST /link-token`. | | **[API token](/docs/guides/api-tokens/creating-api-tokens)** | Server-side bearer for `api.truto.one`. Scoped to one environment. Never ship this to the browser. | | **[Webhooks](/docs/guides/webhooks/overview)** | Outbound events Truto sends your backend — connection lifecycle (`integrated_account:active`, `:authentication_error`), sync runs, and webhook events from the underlying product when Truto receives and forwards them to your app. | ## What you see, what your customer sees Two surfaces sit outside the diagram: - **You see the [Truto Dashboard](https://app.truto.one)** — install integrations, install Unified APIs, mint API tokens, register webhooks, inspect integrated accounts. Every action there is also an HTTP route, so anything you do by hand can be automated. See [API reference](/docs/api-reference/overview/introduction). - **Your customers see [Truto Link](/docs/sdks/link-sdk)** — the connection UI your frontend embeds with `@truto/truto-link-sdk`. It runs the OAuth dance or collects API keys, then hands the result back to Truto. It is the only Truto surface end customers ever interact with. ## Next Read [Getting started](/docs/getting-started) for the runnable version of the request flow above — install an integration, mint a link token, open Truto Link, and make the first Unified API call. Read [Why Truto](/docs/guides/how-truto-works/what-makes-us-different) if you're still deciding whether the pass-through model is the right fit. --- # JSONata bindings in Truto Unified APIs > Source: https://truto.one/docs/guides/unified-apis/mapping-bindings/ **Bindings** are the building blocks you use in Truto Unified APIs to access and work with different parts of an API request and response. They're especially useful when writing JSONata expressions to transform data. When a JSONata expression runs, it uses these bindings to get the input data it needs. For example, `query` gives you access to all query parameters in a request. In this section, we will go through the `JSONata Bindings` available in Truto Unified APIs by each Mapping Type. You can refer to Truto [JSONata](https://www.npmjs.com/package/@truto/truto-jsonata#custom-functions) to know more about the JSONata methods supported. ## Query Mapping ### Available Bindings - **`query`** - **Description:** Contains the `query` parameters sent as part of the Unified API call - **`body`** - **Description:** The request body associated with the Unified API call. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). You can access these properties directly in your integration logic. For example, to access the `authToken`, use `context.authToken`. - **`before`** - **Description:** Contains the result of the `before steps` call. - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` ### Example **Scenario:** User inputs `contact.id` which is mapped to `person_id` that the underying `Salesforce` API accepts. Here, `contact` is the Unified API resource that maps to Persons in Salesforce. To filter Accounts with a particular contact, we use the following query mapping **Query Mapping Configuration:** ```json { "person_id": query.contact.id } ``` **Explanation:** - **`query.contact.id`** accesses the `contact.id` parameter from the user's request. - **`person_id`** is the internal parameter used by Salesforce. **Example Unified Request:** ``` GET /unified/crm/accounts?contact[id]=12345 ``` **Mapped Query Parameters:** ```json { "person_id": "12345" } ``` ## Body Mappings ### Available Bindings - **`body`** - **Description:** The request body associated with the Unified API call. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The query parameters from the user's request before `query` mapping. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). You can access these properties directly in your integration logic. For example, to access the `authToken`, use `context.authToken`. - **`before`** - **Description:** Contains the result of the `before steps` call. - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` ### Example **Body Mapping Configuration:** ```json { "fullName": body.name } ``` **Explanation:** - **`body.name`** accesses the `name` field from the request body. - **`fullName`** is the field used by the underlying API. ## Header Bindings ### Available Bindings - **`headers`** - **Description:** The headers Truto has prepared for the request to the underlying API. Only `content-type` is carried over from the Unified API call; custom headers you send to the Unified API are not passed in. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The query parameters from the user's request before `query` mapping. - **`body`** - **Description:** The request body after Body Mapping, as it will be sent to the underlying API. - **`requestBody`** - **Description:** The request body sent in the Unified API call, before Body Mapping. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). - Dynamic Runtime Values: - `id`: The unified model id that uniquely identifies the record. - `before`: The before steps that run immediately before the API request. You can access these properties directly in your integration logic. For example, use `context.id` to get the unified model id, check `context.before` for the pre-request steps. ### Example **Header Mapping Configuration:** ```json { "Authorization": context.authToken } ``` **Explanation:** - **`context.authToken`** accesses the authentication token from the API call context. - **`Authorization`** header is set with the token for Salesforce authentication. ## Request Path Bindings ### Available Bindings - **`headers`** - **Description:** The headers for the request to the underlying API, after Header Mapping. - **`body`** - **Description:** The request body after Body Mapping, as it will be sent to the underlying API. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The query parameters from the user's request before `query` mapping. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). You can access these properties directly in your integration logic. For example, to access the `authToken`, use `context.authToken`. - **`before`** - **Description:** Contains the result of the `before steps` call. - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` ### Example The expression must return the path as a string. **Request Path Mapping Configuration:** ``` "/users/" & query.user_id ``` **Explanation:** - **`query.user_id`** accesses the mapped `user_id` parameter. - The returned string, for example `/users/12345`, is used as the path of the request to the underlying API. ## Error Bindings ### Available Bindings - **`error`** - **Description:** The error object containing error details returned by the underlying API. - **`headers`** - **Description:** The headers sent in the request to the underlying API, after Header Mapping. - **`body`** - **Description:** The request body after Body Mapping, as sent to the underlying API. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The query parameters from the user's request before `query` mapping. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). You can access these properties directly in your integration logic. For example, to access the `authToken`, use `context.authToken`. - **`before`** - **Description:** Contains the result of the `before steps` call. - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` ## Response Bindings **Used in:** **Response Mapping** **Purpose:** Transform the API response into a user-friendly format. ### Available Bindings - **`response`** - **Description:** The raw API response returned by the API call. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The raw query parameters from the user's request. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). - Dynamic Runtime Values: - `id`: The unified model id that uniquely identifies the record. - `before`: The before steps that run immediately before the API request. You can access these properties directly in your integration logic. For example, use `context.id` to get the unified model id, check `context.before` for the pre-request steps. - **`headers`** - **Description:** HTTP headers in the API response. - **`body`** - **Description:** The request body after Body Mapping, as sent to the underlying API. ### Example **Response Mapping Configuration:** ```json { "id": Id, "owner": { "id": OwnerId }, "name": Name } ``` **Explanation:** - **`Id`** maps Salesforce's `Id` to the API's `id`. - **`OwnerId`** maps to a nested `owner.id`. - **`Name`** maps directly to `name` in the response. **Final API Response:** ```json { "id": "0012w000024KwDeAAK", "owner": { "id": "0052w00000CkYXHAA3" }, "name": "Truto-Archith-Test" } ``` ## Response Header Bindings **Used in:** **Response Header Mapping** **Purpose:** Manage HTTP headers in the API response. ### Available Bindings - **`headers`** - **Description:** HTTP headers in the API response. - **`query`** - **Description:** Mapped query parameters related to the response headers. - **`rawQuery`** - **Description:** The raw query parameters from the user's request. - **`body`** - **Description:** The request body after Body Mapping, as sent to the underlying API. - **`context`** - **Description:** A unified object that gathers all the information your API call needs. It merges: - Account Settings from `integratedAccount.context`: These are persistent configurations specific to the connected account. - Information from `baseContext`: This is used for passing certain info in Sync Jobs, such as the number of records for pagination (e.g., total_records_size). - Dynamic Runtime Values: - `id`: The unified model id that uniquely identifies the record. - `before`: The before steps that run immediately before the API request. You can access these properties directly in your integration logic. For example, use `context.id` to get the unified model id, check `context.before` for the pre-request steps. ## Is Partial Response? Sometimes, the APIs you call may not return all the data you need in a single response. In such situations, you might need to make an additional API call to another endpoint to fetch the remaining data. To handle this, you can enable the Is partial response? option in the Advanced Settings of the Response Mapping configuration. By default, this value is set to true when you enable this option. You can also define a JSONata expression that returns a boolean to validate whether the response is partial. ### Available Bindings - **`data`** - **Description:** The unified response after Response Mapping. - **`query`** - **Description:** Mapped query parameters. - **`rawQuery`** - **Description:** The raw query parameters from the user's request. - **`requestBody`** - **Description:** The request body sent in the Unified API call. - **`before`** - **Description:** Contains the result of the `before steps` call. - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` - **`rawBody`** - **Description:** Contains an `Array Buffer` of the `body`. Useful if the underlying API accepts data in a different formats like `base64`. ![Is Partial Response](/images/unified-apis/is-partial-response.png) ## Before/After Steps ### Available Bindings - **`id`** - **Description:** Can be used for cases when `id` is present in Query Params, for example in `/crm/accounts/:id` - **`query`** - **Description:** The query parameters from the user's request, before Query Mapping. - **`data`** - **Description:** The output of the previous step. In before steps, the first step starts with an empty object. In after steps, the first step starts with the unified response. - **`step`** - **Description:** The results of the earlier steps, keyed by step `name` (or by the step's position when it has no name). For example, `step.get_owner` is the result of the step named `get_owner`. - **`context`** - **Description:** Contains all the variables stored in your Integrated Account. - **`body`** - **Description:** The request body associated with the Unified API call. ## Practical Example ### Scenario: Mapping Contact Resource Map `contact.id` to the internal `person_id` used by Salesforce and then map it back in the response. #### Step 1: Define Query Mapping **Query Mapping Configuration:** ```json { "person_id": query.contact.id } ``` **Explanation:** - **`query.contact.id`** accesses the `contact.id` parameter from the user's request. - **`person_id`** is the internal parameter used by Salesforce. **Example Request:** ``` GET /unified/crm/accounts?contact[id]=12345 ``` **Mapped Query Parameters:** ```json { "person_id": "12345" } ``` #### Step 2: Define Response Mapping **Option 1: Using `query` Binding** **Response Mapping Configuration:** ```json { "contact": { "id": query.person_id } } ``` **Resulting API Response:** ```json { "contact": { "id": "12345" } } ``` **Option 2: Using `rawQuery` Binding** **Response Mapping Configuration:** ```json { "contact": { "id": rawQuery.contact.id } } ``` **Resulting API Response:** ```json { "contact": { "id": "12345" } } ``` --- # Unified API Request Flow > Source: https://truto.one/docs/guides/unified-apis/unified-apis-flow/ The Unified API Request is like a translator and assistant that simplifies how your application talks to multiple services (like Salesforce, HubSpot, or Zendesk). Instead of learning how each service works (different rules, formats, and endpoints), you just make one request to the Unified API, and it handles all the complicated stuff for you. In this section, let's go through each step of the Unified API Request. --- ![Unified API request flow](/images/unified-apis/unified-api-requests.png) 1. **Unified API Request** - **What Happens Here?** The process starts when a user or application makes a request to the Unified API endpoint. For example: - **Request:** `GET /unified/crm/accounts?search_term=Archith`. --- 2. **Is it a list,get call with static mapping?** - **What Does This Mean?** Checks if the Unified API call is a `list` or `get` call. If it is, and `Static Mapping` is enabled, the API call isn't made and the `Static Response` configured is returned. --- 3. **Are before steps configured?** - **What Does This Mean?** Checks if there are any "before steps" configured for preprocessing the request. These steps are optional but can enhance or validate the request or fetch additional data which will be used in the Unified API call. --- 4. **Run before steps (if configured)** - **What Happens Here?** If before steps exist, they are executed. --- 5. **Request Query Mapping** - **What Happens Here?** Maps or converts query parameters to match the requirements of the API (e.g., Salesforce). - **Example:** - Unified API Query: ```json { "name": "Truto", "city": "Bangalore" } ``` - Mapped Query for Salesforce: `SELECT * FROM Account WHERE Name LIKE '%Truto%' AND BillingCity LIKE '%Bangalore%'`. --- 6. **Request Body Mapping** - **What Happens Here?** Adjusts or transforms the request body before sending it to the API. - **Example:** - Unified API Body: ```json { "name": "Archith's Business", "website": "www.archithbiz.com" } ``` - Salesforce Mapped Body: ```json { "Name": "Archith's Business", "Website": "www.archithbiz.com" } ``` --- 7. **Request Headers Mapping** - **What Happens Here?** Ensures required headers are included and formatted correctly. --- 8. **Request Path Mapping** - **What Happens Here?** Maps the API path from the Unified API to the provider API’s endpoint. --- 9. **Does query have `truto_skip_api_call` set to true?** - **What Happens Here?** Checks if the request includes a flag to skip the actual API call. When it is set, Truto does not call the provider API and runs the response mapping on an empty response (`response` is an empty string). The response mapping decides what is returned, for example a result built from `context.before`, `query` or `context`. - **Example:** - Input: `GET /unified/crm/accounts?truto_skip_api_call=true`. - Output: Skips the Salesforce API call; the response mapping runs with an empty `response`. --- 10. **Call the Proxy API configured in the resource and method** - **What Happens Here?** Sends the actual request to the provider API (e.g., Salesforce). - **Example:** - Translates: - Unified API: `GET /unified/crm/accounts`. - API: `GET /services/data/v57.0/sobjects/Account`. --- 11. **Is there an error?** - **What Happens Here?** Checks if the API returned an error (e.g., 404 Not Found or 500 Internal Server Error). --- 12. **Error Mapping (if there's an error)** - **What Happens Here?** Converts errors into a standardized format. - **Example:** - Salesforce Error: ```json { "errorCode": "INVALID_FIELD", "message": "The field 'xyz' is not valid" } ``` - Mapped Error for Unified API: ```json { "error": "Invalid request. The field 'xyz' is not supported." } ``` --- 13. **Throw Error (if there's an error)** - **What Happens Here?** Sends the mapped error back to the user and stops further processing. --- 14. **Fetch Related Resources** - **What Happens Here?** If additional data is needed, fetches them from the API. Usually this is used when the resource being fetched has parent-child relationship with another resource. For example, in Asana, workspace_id is needed to get the projects of that Workspace. --- 15. **Response Mapping** - **What Happens Here?** Converts the provider response into the Unified API’s format. - **Example:** - Salesforce Response: ```json { "Id": "0012w000024KwDeAAK", "Name": "Truto", "BillingCity": "Bangalore" } ``` - Unified API Response: ```json { "id": "0012w000024KwDeAAK", "name": "Truto", "city": "Bangalore" } ``` --- 16. **Response Header Mapping** - **What Happens Here?** Adds or modifies response headers for the Unified API. - **Example:** - Adds `rate-limit` headers: ```json { "X-RateLimit-Limit": 1000, "X-RateLimit-Remaining": 995 } ``` --- 17. **Are after steps configured?** - **What Happens Here?** Checks if any "after steps" are configured for postprocessing the response. --- 18. **Run after steps (if configured)** - **What Happens Here?** Runs the configured after steps in order: `request` steps that call another Unified or Proxy API, `state` steps that compute a value with JSONata, and `replace_data` steps that set the data to an earlier step's result. - **Example:** After an `update` that returns only the record `id`, a `request` step calls `get` to fetch the full record. --- 19. **Set result of after steps as Response** - **What Happens Here?** Updates the response with the output from the after steps (if any). --- 20. **Return the Response** - **What Happens Here?** Sends the final, processed response back to the user. - **Example Final Response:** ```json { "id": "0012w000024KwDeAAK", "name": "Truto", "city": "Bangalore", "phone": "123-456-7890" } ``` --- # Overriding Unified API mappings > Source: https://truto.one/docs/guides/unified-apis/override/ To support use cases where some of your customers might be using a specific custom fields for a resource, you can override the Unified API mappings on an Integrated account level (applies to only that specified integrated account) or Environment level (applies to multiples integrated accounts in that environment). This will allow you to map the custom fields to the Unified API fields. ## How overrides are applied Environment and integrated account overrides combine with the base mapping differently. 1. **Environment override.** Each JSONata mapping field you set (`response_mapping`, `query_mapping`, `request_body_mapping`, and so on) replaces that whole field in the base mapping for every integrated account in the environment. Fields you don't set keep the base mapping. A `response_mapping` override is the complete expression for the response, so it must return every unified field you want, not only the new ones. 2. **Integrated account override.** Truto evaluates the account's `response_mapping` against the same `remote_data` and merges its result on top of the result from Step 1. Attributes returned by both are overwritten by the account override, and new attributes are added to the unified API response. An account override only needs the fields you want to change or add. ![Override Flowchart](/images/misc/overrides-flowchart.png) ## How to specify an override for an Integrated account Let's take an example of HiBob, where we want to specify an override to get the `date_of_birth` for an employee and adding a query_param `name`. To do this, 1. Get the integrated account ID from the UI or the API where you want to apply the override. 2. Make a PATCH request on the integrated account resource with the override details. For the example mentioned before, you'll have to make the following API request, ```bash curl --location --request PATCH 'https://api.truto.one/integrated-account/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "unified_model_override": { "hris": { "employees": { "list": { "query_mapping": "{ \"fullName\": query.name }", "response_mapping": "{ \"date_of_birth\": response.personal.shortBirthDate }" } } } } }' ``` The request body contains the following, - `unified_model_override` This is the object which specifies the overrides - `hris` This is the name of the Unified Model. You can find this on the [Unified Model details page](https://app.truto.one/unified-apis/available/0477048a-f24b-4ad6-ad5b-5eaf15437d19) in the UI. - `employees` This is the resource you want to specify the override for. - `list` The overridden method - `query_mapping` Since we want to add query_param `name` to filter the results based on the name input, we specify the `query_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. `name` is mapped to the query parameter `fullName` which is accepted by the HiBob API. - `response_mapping` Since we want to change the response, we specify the `response_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. The `remote_data` is present in `response` object within the JSONata expression. Now you can go ahead and make the [LIST /unified/hris/employees](https://truto.one/docs/api-reference/unified-hris-api/employees/list) API request for the integrated account and it should return you the data with `date_of_birth` added to it. ## How to specify an override for an Environment Overriding Unified API mappings in Truto allows you to customize how data is translated between your systems and the Unified API. Follow these steps to override and adjust API mappings according to your environment and requirements: ### 1. Navigate to the Unified API Mapping - Go to **Unified APIs → Installed Unified APIs** in your Truto dashboard and open the Unified API. - Open the **Resources** tab, select the resource, and switch to its **Mapping** tab. - From the **Integration** dropdown, choose the integration you want to modify. - Identify the specific API method you wish to override and click on the **pencil icon** next to it. ![Edit Mapping](/images/unified-apis/overriding-unified-api-screen.png) ### 2. Open the Mapping Modal Clicking the pencil icon opens a modal window containing various mapping configurations. Inside this modal, you will see separate sections for: - **Query Mapping** - **Request Body Mapping** - **Response Mapping** - **Error Mapping** - **Request Header Mapping** - **Response Header Mapping** ![Mapping Modal](/images/unified-apis/overriding-mappings-modal.png) Alternatively, you can edit the mappings altogether by toggling the Code view. It opens up a `YAML` configuration that looks like - ![Mapping Modal Code View](/images/unified-apis/code-view-mapping.png) ### 3. Modify and Override the Mappings - **Change the Mappings:** - **Delete Fields:** Remove any fields that are not relevant to your integration needs. - **Add Extra Fields:** Insert new fields or parameters as necessary to tailor the request, response, headers, or error handling. - **Modify Existing Fields:** Adjust the field structure, data types, or `JSONata` transformation logic to align with your specific use case. ## How to specify an override for an Environment thorough API Let's take an example of HiBob, where we want to specify an override to get the `date_of_birth` for an employee and add a query param `name`. To do this, 1. Get the installed unified model ID by specifying the name of the unified model in the following API request. The `id` of the returned record is the `environment_unified_model_id`. ```bash curl --location 'https://api.truto.one/environment-unified-model?unified_model.name=' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' ``` 2. Make a POST request to create an environment mapping override for the resource, integration and method. For the example mentioned before, you'll have to make the following API request, ```bash curl --location --request POST 'https://api.truto.one/environment-unified-model-resource-method' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "environment_unified_model_id": "", "resource_name": "employees", "integration_name": "hibob", "method_name": "list", "config": { "query_mapping": "{ \"fullName\": query.name }", "response_mapping": "{ /* every field from the base response_mapping */ \"id\": response.id, \"date_of_birth\": response.personal.shortBirthDate }" } }' ``` The request body contains the following, - `environment_unified_model_id` The ID of the installed unified model from Step 1. - `resource_name` This is the resource you want to specify the override for. - `integration_name` This is the integration name you want to specify the override for. - `method_name` The overridden method. - `config` The mapping fields to override. Each field you set replaces the same field in the base mapping. - `query_mapping` Since we want to add query_param `name` to filter the results based on the name input, we specify the `query_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. `name` is mapped to the query parameter `fullName` which is accepted by the HiBob API. - `response_mapping` Since we want to change the response, we specify the `response_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. The `remote_data` is present in `response` object within the JSONata expression. This expression replaces the base `response_mapping`, so start from the base mapping and add `date_of_birth` to it. To see the mapping currently in effect, call `GET /environment-unified-model-resource-method?environment_unified_model_id=&resource_name=employees&integration_name=hibob&apply_overrides=true`. Each environment can have one override per resource, integration and method. To change an existing override, find its `id` and current `version` with `GET /environment-unified-model-resource-method?environment_unified_model_id=&resource_name=employees&integration_name=hibob&method_name=list`, then send a PATCH request with the complete `config` you want. The `config` you send replaces the stored one, and a stale `version` is rejected with a 400. ```bash curl --location --request PATCH 'https://api.truto.one/environment-unified-model-resource-method/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "version": , "config": { "query_mapping": "{ \"fullName\": query.name }", "response_mapping": "{ /* every field from the base response_mapping */ \"id\": response.id, \"date_of_birth\": response.personal.shortBirthDate }" } }' ``` To remove the override and fall back to the base mapping, send `DELETE /environment-unified-model-resource-method/`. Now you can go ahead and make the [LIST /unified/hris/employees](https://truto.one/docs/api-reference/unified-hris-api/employees/list) API request for the integrated accounts in the environment and it should return you the data with `date_of_birth` added to it for all of the integrated accounts in the specified environment. ## Bindings available to use in response_mappings Bindings are the data that are sent in the Unified API call, which can be used in response_mappings to apply overrides as per your needs. - `response` This is the raw API response returned by the API call. ``` { "response": { "personal": { "shortBirthDate": "1990-01-01" } } } ``` - `rawQuery` This is the object that contains the raw query parameters sent in the Unified API request. ``` { "fullName": rawQuery.name } ``` - `query` This is the object which specified the query params after mapping is applied as needed by the integration. ``` { "fullName": query.name } ``` :::callout{type="info"} Consider an example of query_mapping where the contact resource is mapped to `person_id` in the following way - ``` { "person_id": rawQuery.contact.id } ``` Now, if you need to map the contact resource in the response_mapping, you can do in the following ways - ``` { "contact": { "id": query.person_id } } ``` or ``` { "contact": { "id": rawQuery.contact.id } } ``` ::: - `body` This is the request body after Body Mapping, as sent to the underlying API. ``` { "fullName": body.name } ``` - `context` This is the object that contains all the variables stored in your Integrated account. ``` { "fullName": context.name } ``` Read more about [Bindings](/docs/guides/unified-apis/mapping-bindings) ## Available JSONata bindings in mappings JSONata methods are lifesavers while writing overrides for transforming the raw API response to the Unified API response schema. You can refer to Truto [JSONata](https://www.npmjs.com/package/@truto/truto-jsonata#custom-functions) to know more about the methods supported. --- # Overview > Source: https://truto.one/docs/guides/unified-apis/installing-unified-api/ In this section, we’ll walk you through how to set up and install Unified APIs in your environment, complete with screenshots to guide you every step of the way. ## Available Unified APIs In Truto, 'Available Unified APIs' refers to a collection of Unified APIs, ready for installation and use. They are classified into different categories such as CRM, E-commerce, Ticketing, etc. ## Installing a Unified API To access and install these APIs you can click [here](https://app.truto.one/catalog/unified-models) or follow these steps: 1. Sign in to your Truto account. 2. Navigate to the Catalog section. It has two tabs, one for `Integrations` and one for `Unified APIs`. ![Install Unified API](/images/unified-apis/unified-api-catalog.png) 3. Click on the `Unified APIs` 4. Find and click on the `Install` button next to the API you wish to use. Now, the chosen Unified API is installed and ready for use in your environment. ### Custom Unified APIs If a specific Unified API you need is not currently available, Truto offers the capability to create custom APIs. Let us know your specific requirements, and we'll create it for you. ## Viewing the resources, schema and mappings for a Unified API In Truto, each Unified API comes with 'resources', 'schema', and 'mappings': - **Resources**: These are the specific data endpoints available within a Unified API. - **Schema**: This outlines the structure and type of data provided by the resources. - **Mappings**: These show how data from the underlying API is transformed into the structure defined by the Unified API schema. ### View Resources, Schema, and Mappings To explore these elements for a Unified API, follow these steps: 1. Sign in to your Truto account. 2. Navigate to the `Unified APIs` section in `Catalog` or `Installed` sections. ![Open a Unified API](/images/unified-apis/unified-apis.png) 3. Locate the `Resources` section. This lists all data endpoints for the selected Unified API. ![Unified APIs Resources](/images/unified-apis/unified-apis-resources.png) 4. Click on any listed resource to view its schema and mapping. The mapping section will display the transformation logic used to convert data from the underlying API into the format defined by the Unified API's schema. ### The Role of Mappings Within the mappings, there's a drop-down list showcasing which integrations support the particular resource mapping. This helps in understanding how data from different underlying APIs can be standardized into the Unified API format. ## To Summarize Unified APIs in Truto are like multi-lingual interpreters that translate and simplify data from different sources, making your work with APIs faster, cheaper, more efficient, and much more straightforward. --- # What Are Unified APIs? > Source: https://truto.one/docs/guides/unified-apis/what-are-unified-apis/ Imagine juggling multiple tools like Salesforce, HubSpot, and Zendesk for your business operations. Each one has its own unique API, authentication process, and data structure. Managing all these separate integrations can quickly become overwhelming, expensive, and error-prone. This is where **Unified APIs** come to the rescue! ## **What Are Unified APIs?** Think of Unified APIs as the Swiss Army knives of the integration world. They bring together different APIs into a single, easy-to-use interface, making your life as a developer much simpler. Instead of dealing with the quirks of each platform's API, you interact with one consistent system that handles everything for you. ### **What Do Unified APIs Do?** Unified APIs tackle several technical headaches so you don't have to: - **Data Normalization**: They convert data from different platforms into a single, unified format. For example, "leads" from Salesforce, HubSpot, and Pipedrive all get transformed into one standard schema. All kinds of APIs like REST, SOAP, GraphQL are abstracted to use only REST. - **Authentication Simplification**: Whether it's OAuth, OAuth 2.0, API keys, or basic authentication, Unified APIs manage it all, letting you authenticate once to access multiple platforms. - **Error Mapping**: Instead of handling different error messages from each platform, Unified APIs provide consistent error responses, making troubleshooting a breeze. - **Multi-Resource Support**: Manage various entities like users, tickets, campaigns, or audiences through across multiple API Providers using one common interface. ## **Two Approaches to Unified APIs** When it comes to Unified APIs, there are two main approaches: **Caching-Based** and **Real-Time**. Let’s dive into why one clearly outshines the other. ### **1. Caching-Based Unified APIs** This approach involves periodically syncing data from different platforms into a central cache or database. While it might sound efficient, it comes with some serious drawbacks: - **Data Inconsistency**: The cached data might not always be up-to-date, leading to outdated or incorrect information. - **Synchronization Complexity**: Keeping everything in sync is tricky and can lead to failed sync jobs or data conflicts. - **Customer Frustration**: Outdated data can lead to poor business decisions and a frustrating user experience. - **Flawed Merge Logic**: Combining cached data with live data during updates can create mismatches and further compromise data integrity. - **Security Risks**: Centralized caches can become attractive targets for hackers. If the cache is compromised, all the cached data can be exposed, leading to significant security breaches. **Bottom Line**: Caching at the provider’s end often leads to unreliable, inconsistent data and introduces significant security vulnerabilities. It’s better to handle caching on the customer side or during data merging, where it can be more contextually managed and secured. ### **2. Real-Time Unified APIs** Real-time Unified APIs take a different route by making live calls to the underlying systems every time you make a request. This ensures that the data you receive is always fresh, accurate, and actionable. #### **Advantages of Real-Time Unified APIs** 1. **Up-to-Date Data**: Get the latest information directly from the source systems whenever you need it. 2. **No Synchronization Overhead**: Forget about complex sync jobs and managing stale data. 3. **Improved Actionability**: Perform actions like updating a CRM record or launching a marketing campaign instantly. 4. **Simplified Architecture**: No need for intermediate caching layers—focus on direct interactions with your source systems. 5. **Enhanced Security**: By avoiding centralized caches, there are fewer points of vulnerability, reducing the risk of large-scale data breaches. **Real-Time APIs** eliminate the risks of stale data and security vulnerabilities associated with caching, making them the superior choice for dynamic and secure business environments. ## **Why are Truto Unified APIs better?** Truto is built entirely on a real-time integration model, addressing all the pitfalls of caching while adding a bunch of awesome features that make it the ultimate choice for seamless integrations. ### **Real-Time Data Access** Truto connects directly with your underlying platforms, ensuring you always get the most current data and can perform actions instantly. No more worrying about outdated or inconsistent information! ### **Webhooks for Event-Driven Automation** With Truto’s [Webhooks](/docs/guides/webhooks/overview), you get real-time notifications whenever something changes in your connected systems. Imagine this: - A new lead is added to Salesforce. - A support ticket is updated in Zendesk. - A campaign status changes in Google Ads. These webhooks let your applications respond immediately to these changes, powering dynamic workflows and cutting down on the need for constant polling. Read more about [Webhooks](/docs/guides/webhooks/overview) ### **Sync Jobs for Data Continuity** While Truto shines in real-time interactions, it also offers sync jobs known as [RapidBridge](/docs/guides/rapid-bridge/overview) for scenarios that require periodic updates, such as: - **Importing Historical Data**: During onboarding, Truto can import your existing data seamlessly. - **Reconciling Data Between Systems**: Ensure consistency and accuracy across platforms with regular syncs. These sync jobs are lightweight and complement Truto’s real-time capabilities, ensuring you have both current and historical data without any hiccups. You can combine these Sync Jobs with webhooks so that your application gets the data it needs. The sync jobs can run on demand or on a `cron` schedule. Read more about [RapidBridge](/docs/guides/rapid-bridge/overview) ### **Security Features** Truto takes security seriously. Here’s how it keeps your data safe: 1. **Data Encryption**: All communications between you, Truto, and your connected systems are encrypted using top-notch protocols like TLS 1.3. 2. **Granular Access Control**: Only authorized users have access or modify your data, thanks to strict access controls. 3. **OAuth Proxying**: Truto handles OAuth authentication on your behalf, securely storing and refreshing tokens as needed. 4. **Auditing and Monitoring**: Every API call and action is logged, providing robust monitoring, auditing, and debugging capabilities. ### **Advanced Error Handling** Truto makes dealing with errors simple by standardizing error responses across all supported platforms. For instance, a rate-limit error from Google Ads and a similar one from LinkedIn are both translated into consistent Truto error codes with clear explanations. ## **How Unified APIs Are Structured** Unified APIs are designed to simplify your interactions with multiple systems, acting as a seamless bridge that handles all the complexities behind the scenes. Let’s dive into the architecture of a Unified API and see how each component works together to make your life easier. ### **1. Abstraction Layer** **What Is It?** The abstraction layer is the heart and soul of a Unified API. Think of it as the translator that converts all the different languages (APIs) into one common language that your application understands. **What Happens Here?** - **Normalization of Resources**: Different platforms represent similar data in various ways. For instance, Salesforce might use "Leads," HubSpot uses "Contacts," and Pipedrive has "Persons." The abstraction layer converts all these into a single, unified "Lead" object, so you don’t have to juggle different terminologies. - **Data Transformation**: Data comes in all shapes and sizes. This layer ensures that whether you’re pulling data from Google Ads, Zendesk, or LinkedIn, it’s formatted uniformly. **Example:** ```json { "id": "0012w000024KwDeAAK", "name": "Truto", "city": "Bangalore" } ``` This standardized format makes it easier to work with data from any integrated platform. - **Error Normalization**: Each platform has its own set of error codes and messages. The abstraction layer standardizes these errors into a consistent format, making troubleshooting much simpler. **Example:** ```json { "error": "Invalid request. The field 'xyz' is not supported." } ``` --- ### **2. Connectors** **What Are They?** Connectors are specialized adapters that link the Unified API to each individual platform. They handle the nitty-gritty details of communication between systems. **What Happens Here?** - **Authentication Management**: Each platform may use different authentication methods like OAuth, API keys, or basic authentication. Connectors manage these varied authentication processes, so you don’t have to worry about the specifics. **Example:** Truto’s connector for Salesforce handles OAuth token retrieval and refreshing automatically. - **Platform-Specific Requests**: When you make a request through the Unified API, connectors translate it into the specific format required by each platform’s API. **Example:** - **Unified API Request:** `GET /unified/crm/accounts` - **Salesforce API Call:** `GET /services/data/v57.0/sobjects/Account` --- ### **3. Sync Jobs for Historical Data** **What Are Sync Jobs?** While real-time data is essential, there are times when you need to work with historical data or perform large data imports. Sync jobs handle these scenarios seamlessly. **What Happens Here?** - **Initial Data Imports**: When you first set up your integration, sync jobs can import all your existing data, getting you up and running quickly. **Example:** Importing all past leads from HubSpot into your unified CRM system during onboarding. - **Periodic Reconciliation**: To ensure data consistency across systems, sync jobs run regular checks and updates, keeping everything in harmony. **Example:** Monthly syncs between your CRM and marketing platforms to reconcile any discrepancies. - **Complementing Real-Time Operations**: Sync jobs work alongside real-time interactions, providing a complete picture by combining current and historical data. **Example:** Having both live campaign data and historical performance metrics available for comprehensive analysis. --- ### **4. Security Layer** **Why It’s Crucial:** Security is the backbone of any Unified API, ensuring that your data remains protected at all times. **What Happens Here?** - **Data Encryption**: All data transfers between your application, the Unified API, and connected platforms are encrypted using industry-standard protocols like TLS 1.3. **Example:** When you send a request to Truto, the data is encrypted during transit, safeguarding it from potential breaches. - **Token Management**: Handling and refreshing authentication tokens can be tricky, but the security layer manages this securely, so you don’t have to worry about it. **Example:** Truto’s ensures OAuth tokens are stored and refreshed securely without exposing sensitive credentials. - **Access Control**: Only authorized users and systems can access or modify your data. Strict access controls prevent unauthorized access and ensure data integrity. **Example:** Setting permissions so that only certain roles within your team can update CRM records through the Unified API. Truto supports setting permissions as `admin` or `member`. ## **Unified APIs in Action** Let’s see how all these components come together with a practical example. Imagine you’re managing your marketing campaigns across Google Ads, Meta Ads, and LinkedIn Ads. With a Unified API like **Truto**, here’s how it works: 1. **Unified API Request** You make a single request to fetch all your campaigns: ``` GET /unified/marketing/campaigns ``` 2. **Abstraction Layer in Action** Truto’s abstraction layer normalizes the request and prepares it for each platform. 3. **Connectors Translate the Request** - For Google Ads: `GET /ads/v1/campaigns` - For Meta Ads: `GET /marketing_api/v2.0/campaigns` - For LinkedIn Ads: `GET /v2/adCampaigns` 4. **Real-Time Data Fetching** Truto makes live calls to each platform, ensuring you receive the most current campaign data. 5. **Webhooks Notify You of Changes** If a campaign status changes in Google Ads, a webhook instantly notifies your application to update the dashboard. 6. **Sync Jobs Handle Historical Data** Regular sync jobs ensure that any historical campaign data is also up-to-date and reconciled across platforms. 7. **Security Layer Protects Your Data** All data transfers are encrypted, and only authorized users can access or modify campaign information. 8. **Error Handling Made Simple** If LinkedIn Ads returns an error, Truto maps it to a standardized format, making it easier for you to handle: ```json { "error": "Invalid request. The field 'xyz' is not supported." } ``` 9. **Response Mapping for Consistency** The response from LinkedIn Ads is transformed into Truto’s unified format: ```json { "id": "cmp-67890", "name": "Holiday Campaign", "status": "Active", "budget": "5000" } ``` 10. **Final Response to Your Application** You receive a consistent, easy-to-use response from Truto: ```json [ { "id": "cmp-12345", "name": "Summer Sale", "status": "Active", "budget": "3000" }, { "id": "cmp-67890", "name": "Holiday Campaign", "status": "Active", "budget": "5000" } ] ``` --- # Creating Unified APIs on Truto > Source: https://truto.one/docs/guides/unified-apis/creating-unified-apis/ ## **Overview** Truto allows you to create Unified APIs that simplify how different applications interact. This guide will walk you through creating a Unified API for a **CRM system** using **Salesforce** as the integration example. ## **Step 1: Add a New Unified API** ### **1.1. Go to the Catalog** 1. **Log in to Truto:** - Navigate to your Truto dashboard. 2. **Navigate to Catalog:** - On the top-right, click on the `Catalog` section. ![Catalog Unified APIs](/images/unified-apis/catalog-unified-apis.png) 3. **Create a New Unified API:** - Click the `Create unified API` button. - ![Create Unified API](/images/unified-apis/create-unified-api.png) ### **1.2. Fill in API Details** A popup will appear for you to enter basic information about your new API. - **Name:** Use lowercase letters with hyphens (kebab-case). *Example:* `crm` *This sets the API path to `/unified/crm`.* - **Label:** A friendly name for your API. *Example:* `Unified CRM API` - **Category:** Helps organize your API. *Example:* `CRM` ![Unified API Popup](/images/unified-apis/create-unified-api-popup.png) ### **1.3. Create the API** 1. After filling in all details, click the `Create` button. 2. You'll be redirected to the `Unified API` page, displaying your newly created API. ![Available Unified API](/images/unified-apis/available-unified-api.png) ## **Step 2: Add a Resource** A **resource** represents a specific part of your API, like "accounts" in a CRM system. ### **2.1. Add a Resource** 1. **Go to Resources:** - Within your Unified API page, click on the `Resources` tab. 2. **Add New Resource:** - Click the `Add Resource` button. ![Add Resource Unified API](/images/unified-apis/add-resources-unified-apis.png) 3. **Enter Resource Name:** - Use lowercase letters with underscores (snake_case). *Example:* `accounts` ![Add a resource modal](/images/unified-apis/add-resource-modal.png) 4. **Create the Resource:** - Click the `Add` button to finalize. ### **2.2. Configure Resource Schema** The **schema** defines the structure of the response data your `Unified API` will handle. It drives the API reference for the resource, and Truto also uses its field types at runtime, for example to cast column types for `truto_super_query` reads. Unified API responses are not validated against it. 1. **Edit Schema:** - In the `Resources` tab, select your newly added `accounts` resource. - Click on the `Schema` tab. - Click the edit (pencil) icon to modify the schema. ![Schema Edit](/images/unified-apis/schema-edit.png) 2. **Define the Schema:** - **Fields:** Specify each piece of data your API will manage. - **Types:** Indicate the type of data (e.g., string, integer). - **Descriptions:** Provide a brief explanation for each field. You can add the schema using the Form or in JSON. ![Resource schema form](/images/unified-apis/resource-schema-form.png) 3. **Save the Schema:** - After entering all fields, click the `Save` button. ![Add Schema Details](/images/unified-apis/add-schema-details.png) Note: This is how the schema will look like in `JSON` ```json { "type": "object", "properties": { "id": { "type": "string", "description": "The account's unique identifier", "required": true }, "owner": { "type": "object", "description": "The account's owner", "properties": { "id": { "type": "string", "description": "The owner's unique identifier" } } }, "name": { "type": "string", "description": "The account's name" }, "website": { "type": "string", "description": "The account's website" } // Add other fields as needed } } ``` ## **Step 3: Add Methods and Configure Mapping** The next step is to add a method, which is how the interaction happens with `Salesforce` ### **3.1. Add a Method** 1. **Add Method:** - Within the `accounts` resource, click the `Mapping` tab. - Click the `Add method` button. - Enter the method name in **snake_case** (e.g., `list`). - **Supported Methods:** `list`, `get`, `create`, `update`, `delete`, etc. ![Add Method](/images/unified-apis/add-method-unified-mapping.png) 2. **Save the Method:** - Click the `Save` button. - This will open the **Mapping** screen. ### **3.2. Configure Mapping Screen** As soon as the `Method` above is saved, this screens opens up. **Note:** These resources and their corresponding methods come from the **Integrations** (in this case, **Salesforce**). 1. **Select Resource and Method:** - **Resource:** Choose `accounts`. - **Method:** Select the method you added earlier (e.g., `list`). ![Mapping Screen](/images/unified-apis/resource-mapping-unified-apis.png) ## **Step 4. Define Query Mapping** Translates query parameters in the Unified API call into the query supported by the underlying API. This step is generally optional. Use it when you want to pass custom Query Params to the underlying API that are different from what you are passing in the request. 1. **Go to Query Mapping:** - Click on the `Query Mapping` tab. ![Query Mapping](/images/unified-apis/query-mapping.png) 2. **Query Schema:** The Query Schema specifies what should be in the Query Parameters. Since the schema is defined in Resource Schema, you can just specify the fields from the schema that will be used in the Query and `required`, `type`, `description` will be automatically used from the Resource Schema. The Query Schema is specified in `YAML`. ```yaml name: {} owner: {} city: {} state: {} country: {} created_at: {} updated_at: {} last_activity_at: {} website: {} industry: {} number_of_employees: {} fields: {} custom_fields: {} search_term: {} ``` 3. **Example:** A sample query input demonstrating how users can interact with the API. ```json { "query": { "search_term": "Archith", "name": "Archith's", "website": "truto", "include_custom_fields": ["field_1"], "fields": ["fields"] } } ``` 4. **Mapping Logic:** Translates the Unified API's query parameters into a Salesforce-compatible SOQL query. ```javascript ( $whereClause := query ? $convertQueryToSql( $merge([ query .{ "created_at": created_at, "updated_at": updated_at, "last_activity_at": last_activity_at, "name": name ? { "LIKE": "%" & name & "%" }, "owner": owner.id, "city": city ? { "LIKE": "%" & city & "%" }, "state": state ? { "LIKE": "%" & state & "%" }, "country": country ? { "LIKE": "%" & country & "%" }, "website": website.eq ? website.eq : website ? { "LIKE": "%" & website & "%" }, "industry": industry ? { "LIKE": "%" & industry & "%" }, "number_of_employees": number_of_employees }, $sift(query.custom_fields, function($v, $k) { $k ~> /__c$/i }) ]), [ "created_at", "updated_at", "last_activity_at", "name", "owner", "city", "state", "country", "website", "industry", "number_of_employees", $keys(query.custom_fields) ], { "created_at": "CreatedDate", "updated_at": "LastModifiedDate", "last_activity_at": "LastActivityDate", "name": "Name", "owner": "OwnerId", "city": "BillingCity", "state": "BillingState", "country": "BillingCountry", "website": "Website", "industry": "Industry", "number_of_employees": "NumberOfEmployees" }, $merge([ { "created_at": "date", "updated_at": "date", "last_activity_at": "date|yyyy-LL-dd", "name": "string", "owner": "string", "city": "string", "state": "string", "country": "string", "website": "string", "industry": "string", "number_of_employees": "number" }, $keys(query.custom_fields).{ $: "string" } ]), { "LIKE": "LIKE" }, { "noQuotesForDate": true, "escapeSingleQuotes": true } ); $searchTermWhereClause := $whereClause ? " WHERE " & $whereClause; $searchTermCustomFields := $firstNonEmpty(query.include_custom_fields, query.fields) ? ", " & $join($firstNonEmpty(query.include_custom_fields, query.fields), ","); { "q": query.search_term ? "FIND {" & query.search_term & "} RETURNING Account(Id, OwnerId, Name, Description, Industry, NumberOfEmployees, Website, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, ShippingStreet, ShippingCity, ShippingState, ShippingPostalCode, ShippingCountry, Phone, Fax, LastActivityDate, CreatedDate, LastModifiedDate" & $searchTermCustomFields & $searchTermWhereClause & ")", "where": $whereClause ? "WHERE " & $whereClause, "include_custom_fields": $firstNonEmpty(query.include_custom_fields, query.fields) ? ", " & $join($firstNonEmpty(query.include_custom_fields, query.fields), ",") } ) ``` 5. **Mapped (Result):** An example of how the above mapping logic transforms the input into a Salesforce-compatible query. ```json { "q": "FIND {Archith} RETURNING Account(Id, OwnerId, Name, Description, Industry, NumberOfEmployees, Website, BillingStreet, BillingCity, BillingState, BillingPostalCode, BillingCountry, ShippingStreet, ShippingCity, ShippingState, ShippingPostalCode, ShippingCountry, Phone, Fax, LastActivityDate, CreatedDate, LastModifiedDate, field_1 WHERE Name LIKE '%Archith\\'s%' AND Website LIKE '%truto%')", "where": "WHERE Name LIKE '%Archith\\'s%' AND Website LIKE '%truto%'", "include_custom_fields": ", field_1" } ``` ## **Step 5: Add Response Mapping** After configuring how queries are handled, define how responses from the underlying API are transformed to fit your Unified API's structure. ### **4.1. Configure Response Mapping** 1. **Go to Response Mapping:** - Click on the `Response Mapping` tab. ![Response Mapping](/images/unified-apis/response-mapping.png) 2. **Response Schema:** This defines the structure of the data your API will return to users. This is specified in `YAML` and autopopulated from the Resource Schema defined above. ``` yaml type: object properties: id: type: string description: The account's unique identifier required: true owner: type: object description: The account's owner properties: id: type: string description: The owner's unique identifier name: type: string description: The account's name description: type: string description: The account's description industry: type: string description: The account's industry website: type: string description: The account's website number_of_employees: type: integer description: The account's number of employees addresses: type: array items: type: object properties: id: type: string description: The unique identifier of the address street_1: type: string description: Line 1 of the street address street_2: type: string description: Line 2 of the street address city: type: string description: The city state: type: string description: The state postal_code: type: string description: The postal code country: type: string description: The country type: type: string description: The address type phone_numbers: type: array items: type: object properties: id: type: string description: The unique identifier of the phone number number: type: string description: The phone number extension: type: string description: The extension of the phone number type: type: string description: The phone number type urls: type: array items: type: object properties: url: type: string description: The account's URL type: type: string description: The account's URL type description: The account's urls tags: type: array items: type: object properties: id: type: string description: The tag's unique identifier name: type: string description: The tag's name description: The contact's tags custom_fields: type: object description: All the custom fields present on the account additionalProperties: true last_activity_at: type: string description: The date and time of the account's last activity format: date-time updated_at: type: string description: The date and time of the account's last update format: date-time created_at: type: string description: The date and time of the account's creation format: date-time ``` 3. **Provide an Example Response:** Provide an example raw API response from `Salesforce` so that you can verify your mapping ```json { "response": { "attributes": { "type": "Account", "url": "/services/data/v57.0/sobjects/Account/0012w000024KwDeAAK" }, "truto__Custom_Alternate_Email__c": "Archith@truto.dev", "Id": "0012w000024KwDeAAK", "IsDeleted": false, "MasterRecordId": null, "Name": "Truto-Archith-Test", "Type": null, "ParentId": null, "BillingStreet": "5", "BillingCity": "BNGLR", "BillingState": "KA", "BillingPostalCode": "560066", "BillingCountry": "INDIA", "BillingLatitude": null, "BillingLongitude": null, "BillingGeocodeAccuracy": null, "BillingAddress": { "city": "BNGLR", "country": "INDIA", "geocodeAccuracy": null, "latitude": null, "longitude": null, "postalCode": "560066", "state": "KA", "street": "5" }, "ShippingStreet": "sdf", "ShippingCity": "sf", "ShippingState": "fsfs", "ShippingPostalCode": "fsfssf", "ShippingCountry": "sffsnull", "ShippingLatitude": null, "ShippingLongitude": null, "ShippingGeocodeAccuracy": null, "ShippingAddress": { "city": "sf", "country": "sffsnull", "geocodeAccuracy": null, "latitude": null, "longitude": null, "postalCode": "fsfssf", "state": "fsfs", "street": "sdf" }, "Phone": "89845552321", "Fax": "5754545585544", "AccountNumber": null, "Website": "hi-triuto.one", "PhotoUrl": "/services/images/photo/0012w000024KwDeAAK", "Sic": null, "Industry": "Automation", "AnnualRevenue": null, "NumberOfEmployees": 2, "Ownership": null, "TickerSymbol": null, "Description": "Test", "Rating": null, "Site": null, "OwnerId": "0052w00000CkYXHAA3", "CreatedDate": "2024-01-09T06:07:11.000+0000", "CreatedById": "0052w00000CkYXHAA3", "LastModifiedDate": "2024-08-29T06:53:52.000+0000", "LastModifiedById": "0052w00000CkYXHAA3", "SystemModstamp": "2024-08-29T06:53:52.000+0000", "LastActivityDate": "2024-05-01", "LastViewedDate": "2024-08-29T06:53:52.000+0000", "LastReferencedDate": "2024-08-29T06:53:52.000+0000", "Jigsaw": null, "JigsawCompanyId": null, "CleanStatus": "Pending", "AccountSource": null, "DunsNumber": null, "Tradestyle": null, "NaicsCode": null, "NaicsDesc": null, "YearStarted": null, "SicDesc": null, "DandbCompanyId": null, "OperatingHoursId": null } } ``` 4. **Define the Mapping Logic:** Transforms the raw Salesforce response into the structure defined by your Unified API's response schema. ```json response .{ "id": Id, "owner": { "id": OwnerId }, "name": Name, "description": Description, "industry": Industry, "number_of_employees": NumberOfEmployees, "website": Website, "addresses": [ { "street_1": BillingStreet, "city": BillingCity, "state": BillingState, "postal_code": BillingPostalCode, "country": BillingCountry, "type": "billing" }, { "street_1": ShippingStreet, "city": ShippingCity, "state": ShippingState, "postal_code": ShippingPostalCode, "country": ShippingCountry, "type": "shipping" } ], "phone_numbers": [ { "number": Phone, "type": "phone" }, { "number": Fax, "type": "fax" } ], "last_activity_at": LastActivityDate, "created_at": CreatedDate, "updated_at": LastModifiedDate, "custom_fields": $sift($, function($v, $k) { $k ~> /__c$/i and $boolean($v) }) } ``` **Explanation:** - **id:** Maps Salesforce's `Id` to your API's `id`. - **owner:** Extracts `OwnerId` from Salesforce and nests it under `owner.id`. - **addresses:** Combines billing and shipping addresses into a single array, distinguishing them by type. - **phone_numbers:** Includes both `Phone` and `Fax` numbers with their respective types. - **custom_fields:** Filters and includes only custom fields from Salesforce that end with `__c` and have valid values. 5. **Check the Mapped (Result):** This is the result of your `Response Example` above transformed through the `Response Mapping`. Use it to verify that the mapping is correct. ```json { "id": "0012w000024KwDeAAK", "owner": { "id": "0052w00000CkYXHAA3" }, "name": "Truto-Archith-Test", "description": "Test", "industry": "Automation", "number_of_employees": 2, "website": "hi-triuto.one", "addresses": [ { "street_1": "5", "city": "BNGLR", "state": "KA", "postal_code": "560066", "country": "INDIA", "type": "billing" }, { "street_1": "sdf", "city": "sf", "state": "fsfs", "postal_code": "fsfssf", "country": "sffsnull", "type": "shipping" } ], "phone_numbers": [ { "number": "89845552321", "type": "phone" }, { "number": "5754545585544", "type": "fax" } ], "last_activity_at": "2024-05-01", "created_at": "2024-01-09T06:07:11.000+0000", "updated_at": "2024-08-29T06:53:52.000+0000", "custom_fields": { "truto__Custom_Alternate_Email__c": "Archith@truto.dev" } } ``` Once done, save your mapping by clicking on `Save`. This will save your Unified API mapping for the resource. You can test the Unified API created after connecting an [Integrated Accounts](/docs/guides/integrated-accounts/making-api-calls.md). ## **Static Mapping** Sometimes, an API endpoint always returns the same, unchanging data (like a predefined list of options or a fixed configuration). In such cases, instead of making unnecessary API calls to fetch the same static data every time, you can use **Static Mapping**. Static Mapping allows you to configure a response directly in the Unified API, so the response is sent without actually making any API calls. This is especially useful for **list** or **get** endpoints where the data doesn't change often or at all - you can enable **Static Mapping** for these methods. ### **How to Enable Static Mapping** 1. **Navigate to the Response Mapping Tab** - Go to the resource you're working on (e.g., `/list-options` or `/configurations`). - Open the **Response Mapping** section for that resource. 2. **Enable Static Mapping** - Look for the **Static Mapping** toggle. - Turn it **on** to activate static mapping for this resource. 3. **Define the Static Response** - Once enabled, you can define the static response that will be returned every time this endpoint is called. - Example: ```json { "options": [ { "id": 1, "name": "Option A" }, { "id": 2, "name": "Option B" }, { "id": 3, "name": "Option C" } ] } ``` Once enabled, it should look like : ![Static Mapping](/images/unified-apis/static-mapping.png) 4. **Save Your Configuration** - Save your changes, and the Unified API will now return the static response whenever this endpoint is called. --- ### **When to Use Static Mapping?** - **List or Get Endpoints:** For endpoints that return predefined or rarely changing data, such as dropdown options or fixed settings. - **No Backend Dependency:** If you don't want the response to rely on a API call. - **Faster Responses:** Reduces latency since no actual API request is made. ## Error Mapping In case the underlying API returns an error, you can define a custom mapping to standardize the error structure for your Unified API consumers. ### Configure Error Mapping 1. Go to **Error Mapping**: - Click on the **Error** tab. 2. **Error Example** (JSON): ```json { "message": "Something went wrong", "errorCode": 4001 } ``` ### Error Mapping Error mapping should return an object that includes the following: - **Error Message (`message`)**: The main error message describing what went wrong. - **Metadata (`metadata`)**: Optional additional details about the error, such as timestamps, request IDs, or other context. - **Status (`status`)**: Optional HTTP status code associated with the error, e.g., 400 for a bad request or 500 for an internal server error. If you return a status below 400, the Unified API treats the call as a success and returns that status with `response` as the result. - **Response (`response`)**: Optional. The result to return when `status` is below 400. Any other keys are ignored. #### Example: ```json { "message": "Invalid input provided", "status": 422, "metadata": { "field": "email", "errorCode": "INVALID_EMAIL_FORMAT", "timestamp": "2025-01-24T12:34:56Z" } } ``` ![Error Mapping](/images/unified-apis/error-mapping.png) #### View Available Bindings Use platform-specific bindings to reference error details, status codes, etc. ### Mapped Error (Result) Applying your mapping to the example error might produce the following result: ```json { "message": "Invalid input provided", "metadata": { "field": "email", "errorCode": "INVALID_EMAIL_FORMAT" } } ``` ## Request Header Mapping You can define how your Unified API injects or transforms headers before sending them to the underlying API. The `headers` binding holds the headers Truto has prepared for that request; of the headers sent to the Unified API, only `content-type` is carried over, so custom headers on the Unified API call are not available here. Use `context`, `query` or `body` to source values instead. ### Configure Request Header Mapping 1. Go to **Request Header**: - Click on the **Request Header** tab. 2. **Request Header Example** (JSON): ```json { "x-truto-header": "abc123", "x-truto-custom-header": "myValue" } ``` This is sample `headers` input used to preview the mapping. ### Request Header Mapping - **The mapping should return an object** where the key-values contain the header name and the value. Example JSONata mapping: ```jsonata { "header": headers.`x-truto-header`, "customHeader": headers.`x-truto-custom-header` } ``` - **View available bindings**: Use platform-specific bindings to reference dynamic values if needed. - **Beautify JSONata** (optional): Prettifies the expression for easier readability. ### Mapped Header (Result) After applying your JSONata mapping, you’ll see a preview of what headers will be sent. The object you return is merged over the incoming `headers`. For example: ```json { "x-truto-header": "abc123", "x-truto-custom-header": "myValue", "header": "abc123", "customHeader": "myValue" } ``` ![Request Header Mapping](/images/unified-apis/request-mapping.png) ## Response Header Mapping You can define how headers returned by the underlying API are transformed or exposed back to the consumer of the Unified API. ### Configure Response Header Mapping 1. Go to **Response Header**: - Click on the **Response Header** tab. 2. **Response Header Example** (JSON): ```json { "some-internal-header": "some-value", "some-other-header": "sessionid=123456" } ``` ### Response Header Mapping - **The mapping should return an object** where the key-values contain the header name and the value. Example JSONata mapping: ```jsonata { "x-truto-header": headers.`some-internal-header` } ``` - The object you return is merged over the headers returned by the underlying API, and all header names are lowercased. Use it to add or overwrite headers; headers you leave out are still returned. ### Mapped Header (Result) For the example above, the mapping adds `x-truto-header` alongside the original headers: ```json { "some-internal-header": "some-value", "some-other-header": "sessionid=123456", "x-truto-header": "some-value" } ``` You’ll see the final headers that will be returned to the client in this preview. ![Response Header Mapping](/images/unified-apis/response-header-mapping.png) ## **Before Steps** Before Steps are actions that run **before** the main request is made by the Unified API. Think of Before Steps as a way to prepare your request with extra data, replace missing fields, or add logic to handle specific conditions. ### **How to Set Up Before Steps** 1. **Choose the Type of Step** There are three types of Before Steps you can configure: - **Request:** Fetch additional data. - **State:** Store the data for later use in `Before Steps`. - **Replace Data:** Set the step data to the result of an earlier step, by name. ### **Detailed Step Types** #### **1. Unified API (Fetch Additional Data)** Use this step to call another Unified API resource and fetch additional data before the Unified API call. - **When to Use It:** If your request requires data from another resource, like fetching interview details before querying candidates. - **Setup:** - **Name:** Enter a name for the step. Example: `Fetch Interview Details` - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (Optional):** Add a **JSONata expression** to decide whether the step should run. Example: ```jsonata $exists(query.interview_id) ``` This step will run only if `interview_id` exists in the query. - **Is JSONata Expression?:** Enable this to specify a `JSONata` expression for the `Request`. You should specify the following attributes in the `JSONata` expression : - `resource` - The name of the resource to call - `method` - The method which can be a **get**, **list**, **create**, **update**, **delete** - `type` - The type of the request, `unified` or `proxy`. Defaults to `unified`. - `config` - An object with the `id`, `query` and `body` to send with the request. Return an array of these objects to make several requests in parallel; the step result is then an array of their results. Example: ```jsonata { "resource": "interviews", "method": "get", "type": "unified", "config": { "id": query.interview_id } } ``` You can also use the available [Before/After JSONata Bindings](/docs/guides/unified-apis/mapping-bindings#before-after-steps) to send, access, and modify `body`, `query` or `id` values. Alternatively, you can select the following options : - **Request Type:** Select the `Unified` or `Proxy` API. - **Resource to Fetch:** Select the resource (e.g., `interviews`). - **Method to Call:** Choose the method (e.g., `get` or `list`). - **Enter ID (if needed):** Provide the ID for the resource to fetch. Used in `get` methods. - **Query Parameters:** Add any parameters needed in JSON format. Example: ```json { "include_details": true } ``` - **Request Body (if applicable):** Specify the body in JSON format. --- #### **2. State** Use this to store the data for later use in `Before Steps`. - **Setup:** - **Name:** Enter a name for the step. Example: `Set Default Priority` - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (JSONata):** Provide a JSONata expression that returns `true` or `false` to determine whether the step should run. Example: ```jsonata $not($exists(query.priority)) ``` This step will run only if the `priority` field is missing. --- #### **3. Replace Data** Use this step to set the data passed along the Before Steps to the result of an earlier step. - **Setup:** - **Name:** Enter a name for the step. - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (JSONata):** Provide a JSONata expression that returns `true` or `false` to determine whether the step should run. - **State Name:** Specify the name of the earlier step whose result becomes the data. The `Before Steps` screen looks like - ![Before Steps](/images/unified-apis/before-steps.png) ## **After Steps** After Steps are actions that run **after** the main request is made by the Unified API. Think of After Steps as a way to modify your request with extra data, replace missing fields, or add logic to handle specific conditions before returning the data to the user. ### **How to Set Up After Steps** 1. **Choose the Type of Step** There are three types of After Steps you can configure: - **Request:** Fetch additional data. - **State:** Store the data for later use in `After Steps`. - **Replace Data:** Set the step data to the result of an earlier step, by name. ### **Detailed Step Types** #### **1. Unified API (Fetch Additional Data)** Use this step to call another Unified API resource and fetch additional data after the Unified API call. - **When to Use It:** Say, for example, in a `PATCH` request, if the underlying API only returns the `id` of the updated resource, you can use after steps to fetch the complete details. After the PATCH request is processed, an after step can make a GET call to retrieve the full resource data and return the complete response to the user - **Setup:** - **Name:** Enter a name for the step. Example: `Fetch Interview Details` - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (Optional):** Add a **JSONata expression** to decide whether the step should run. - **Is JSONata Expression?:** Enable this to specify a `JSONata` expression for the `Request`. You should specify the following attributes in the `JSONata` expression : - `resource` - The name of the resource to call - `method` - The method which can be a **get**, **list**, **create**, **update**, **delete** - `type` - The type of the request, `unified` or `proxy`. Defaults to `unified`. - `config` - An object with the `id`, `query` and `body` to send with the request. Return an array of these objects to make several requests in parallel; the step result is then an array of their results. Example: ```jsonata { "resource": "interviews", "method": "get", "type": "unified", "config": { "id": query.interview_id } } ``` You can also use the available [Before/After JSONata Bindings](/docs/guides/unified-apis/mapping-bindings#before-after-steps) to send, access, and modify `body`, `query` or `id` values. Alternatively, you can select the following options : - **Resource to Fetch:** Select the resource (e.g., `interviews`). - **Method to Call:** Choose the method (e.g., `get` or `list`). - **Enter ID (if needed):** Provide the ID for the resource to fetch. Used in `get` methods. - **Query Parameters:** Add any parameters needed in JSON format. Example: ```json { "include_details": true } ``` - **Request Body (if applicable):** Specify the body in JSON format. --- #### **2. State** Use this to store the data for later use - **Setup:** - **Name:** Enter a name for the step. Example: `Set Default Priority` - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (JSONata):** Provide a JSONata expression that returns `true` or `false` to determine whether the step should run. Example: ```jsonata $not($exists(query.priority)) ``` This step will run only if the `priority` field is missing. --- #### **3. Replace Data** Use this step to set the data passed along the After Steps, which becomes the Unified API response, to the result of an earlier step. - **Setup:** - **Name:** Enter a name for the step. - **Run Conditionally:** Enable this to only run the step when needed. - **Run If (JSONata):** Provide a JSONata expression that returns `true` or `false` to determine whether the step should run. - **State Name:** Specify the name of the earlier step whose result becomes the data. The `After Steps` screen looks like - ![After Steps](/images/unified-apis/after-steps.png) ## Truto Notes This section is a space where the Truto team jots down important details, limitations, and potential pitfalls specific to this resource in our Unified Model. You can also add details here to note important details. ### What You Can Write Here - **Key Characteristics**: Describe what makes this resource unique or any quirks it might have. This helps set expectations and provides context. - **Usage Tips**: Share simple tips and best practices on how to use this resource effectively. For example, mention common pitfalls or suggest smoother ways to handle certain tasks. - **Limitations**: Point out any known limitations or constraints. If the underlying API has restrictions that affect this resource, note them here in plain language. - **Troubleshooting Advice**: Offer friendly guidance on what to do if things don't work as expected. This can include hints on where to look for errors or how to fix common issues. - **Reminders and Warnings**: Add any reminders or gentle warnings that can help users avoid mistakes or understand important considerations when interacting with the resource. - **General Observations**: Write down observations or thoughts that might be useful for anyone working with or maintaining this resource in the future. ![Truto Notes](/images/misc/truto-notes.png) --- # Webhooks Overview > Source: https://truto.one/docs/guides/webhooks/overview/ Truto provides webhooks which can notify you of interesting events happening in your Truto account. They can also notify you about changes happening in the third party app integrations where Truto receives the webhook events from the integrations and proxies them to your endpoint in a unified format as `record:*` events. > [Webhooks API reference](/docs/api-reference/admin/webhooks/list) ## Webhook endpoints ### HTTPS and POST Use an HTTPS URL for every webhook endpoint so event payloads are encrypted in transit. The endpoint must accept the POST method. Each environment has a limit on the number of webhooks it can hold. Creating one past the limit returns a `400` error. ## Security ### SHA256 Signature Every request made to a webhook endpoint has `x-truto-signature` header which contains the SHA256 HMAC of the request body being sent. This helps you make sure that the requests are originating from Truto. The SHA256 HMAC uses a `secret` string (UUID) which is shared with you when the webhook is created. See [creating webhook endpoint](/docs/api-reference/admin/webhooks/create). To prevent replay attacks, you can check the `created_at` attribute of the request body and ignore the webhook event if it's longer than a certain timeframe, there is also a unique `id` in the request body for each webhook event. > See [verifying webhook events](/docs/guides/webhooks/processing-webhook-events#verification-of-the-webhook-event) ## Retries Webhook endpoints need to respond with any `2XX` status code. Truto makes up to five delivery attempts: one immediately, then retries after 30 seconds, 1 minute, 1.5 minutes, and 2 minutes, all inside a five-minute window. After the last attempt the event is marked as failed. Network errors and other non-`2XX` responses are retried. `400`, `404`, and `413` responses are treated as permanent and are not retried. ## Logging Every webhook delivery is logged. View deliveries in the Truto dashboard under **Logs → Webhook**, or fetch them with `GET /log?log_type=webhook`. --- # Processing webhook events > Source: https://truto.one/docs/guides/webhooks/processing-webhook-events/ General guidelines for processing Truto webhook events. ## Webhook event payload structure The webhook event is a JSON object with the following properties. When a sync job sends file contents as `sync_job_run:record` records, the same fields arrive as a `multipart/form-data` body instead. ### Body - `id` is the unique ID for the webhook event. - `event` is the name of the event. E.g, `integrated_account:created`. It's in the format `truto_entity:action`, where `truto_entity` can be a resource in Truto and `action` can be `created`, `updated`, `deleted`, etc. - `payload` is the data associated with the action. In most cases, it will be updated resource. For `record:*` events it holds `resource`, `records`, `integrated_account_id`, `raw_event_type`, and `raw_payload` (the event as the integration sent it). - `environment_id` is the environment this webhook event is associated with. - `created_at` is the time when this webhook event was generated. - `webhook_id` is the ID of the webhook associated with this event. An example webhook event sent when a new integrated account is connected is shown below, ```json { "id": "3a0da6ba-b2d1-473f-957c-51f6825e3623", "event": "integrated_account:created", "payload": { "id": "79a39d69-e27e-49cb-b9a9-79f5eea7aa26", "tenant_id": "acme-1", "environment_integration_id": "27a8c0ff-0c2e-4383-b651-0772b3515921", "context": {}, "created_at": "2023-06-16T09:21:21.000Z", "updated_at": "2023-06-16T09:21:21.000Z", "is_sandbox": false, "unified_model_override": {}, "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c177", "integration": { "id": "1fa47bf3-5f1f-4b65-bcd0-8d07ab455e15", "name": "helpscout", "config": { "label": "Help Scout" } }, "environment_integration": { "id": "27a8c0ff-0c2e-4383-b651-0772b3515921", "integration_id": "1fa47bf3-5f1f-4b65-bcd0-8d07ab455e15", "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c177", "show_in_catalog": true, "is_enabled": true, "created_at": "2023-02-16T09:27:16.000Z", "updated_at": "2023-02-16T09:27:16.000Z" } }, "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c177", "created_at": "2023-06-16T09:21:22.369Z", "webhook_id": "077ec306-5756-43fa-9a06-0cc0da4eabe0" } ``` ### Header For security, Truto adds a `X-Truto-Signature` header which contains the URL-safe Base64 encoded SHA256 HMAC of the raw request body, without `=` padding. For the request body shown above, the following header will be added to the request, ```http request X-Truto-Signature: format=sha256,v=WDHLSeu0EEcUf9YV5N659YZ9EFOnfuIOrLj8UMBDhOo ``` ## Verification of the webhook event You can get the SHA256 HMAC in the `v` part of the header value and do the following steps to make sure the webhook event is legit and sent from Truto, 1. Store the `v` value sent as part of `X-Truto-Signature` header. `WDHLSeu0EEcUf9YV5N659YZ9EFOnfuIOrLj8UMBDhOo` in the example above. 2. Calculate the SHA256 HMAC of the request body using the `secret` attribute returned to you when you had created the webhook. **IMPORTANT**: Please use the raw bytes received as the body and not the JSON parsed version of it that most frameworks return you in the middleware function. For `multipart/form-data` deliveries, sign the raw multipart body exactly as received. 3. Calculate the Base64 encoded version of the data calculated in step 2. Make sure that the Base64 encoding is URL safe (`-` and `_` in place of `+` and `/`) and has no `=` padding. 4. Compare the value obtained in step 3 with the value stored in step 1. They should be equal. If they are not, then the payload has been tampered with and the webhook event is not generated by Truto. :::code-tabs ```js label="Node.js" const crypto = require("crypto"); function verifyWebhook(headerValue, secret, body) { // Reject requests without a signature header if (typeof headerValue !== "string" || !headerValue.includes("v=")) { return false; } // Get HMAC from header const hmacFromHeader = Buffer.from(headerValue.split("v=")[1]); // Calculate the SHA256 HMAC of the request body, URL-safe Base64 without padding const calculatedHmac = Buffer.from( crypto.createHmac("sha256", secret).update(body).digest("base64url") ); // timingSafeEqual throws when lengths differ if (hmacFromHeader.length !== calculatedHmac.length) { return false; } return crypto.timingSafeEqual(hmacFromHeader, calculatedHmac); } // Note: You need to pass the raw body of the webhook request to the verifyWebhook function. If you are using Express.js, you can get the raw body like this: app.use( bodyParser.json({ verify: function (req, res, buf) { req.rawBody = buf; }, }) ); // And then in your route: app.post("/webhook", (req, res) => { let isVerified = verifyWebhook( req.headers["x-truto-signature"], secret, req.rawBody ); console.log(isVerified ? "Webhook Verified" : "Webhook Verification Failed"); }); ``` ```csharp label="C#" public static bool VerifyWebhook(string headerValue, string secret, string body) { // Get HMAC from header var hmacFromHeader = Encoding.UTF8.GetBytes(headerValue.Split("v=")[1]); var secretBytes = Encoding.UTF8.GetBytes(secret); var bodyBytes = Encoding.UTF8.GetBytes(body); // Calculate the SHA256 HMAC of the request body var hmac = new HMACSHA256(secretBytes); var calculatedHmac = hmac.ComputeHash(bodyBytes); var base64OfCalculatedHmac = Convert.ToBase64String(calculatedHmac); string urlSafeBase64String = base64OfCalculatedHmac.Replace('+', '-').Replace('/', '_').TrimEnd('='); var generatedBytes = Encoding.UTF8.GetBytes(urlSafeBase64String); return CryptographicOperations.FixedTimeEquals(hmacFromHeader, generatedBytes); } ``` ::: --- # Creating a webhook through API > Source: https://truto.one/docs/guides/webhooks/creating-a-webhook-through-api/ To create a webhook in Truto, call the webhook create endpoint. An example webhook create request would look something like, ```bash curl --location 'https://api.truto.one/webhook' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "target_url": "https://webhook.site/6a7cc86e-9286-4be8-ba79-bcd8dfdbeee1", "is_active": true, "event_types": ["integrated_account:created"] }' ``` In the example request above, - `target_url` is the webhook endpoint where a POST request with the webhook payload as the request body will be made. - `is_active` is an optional field which specifies if the `target_url` should receive webhook events. - `event_types` is an array of webhook event types that the `target_url` should receive data for. It is optional and if not mentioned in the request, then the `target_url` will receive data for all webhook event types. The request should yield a response like so, ```json { "id": "b6d29b9b-3d9d-44fd-aa77-512fd83b28c1", "target_url": "https://webhook.site/6a7cc86e-9286-4be8-ba79-bcd8dfdbeee1", "secret": "6e17561c-a20c-44ce-b8b5-caff0bf786fe", "is_active": true, "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c199", "event_types": ["integrated_account:created"], "created_at": "2023-06-15T14:40:03.000Z", "updated_at": "2023-06-15T14:40:03.000Z" } ``` - `event_types` lists the subscribed event types. It is `["all"]` when the request did not specify any. - `secret` is returned only in this response. Fetching or listing webhooks later does not include it, so store it securely now. It must be used to verify the webhook event's signature, which can be found `X-Truto-Signature` header of the request body of the webhook event. The `secret` is unique to each webhook that you create. See [verifying webhook events](/docs/guides/webhooks/processing-webhook-events#verification-of-the-webhook-event). ## Send test event To send a test event to the webhook, call the webhook send test event endpoint. ```bash curl --location 'https://api.truto.one/webhook/test' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "id": "b6d29b9b-3d9d-44fd-aa77-512fd83b28c1", "event_type": "integrated_account:created" }' ``` - `id` is the ID of the webhook to send the test event to. - `event_type` is optional and defaults to `integrated_account:created`. It can be any event type from the [list of webhook event types](/docs/guides/webhooks/list-webhook-events) except `all`. - `integrated_account_id` is optional. When set, the test payload is built from that integrated account, which must belong to the webhook's environment. - `payload` is an optional object merged into the generated test payload. A successful test returns the event that was sent, ```json { "success": true, "event_type": "integrated_account:created", "payload": { ... } } ``` If your endpoint responds with a non-`2XX` status code, the request fails with a `500` error whose message includes the status code and response body your endpoint returned. ## API Reference Refer [Webhooks API reference](/docs/api-reference/admin/webhooks/list) for all the endpoints. --- # Creating a webhook > Source: https://truto.one/docs/guides/webhooks/creating-a-webhook-through-ui/ To create a webhook in Truto, follow these step-by-step instructions: **1. Navigate to the Webhooks Screen** Log in to your Truto account and navigate to the “Webhooks” section of the dashboard. ![Webhook Page](/images/webhooks/webhook-page.png) **2. Start Creating a Webhook** In the top right corner of the Webhooks screen, click on the **“Create Webhook”** button. ![Creating a Webhook](/images/webhooks/creating-a-webhook.png) **3. Fill Out the Webhook Details** A popup form will appear titled “Create a webhook” with several required fields: - **Endpoint *:** Enter the URL where you want to receive webhook events, for example: `https://yourdomain.com/truto-webhook` - The URL must use HTTPS. - The endpoint must support the POST HTTP method. - **Environment *:** Choose the environment where the webhook should be created, usually “Default” unless you have multiple environments. - **Active:** Toggle this option to determine whether the webhook should actively receive events once created. - **Events *:** Select which events the webhook should listen for. Options typically include a broad range of event types such as: - All events (`all`) - Specific account events (e.g., `integrated_account:created`, `integrated_account:updated`, etc.) - Sync job events (e.g., `sync_job_run:started`, `sync_job_run:completed`, etc.) - Record events (e.g., `record:created`, `record:updated`, etc.) - Batch job events and more. Check off the events that are relevant to your use case. You can select “all” if you want to receive every possible event. ![Creating a Webhook page](/images/webhooks/creating-a-webhook-page.png) **4. Create the Webhook** After filling in the fields and selecting the desired events, click the **“Create Webhook”** button at the bottom of the popup. This will save and register your webhook with the selected configuration. The next screen shows the webhook's secret, which signs the `X-Truto-Signature` header. Copy it and store it securely, since it is not shown again. Check **"I have copied my webhook secret shown above"** to close the screen. **5. Test Your Webhook** Once the webhook is created: - Return to the landing page for the list of webhooks. - Find your newly created webhook. - Click on the three-dot menu (found next to the webhook entry). - Select **“Send Test Event”** to simulate an event and verify that your endpoint is correctly receiving and processing webhook data. ![Send test event](/images/misc/send-test-event.png) Your Truto webhook should be properly configured and ready to receive events now. --- # List of webhook event types > Source: https://truto.one/docs/guides/webhooks/list-webhook-events/ The webhook event types used in Truto. These values can be found in the `event` attribute of a webhook event. Subscribe a webhook to `all` to receive every event type listed below. ## Integrated accounts - `integrated_account:created` - A new integrated account is connected - `integrated_account:updated` - Integrated account is updated - `integrated_account:deleted` - Integrated account is deleted - `integrated_account:post_install_error` - Post install steps failed after an integrated account got connected. The integrated account will need re-authorization. - `integrated_account:validation_error` - If defined for the Installed integration, Connection validation steps defined for the integrated account failed. The integrated account will need re-authorization. - `integrated_account:active` - Integrated account is activated and ready to use - `integrated_account:post_connect_form_submitted` - If defined for the Installed integration, RapidForm has been submitted by the user. - `integrated_account:authentication_error` - Sent when there is an issue with refreshing the access token in case of OAuth authentication or the credentials are no longer valid for other authentication methods for an integrated account. - `integrated_account:reactivated` - This event is sent when an integrated account is moved to active state after it is in `needs_reauth` state. **Important:** This event will NOT be sent if you are [reauthenticating the integrated account](/docs/guides/integrated-accounts/reauthorizing-connections#reauthorizing-connections-in-an-integrated-account), it will only be sent if Truto detects that the integrated account didn't error out with 401 status code when calling the underlying integration's API, this can happen when proxy and unified APIs are called, or when Sync Jobs are run. This event is provided to handle transient authentication errors if any. - `integrated_account:forbidden_error` - A call made with the integrated account got a `403` from the underlying integration, for example because the connection is missing a required scope. The account stays `active`. ## Link tokens - `link_token:connection_error` - A connection attempt started from a link token failed before an integrated account was created, for example an OAuth authorization error. ## Installed integrations - `environment_integration:created` - An integration is installed in the environment - `environment_integration:updated` - An installed integration is updated - `environment_integration:deleted` - An installed integration is removed from the environment ## Environment unified models - `environment_unified_model:created` - A unified model is added to the environment - `environment_unified_model:updated` - A unified model in the environment is updated - `environment_unified_model:deleted` - A unified model is removed from the environment ## API tokens - `api_token:created` - An API token is created - `api_token:updated` - An API token is updated - `api_token:deleted` - An API token is deleted ## Sync Job Run - `sync_job_run:created` - A new sync job run is created - `sync_job_run:started` - Sync job run has started - `sync_job_run:record` - Webhook containing the records fetched from a resource during the sync job run - `sync_job_run:completed` - Sync job run has completed - `sync_job_run:failed` - Sync job run has failed - `sync_job_run:updated` - Sync job run has been updated - `sync_job_run:deleted` - Sync job run has been deleted - `sync_job_run:record_error` - Fetching records from a resource failed during the sync job run - `sync_job_run:rate_limited` - The underlying integration rate limited a request during the sync job run ## Sync job cron triggers - `sync_job_cron_trigger:failed` - A sync job cron trigger could not start a new sync job run because the previous run has not completed yet ## Records Sent when webhooks have been setup for the underlying Integration. - `record:created` - A new record is created in the underlying integration. - `record:updated` - Record is updated in the underlying integration. - `record:deleted` - Record is deleted in the underlying integration. - `record:meta` - The underlying integration sent a non-record event, such as a subscription lifecycle notification. `records` is empty. ## Batch jobs - `batch_job:dry_run_completed` - A batch job dry run has completed - `batch_job:completed` - A batch job has completed - `batch_job:dry_run_failed` - A batch job dry run has failed - `batch_job:failed` - A batch job has failed --- # Overview > Source: https://truto.one/docs/guides/environments/overview/ Every Truto team gets three environments — `development`, `staging`, and `production` — and they share nothing on the data plane. An API token issued in `staging` can't see an integrated account in `production`, and a method you add to an integration in `development` doesn't exist in the other two until you add it there as well. ## What are Environments? An environment is the boundary around one set of installed integrations, the integrated accounts connected to them, the API tokens that authenticate calls against them, the webhooks that fire on them, and any per-integration overrides — Unified API mappings, custom proxy methods, custom resources — that you've layered on top. Pick which environment a request runs against by using that environment's API token; for the few Admin API calls that accept it explicitly, you can also pass `environment_id`. ## API Tokens are specific to an environment Every API token is created inside one environment and only resolves resources from that environment. Listing accounts with a `staging` token returns staging accounts; the same call with a `production` token returns production accounts, and there's no token shape that spans both. On any data-plane call, `environment_id` is inferred from the token automatically — you don't pass it as a query parameter. Create and revoke tokens per environment from [Settings → API Tokens](/docs/guides/api-tokens/creating-api-tokens). ## Integrated accounts are specific to an environment When your customer connects an account through Truto Link, the resulting integrated account belongs to whichever environment minted the link token. Running the same connection flow against a different environment creates a separate integrated account with a separate `integrated_account_id`. The customer connects once per environment they're meant to appear in. [Tenants](/docs/guides/tenants/overview) sit inside the environment scope too: the same `tenant_id` value can exist in `development`, `staging`, and `production` as three separate tenants with three separate sets of connected accounts. ## FAQ **My new method works locally but 404s in production.** Methods you add to an integration — and any other integration override (unified-model mappings, custom proxy methods, custom resources, auth-field tweaks) — live on one environment only. If you added it in `development`, `production` doesn't have it yet. Re-apply the change against the production environment's installed integration. **Can I create more than three environments?** Email [support@truto.one](mailto:support@truto.one) — environment creation isn't self-serve in the dashboard. --- # Overriding OAuth credentials > Source: https://truto.one/docs/guides/integrations/overriding-oauth-credentials/ We understand that you may want to customize the way your users give your application permission to access their data. This process is known as authorization. In Truto, you can customize this authorization process by overriding OAuth credentials. Let's simplify this for you. ## What does 'Overriding OAuth Credentials' mean? OAuth (Open Authorization) is a standard that apps use to provide client applications with 'secure delegated access'. It's like a virtual handshake between the online platforms. Overriding OAuth credentials in Truto is akin to setting the terms of this virtual handshake yourself. ### Customizing OAuth Details In Truto, you have the power to customize or change the OAuth details, such as the Client ID and Client Secret. Think of these as unique identifiers for your application. Changing these details is like giving your application a new identity. ### Defining Your Own Scopes 'Scopes' in OAuth determine what kind of access you're giving to your application. It's like defining the boundaries for your application's reach. In Truto, you can define these scopes according to your needs by looking into integrations API documentation for allowed scopes and how to add them. ### The Result of Overriding OAuth Credentials When you override the OAuth credentials, your customers will see an OAuth app asking for authorization from the application created by you, not the standard Truto process. This means they'll be interacting with the identity and boundaries you've set, creating a more personalized and secure experience for your users. ## Until the app is configured Some integrations ship with no OAuth app of Truto's own — their client id is a placeholder until you supply yours here. Until you do, such an integration is left out of the connect UI and the connections widget, and reauthorizing an existing account on it is refused with `400` and `truto_error_code: app_credentials_not_configured` when no other sign-in method can connect it (see [Reauthorizing connections](/docs/guides/integrated-accounts/reauthorizing-connections#when-the-token-is-refused)). Integrations where the end user types the client id on the connect form are not affected. AWS STS integrations work the same way with their own toggle: **Configuration** tab → **Use your own signing credentials**, where you enter the IAM access key pair that signs `AssumeRole`. The API's refusal message calls both places *Integration Settings*. ## Install an integration Before overriding the OAuth credentials for an integration, make sure to install it from `Available Integrations`. You can check the documentation for installing an integration [here](https://truto.one/docs/guides/integrations/overview#installing-an-integration). ## Steps to Overriding OAuth 1. Click on `Integrations` and select the integration you want for overriding OAuth in `Installed` integrations. ![Find installed integration](/images/integrations/integrations.png) 2. Open the **Configuration** tab and toggle **Use your own OAuth settings**. Add the Redirect URL from Truto to the OAuth app you created, then enter your `Client ID`, `Client Secret`, and `Scopes` (if you need to define them) from that app. ![Change details for OAuth App](/images/integrations/override-oauth-details.png) 3. Click on `Save` after adding the details mentioned above. 4. Voila! You should now see that `Save` is disabled. You can now use your OAuth App. ## Use a redirect URL on your own domain By default, the provider sends your users back to Truto's callback, for example `https://api.truto.one/connect/hubspot/callback`. Some providers show this URL on their consent screen, and some app reviews ask for a URL on your own domain. You can use your own URL instead, for each installed integration. :::callout{type="warning"} This works only for OAuth 2.0 integrations that use your own Client ID and Client Secret. Truto's OAuth app accepts only Truto's callback, so Truto will not save a custom redirect URL until you add your own credentials. ::: ### 1. Add a redirect page on your domain Your URL must send the browser on to Truto's callback with a redirect. Keep the query string exactly as it came in: the provider puts the `code` and `state` there, and Truto needs both. - The URL must use `https`. - The URL cannot have a `#` fragment. We recommend that you change only the domain, and keep Truto's path: | | URL | |---|---| | Truto's callback | `https://api.truto.one/connect/hubspot/callback` | | Your URL | `https://auth.example.com/connect/hubspot/callback` | Then one redirect rule works for every integration: send the browser to `api.truto.one` with the same path and query string. When you add another integration later, you do not have to change the rule. Truto's callback for each integration shows in the `Redirect URL` field. ![Redirect URL field showing Truto's callback](/images/integrations/redirect-url-default.png) Use a temporary redirect (`302` or `307`), so browsers do not cache it. For example: :::code-tabs ```nginx label="Nginx" location ~ ^/connect/[^/]+/callback$ { return 302 https://api.truto.one$request_uri; } ``` ```apache label="Apache" # .htaccess or the site config RewriteEngine On RewriteRule ^/?connect/([^/]+)/callback$ https://api.truto.one/connect/$1/callback [R=302,L] ``` ```txt label="Caddy" # Caddyfile @trutoCallback path_regexp ^/connect/[^/]+/callback$ redir @trutoCallback https://api.truto.one{uri} 302 ``` ```js label="Cloudflare" // Cloudflare Worker export default { fetch(request) { const { pathname, search } = new URL(request.url) if (!/^\/connect\/[^/]+\/callback$/.test(pathname)) { return new Response('Not found', { status: 404 }) } return Response.redirect(`https://api.truto.one${pathname}${search}`, 302) }, } ``` ```json label="Vercel" { "redirects": [ { "source": "/connect/:integration/callback", "destination": "https://api.truto.one/connect/:integration/callback", "permanent": false } ] } ``` ```txt label="Netlify" # _redirects /connect/:integration/callback https://api.truto.one/connect/:integration/callback 302 ``` ```js label="Next.js" // next.config.js module.exports = { async redirects() { return [ { source: '/connect/:integration/callback', destination: 'https://api.truto.one/connect/:integration/callback', permanent: false, }, ] }, } ``` ```js label="Express" app.get('/connect/:integration/callback', (req, res) => { res.redirect(302, `https://api.truto.one${req.originalUrl}`) }) ``` ::: On Vercel, the rule goes in `vercel.json`. ### 2. Register the URL in your OAuth app In the provider's developer console, add your URL as an allowed redirect URL (it is sometimes called a callback URL) in your OAuth app. You can keep Truto's callback in the list too. ### 3. Set the URL in Truto 1. Open the installed integration and turn on `Use your own OAuth settings`. 2. Add your `Client ID` and `Client Secret`. 3. In `Redirect URL`, replace `api.truto.one` with your domain. Keep the rest of the URL. 4. Click `Save`. ![Redirect URL field with a URL on your own domain](/images/integrations/redirect-url-custom.png) You can also set the URL in the install dialog and on the integration's `Authentication` tab. If you enter a URL before you add your own Client ID, a `Needs your own OAuth app` warning shows, and `Save` is refused until you add one. ![Needs your own OAuth app warning under the Redirect URL field](/images/integrations/redirect-url-needs-own-app.png) To go back to Truto's callback, click `Revert to original` under the field, or clear the field. Then click `Save`. ### What changes - Truto sends your URL on the authorize step and on the token exchange. Where the integration also sends a redirect URL when it refreshes a token, Truto sends yours there too. - New connections and reconnections use your URL. Accounts that are already connected keep their tokens. - The URL applies only to this environment. Other environments keep their own settings. - OAuth 1.0 integrations always use Truto's callback. ### Set the URL with the API The URL is stored in the environment integration's `override`, at `credentials.oauth2.config.params.redirect_uri` (the authorize step) and `credentials.oauth2.config.tokenParams.redirect_uri` (the token exchange). Set both to the same URL, or the provider rejects the code. `PATCH /environment-integration/{id}` replaces the whole `override`. So first get the environment integration, add the two keys to its `override`, and send the full `override` back. A Client Secret you leave out is kept. ```json { "override": { "credentials": { "oauth2": { "config": { "client": { "id": "your-client-id" }, "params": { "redirect_uri": "https://auth.example.com/connect/hubspot/callback" }, "tokenParams": { "redirect_uri": "https://auth.example.com/connect/hubspot/callback" } } } } } } ``` The API does not check that the override has your own Client ID. Set one, or every connection fails with a `redirect_uri_mismatch` error. ## To Summarize Overriding OAuth Credentials in Truto is all about customization. It gives you the power to modify the OAuth details and define the scopes, which results in a unique and personalized authorization experience for your users. It's another way Truto helps you make your interaction with APIs a smooth and efficient process. --- # Truto-generated key pairs > Source: https://truto.one/docs/guides/integrations/generated-key-pairs/ Some providers let a service account sign in with a key pair. You install a public key with the provider. The client then proves who it is by signing a short-lived token, a JWT, with the matching private key. With a Truto-generated key pair, Truto makes that key pair for each connection. Your end user only ever sees the public key, and installs it with the provider. The private key is encrypted, never leaves Truto, and only Truto's JWT signer can read it. Nobody has to create, store or paste a private key. Snowflake's **Key pair (service user)** method works this way. See the [Snowflake guide](/docs/integration-guides/snowflake) for what your end users see. ## How a connection is made 1. The user picks the method on the connect screen. Truto makes the key pair then, once per connection link, and shows the public key in the method's instructions. 2. The user installs the public key with the provider, for example by running SQL the instructions show, then clicks **Connect**. 3. The connect screen sends back the fingerprint of the key it showed. If that is not the key Truto holds for the link (a waiting key lasts 7 days), Truto refuses, and the screen loads the current key and asks the user to install it. 4. Truto stores the key pair on the connection, and signs a JWT with the private key for the provider's API. It signs a new one before the old one expires. A reconnect that keeps the method shows the key the connection already has, so nothing needs reinstalling. Only a key that waits for its link asks the user to keep the window open: a screen opened on another link would show another key. ## Configure the credential A key pair is declared in a credential's `generated_fields`, and used by a `jwt_bearer` credential. This is the shape of Snowflake's: ```json { "jwt_bearer": { "format": "jwt_bearer", "config": { "label": "Key pair (service user)", "generated_fields": [ { "name": "snowflake_key", "type": "rsa_key_pair", "modulus_length": 2048 } ], "signing": { "id": "", "generated": "snowflake_key" }, "jwt": { "algorithm": "RS256", "expires_in": 3300, "claims": {}, "claims_expression": "( $acct := $uppercase($substringBefore($substringAfter(context.base_url, \"://\"), \".\")); $user := $uppercase($trim(context.snowflake_user)); { \"iss\": $acct & \".\" & $user & \".\" & signing.public.fingerprint, \"sub\": $acct & \".\" & $user } )" }, "fields": [ { "name": "base_url", "label": "Snowflake Account URL", "type": "text", "required": true }, { "name": "snowflake_user", "label": "Service user login name", "type": "text", "required": true } ], "permissions_text": "Add this public key to {{form.snowflake_user}}:\n\n```sql\nALTER USER {{form.snowflake_user}} ADD KEY PAIR TRUTO_{{snowflake_key.key_id_short}} PUBLIC_KEY = '{{snowflake_key.public_key}}';\n```\n\nFingerprint: `{{snowflake_key.fingerprint}}`" } } } ``` Snowflake wants `iss` to be `ACCOUNT.USER.SHA256:` and `sub` to be `ACCOUNT.USER`, with the account and the user in upper case. The expression takes the account from the first part of the account URL's host, `myorg-myaccount` in `https://myorg-myaccount.snowflakecomputing.com`, so an account locator URL loses its region the way Snowflake expects. A claim without the account is refused by Snowflake. ### `generated_fields` entry | Key | What it is | | --- | --- | | `name` | Where the public half is stored on the connection (`context.`), and the start of its placeholders. Letters, digits and underscores, not starting with a digit or with `truto_`. It cannot be a name Truto keeps secrets under (`api_key`, `token`, `oauth`, `secret`, `generated_secrets` and the like), or the name of one of the credential's `fields`. | | `type` | `rsa_key_pair`. `generated_fields` also takes `uuid`, which stores a random UUID under `name`, with an optional `prefix`; it is not a key pair. | | `modulus_length` | Key size in bits: `2048` (the default), `3072` or `4096`. | A key pair cannot be declared on a credential that connects through a browser redirect, such as a `jwt_bearer` or `oauth2_client_credentials` credential with `auth.authorizeHost`: that flow has no connect screen to show the key on. An environment override that sets `generated_fields` replaces the integration's list rather than adding to it, like every other array in an override, so it has to repeat every key pair the integration declares. Truto refuses an override that would leave `signing.generated` naming a key pair the credential no longer declares. A connection's own `integration_override` cannot declare a key pair or set `signing.generated`. On an integration with a key-pair method, it also cannot add or change anything that method could use: anything outside `credentials` (a base URL, a resource, an authorization), or that method's own credential. Those parts can only be removed, all of them or some. Another method's credentials can still be overridden. ### `signing.generated` The `name` of the key pair the JWT is signed with. The signer reads the private key directly; it is never reached through a `{{…}}` placeholder. When `generated` is set, `signing.key` is ignored. A JWT signed with a generated key lives at most an hour, so `jwt.expires_in` can be at most `3600`. The key is an RSA key, so `jwt.algorithm` must be `RS256`, `RS384`, `RS512`, `PS256`, `PS384` or `PS512`. Truto refuses a config that breaks either rule, and refuses to sign with one. ### `jwt.claims_expression` A JSONata expression that returns an object of claims, merged over `jwt.claims`. It runs over: ```json { "context": "the connection's context, without any private key", "signing": { "id": "signing.id", "public": { "fingerprint": "…", "public_key": "…", "key_id": "…" } } } ``` It is never placeholder-substituted, so a value the user typed cannot change the expression. Truto sets `iat` and `exp` itself, after the expression runs, from `jwt.expires_in`. If the expression fails, the error says only that it failed and gives JSONata's error code, so nothing from the context ends up in an error message. ### `requires_static_gate` When `true`, a connection must have a `truto_static_gate_id`. Use it for a provider whose network policy admits only Truto's Static Gate IP addresses: a connection without the gate could never make a call. Truto refuses: - a connect without one, and the connect screen says so before it shows a key, so nobody installs a key that cannot connect; - `POST /integrated-account` without one in the `context`; - a `PATCH` that would take it away from a connection that has one. A link gets its gate from `truto_static_gate_id` when the link token is created, or from **Advanced settings → Static gate** in the dashboard's **Get connection link** dialog. A re-authorize link starts with the connection's own gate. ## Write the instructions `permissions_text` is markdown shown on the connect screen once the user picks the method. For a key-pair method it can use these placeholders: | Placeholder | Filled in with | | --- | --- | | `{{.public_key}}` | The public key as one line of base64 (DER SubjectPublicKeyInfo), with no PEM header. | | `{{.public_key_pem}}` | The public key in PEM form. | | `{{.fingerprint}}` | `SHA256:` followed by the base64 SHA-256 of the DER public key. | | `{{.key_id}}` | The key's random ID. | | `{{.key_id_short}}` | The first 8 characters of `key_id`, in upper case. Use it to name the key with the provider, so that installing the key of another connection does not clash with an old one. | | `{{form.}}` | What the user has typed into that field so far. | Truto fills in the key's placeholders before the screen gets the text. The connect screen fills in `{{form.}}` as the user types: - Only the plain form is supported: no fallbacks, defaults or type casts. - A field with nothing in it keeps its placeholder, so a half-filled form shows what is still missing. - The value is shown as Connect will save it: trimmed, with the field's own `transform` and the credential's `transform_expression` applied. - A `password` field is never filled in. Every code block in the instructions gets a **Copy** button. Write steps the user runs as code blocks, and make them safe to run twice: users close the window, reopen the link and run the steps again. In a numbered list, indent a code block under its step, or the numbering starts again at 1 after it. ## Replacing a key Truto does not rotate a connection's key yet. A reconnect that keeps the method keeps the key the connection already has. To move to a new key, connect a new account with a new connection link, then delete the old one. The new account has a new ID, and the old account's synced data goes with it when it is deleted. ## Accounts created through the API `POST /integrated-account` with a key-pair credential makes the key pair when it creates the account. The response carries the public half under `context.`. Nothing is signed with the key until something needs a token, so the account is created even though the provider does not have the key yet. For the same reason, the integration's post-install and validation actions wait. Install the key with the provider, then call `POST /integrated-account/run-post-install-actions` with the account's `id`: it runs those actions, as a connect does, and sends `integrated_account:active` once they pass. A request made before the key is installed fails. If the method has `requires_static_gate`, put `truto_static_gate_id` in the account's `context`. ## Why the private key cannot be read - It is encrypted with the connection's other secrets, and no API returns it: not `GET /integrated-account/{id}`, not `GET /integrated-account/me`, and no webhook. - It is removed from the context that every template, mapping and expression gets: `{{…}}` placeholders in an override's headers, query, body or base URL, unified API mappings, sync jobs, workflows, actions and unified webhooks. So no configuration, and no debug response, can pull it into a request or a response. - Only the JWT signer reads it, through `signing.generated`. - While a connection link waits for **Connect**, its key pair is kept encrypted, and it is deleted once the connection holds it. - The connect screen only ever receives the public half. --- # Enabling/Disabling integrations > Source: https://truto.one/docs/guides/integrations/enabling-disabling-integrations/ In Truto, we understand that flexibility is key to a smooth and efficient workflow. That's why we've made it easy for you to manage the visibility and availability of your integrations. In simpler terms, you can decide whether your customers can see and connect with certain integrations or not. Let's break this down. ## What does Enabling/Disabling Integrations mean? Just like you can switch on or off the lights in your house, in Truto, you can 'enable' or 'disable' integrations. When an integration is 'enabled', your customers can see it and connect their accounts with it. When it's 'disabled', the integration becomes invisible to the customers, and they won't be able to connect their accounts with it. ### Enabling an Integration When you 'enable' an integration, it's like opening a door for your customers. They will be able to see the integration on the connection screen, where they authorize applications for use in Truto. It's like inviting your customers to connect their account with that particular integration. ### Disabling an Integration On the other hand, when you 'disable' an integration, it's like closing that door. The integration will no longer be visible on the connection screen, and customers won't be able to authorize or connect their accounts with it. ## Install an integration Before using enabling/disabling for an integration, make sure to install it from `Available Integrations`. You can check the documentation for installing an integration [here](https://truto.one/docs/guides/integrations/overview#installing-an-integration). ## Steps to Enable/Disable Integration 1. Click on `Integrations` and select the integration you want for Enabling/Disabling in `Installed` integrations. ![Find installed integration](/images/integrations/installed-integrations-select.png) 2. Open the **Configuration** tab and set the two toggles as needed: - **Enabled** controls whether your customers can connect their accounts with the integration. - **Show in Connect UI** controls whether the integration appears in the integration list on the connection screen. The integration is listed on the connection screen only when both are on. ![Toggle Enabled option in Configuration](/images/integrations/enable-disable-integration.png) 3. Click on `Save` after adding the details mentioned above. 4. Voila! You should now see that `Save` is disabled which means Enabling/Disabling integration has been done successfully. ## In Conclusion Enabling or disabling integrations in Truto provides you with control over which integrations your customers can see and connect with. It's a useful feature to manage the availability of integrations according to your needs and preferences. With Truto, you have the power to customize your customer's experience with APIs. --- # Customizing Integrations on Truto > Source: https://truto.one/docs/guides/integrations/customising-integrations/ Once you've installed an integration on Truto, you have the flexibility to customize its configuration to better suit your specific needs. Customizing integrations allows you to override default settings, add new functionalities, and tailor the integration to fit seamlessly within your environment. This page will guide you through the various ways you can customize your integrations. ## Overview Customizing an integration involves modifying its configuration after installation. This can include: - **Overriding OAuth Credentials**: Change the OAuth settings to use different authorization servers or credentials. - **Adding Custom RapidForm Configurations**: Create customized forms to collect additional user inputs during integration setup. - **Introducing Custom Resources**: Add new data resources that are not available in the base integration. - **Environment-Specific Adjustments**: Different environments (such as development, staging, and production) may require distinct integration settings. Truto allows you to customize integrations based on the environment to ensure smooth operation across all stages of your deployment. These are just examples of the customization possibilities. Additionally, you can modify other critical aspects of the integration to better align with your specific requirements. To modify, simply go into the Installed Integration of that environment - ![Environment Integrations](/images/integrations/environment-integration.png) ## Overriding Integration Configuration After installing an integration, you can override any of its default configuration fields. This ensures that the integration aligns perfectly with your unique requirements and environment settings. ### Overriding OAuth Credentials OAuth credentials are crucial for securely connecting your integration to external services. Truto allows you to override the default OAuth configuration to use different credentials or authorization servers. - **Authorization Host & Path**: Change the authorization server URL and path if you're using a different OAuth provider or a custom authorization server. - **Token Host & Path**: Modify the token endpoint to accommodate different OAuth implementations. - **Client ID & Client Secret**: Update these credentials to match those provided by your OAuth provider. For overriding OAuth credentials, visit our [Overriding OAuth Credentials Guide](/docs/guides/integrations/overriding-oauth-credentials). ## Adding Custom RapidForm Configurations ### Benefits of Custom RapidForms - **Enhanced Data Collection**: Gather more specific data tailored to your business needs. - **Improved User Experience**: Provide a more comprehensive setup process for users. For setting up a RapidForm, visit our [RapidForm Guide](/docs/guides/rapid-form/overview). ## Overriding Other Integration Configuration Beyond the examples provided above, you can customize virtually any aspect of an integration's configuration. This comprehensive customization capability ensures that every component of your integration can be tailored to meet your specific needs. The following key areas can also be customized: - **Variables**: Modify or add variables to store essential information like API keys, subdomains, and client credentials. - **Authentication**: Change authentication methods or update credentials to ensure secure connections. - **Authorization**: Adjust authorization types, token handling, and add custom headers to control access permissions. - **Base URL and Headers**: Customize the main API endpoint and modify headers to include necessary metadata or authentication tokens. - **Query Parameters**: Refine or add query parameters to filter and retrieve specific data from external APIs. - **Pagination**: Change pagination methods and settings to efficiently handle large data sets. - **Rate Limiting**: Adjust how your integration manages API request limits to prevent exceeding provider constraints. - **Error Expressions**: Customize error handling to standardize and clarify error responses from external APIs. - **Resources**: Add or modify data resources to interact with additional or specialized data types. - **Actions**: Override or add automated tasks that occur after connecting an account to streamline workflows. - **Webhooks**: Customize how incoming webhook events are processed and verified to handle real-time notifications effectively. Taking an example, to customize the **Salesforce Integration** and to add a new **Resource**, follow these steps: 1. Open the installed integration, go to the **Resources** tab, and choose **Edit** from the page menu. ![Edit Integrations](/images/integrations/edit-integrations.png) 2. Scroll down and click the **Add Resource** button. ![Resources](/images/integrations/edit-resources-integrations.png) 3. Fill in the details for the new resource: - Name your resource. - Select the required endpoints. - Provide the necessary configuration details. ![Add resources](/images/misc/add-resource-installed.png) 4. Once you've completed the setup, click the **Save** button to save your changes. ![Save Installed](/images/misc/save-installed.png) Your new resource will now be available as part of the `Integration` for the Environment. --- # Creating Integrations on Truto > Source: https://truto.one/docs/guides/integrations/creating-integrations/ ## Overview Truto allows you to install pre-built integrations or create custom ones tailored to your needs. This step-by-step guide will walk you through creating an integration on Truto, using Salesforce as an example to make it easy to follow. ## Adding a New Integration 1. **Navigate to the Catalog** Start by going to the `Catalog` section and clicking the `Create Integration` button. ![Create Integration](/images/integrations/create-integrations.png) 2. **Open the Create Integration Page** Clicking the button takes you to the `Create Integration` page where you’ll configure all details. ![Create Integration overview](/images/integrations/creating-integrations.png) ## Step-by-Step Integration Creation ### Step 1: Adding Basic Details In the **Basic Details** section, you'll enter foundational information about the integration. #### Crucial Fields: - **Label**: The name of your integration. This will be visible in the catalog (e.g., “Salesforce”). - **Identifier**: A unique code that makes your integration different from others and helps with OAuth callbacks. This will be used in the OAuth callbacks, [Link SDK](/docs/guides/link-sdk/how-to-embed), Unified Model Mapping. #### Optional Fields: - **Category**: Categorize your integration to make it easy to find. - **Logo & Icon**: These help visually represent the integration. This is used in the Truto Connection UI. - **Is Beta?**: Check this if the integration is still in testing. For our Salesforce example, these details might look like this: ![Salesforce Basic Details](/images/integrations/salesforce-integration-basic.png) --- ### Step 2: Configuring Authentication and Variables **Authentication** is how you securely connect your integration to an external service like Salesforce. Depending on the authentication type you choose, the **Variables** section adjusts to collect the necessary inputs. #### Authentication Options 1. **OAuth 2.0 Authorization**: - **What it is**: Users log in through the external service to grant access. - **Why use it**: Secure and easy to manage; it’s the recommended way. 2. **API Key Authentication**: - **What it is**: Users provide an API key, similar to a password. - **Why use it**: Simple but less secure compared to OAuth. 3. **Keka OAuth Authentication**: - **What it is**: A specific OAuth type used only for Keka integrations. 4. **OAuth 2.0 Client Credentials Flow**: - **What it is**: A server-to-server way to authenticate, used when users don't need to log in. - **Why use it**: Ideal for backend services. 5. **JWT**: - **What it is**: Authentication using JSON Web Tokens. - **Why use it**: For providers that issue or accept JWTs for API access. - Read more in [Configuration References — JWT](/docs/guides/integrations/configuration-reference#5-jwt). 6. **OAuth 1.0**: - **What it is**: The original OAuth signing flow, still used by some APIs. - **Why use it**: When the provider requires OAuth 1.0 instead of OAuth 2.0. - Read more in [Configuration References — OAuth 1.0](/docs/guides/integrations/configuration-reference#6-oauth-10). #### Salesforce Example: OAuth 2.0 Authorization For Salesforce, **OAuth 2.0 Authorization** is used. Here’s what the configuration looks like: ![Salesforce OAuth](/images/integrations/salesforce-integration-oauth.png) Also, refer to our blog on [Creating an OAuth App on Salesforce](https://truto.one/blog/integrate-salesforce) - **Redirect URL**: This URL tells Salesforce where to send users after logging in (`https://api.truto.one/connect/salesforce/callback`). You must add this to your Salesforce OAuth app settings. - **Client ID and Client Secret**: Think of these as the “username” and “password” for Salesforce. You get these values when you create the OAuth app in Salesforce. - **Authorization Host and Path**: These are provided by Salesforce and indicate where users log in to give you access. - **Token Host and Path**: This URL is used to get the access token that allows you to make API calls on behalf of the user. These are provided by Salesforce in their documentation. Read more on [Authentication](/docs/guides/integrations/configuration-reference#authentication) --- #### Variables Section **Variables** let you add specific information needed for your integration, like a `subdomain` or `client_id`. This makes the integration reusable for each user. This section gets enabled after an authentication is selected. For instance, if Salesforce uses a unique subdomain for each customer, you can use a **variable** (`subdomain`) in the **Base URL** instead of hardcoding it. This way, every customer can provide their own subdomain when they connect their Salesforce account. ![Integration Variables Screenshots](/images/integrations/integration-variables-oauth.png) For Salesforce, we use a variable called `subdomain`: ![Salesforce OAuth Variables](/images/integrations/salesforce-oauth-variables.png) Read more on [Variables](/docs/guides/integrations/configuration-reference#variables) --- #### Token Details Towards the end of the **Authentication** section, fill in additional token details based on Salesforce’s documentation. ![Salesforce OAuth Tokens](/images/api-tokens/oauth-salesforce-token.png) --- ### Step 3: Authorization Options With Salesforce, the **Bearer Token** is used to authorize every API request. Essentially, the access token needs to be added to each request like this: ``` Authorization: Bearer {{oauth.token.access_token}} ``` Truto automatically includes this token to make sure that Salesforce knows you’re authorized to access the data. Select the format as mentioned in the documentation. Here’s how it looks: ![Salesforce Authorization](/images/integrations/salesforce-authorization-integration.png) Read more on [Authorization](/docs/guides/integrations/configuration-reference#authorization) --- ### Step 4: Configuring Base URL and Headers The **Base URL** and **Headers** sections define how API requests will be sent to Salesforce (or any other system). #### Base URL The **Base URL** is like the home address for all API calls. For Salesforce, it looks like this: ``` https://{{subdomain}}.my.salesforce.com ``` - **Subdomain**: This variable (`subdomain`) is provided by the user during account connection and makes sure that each request reaches the correct Salesforce environment. #### Headers ![Base URL & Headers](/images/integrations/salesforce-base-url-integration.png) Read more on [Base URL and Headers](/docs/guides/integrations/configuration-reference#base-url-and-headers) --- ### Step 5: Configuring Query Parameters The **Query Parameters** section lets you add specific key-value pairs to your API request URLs. These parameters help customize what data you’re getting from the API. Click on the format supported and add the query parameters. For example, you could add: - **`filter`**: To filter the results (e.g., get only active accounts). - **`sort`**: To sort the data in a particular order. - **`limit`**: To limit the number of records returned. These parameters make the API requests more specific and useful. ![Salesforce Query Parameters](/images/integrations/salesforce-query-integration.png) **Note**: These query parameters are included in every API request unless you set different ones for a specific resource in the `Resources` section. Read more on [Query Parameters](/docs/guides/integrations/configuration-reference#query-parameters) --- ### Step 6: Configuring Pagination Some APIs limit how much data they return in a single response. **Pagination** allows you to get all the data in smaller chunks or pages. #### Salesforce Example for Pagination For Salesforce, you set up pagination by defining: - **Cursor Path**: Salesforce uses `nextRecordsUrl` to show where the next page of data is. - **Is Cursor Link**: This is checked because `nextRecordsUrl` is a full link. - **Use Path from Cursor Link**: Salesforce provides a link, so Truto uses that path for the next request. ![Salesforce Pagination Setup](/images/integrations/pagination-salesforce-integration.png) This setup makes sure that your integration can handle large amounts of data in manageable pages. Read more on [Pagination](/docs/guides/integrations/configuration-reference#pagination) --- ### Step 7: Configuring Rate Limiting APIs often limit how many requests you can make within a given timeframe. **Rate Limiting** lets you handle these limits without getting blocked by the API. #### Truto’s Default Values Truto automatically handles rate limits if the response status code is `429` (Too Many Requests). Truto also looks for a `Retry-After` header to determine how long to wait before retrying. You can configure this with JSONata expressions, but Truto’s default settings work well for most cases. ![Salesforce Rate Limit](/images/integrations/rate-limit-salesforce-integration.png) This ensures that your integration stays compliant with the API’s rate limits, preventing disruptions. Read more on [Rate Limiting](/docs/guides/integrations/configuration-reference#rate-limiting) --- ### Step 8: Setting Up Resources The **Resources** section is where you define the core data you want to work with, like **accounts**. You also specify what operations you can perform on this data, such as listing accounts, retrieving a single account, creating, or updating an account. You can add multiple resources in an Integration. Truto uses the **CRUD** model (Create, Read, Update, Delete) to define resources - which means that we try convert the underlying product's API into CRUD APIs. ### Key Elements of Resources: 1. **Resource Name**: This is the type of data you’re working with (e.g., `accounts`). 2. **Method (Operations)**: Define actions such as: - **List**: Fetch all records (`GET /services/data/v57.0/query`). - **Retrieve**: Get a single record by ID (`GET /services/data/v57.0/sobjects/Account/{{id}}`). - **Create**: Add a new record (`POST /services/data/v57.0/sobjects/Account`). - **Update**: Modify an existing record (`PATCH /services/data/v57.0/sobjects/Account/{{id}}`). 3. **Path**: The API endpoint for each method. For Salesforce, it might be something like `/services/data/v57.0/query`. The **SOQL endpoint** is called for the list method and for other methods, the REST APIs are called. 4. **Response Path**: Salesforce returns account data inside an object called `records`. This path helps Truto understand where to find the list of accounts in the response. 5. **Query Parameters**: Add any queries that help you refine or filter your data. These **Query Parameters** are included in every API request. If you add **Query Parameters** for a specific resource, they will be combined with the global ones defined in the `Query Parameters`. ![Salesforce Accounts Resource](/images/integrations/salesforcer-resources-integration.png) This setup ensures your integration knows what data to interact with and what actions to perform on it. Read more on Resources [here](/docs/guides/integrations/configuration-reference#resources) --- ### Step 9: Setting Up Actions **Actions** are automated tasks that run after an account is connected. Think of them as pre-set instructions your integration follows. #### General Steps for Actions: 1. **Get Context**: Gather information 2. **Transform**: Use this information to make changes or add context (e.g., format the subdomain into a label). Use a **JSONata** transformation expression. 3. **Update Context**: Save this transformed information for use across the integration. For Salesforce, after connecting a user’s account: 1. **Get Context**: Retrieve the Salesforce subdomain that the user provides. 2. **Transform**: Create a label for the integrated account, using the subdomain. 3. **Update Context**: Save this label for later use. These steps make sure the integration runs smoothly and users can easily identify their connected accounts. ![Salesforce Actions](/images/integrations/salesforce-post-install.png) Once the Integrated Account is connected for a user, this is how the label shows up on the account: ![Integrated account label](/images/integrations/salesforce-integration-label.png) Read more on Actions [here](/docs/guides/integrations/configuration-reference#actions) If you need further assistance, refer to the [Configuration References](/docs/guides/integrations/configuration-reference) for additional guidance. --- # Uninstalling > Source: https://truto.one/docs/guides/integrations/uninstalling/ Truto is all about flexibility and ease-of-use, and that includes giving you the power to remove integrations that you no longer need. This process is called 'uninstalling an integration'. Let's simplify this for you. ## What does Uninstalling an Integration mean? Uninstalling an integration is a bit like deleting an app from your smartphone. When you uninstall an integration in Truto, you're removing that specific API connection from your environment. It's as if you're telling Truto, "I don't need this one anymore." ### What happens when you uninstall an Integration? When you uninstall an integration, Truto also removes all the integrated accounts associated with that integration. For accounts connected with OAuth, Truto asks the provider to revoke their access tokens. Truto then sends an `environment_integration:deleted` webhook event. It's like doing a thorough cleanup of everything related to that particular integration. This means that once you uninstall an integration, you and your customers won't be able to access any of the features or data associated with it, until you decide to install it again. ## Steps to Uninstall Integration 1. Click on `Integrations` and select the integration you want to uninstall in `Installed` integrations. ![Find installed integration](/images/integrations/installed-integrations-select.png) 2. Open the overflow menu (**⋯**) and choose **Uninstall**. ![Uninstall from the overflow menu](/images/integrations/uninstall-integration.png) 3. Click on `Uninstall`, after this the integration will be uninstalled from the environment you were in. ![Click on Uninstall button](/images/integrations/uninstall-integration-prompt.png) 4. Voila! You will now be redirected to Integrations section and integration has been successfully uninstalled from the environment. ## To Summarize Uninstalling an integration in Truto is like removing a tool you no longer need from your toolbox. It helps you keep your work environment tidy, organized, and free from clutter. And remember, you can always reinstall the integration if you need it in the future. --- # Overview > Source: https://truto.one/docs/guides/integrations/overview/ One of Truto's key features is 'Integrations'. In the world of Truto, Integrations represent the variety of online APIs we support and enable you to interact with. Let's delve deeper into what Integrations mean within the Truto platform. ## What are Integrations? In Truto, 'Integrations' refer to the wide array of online APIs that we support. These are essentially different online platforms and services that you can connect with using Truto. ## **Available Integrations** Under the Catalog section, there are two tabs - `Integrations` and `Unified APIs`. Under `Integrations`, you'll find a list of APIs that Truto supports and that you can integrate with. Some of these APIs are immediately accessible for integration, you can find an install button in those, while others can be made available upon your request. If you don't find the API you're seeking, don't worry – just reach out to us and we'll work towards adding it for you. The available integrations can be found [here](https://app.truto.one/catalog/integrations). ## **Installing an Integration** Once you choose an API from the available integrations list and install it, it moves to your 'Installed Integrations'. These are the APIs that you've actively chosen to work with. Each Installed Integration comes complete with all the necessary details and resources needed for you to connect your account and start using the API. The installed integrations can be found [here](https://app.truto.one/integrations/installed) and to Install an integration, you can simply follow below given steps! 1. Head over to the Catalog and click on `Integrations` tab on the left. After this search for integration you want and then click on `Install` button (If the integration is listed but not available, you can click on `Request access` or otherwise you can reach out to us and we'll work towards adding it for you.) ![Steps to install integration](/images/integrations/install-integrations.png) 2. Select **Development** or **Sandbox** for the environment where you want to install this integration, then click `Install` ![Select an environment](/images/integrations/integrations-install-environments.png) 3. Voila! You should now see a installed successful message. You can now go to `Installed` in Integrations and you should see the newly installed integration there. ## To Summarize Integrations in Truto provide you with a diverse selection of online APIs. With 'Available Integrations', you get to choose from a range of APIs, while 'Installed Integrations' represent the APIs you've chosen and are ready to use. At Truto, our aim is to offer a broad choice of APIs to cater to your unique needs and facilitate your work efficiency. Enjoy the seamless interaction with various online APIs through Truto! --- # Configuration References > Source: https://truto.one/docs/guides/integrations/configuration-reference/ Welcome to the Truto Integrations References! This section will help you understand each section in `Integrations` in Truto. We'll explain everything you need to know, with examples wherever needed and easy-to-understand descriptions. ## Authentication The **Authentication** section is all about how your integration securely connects to other systems like Salesforce, Shopify, or Keka. Each type of authentication needs different settings. Let’s look at the different authentication methods, their fields, and how to configure them. ### 1. OAuth 2.0 Authorization **OAuth 2.0** is a popular and secure way to log in using a third-party service. Truto recommends using this method wherever possible. #### OAuth 2.0 Fields and Settings - **Redirect URL**: - **What It Is**: The webpage users go to after they log in. - **Example**: `https://api.truto.one/connect/salesforce/callback` - **Note**: You must register this URL with the service you’re connecting to. - **Client ID & Client Secret**: - **Client ID Param Name**: - **What It Is**: Identifies the OAuth client. - **Default**: `client_id` - **Client Secret Param Name**: - **What It Is**: Authenticates the OAuth client. - **Default**: `client_secret` - **Authorization Host & Path**: Check the Authorization Host in the product documentation and enter it here as in the example. - **Authorization Host**: - **Example**: ``` https://truto.my.salesforce.com ``` - **Authorization Path**: - **Default**: `/oauth/authorize` - **Token Host & Path**: Check the Token Host in the product documentation and enter it here as in the example. - **Token Host**: - **Example**: ``` https://truto.my.salesforce.com ``` - **Token Path**: - **Default**: `/oauth/token` - **Scopes**: - **What It Is**: Permissions you request during login. - **Format**: List one permission per line (e.g., read, write). - **Scope separator**: A space by default. - **Optional Scopes**: - **What It Is**: Scopes the user may grant or decline, sent separately from **Scopes**. Used by HubSpot. - **Use OAuth token scope**: - **What It Is**: When on, a token refresh asks only for the scopes returned in the token response. Useful for providers like Google, where users can consent to fewer scopes than you asked for. - **OAuth token scope separator**: How to split the scope string in the token response. A space by default. - **Permissions Text**: - **What It Is**: A friendly description of the permissions you’re asking for. You can use **HTML** or **Markdown** to make it look nice. - **Example**: ```markdown **Access Required:** - View and manage your Salesforce data. - Send updates to Salesforce on your behalf. ``` - **Why It’s Important**: Helps users understand what they’re agreeing to. - **OAuth Token Request Authorization Format**: - **Options**: **Header** or **Body** or **Query** - **OAuth Token Request Body Format**: - **Options**: `Form`, `JSON`, `Query`. Usually, it’s a form. - **Token Expiry Duration**: - **What It Is**: How long the token lasts, in seconds (e.g., `3600`). - **Add authorize URL params**, **Add token params**, **Add refresh token params**: - **What It Is**: Extra key-value parameters added to the authorize URL, the token request, and the refresh token request. - **Connect UI Label** and **Connect UI Help Text**: - **What It Is**: The name and description of this sign-in method on the connect screen. A few OAuth 2.0 settings are set in the integration's JSON rather than the form: | Key | What it does | | --- | --- | | `pkce` | Turns on PKCE. `method` is `S256` or `plain`. | | `auth.refreshPath` | Path for the refresh token request. Defaults to the token path. | | `auth.revokePath` | Path Truto calls to revoke the token when a connection is removed. Defaults to `/oauth/revoke`. | | `options.expiresInPropertyName` | Name of the token response field that holds the token lifetime, when it is not `expires_in`. | ##### Example: Salesforce OAuth 2.0 Setup - **Redirect URL**: `https://api.truto.one/connect/salesforce/callback` - **Authorization Host**: ``` https://{{subdomain}}.my.salesforce.com ``` ![OAuth](/images/integrations/oauth-integration.png) --- ### 2. API Key Authentication **API Key Authentication** is a simple way to verify by using an API key in every request. - **Scopes**: - **What It Is**: The permissions the API key needs. - **Format**: List one permission per line (e.g., read, write). - **Permissions Text**: - **What It Is**: A friendly description of the permissions you’re asking for. You can use **HTML** or **Markdown** to make it look nice. - **Example**: ```markdown **Access Required:** - View and manage your 15five data. ``` ![API Key](/images/integrations/api-key-integration.png) #### API Key Variables and Setup For API Key Authentication, you need the `api_key` variable. This will get added automatically in the `Variables` section. ##### Required Fields for API Key Variables: - **Name**: - **Value**: `api_key` (this is how Truto identifies it internally). - **Label**: - **Value**: `API Key` (the label). - **Type**: - **Password** (hides the key for security). - **Default Value**: - Usually left blank. Add any default values. - **Help Text**: - **Example**: "The API Key provided by your service provider. This is required to authenticate your API requests." - **Transforms**: - Optional changes you can apply to the key. The values are `None`, `lowercase`, `UPPERCASE`, `SHA256` - **Pattern**: - A regular expression to validate the key. - **Example**: `^AK-` (API key must start with `AK-`). - **Credential Documentation Link**: - **What It Is**: A link to help users find or create their API key. - **Example**: `"https://docs.example.com/api-keys"` - **Permissions Text**: - **What It Is**: Explains what the API key can do. - **Example**: ```markdown **This API key will grant access to your Shopify store's data and settings.** ``` ##### Example Usage of API Key In Cloudflare integration: - **API Key** is used in headers: ``` Authorization: Bearer {{api_key}} ``` ![API Key Variable Example](/images/integrations/variables-api-key-integration.png) --- ### 3. OAuth 2.0 Client Credentials Flow **OAuth 2.0 Client Credentials Flow** is another way to use OAuth 2.0. Check the documentation of the product you're integrating to decide on whether to use this. #### OAuth 2.0 Client Credentials Fields and Settings - **Token Host & Path**: - **Token Host**: - **What It Is**: The URL where tokens are issued. - **Example**: `https://login.salesforce.com` - **Token Path**: - **Default**: `/oauth/token` - **OAuth Token Request Authorization Format**: - **Options**: **Header** or **Body** or **Query** - **What It Means**: Decides where to send the **Client ID** and **Client Secret**. - **OAuth Token Request Body Format**: - **What It Is**: The format of the request body when asking for a token. Usually **Form**. Other values include **JSON**, **Query**. - **Add Token Params**: - **What It Is**: Extra parameters needed by the API. - **Use**: Add as needed by the provider. - **Permissions Text**: - **What It Is**: Explains what access the integration will have. - **Example**: ```markdown **Permissions Required:** - Full read access to your Salesforce accounts. - Ability to create and modify records as needed. ``` ![OAuth 2.0 Client Credentials](/images/integrations/oauth2-client-credentials.png) ##### Optional Fields for OAuth 2.0 Client Credentials Variables: 1. **Client ID**: - **Name**: `client_id` - **Label**: `Client ID` - **Type**: **Text** - **Placeholder**: "Enter Client ID." - **Required?**: Yes - **Help Text**: "Client ID provided by the service" 2. **Client Secret**: - **Name**: `client_secret` - **Label**: `Client Secret` - **Type**: **Password** - **Placeholder**: "Enter Client Secret." - **Required?**: Yes - **Help Text**: "The secret key provided by the service for authenticating requests." ![OAuth 2.0 Variables](/images/integrations/oauth-2-variables-integration.png) --- ### 4. Keka OAuth Authentication **Keka OAuth** is specifically for **Keka**, a platform for HR and payroll services. It needs several pieces of information to work. #### Keka OAuth Variables Setup In the **Variables** section for **Keka OAuth**, you need to enter multiple details to authenticate with Keka. ##### Required Fields for Keka OAuth Variables: 1. **Client ID**: - **Name**: `client_id` - **Label**: `Client ID` - **Type**: **Text** - **Placeholder**: "Enter Client ID provided by Keka" - **Required?**: Yes - **Help Text**: "Client ID provided by Keka, used to identify your app." 2. **Client Secret**: - **Name**: `client_secret` - **Label**: `Client Secret` - **Type**: **Password** - **Placeholder**: "Enter Client Secret." - **Required?**: Yes - **Help Text**: "The secret key provided by Keka for authenticating requests." 3. **API Key**: - **Name**: `api_key` - **Label**: `API Key` - **Type**: **Password** - **Placeholder**: "Enter API key." - **Required?**: Yes - **Help Text**: "API key provided by Keka to authenticate API calls." - **Permissions Text**: - **What It Is**: Explains what access is given when connecting Keka. - **Example**: ```markdown **Permissions Required**: Access to HR and payroll data for your employees to synchronize with other services. ``` ##### Example Usage in Keka Integration All three fields are required for Keka OAuth. Users must enter them correctly to connect smoothly. ![Keka OAuth Variable Example](/images/integrations/keka-ouath-integrations.png) --- ### 5. JWT **JWT** is for integrations where authentication uses JSON Web Tokens. Use it when the provider issues or accepts JWTs for API access. Open the integration’s **Authentication** tab, choose **Edit** from the page menu, and select **JWT** as the authentication format. The fields shown depend on the provider — use their documentation to fill them in. ![JWT](/images/integrations/jwt-bearer-integration.png) If the provider signs in a service account with a key pair, Truto can make the key pair for each connection, so that your end users only install a public key. See [Truto-generated key pairs](/docs/guides/integrations/generated-key-pairs). --- ### 6. OAuth 1.0 **OAuth 1.0** is for integrations that use the OAuth 1.0 signing flow. Use it when the provider requires OAuth 1.0 instead of OAuth 2.0. Open the integration’s **Authentication** tab, choose **Edit** from the page menu, and select **OAuth 1.0** as the authentication format. Configure the settings shown according to your provider’s documentation. ![OAuth 1.0](/images/integrations/oauth1-integration.png) ## Variables **Variables** help make your integration flexible by allowing you to collect specific information from users, like API keys or subdomains. This makes your integration adaptable for different users and situations. Click **Add Variable** to create a new field. Note that an option from `Authentication` section has to be selected to be able to use variables. ### Key Points About Variables - **Reusable**: Different users can use the same integration with their own unique information. - **Customization**: Store unique details like **API keys**, **subdomains**, or **client credentials**. #### Common Examples of Variables: 1. **Subdomain**: - **Usage**: Used in the **Base URL**. - **Example**: ``` https://{{subdomain}}.myshopify.com ``` 2. **API Key**: - **Usage**: Used in **Headers**. - **Example**: ``` Authorization: Bearer {{api_key}} ``` #### Fields in Variables Setup: - **Name**: Unique identifier for the variable. - **Label**: What users see. - **Type**: **Text**, **Password**, **Single Select**. - **Options**: For **Single Select**, the choices the user picks from, each with a label and a value. - **Default Value**: Optional starting value. - **Placeholder**: Hints for users on what to enter. - **Format**: For **Text**, checks the value is an **Email**, **Number**, **UUID** or **URL**. - **Required?**: If checked, users must fill it out. - **Help Text**: Explains what the variable is for. - **Pattern**: Regex to validate the input. - **Credential Documentation Link**: - **What It Is**: Link to help users generate or find their credentials. - **Example**: `"https://docs.example.com/generate-api-keys"` - **Permissions Text**: - **What It Is**: Explains what access the integration is requesting. - **Format**: **Markdown** or **HTML** for clarity. ![Integration Variables Example](/images/integrations/integration-variables-oauth.png) ## Authorization The **Authorization** section sets up how your integration proves it’s allowed to access data every time it makes a request to an external system. This is different from **Authentication**, which is about logging in initially. Authorization ensures each request has the right permissions. ### Authorization Types and How to Set Them Up This section offers different ways to manage authorized requests to external APIs. Each method has specific settings to configure how your integration behaves. ### 1. Bearer Auth **Bearer Authentication** is a simple way to authorize requests by including a token in the request headers. This token is usually an access token you got during the OAuth login process. #### Bearer Auth Fields and Settings - **Format**: - Choose **Bearer Auth** as the authorization method. - **Bearer Token**: - **What It Is**: The token used to authorize the request. - **Example**: ``` {{oauth.token.access_token}} ``` - This dynamically uses the access token from the OAuth flow. ##### Example Usage: When integrating with Salesforce, use the Bearer Token for each API request: - The Bearer Token is stored as: ``` {{oauth.token.access_token}} ``` ![Bearer authorization](/images/integrations/bearer-auth-integration.png) ### 2. Basic Auth **Basic Authentication** requires a username and password to access an API. These credentials are sent in the request headers in an encoded format. #### Basic Auth Fields and Settings - **Format**: - Choose **Basic Auth** as the authorization method. - **Username**: - **What It Is**: The username for the external system. - **Usage**: Use variables to allow users to input their own username. - **Password**: - **What It Is**: The password for the external system. - **Usage**: Use variables to store the password securely. ![Basic authorization](/images/integrations/basic-auth-integration.png) ### 3. Custom Header Authorization **Custom Header Authorization** lets you create your own authorization logic, which is useful if the API you’re connecting to doesn’t use standard methods like OAuth or API Keys. #### Custom Header Fields and Settings - **Format**: - Choose **Custom Header** as the authorization method. - **Use JSONata**: - **What It Is**: Use JSONata expressions to set custom headers based on the request. - **How It Works**: Write a JSONata expression to define how headers should be set. - **Custom Header Expression**: - **What It Is**: A JSONata expression that sets custom headers. - **Available Data**: - **`url`**: The full URL of the request. - **`requestOptions`**: The request details, including headers and body. - **`context`**: Information stored in the account’s context. - **What It Must Return**: An object with `url` and `requestOptions` properties. The returned `requestOptions` replaces the request's options as a whole, so merge your changes into the incoming `requestOptions` to keep its method, body and other headers. ##### Example of JSONata Expression for Custom Header: If an API needs a special signature in the header based on the URL and a secret key, you can use: ```jsonata { "url": url, "requestOptions": $merge([ requestOptions, { "headers": $merge([ requestOptions.headers, { "X-Custom-Signature": $digest(url & context.secret, "SHA-256", "hex") } ]) } ]) } ``` - **Explanation**: - **`$digest`**: Hashes the request URL joined with a **secret** from the context, using SHA-256, as a hex string. - **`$merge`**: Keeps everything already in `requestOptions` and its headers, and adds the new header (`X-Custom-Signature`). ![Custom header authorization](/images/integrations/custom-header-auth-integration.png) ## Base URL and Headers The **Base URL and Headers** section is essential for telling your integration where to send requests and what information to include in those requests. ### Base URL The **Base URL** is the main address for all API requests. Every API call you make will start with this URL. - **Base URL**: - **What It Is**: The main URL of the external API. - **Variables Enabled**: Use variables to make it dynamic based on user settings. - **Example**: ``` https://{{subdomain}}.api.example.com ``` - **`subdomain`** is a variable from the user, allowing different users to connect to their own API endpoints. - **Use Case**: Easily connect to different instances of a service (e.g., different Salesforce accounts with unique subdomains). ### Headers **Headers** are pieces of information sent with each API request, like content type or authorization tokens. They help the API understand how to process your request. ##### Fields for Headers - **Header Name**: - **What It Is**: The name of the header (e.g., `Authorization`, `Content-Type`). - **Value**: - **What It Is**: The value for the header, which can be static or use variables. - **Example**: - **`Authorization`**: ``` "Bearer {{oauth.token.access_token}}" ``` - Uses the OAuth token. - **`Content-Type`**: `"application/json"` - Indicates the data format. - **Add Header**: - **What It Is**: Add multiple headers as needed. - **Use Case**: Include headers like **`User-Agent`** or **`Accept-Language`** for more customized requests. ### Example Usage: Base URL and Headers If you’re connecting to Salesforce to get customer data, here’s how you might set it up: - **Base URL**: ``` https://{{subdomain}}.my.salesforce.com ``` - **`subdomain`** comes from the user, ensuring requests go to the correct Salesforce account. - **Headers**: 1. **Authorization**: - **Value**: ``` "Bearer {{oauth.token.access_token}}" ``` - Authorizes each request to Salesforce. 2. **Content-Type**: - **Value**: `"application/json"` - Specifies that you’re sending JSON data. 3. **User-Agent**: - **Value**: `"truto"` - Identifies your integration for logging or debugging. 4. **Sforce-Query-Options** (Optional for Salesforce): - **Value**: `"batchSize=200"` - Optimizes data retrieval by limiting the number of records per request. Here’s a visual of the **Base URL and Headers** setup: ![Base URL and Headers Example](/images/integrations/salesforce-base-url-integration.png) ## Query Parameters **Query Parameters** are used to refine or filter the data retrieved from external APIs. They are appended to the API request URL and help in specifying exactly what data you need. Understanding how to properly format and add query parameters is essential for effective data retrieval and integration performance. ### Query Array Format When a query parameter holds an array, for example one set in a resource method's query or a Unified API query mapping, the **Query Array Format** determines how its values are written in the URL. The default is **Repeat**. A resource method can override it. Truto supports the following array formats: #### 1. Comma **Description**: Elements in the array are separated by commas within a single query parameter. **Example**: ``` https://api.example.com/items?colors=red,green,blue ``` **Usage**: Use this format when the external API expects array values to be comma-separated. #### 2. Brackets **Description**: Each element in the array is specified with empty brackets `[]` after the parameter name. **Example**: ``` https://api.example.com/items?colors[]=red&colors[]=green&colors[]=blue ``` **Usage**: Use this format when the external API expects array values to be listed with brackets, allowing the server to recognize them as separate elements. #### 3. Index **Description**: Each element in the array is specified with an index inside the brackets `[]` after the parameter name. **Example**: ``` https://api.example.com/items?colors[0]=red&colors[1]=green&colors[2]=blue ``` **Usage**: Use this format when the external API requires indexed array parameters, which can be useful for maintaining the order of elements. #### 4. Repeat **Description**: The same query parameter name is repeated for each element in the array. **Example**: ``` https://api.example.com/items?colors=red&colors=green&colors=blue ``` **Usage**: Use this format when the external API expects multiple instances of the same query parameter to represent array values. ![Query array format](/images/integrations/query-array-format.png) ### Adding Query Parameters To add query parameters to your integration requests in Truto, follow these guidelines: 1. **Identify Required Parameters**: Determine which query parameters are needed based on the external API’s documentation. 2. **Choose the Appropriate Array Format**: Select one of the supported **Query Array Formats** (Comma, Brackets, Index, Repeat) that aligns with the external API’s requirements. 3. **Configure the Parameters**: - **Key**: The name of the query parameter (e.g., `api_version`). - **Value**: A single text value, which can use placeholders (e.g., `{{api_version}}`). 4. **Add to Query Parameters**: - Navigate to the **Query Parameters** section of your integration. - Enter the key and value. These parameters are added to every request. - Specify the chosen **Query Array Format**. **Example Scenario**: Suppose you are integrating with an API that retrieves products based on selected colors and expects the colors to be provided using the **Brackets** format. - **Desired Colors**: `red`, `green`, `blue` - **API Expectation**: `colors[]=red&colors[]=green&colors[]=blue` **Configuration in Truto**: - **Query Array Format**: `Brackets` **Query value**: a resource method's query, or a Unified API query mapping, sets `colors` to an array: ```json { "colors": ["red", "green", "blue"] } ``` **Resulting Query URL**: ``` https://api.example.com/products?colors[]=red&colors[]=green&colors[]=blue ``` ![Query Parameters](/images/integrations/query-params-integrations.png) ## Pagination The **Pagination** section helps your integration handle large amounts of data by breaking it into smaller, manageable chunks. This prevents overwhelming the server and avoids hitting rate limits. ### Types of Pagination Methods Different APIs use different ways to paginate data. Truto supports several methods to match these APIs. ### No Pagination - **Description**: Choose this if the API sends all data at once and doesn’t need pagination. ![No pagination](/images/integrations/no-pagination.png) ### Offset-Based Pagination **Offset-Based Pagination** is used when the API sends data in chunks based on a starting point (offset). #### Fields and Settings: - **Format**: Offset Based - **Total Record Path**: - **What It Is**: The path in the response where the total number of records is found, written as a plain dot path. - **Example**: `total_records`, or `meta.total` for a nested field - **Offset Key**: - **Default**: `offset` - **What It Is**: The query parameter name for the starting point. - **Default Offset**: - **What It Is**: The starting value for the offset. - **Limit Key**: - **Default**: `limit` - **What It Is**: The query parameter name for the number of items to fetch. - **Max Limit**: - **Default**: `100` - **What It Is**: The maximum number of items per request. - **Use Content Hashing**: - **Default**: On - **What It Is**: Prevents endless loops by comparing content between requests. - **Add Pagination to Query Parameter**: - **Options**: Add pagination details to the request body or as query parameters. Click in `Add Pagination Header` with their Value. - **Add Pagination Header**: - **What It Is**: Define custom headers for pagination. ##### Example Use Case for Offset-Based Pagination: Used when APIs need you to specify where to start (offset) and how many records to get (limit). ![Offset Pagination](/images/integrations/offset-based-pagination.png) --- ### Cursor-Based Pagination **Cursor-Based Pagination** is best for APIs that provide a unique pointer (cursor) to the next set of results. #### Fields and Settings: - **Format**: Cursor Based - **Cursor Path Object**: - **Default**: Body - **What It Is**: Where the cursor is found in the response: the **Body** or the **Header**. - **Cursor Path**: - **Required**: Yes - **What It Is**: The path to the cursor in the response. - **Previous Cursor Path**: - **What It Is**: The path to the previous page's cursor in the response, if the API returns one. - **Cursor Key**: - **Default**: `cursor` - **What It Is**: The query parameter name for the cursor. - **Has Next Path**: - **What It Is**: Path in the response that shows if more results are available. - **Limit Key**: - **Default**: `limit` - **Max Limit**: - **Default**: `100` - **Is Cursor Link**: - **What It Is**: If the cursor is a full URL, its query parameters are used to get the next page. - **Use the path retrieved from the cursor link**: - **What It Is**: With **Is Cursor Link** on, also use the cursor URL's path for the next page. - **Cursor is URL-encoded**: - **What It Is**: Decode the cursor before sending it, for APIs that return URL-encoded cursors. - **Ignore Limit in Pagination**: - **What It Is**: Don’t add the **limit** parameter if **next_cursor** is used. - **Use Content Hashing**: - **Default**: Off - Prevents endless loops by comparing content. Applies only when the cursor is read from the body. - **Add Pagination to Request Body or Query Parameter**: - Same as Offset-Based. Two cursor settings are set in the integration's JSON rather than the form: | Key | What it does | | --- | --- | | `limit_data_type` | `number` (default) or `string`. The type of the limit when pagination is added to the request body. | | `allow_empty_page_cursor` | Keep returning the next cursor when a page comes back empty. By default an empty page ends pagination. | ![Cursor Pagination](/images/integrations/cursor-pagination.png) --- ### Page-Based Pagination **Page-Based Pagination** splits data into pages, each accessed by a page number. #### Fields and Settings: - **Format**: Page Based - **Page Key**: - **Default**: `page` - **What It Is**: The query parameter name for the page number. - **Limit Key**: - **Default**: `limit` - **What It Is**: Number of items per page. - **Starting Page**: - **Default**: `1` - **What It Is**: The first page number to start from. - **Max Limit**: - **Default**: `100` - **Use Content Hashing**: - **Default**: On - Prevents endless loops by comparing content. - **Ignore Limit**: - **What It Is**: Don’t add the **limit** parameter to the request. - **Add Pagination to Request Body or Query Parameter**: - Same as Offset-Based. ##### Example Use Case for Page-Based Pagination: Used when APIs require a page number and limit to fetch specific pages of data. ![Page Pagination](/images/integrations/page-pagination.png) --- ### Range-Based Pagination **Range-Based Pagination** is useful when you specify a range of records instead of pages or cursors. #### Fields and Settings: - **Format**: Range Based - **Default Start Value**: - **Default**: `0` - **What It Is**: Starting point for data retrieval. - **Max Limit**: - **Default**: `100` - **What It Is**: The largest range per request. The first request asks for `start` = **Default Start Value** and `end` = start plus the page size, which is at most **Max Limit**. - **Ignore Limit**: - **What It Is**: Don’t add the start and end parameters to the request. - **Add Pagination to Request Body or Query Parameter**: - Same as Offset-Based. The parameter names are set in the integration's JSON: `start_key` (default `start`) and `end_key` (default `end`). ##### Example Use Case for Range-Based Pagination: Used when APIs need a specific range or starting point and the number of records to fetch. ![Range Pagination](/images/integrations/range-pagination.png) --- ### Link Header-Based Pagination **Link Header-Based Pagination** uses links in the response headers to access the next pages. #### Fields and Settings: - **Format**: Link Header Based - **Page Key**: - **Default**: `page` - **What It Is**: Current page indicator. - **Limit Key**: - **Default**: `per_page` - **What It Is**: Number of items per page. - **Max Limit**: - **Default**: `100` - **Ignore Limit**: - **What It Is**: Don’t add the **limit** parameter to the request. Link Header-Based pagination always uses query parameters: the next page's URL comes from the `Link` header. ##### Example Use Case for Link Header-Based Pagination: Common in APIs that include next, previous, or last page links in the response headers (e.g., `Link: ; rel="next"`). ![Link Header Pagination](/images/integrations/link-header-pagination.png) --- ### Adding Pagination Headers For most pagination methods, you can also add specific headers related to pagination: - **Add Pagination Header**: - **Header Name**: Name of the pagination-related header. - **Value**: The value for the header. - **Variables Enabled**: Use variables for dynamic values. ![Pagination Headers](/images/integrations/pagination-header-.png) ## Rate Limiting The **Rate Limiting** section helps Truto manage how many API requests your integration makes. This prevents you from exceeding the limits set by the external API, which could cause your integration to stop working temporarily. ### Why Rate Limiting Matters External APIs often limit how many requests you can make in a certain time period (like per minute or hour). If you go over these limits, your integration might get blocked. Rate limiting helps avoid these problems by controlling how often your integration makes requests. ### How to Set Up Rate Limiting In Truto, you use **JSONata** expressions to set up how rate limiting works. These expressions look at the API’s response to decide if you’ve hit the limit and how to handle it. #### Rate Limiting Fields and Settings 1. **Is Rate Limited Expression?** - **What It Is**: A JSONata expression that checks if your request was rate-limited. - **Should Return**: `true` or `false`. - **Data Available**: - **`headers`**: API response headers. Header names are lowercase. - **`status`**: HTTP status code. - **Default**: Checks if the status code is `429` (rate limit exceeded). - **Example Expression**: ```jsonata status = 429 ``` 2. **Rate Limit Headers Expression** - **What It Is**: A JSONata expression to get rate limit details from the response headers. - **Should Return**: An object with `limit`, `remaining`, and `reset`. - **Data Available**: - **`headers`**: API response headers. Header names are lowercase. - **`status`**: HTTP status code. - **Example Expression**: ```jsonata { "limit": headers."x-ratelimit-limit", "remaining": headers."x-ratelimit-remaining", "reset": headers."x-ratelimit-reset" } ``` 3. **Retry After Header Expression** - **What It Is**: A JSONata expression to get how long to wait before retrying. - **Should Return**: A number of seconds to wait. - **Data Available**: - **`headers`**: API response headers. Header names are lowercase. - **`status`**: HTTP status code. - **Default**: Looks for the `Retry-After` header. - **Example Expression**: ```jsonata $number(headers."retry-after") ``` ![Rate limit expressions](/images/integrations/rate-limit-limit-expression.png) ### Default Rate Limiting in Truto By default, Truto: - Checks if the status code is `429`. - Looks for a `Retry-After` header to know how long to wait before trying again. This setup works well for most APIs, but you can customize it with your own JSONata expressions if needed. ![Rate Limiting](/images/integrations/rate-limiting-integration.png) --- ## Error Expressions The **Error Expressions** section helps you handle errors from external APIs, especially when those APIs don’t use standard error codes. ### What Are Error Expressions? **Error Expressions** are JSONata expressions that convert API error responses into standard HTTP status codes and messages. This makes it easier to manage errors consistently, even if the external API has unusual error formats. ### Error Expression Fields and Settings 1. **Error Expression (JSONata)** - **What It Is**: A JSONata expression that turns API errors into standard error codes and messages. - **Data Available**: - **`response`**: The entire API response. - **`status`**: The HTTP status code. - **`headers`**: Response headers. Header names are lowercase. - **`data`**: The response body (usually JSON). - **Should Return**: An object with: - **`status`** (number): HTTP status code for the error. - **`message`** (string): A clear error message. - **`metadata`** (optional): Extra info about the error. - **`headers`** (optional): Any related headers. - **`result`** (required when `status` is below `400`): The body to return instead of an error. Use it to turn an error response from the API into a successful one. - **When to Use**: The expression runs on every response, successful or not. Return an object only when the response is an error. Otherwise return nothing (**undefined**), and Truto handles the response as usual. Returning a `status` below `400` without a `result` fails the request. - **Example Expression**: ```jsonata data.errorCode or status >= 400 ? { "status": data.errorCode = "INVALID_TOKEN" ? 401 : (status >= 400 ? status : 500), "message": data.message ? data.message : "Unknown error occurred", "metadata": data, "headers": headers } ``` - **Explanation**: - The object is returned only when the body has an **`errorCode`** or the status is `400` or above. - If **`data.errorCode`** is `"INVALID_TOKEN"`, set **`status`** to **401** (Unauthorized). Other errors in a successful response become **500**. - Use **`data.message`** if available; otherwise, use a generic message. - Include **`metadata`** and **`headers`** for more details. ![Error expression](/images/integrations/error-expression.png) ### Example Use Case: Salesforce Integration Error Handling Suppose Salesforce sometimes returns custom errors like this: ```json { "errorCode": "INSUFFICIENT_ACCESS", "message": "You do not have permission to perform this action" } ``` You can handle it with this Error Expression: ```jsonata data.errorCode or status >= 400 ? { "status": data.errorCode = "INSUFFICIENT_ACCESS" ? 403 : (status >= 400 ? status : 500), "message": data.message ? data.message : "Unknown error occurred", "metadata": data } ``` - **Status**: `"INSUFFICIENT_ACCESS"` becomes **403** (Forbidden). - **Message**: Uses the message from Salesforce. - **Metadata**: Includes the whole error response for more info. ### Benefits of Using Error Expressions 1. **Consistency**: Handle errors the same way, making it easier to manage. 2. **Customization**: Tailor error handling to fit the API’s specific needs. 3. **Better User Experience**: Provide clear and understandable error messages. ## Resources The **Resources** section is where you define what data your integration will work with and what actions you can perform on that data. It helps you organize the main functions of your integration. ### Truto's CRUD Model Truto uses the **CRUD** model (Create, Read, Update, Delete) to define resources. For each type of data, you set up different actions you can do with it. This makes your integration easy to use and complete. Here are the main parts of **Resources**: 1. **Resource Name**: The type of data, like **accounts**, **contacts**, **invoices**, etc. 2. **Operations (Methods)**: The actions you can perform on the data, following CRUD: - **List**: Get all items (`GET`). - **Get**: Get one item by ID (`GET`). - **Create**: Add a new item (`POST`). - **Update**: Change an existing item (`PATCH` or `PUT`). - **Delete**: Remove an item (`DELETE`). ### Key Elements of Resources Configuration 1. **Resource Name**: - **What It Is**: A name that identifies the type of data. - **Example**: `accounts`, `contacts`, `orders`. - **Use Case**: In Salesforce, a resource could be named **`accounts`**. 2. **Operations (Methods)**: Each **Resource** can have several methods that define what actions you can take: - **List**: - **Path**: The endpoint to get all records. - **Method**: `GET` - **Example**: `/services/data/v57.0/query` - Gets a list of accounts. - **Response Path**: Where the data array is in the response. - **Example**: In Salesforce, data might be under `records`. - **Use Case**: Helps Truto find the list of items in the response. - **Get**: - **Path**: The endpoint to get a specific record. - **Method**: `GET` - **Example**: ``` /services/data/v57.0/sobjects/Account/{{id}} ``` - Gets a specific account by `id`. - **Variables Enabled**: Use placeholders like `{{id}}` to get specific records. - **Create**: - **Path**: The endpoint to add new records. - **Method**: `POST` - **Body Format**: Usually JSON. - **Example**: `/services/data/v57.0/sobjects/Account` - Adds a new account. - **Body**: The default data sent when creating a new record. - **Update**: - **Path**: The endpoint to change existing records. - **Method**: `PATCH` or `PUT` - **Example**: ``` /services/data/v57.0/sobjects/Account/{{id}} ``` - Updates an existing account by `id`. - **Body Format**: Usually JSON. - **Body**: The data you want to update. - **Delete**: - **Path**: The endpoint to delete a record. - **Method**: `DELETE` - **Example**: ``` /services/data/v57.0/sobjects/Account/{{id}} ``` - Deletes a specific account by `id`. ### Response Path and API Response Format - **Response Path**: - **What It Is**: The location in the API response where the actual data is found. - **Example**: In Salesforce, account records might be under `records`. - **Use Case**: Helps Truto find the list or specific item in the API’s response. ![Resource method response path](/images/integrations/resource-method-response-path.png) - **API Response Format**: - **Default**: **Detect from response** - **What It Is**: The expected format of the API response. - **Example**: **`application/json`** or **`text/html`**. - **Note**: Change it if the API doesn’t set the **Content-Type** correctly. ### Query Parameters **Query Parameters** let you filter or refine the data you’re retrieving. These can be dynamic, using placeholders that get replaced when the integration runs. ![Resource method query parameters](/images/integrations/resource-method-query.png) ### Headers and Authentication Options - **Headers**: - Each operation can have its own headers. - Example: The **Authorization** header is usually needed to make secure requests. - **No Auth**: - Allows sending requests without authentication headers. - **Use Only If**: The API is public or doesn’t need authentication. ![Resource method headers](/images/integrations/resource-method-headers.png) ### Override Options Sometimes, specific methods need different settings from the rest of the integration: 1. **Override Base URL**: - Use a different base URL for this method. 2. **Override Pagination**: - Use a different pagination method for this method. 3. **Override Query Array Format**: - Change how query arrays are formatted for this method. 4. **Override Error Expression**: - Use a custom error-handling expression for this method. ![Resource method overrides](/images/integrations/resource-method-overrides.png) ## Actions The **Actions** section lets you set up automated tasks that run at set points in a connected account's life. These tasks can gather information, update settings, make requests, or perform specific operations. Actions help make your integrations work smoothly without manual steps. ### When Actions Run Each action is stored under a key in the integration's `actions`, and the key decides when it runs: - **`post_install`** (**Post-install**): Runs right after an account connects. While it runs, the account is `connecting`. If it fails, the account moves to `post_install_error`. - **`validation`**: Runs after `post_install` succeeds, to check the connection works. If it fails, the account moves to `validation_error`. You can also run it again on an existing account. - **`post_connect_user_form`**: A form shown to the user on the connect screen after the account connects, to collect more details. - **`refresh_token`** (**Scheduled action**): Runs on a schedule, every set number of seconds (**Duration**) or on a **Cron Expression**. Turn on **Reactivate auth** to make an account active again when the scheduled action succeeds. ### Types of Steps Here’s how actions typically work in Truto: 1. **Get Context**: Collect initial information needed for the integration. 2. **Transform**: Change or enhance the collected information using **JSONata**. 3. **Update Context**: Save the collected or transformed data for later use. 4. **Set Context**: Update specific values in the integration’s context. 5. **Request**: Make API requests to get or change data in real time. ### Types of Steps in Detail ![Action step type picker](/images/integrations/actions-step-type-picker.png) #### 1. **Get Context** - **What It Is**: Collect initial data from the connected account, like subdomains or API keys. - **Example**: Getting the user’s **Salesforce subdomain** when connecting to Salesforce. #### 2. **Transform** - **What It Is**: Modify or enhance the collected data using a **JSONata** expression. - **JSONata Example**: ```jsonata { "label": $.subdomain } ``` - **Explanation**: Creates a **label** from the **subdomain** to make the account easier to recognize. #### 3. **Update Context** - **What It Is**: Save the transformed data for future use in the integration. - **Example**: Saving the Salesforce label so users can easily see their connected Salesforce account. #### 4. **Set Context** - **What It Is**: Set or update specific key-value pairs in the integration’s context. - **Use Case**: Storing user credentials securely for future API calls. #### 5. **Request** - **What It Is**: Make specific API calls to fetch or change data. - **Use Case**: After connecting to Salesforce, verify account details by fetching additional user information. - **Request Type Fields**: - **Request type**: **Proxy API** calls one of the integration's resources. **Unified API** calls a Unified API resource, such as `crm/contacts`. - **Resource**: The resource to act on, like "accounts" or "contacts." - **Method to Call**: The resource method to run, such as `list`, `get`, `create`, `update`, `delete`, or a custom method. - **ID**: The record ID, for the `get` method. - **Body**: The data sent with the request, for methods like `create` or `update`. - **Query**: Add query parameters to refine or filter data. - **Throw error**: On by default, so a failed request fails the action. Turn it off to pass the error to the next step, such as a **Transform**, instead. - **Run conditionally**: Run the step only when a JSONata expression returns `true`. ### Salesforce Example: Setting Up Actions Here’s how you might set up actions when connecting a Salesforce account: 1. **Step 1: Get Context**: - **Type**: **Get Context** - **Action**: Retrieve the **Salesforce subdomain** provided by the user. - **Use Case**: Needed to make API requests to the correct Salesforce instance. 2. **Step 2: Transform**: - **Type**: **Transform** - **JSONata Expression**: ```jsonata { "label": $.subdomain } ``` - **Explanation**: Creates a user-friendly **label** using the **subdomain**. 3. **Step 3: Update Context**: - **Type**: **Update Context** - **Action**: Save the label so users can easily identify their Salesforce account. ### Webhooks and Event Handling in Actions - **Handle Verification**: Some webhooks need to be verified before use. Add a **Request** or **Get Context** step in **Actions** to handle this automatically. - **Format and Compare**: Add steps to check specific fields in the webhook payload to verify data integrity and authenticity. ### Example of Salesforce Action Setup Here’s how the Salesforce integration might look after setting up actions: ![Salesforce Actions](/images/integrations/salesforce-post-install.png) After connecting the account, the label appears like this, making it easy to recognize: ![Salesforce Integrated Account Label](/images/integrations/salesforce-integration-label.png) ## Webhooks **Webhooks** let you receive real-time notifications from other systems when certain events happen. This section explains how to set up and handle incoming webhook events and any necessary verification. For more details, check out the [Webhooks Documentation](/docs/guides/webhooks/overview). ## RapidForm **RapidForm** helps you create customizable forms to collect user input during the integration process. You can use it to gather required credentials or other information needed to set up your integration successfully. Learn more in the [RapidForm Documentation](/docs/guides/rapid-form/overview). --- # Adding Team Members > Source: https://truto.one/docs/guides/team-members/adding-team-members/ In Truto, you can invite others to collaborate with you. Here's a simple guide on how to add team members: ## Steps to Add a Team Member 1. Log in to your Truto account. 2. Navigate to `Settings` and select `Team Members` or simply click [here](https://app.truto.one/settings/team-members). ![Team Members in Settings](/images/team-members/team-members.png) 3. Click on the `Invite to Team` button. 4. Fill in the details of the person you want to invite. These details include: - Email (required) - Name - Role: You can assign one of two roles, 'Admin' or 'Member'. - Environments: Shown only for the 'Member' role. You can grant access to one or more environments (Staging, Development, or Production). Admins get access to all environments. ![Invite a team member](/images/team-members/add-team-members.png) 5. After selecting all the details, click on the 'Invite' button. 6. An invitation will be sent to the person's email. They can join your team by accepting the invitation. And that's it! You have successfully sent an invitation to your team member. To remove someone later, open their entry in `Team Members` and turn off the **Active** toggle. They are removed from the team; their Truto account stays. ## Understanding Roles and Environments - Role: - Admin: Admins can add members and have access to all environments. - Member: Members cannot add members. They have access only to environments that the Admin allows. - Environments: - Staging: This is a testing environment. - Development: This is where you build and test your product. - Production: This is the live environment, where your product is fully functional and available to users. --- # How to Embed Truto Link SDK > Source: https://truto.one/docs/guides/link-sdk/how-to-embed/ Truto allows you to integrate its system within your application using a frontend SDK. This provides your users a seamless experience when connecting their SaaS applications with Truto. ## Steps to Embed Truto Link SDK 1. **Generate a Link Token:** In order for the SDK to function, it requires a Link Token that needs to be generated from your backend server. 2. **Implement the SDK in your Application:** Once you have the Link Token, you can implement the Truto frontend SDK in your application. To install Truto frontend SDK to embed the linking workflow click [here](https://www.npmjs.com/package/@truto/truto-link-sdk/). This opens a full-screen overlay (an iframe) on your page with an interface for the user to connect their account. ### Install the frontend SDK ```bash npm install @truto/truto-link-sdk # yarn add @truto/truto-link-sdk ``` ### Initiate the connection workflow using the SDK The SDK opens a full-screen overlay (an iframe) on top of your page with the same interface as the magic-link connection workflow, allowing the customer to connect their account. Pass `iframe: false` to open it in a popup window instead. ```js import authenticate from '@truto/truto-link-sdk'; // token received from the server const linkToken = 'bc8084a0-d745-46bd-9ca8-a9bedee9b8c6'; // authenticate opens the Truto Link UI in an overlay on your page, and returns a promise // which resolves after your customer has successfully connected their account. // It rejects if the customer closes the overlay or if there was an error while connecting their account. authenticate(linkToken).then((response) => { console.log(response); // { result: 'success', integration: 'copper', integrated_account_id: '...', post_connect_form: '{}' } }).catch((error) => { console.log(error); }) ``` > Note: Truto also provides a 'Magic Link' feature. You can check it [here](https://truto.one/docs/guides/integrated-accounts/connecting-an-account#connecting-an-account-via-truto-interface). It is a one-time connection link you can share with your customers to connect their SaaS applications with Truto. Once the connection is complete, an 'Integrated Account' is created in your Truto account for that customer. --- # Creating API Tokens > Source: https://truto.one/docs/guides/api-tokens/creating-api-tokens/ ## Understanding API Tokens An API Token is a unique identifier that authenticates requests associated with your Truto account. Each API token belongs to one [environment](/docs/guides/environments/overview) and can only access resources in that environment. API tokens cannot create, update, or delete other API tokens; manage tokens from the Truto dashboard. ## Importance of API Tokens API Tokens allow for secure communication between your software and Truto's APIs. Without an API Token, attempts to interact with Truto outside of the User Interface (UI) will fail. ## Generating an API Token Follow these steps to generate an API Token in Truto: 1. Sign in to your Truto account. 2. Navigate to the `Settings` menu and select `API Tokens`. ![Go to API tokens in Settings](/images/api-tokens/create-api-token.png) 3. Click on the `Create API Token` button. 4. Fill in the API Token details: - **Environment**: The environment the token can access. - **Name of the API Token**: For your reference only. - **Whitelisted IPs** (optional): IP addresses or CIDR ranges, such as `203.0.113.0/24`, allowed to use the token. Press Enter or comma to add each one. - **Expires At** (optional): The date and time after which the token stops working. It cannot be in the past. ![Enter Name](/images/api-tokens/name-api-token.png) 5. After entering the details, click on `Create API Token`. 6. Your API Token will be generated. This token is a unique string of alphanumeric characters. 7. Immediately copy the token and securely store it. This token is sensitive information and should not be shared publicly. ![Copy API Token](/images/docs/api-tokens/api-token-generated.png) 8. Confirm that you have copied your token by checking the box "I have copied my API Token shown above", then click `Done`. Now, you have an API Token which you can use to interact with Truto's Admin APIs. The API Tokens list shows when each token was last used and when it expires. Tokens unused for 30 days are marked **Stale**; turn on **Show stale only** to list them along with tokens that have never been used. --- # Getting started with Truto > Source: https://truto.one/docs/getting-started/ Install an integration, connect a Hubspot account, mint a link token from your backend, open the Truto Link UI from your frontend, and make your first Unified API call. :::skip-reading{header="true" cli="curl -fsSL https://cli.truto.one/install.sh | bash && truto login --token $TRUTO_API_TOKEN" skill="truto"} ::: :::callout{type="info"} On **Windows**, install the CLI with PowerShell instead: `irm https://cli.truto.one/install.ps1 | iex`, then `truto login --token $env:TRUTO_API_TOKEN`. ::: ## Setting up Truto with a coding agent If you're using Cursor, Claude Code, or any other agent that supports the [Agent Skills](https://www.anthropic.com/news/skills) convention, install the Truto skills pack and the Truto CLI once — the agent then knows how to wire Truto into your codebase from a single prompt. ### 1. Install the Truto skills pack ```bash npx skills add trutohq/truto-skills ``` This installs eight skills your agent can call into: | Skill | What it covers | |-------|----------------| | `truto` | Application code that calls the Truto API — link-token routes, unified/proxy/custom calls, webhook handlers | | `truto-link-sdk` | Embedding the Truto connection UI in a frontend with `@truto/truto-link-sdk` | | `truto-cli` | Driving the Truto CLI for setup, exploration, and debugging in the terminal | | `truto-jsonata` | Writing JSONata for unified-API mappings, sync jobs, workflows, RapidForms | | `truto-api-conventions` | Truto API base URL, auth header, URL patterns, pagination, idempotency | | `truto-integrations-build` | Building a new integration definition from a vendor's API docs with the CLI | | `truto-unified-mappings` | Building and applying the mappings that connect one integration to a unified model | | `truto-operator` | Debugging and operating a live workspace from the in-dashboard Platform Assistant | ### 2. Install the Truto CLI **Linux / macOS:** ```bash curl -fsSL https://cli.truto.one/install.sh | bash truto login --token "$TRUTO_API_TOKEN" truto whoami -o json ``` **Windows (PowerShell):** ```powershell irm https://cli.truto.one/install.ps1 | iex truto login --token $env:TRUTO_API_TOKEN truto whoami -o json ``` The installer drops the `truto` binary in `~/.truto/bin` (macOS/Linux) or `%USERPROFILE%\.truto\bin` (Windows). `TRUTO_API_TOKEN` is an API token created from the Truto Dashboard — see [Generating an API token](/docs/guides/api-tokens/creating-api-tokens). `truto whoami -o json` prints your team and environment. If you see your team name, the agent and the CLI are ready. ### 3. Prompts to drop into your agent Once the skills and CLI are in place, paste any of these into your agent. Each one uses skills installed in step 1 and is enough on its own. ```text Set up Truto in this codebase. Add a POST /api/truto/link-token route on the backend that mints a link token for a given tenantId (and reconnects an existing integratedAccountId), returning the API's own status and body when the mint is refused, and a button in the frontend that opens Truto Link with @truto/truto-link-sdk. Use the truto and truto-link-sdk skills. ``` ```text Add a webhook handler at POST /webhooks/truto. Switch on event_type. When we receive integrated_account:active, mark the tenant's connection as ready and store the integrated_account_id. Handle integrated_account:post_install_error and integrated_account:validation_error too. Use the truto skill. ``` ```text Add a server-side helper that lists CRM contacts for a given integrated_account_id by calling GET /unified/crm/contacts on api.truto.one, then walks pages with next_cursor. Use the truto skill. ``` --- ## Asking the docs with AI The Truto Docs MCP server lets any AI assistant search and read these docs directly. No API key, no install — point your client at the endpoint and ask questions. ``` https://docs-mcp.truto.one/mcp ``` Pick your client below and add the config. ### Claude Desktop Claude Desktop connects to remote MCP servers through an `npx` bridge. Add this to your `claude_desktop_config.json` (Settings > Developer > Edit Config): ```json { "mcpServers": { "truto_docs": { "command": "npx", "args": ["-y", "mcp-remote", "https://docs-mcp.truto.one/mcp"] } } } ``` Fully quit and reopen Claude Desktop after saving. ### Cursor Cursor supports remote MCP servers natively. Add this to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally: ```json { "mcpServers": { "truto_docs": { "url": "https://docs-mcp.truto.one/mcp" } } } ``` ### Claude Code ```bash claude mcp add --transport http truto_docs https://docs-mcp.truto.one/mcp ``` Add `--scope user` to make it available across all projects. ### VS Code + Copilot Add this to `.vscode/mcp.json` in your workspace: ```json { "servers": { "truto_docs": { "type": "http", "url": "https://docs-mcp.truto.one/mcp" } } } ``` ### Windsurf Add this to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "truto_docs": { "serverUrl": "https://docs-mcp.truto.one/mcp" } } } ``` --- ## Setting up Truto by hand The rest of this page is the same flow without an agent — install integrations from the Dashboard, generate an API token, mint a link token from your backend, and call the unified API yourself. Use it as a step-by-step walkthrough on its own, or as a reference for what the agent prompts above are doing. ### Install your first integration Integrations are what enable you to connect your customer's apps to Truto. Your Truto account by default doesn't come with any Integrations installed and any integration you need to use needs to be installed manually before connecting an account for it. You can head on over to the [Catalog](https://app.truto.one/catalog/integrations) to see the integrations available for installation under the **Integrations** tab. In this guide, we'll install the HubSpot integration. Find it in the Catalog and click **Install**. ![HubSpot in the Catalog](/images/getting-started/hubspot-integration-install.png) Pick the environments you want it in and click **Install**. ![Install HubSpot integration modal](/images/getting-started/hubspot-integration-install-modal.png) :::callout{type="info"} Environments are logical grouping of resources in your Truto account. They help you try out things in isolation without affecting your production data. ::: ### Install the Unified API for CRMs After installing Hubspot, we will install the Unified API for CRMs which will enable us to query the Hubspot API and get responses in a unified format. This Unified API can also be used with other CRMs. In the same [Catalog](https://app.truto.one/catalog/unified-models), switch to the **Unified APIs** tab and install the **crm** Unified API. Installing a Unified API works the same way as installing an integration. ![CRM Unified API in the Catalog](/images/getting-started/crm-model-install.png) ![Install unified API modal](/images/getting-started/crm-model-install-modal.png) ### Generate an API token You can follow our guide to generate an API token [here](/docs/guides/api-tokens/creating-api-tokens). ### Connect your first Hubspot account #### Via the dashboard Go to the [Integrated accounts](https://app.truto.one/integrated-accounts) tab and click **Connect Account** in the top-right corner. ![Integrated accounts tab](/images/getting-started/truto-connect-account.png) Fill in the **Tenant ID** — your own identifier for the customer this account belongs to, so you can match accounts back to them later. This creates (or reuses) a [tenant](/docs/guides/tenants/overview) in the environment; the same ID always refers to the same tenant, so every account this customer connects will roll up under it. Pick the **Environment** and **Region**, then click **Get connection link**. ![Connect an account modal](/images/getting-started/truto-connect-account-modal.png) Truto returns a connection link. Copy it and open it yourself, or share it with the customer. ![Connection link to share](/images/getting-started/truto-connect-account-link.png) On that page, select **HubSpot** and complete the OAuth flow. ![Select HubSpot to connect](/images/getting-started/select-hubspot.png) Back in the dashboard, click **Done** to close the modal. The new account now shows on the **Integrated accounts** tab. #### From your own app Connecting an account from your own app is two steps: 1. **Backend**: mint a link token by `POST`ing to `https://api.truto.one/link-token` with your API token. 2. **Frontend**: open the Truto Link UI with `@truto/truto-link-sdk` and that link token. **Step 1. Mint a link token from your backend** `TRUTO_API_TOKEN` is a server-side secret. Read it from an env var; never ship it to the browser. The same route handles new connections (`tenant_id`) and reconnections (`integrated_account_id`) — wiring both from the start prevents users from creating duplicate accounts when an existing connection fails. Truto auto-creates a [tenant](/docs/guides/tenants/overview) the first time a given `tenant_id` connects an account. If you'd rather pre-create the tenant (to attach `metadata` like tier or region before the customer connects), call `POST /tenant` first — see [Creating tenants](/docs/guides/tenants/creating-tenants). :::code-tabs ```bash label="cURL" curl --location 'https://api.truto.one/link-token' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $TRUTO_API_TOKEN" \ --data '{ "tenant_id": "acme-1" }' ``` ```typescript label="TypeScript (Express)" import express from 'express'; const app = express(); app.use(express.json()); app.post('/api/truto/link-token', async (req, res) => { const { tenantId, integratedAccountId } = req.body; const body = integratedAccountId ? { integrated_account_id: integratedAccountId, persist_previous_context: true } : { tenant_id: tenantId }; const response = await fetch('https://api.truto.one/link-token', { method: 'POST', headers: { Authorization: `Bearer ${process.env.TRUTO_API_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify(body), }); const { link_token } = await response.json(); res.json({ linkToken: link_token }); }); ``` ```typescript label="TypeScript (Next.js)" // app/api/truto/link-token/route.ts export async function POST(req: Request) { const { tenantId, integratedAccountId } = await req.json(); const body = integratedAccountId ? { integrated_account_id: integratedAccountId, persist_previous_context: true } : { tenant_id: tenantId }; const response = await fetch('https://api.truto.one/link-token', { method: 'POST', headers: { Authorization: `Bearer ${process.env.TRUTO_API_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify(body), }); const { link_token } = await response.json(); return Response.json({ linkToken: link_token }); } ``` ```typescript label="TypeScript (Hono)" import { Hono } from 'hono'; type Env = { TRUTO_API_TOKEN: string }; const app = new Hono<{ Bindings: Env }>(); app.post('/api/truto/link-token', async (c) => { const { tenantId, integratedAccountId } = await c.req.json(); const body = integratedAccountId ? { integrated_account_id: integratedAccountId, persist_previous_context: true } : { tenant_id: tenantId }; const response = await fetch('https://api.truto.one/link-token', { method: 'POST', headers: { Authorization: `Bearer ${c.env.TRUTO_API_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify(body), }); const { link_token } = await response.json(); return c.json({ linkToken: link_token }); }); export default app; ``` ```typescript label="TypeScript SDK" // npm install @truto/truto-ts-sdk import TrutoApi from '@truto/truto-ts-sdk'; const truto = new TrutoApi({ token: process.env.TRUTO_API_TOKEN!, }); // New connection const { link_token } = await truto.linkToken.createForNewIntegration({ tenant_id: 'acme-1', }); // Reconnect an existing account const reconnect = await truto.linkToken.createForExistingIntegratedAccount({ integrated_account_id: 'existing-account-id', }); ``` ```python label="Python (Flask)" import os import requests from flask import Flask, request, jsonify app = Flask(__name__) @app.post("/api/truto/link-token") def link_token(): payload = request.get_json() or {} tenant_id = payload.get("tenantId") integrated_account_id = payload.get("integratedAccountId") body = ( {"integrated_account_id": integrated_account_id, "persist_previous_context": True} if integrated_account_id else {"tenant_id": tenant_id} ) response = requests.post( "https://api.truto.one/link-token", headers={ "Authorization": f"Bearer {os.environ['TRUTO_API_TOKEN']}", "Content-Type": "application/json", }, json=body, timeout=10, ) response.raise_for_status() return jsonify(linkToken=response.json()["link_token"]) ``` ```python label="Python SDK" # pip install truto-python-sdk import asyncio, os from truto_python_sdk import TrutoApi async def main(): truto = TrutoApi(token=os.environ["TRUTO_API_TOKEN"]) # New connection new_token = await truto.link_tokens.create({"tenant_id": "acme-1"}) # Reconnect an existing account reconnect_token = await truto.link_tokens.create({ "integrated_account_id": "existing-account-id", "persist_previous_context": True, }) print(new_token, reconnect_token) asyncio.run(main()) ``` ::: Response: ```json { "link_token": "e73c7b9b-2e4d-47d1-b5d2-83441fd24e4c" } ``` :::callout{type="warning"} `TRUTO_API_TOKEN` must stay on the server. Never expose it to the browser, and never hardcode it in client bundles. Link tokens are safe for the frontend — each one expires after 7 days and is used up once a connection completes with it; the API token isn't. ::: **Step 2. Open Truto Link from your frontend** Install the SDK: ```bash npm install @truto/truto-link-sdk ``` Call your backend route to get a link token, then hand it to `authenticate()`. The same call works for new connections and reconnections — the difference is in the body your backend posts. ```typescript import authenticate from '@truto/truto-link-sdk'; async function getLinkToken(body: Record) { const res = await fetch('/api/truto/link-token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); const { linkToken } = await res.json(); return linkToken; } async function openTrutoLink(linkToken: string) { try { const result = await authenticate(linkToken); console.log('Connected:', result); // { result: 'success', integration: 'hubspot', integrated_account_id: '...' } return result; } catch (err) { if (err === 'closed') { console.log('User closed the connection dialog'); } else { console.error('Connection failed:', err); } throw err; } } // New connection const linkToken = await getLinkToken({ tenantId: 'acme-1' }); await openTrutoLink(linkToken); // Reconnect an existing account const reconnectToken = await getLinkToken({ integratedAccountId: 'existing-account-id' }); await openTrutoLink(reconnectToken); ``` If you'd rather not embed the SDK, you can hand the link token to Truto's hosted connection page directly: ```http https://app.truto.one/connect-account?link_token= ``` See [Embedding the Truto Link SDK](/docs/guides/link-sdk/how-to-embed) for popup, iframe, and same-window options, and the full request schema for [`POST /link-token`](/docs/api-reference/admin/link-token/create). ### Make your first API request Open the newly connected HubSpot account's detail page and switch to the **Unified API** tab. This opens a playground where you can pick a resource (like `crm/contacts`) and method, call the API, and see the unified response — a quick way to try calls before wiring them into your code. ![Try the Unified API for a connected account](/images/getting-started/integrated-account-unified-api.png) To make the same call from your code, use your API token in the `Authorization: Bearer` header. The API reference page for the [CRM Unified API](/docs/api-reference/unified-crm-api/accounts) lists every available resource and method. ## API Reference To know more about how our APIs work, you can checkout our [API Reference](/docs/api-reference/overview/introduction). --- # Admin API > Source: https://truto.one/docs/api-reference/admin/ Base URL: `https://api.truto.one/unified/` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Ping](/api-reference/admin/ping) - [GET /ping](/api-reference/admin/ping/ping) — Ping - [Link token](/api-reference/admin/link-token) - [POST /link-token](/api-reference/admin/link-token/create) — Create link token - [Session tokens](/api-reference/admin/session-tokens) - [POST /session-token](/api-reference/admin/session-tokens/create) — Create session token - [DELETE /session-token](/api-reference/admin/session-tokens/revoke) — Revoke session tokens - [POST /session-token/renew](/api-reference/admin/session-tokens/renew) — Renew session token - [GET /session-token/me](/api-reference/admin/session-tokens/me) — Introspect the current token - [Link UI](/api-reference/admin/link-ui) - [GET /link-ui/{id}/frame-ancestors](/api-reference/admin/link-ui/frame-ancestors) — Get widget frame ancestors - [Integrated accounts](/api-reference/admin/integrated-accounts) - [GET /integrated-account](/api-reference/admin/integrated-accounts/list) — List integrated accounts - [POST /integrated-account](/api-reference/admin/integrated-accounts/create) — Import integrated account - [GET /integrated-account/{id}](/api-reference/admin/integrated-accounts/get) — Get integrated account - [PATCH /integrated-account/{id}](/api-reference/admin/integrated-accounts/update) — Update integrated account - [DELETE /integrated-account/{id}](/api-reference/admin/integrated-accounts/delete) — Delete integrated account - [PATCH /integrated-account/{id}/credentials](/api-reference/admin/integrated-accounts/update-credentials) — Update integrated account credentials - [POST /integrated-account/bulk-delete](/api-reference/admin/integrated-accounts/bulk-delete) — Bulk delete integrated accounts - [POST /integrated-account/token](/api-reference/admin/integrated-accounts/create-token) — Create integrated account token - [POST /integrated-account/refresh-credentials](/api-reference/admin/integrated-accounts/refresh-credentials) — Refresh credentials - [POST /integrated-account/refresh-mapping-cache](/api-reference/admin/integrated-accounts/refresh-mapping-cache) — Refresh the mapping cache - [POST /integrated-account/form-token](/api-reference/admin/integrated-accounts/form-token) — Create post-connect form token - [POST /integrated-account/run-post-install-actions](/api-reference/admin/integrated-accounts/run-post-install-actions) — Run post install actions - [POST /integrated-account/{id}/validate](/api-reference/admin/integrated-accounts/validate) — Validate a connection now - [GET /integrated-account/{id}/tools](/api-reference/admin/integrated-accounts/tools) — (Deprecated) Get available tools for an integrated account - [GET /integrated-account/{id}/capabilities](/api-reference/admin/integrated-accounts/capabilities) — Get integrated account capabilities - [MCP](/api-reference/admin/mcp) - [GET /integrated-account/{integrated_account_id}/mcp](/api-reference/admin/mcp/list) — List MCP servers - [POST /integrated-account/{integrated_account_id}/mcp](/api-reference/admin/mcp/create) — Create MCP server - [GET /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/get) — Get MCP server - [PATCH /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/update) — Update MCP server - [DELETE /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/delete) — Delete MCP server - [Sync jobs](/api-reference/admin/sync-jobs) - [GET /sync-job](/api-reference/admin/sync-jobs/list) — List sync jobs - [POST /sync-job](/api-reference/admin/sync-jobs/create) — Create sync job - [GET /sync-job/{id}](/api-reference/admin/sync-jobs/get) — Get sync job - [PATCH /sync-job/{id}](/api-reference/admin/sync-jobs/update) — Update sync job - [DELETE /sync-job/{id}](/api-reference/admin/sync-jobs/delete) — Delete sync job - [Sync job runs](/api-reference/admin/sync-job-runs) - [GET /sync-job-run](/api-reference/admin/sync-job-runs/list) — List sync job runs - [POST /sync-job-run](/api-reference/admin/sync-job-runs/create) — Create sync job run - [GET /sync-job-run/{id}](/api-reference/admin/sync-job-runs/get) — Get sync job run - [DELETE /sync-job-run/{id}](/api-reference/admin/sync-job-runs/delete) — Stop sync job run - [Sync job cron triggers](/api-reference/admin/sync-job-cron-triggers) - [GET /sync-job-cron-trigger](/api-reference/admin/sync-job-cron-triggers/list) — List sync job cron triggers - [POST /sync-job-cron-trigger](/api-reference/admin/sync-job-cron-triggers/create) — Create sync job cron triggers - [GET /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/get) — Get sync job cron trigger - [PATCH /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/update) — Update sync job cron trigger - [DELETE /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/delete) — Delete sync job cron trigger - [Sync Job Templates](/api-reference/admin/sync-job-templates) - [GET /sync-job-template](/api-reference/admin/sync-job-templates/list) — List sync job templates - [POST /sync-job-template](/api-reference/admin/sync-job-templates/create) — Create sync job template - [GET /sync-job-template/{id}](/api-reference/admin/sync-job-templates/get) — Get sync job template by ID - [PATCH /sync-job-template/{id}](/api-reference/admin/sync-job-templates/update) — Update sync job template - [DELETE /sync-job-template/{id}](/api-reference/admin/sync-job-templates/delete) — Delete sync job template - [Webhooks](/api-reference/admin/webhooks) - [GET /webhook](/api-reference/admin/webhooks/list) — List webhooks - [POST /webhook](/api-reference/admin/webhooks/create) — Create webhook - [GET /webhook/{id}](/api-reference/admin/webhooks/get) — Get webhook - [PATCH /webhook/{id}](/api-reference/admin/webhooks/update) — Update webhook - [DELETE /webhook/{id}](/api-reference/admin/webhooks/delete) — Delete webhook - [POST /webhook/test](/api-reference/admin/webhooks/test) — Send test event - [Unified Model Docs](/api-reference/admin/unified-model-docs) - [GET /unified/meta/{model_name}/{integration_name}](/api-reference/admin/unified-model-docs/get) — Get integration specific documentation - [Batch Requests](/api-reference/admin/batch-requests) - [POST /batch-request](/api-reference/admin/batch-requests/create) — Execute a batch request - [Datastores](/api-reference/admin/datastores) - [GET /datastore](/api-reference/admin/datastores/list) — List datastores - [POST /datastore](/api-reference/admin/datastores/create) — Create a datastore - [GET /datastore/{id}](/api-reference/admin/datastores/get) — Get datastore - [PATCH /datastore/{id}](/api-reference/admin/datastores/update) — Update datastore - [DELETE /datastore/{id}](/api-reference/admin/datastores/delete) — Delete datastore - [Documentation](/api-reference/admin/documentation) - [GET /documentation](/api-reference/admin/documentation/list) — List documentation rows - [POST /documentation](/api-reference/admin/documentation/create) — Create a documentation row - [GET /documentation/{id}](/api-reference/admin/documentation/get) — Get a documentation row - [PATCH /documentation/{id}](/api-reference/admin/documentation/update) — Update a documentation row - [DELETE /documentation/{id}](/api-reference/admin/documentation/delete) — Delete a documentation row - [Logs](/api-reference/admin/logs) - [GET /log](/api-reference/admin/logs/list) — List logs - [Tenants](/api-reference/admin/tenants) - [GET /tenant](/api-reference/admin/tenants/list) — List tenants - [POST /tenant](/api-reference/admin/tenants/create) — Create tenant - [POST /tenant/bulk](/api-reference/admin/tenants/create-bulk) — Bulk create or upsert tenants - [GET /tenant/{id}](/api-reference/admin/tenants/get) — Get tenant - [PATCH /tenant/{id}](/api-reference/admin/tenants/update) — Update tenant - [DELETE /tenant/{id}](/api-reference/admin/tenants/delete) — Delete tenant - [Installed Integrations - Environment Integrations](/api-reference/admin/installed-integrations-environment-integrations) - [GET /environment-integration](/api-reference/admin/installed-integrations-environment-integrations/list) — List environment integrations - [POST /environment-integration](/api-reference/admin/installed-integrations-environment-integrations/create) — Create environment integration - [GET /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/get) — Get environment integration - [PATCH /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/update) — Update environment integration - [DELETE /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/delete) — Delete environment integration - [Integrations](/api-reference/admin/integrations) - [GET /integration](/api-reference/admin/integrations/list) — List integrations - [POST /integration](/api-reference/admin/integrations/create) — Create integration - [GET /integration/{id}](/api-reference/admin/integrations/get) — Get integration - [PATCH /integration/{id}](/api-reference/admin/integrations/update) — Update integration - [DELETE /integration/{id}](/api-reference/admin/integrations/delete) — Delete integration - [GET /integration/{id}/tools](/api-reference/admin/integrations/tools) — (Deprecated) Get integration tools - [GET /integration/{id}/unified-apis](/api-reference/admin/integrations/unified-apis) — (Deprecated) Get unified APIs supported by an integration - [GET /integration/{id}/capabilities](/api-reference/admin/integrations/capabilities) — Get integration capabilities (proxy + unified + auth) - [Api Tokens](/api-reference/admin/api-tokens) - [GET /api-token](/api-reference/admin/api-tokens/list) — List API tokens - [GET /api-token/{id}](/api-reference/admin/api-tokens/get) — Get API token - [SSO Connections](/api-reference/admin/sso-connections) - [GET /sso-connection](/api-reference/admin/sso-connections/list) — List SSO connections - [POST /sso-connection](/api-reference/admin/sso-connections/create) — Create SSO connection - [GET /sso-connection/{id}](/api-reference/admin/sso-connections/get) — Get SSO connection - [PATCH /sso-connection/{id}](/api-reference/admin/sso-connections/update) — Update SSO connection - [DELETE /sso-connection/{id}](/api-reference/admin/sso-connections/delete) — Delete SSO connection - [GET /sso-connection/{id}/domains](/api-reference/admin/sso-connections/list-domains) — List SSO connection domains - [POST /sso-connection/{id}/domains](/api-reference/admin/sso-connections/add-domain) — Add SSO connection domain - [POST /sso-connection/{id}/domains/{domain}/verify](/api-reference/admin/sso-connections/verify) — Verify SSO connection domain - [DELETE /sso-connection/{id}/domains/{domain}](/api-reference/admin/sso-connections/remove-domain) — Remove SSO connection domain - [SCIM Tokens](/api-reference/admin/scim-tokens) - [GET /scim-token](/api-reference/admin/scim-tokens/list) — List SCIM tokens - [POST /scim-token](/api-reference/admin/scim-tokens/create) — Create SCIM token - [GET /scim-token/{id}](/api-reference/admin/scim-tokens/get) — Get SCIM token - [DELETE /scim-token/{id}](/api-reference/admin/scim-tokens/delete) — Delete SCIM token - [SCIM Groups](/api-reference/admin/scim-groups) - [GET /scim-group](/api-reference/admin/scim-groups/list) — List SCIM groups - [Group Mappings](/api-reference/admin/group-mappings) - [GET /group-mapping](/api-reference/admin/group-mappings/list) — List group mappings - [POST /group-mapping](/api-reference/admin/group-mappings/create) — Create group mapping - [PATCH /group-mapping/{id}](/api-reference/admin/group-mappings/update) — Update group mapping - [DELETE /group-mapping/{id}](/api-reference/admin/group-mappings/delete) — Delete group mapping - [Static Gates](/api-reference/admin/static-gates) - [GET /static-gate](/api-reference/admin/static-gates/list) — List static gates - [POST /static-gate](/api-reference/admin/static-gates/create) — Create static gate - [GET /static-gate/{id}](/api-reference/admin/static-gates/get) — Get static gate - [PATCH /static-gate/{id}](/api-reference/admin/static-gates/patch) — Update static gate - [DELETE /static-gate/{id}](/api-reference/admin/static-gates/delete) — Delete static gate - [Observability destinations](/api-reference/admin/observability-destinations) - [GET /observability-destination](/api-reference/admin/observability-destinations/list) — List observability destinations - [POST /observability-destination](/api-reference/admin/observability-destinations/create) — Create observability destination - [GET /observability-destination/{id}](/api-reference/admin/observability-destinations/get) — Get observability destination - [PATCH /observability-destination/{id}](/api-reference/admin/observability-destinations/update) — Update observability destination - [DELETE /observability-destination/{id}](/api-reference/admin/observability-destinations/delete) — Delete observability destination - [POST /observability-destination/{id}/test](/api-reference/admin/observability-destinations/test) — Test observability destination - [Environments](/api-reference/admin/environments) - [GET /environment](/api-reference/admin/environments/list) — List environments - [Unified Models](/api-reference/admin/unified-models) - [GET /unified-model](/api-reference/admin/unified-models/list) — List unified models - [POST /unified-model](/api-reference/admin/unified-models/create) — Create unified model - [GET /unified-model/{id}](/api-reference/admin/unified-models/get) — Get unified model - [PATCH /unified-model/{id}](/api-reference/admin/unified-models/update) — Update unified model - [DELETE /unified-model/{id}](/api-reference/admin/unified-models/delete) — Delete unified model - [Installed Unified Models - Environment Unified Models](/api-reference/admin/installed-unified-models-environment-unified-models) - [GET /environment-unified-model](/api-reference/admin/installed-unified-models-environment-unified-models/list) — List environment unified models - [POST /environment-unified-model](/api-reference/admin/installed-unified-models-environment-unified-models/create) — Create environment unified model - [GET /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/get) — Get environment unified model - [PATCH /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/update) — Update environment unified model - [DELETE /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/delete) — Delete environment unified model - [Unified Model Mappings](/api-reference/admin/unified-model-mappings) - [GET /unified-model-resource-method](/api-reference/admin/unified-model-mappings/list) — List unified model mappings - [POST /unified-model-resource-method](/api-reference/admin/unified-model-mappings/create) — Create unified model mapping - [GET /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/get) — Get unified model mapping - [PATCH /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/update) — Update unified model mapping - [DELETE /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/delete) — Delete unified model mapping - [Installed Unified Models - Environment Unified Model Mappings](/api-reference/admin/installed-unified-models-environment-unified-model-mappings) - [GET /environment-unified-model-resource-method](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/list) — List environment unified model mappings - [POST /environment-unified-model-resource-method](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/create) — Create environment unified model mapping - [GET /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/get) — Get environment unified model mapping - [PATCH /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/update) — Update environment unified model mapping - [DELETE /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/delete) — Delete environment unified model mapping - [Categories](/api-reference/admin/categories) - [GET /category](/api-reference/admin/categories/list) — List categories - [Sync Job Run State](/api-reference/admin/sync-job-run-state) - [GET /sync-job-run-state](/api-reference/admin/sync-job-run-state/list) — List sync job run states - [POST /sync-job-run-state](/api-reference/admin/sync-job-run-state/create) — Create sync job run state - [GET /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/get) — Get sync job run state - [PATCH /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/update) — Update sync job run state - [DELETE /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/delete) — Delete sync job run state - [Workflows](/api-reference/admin/workflows) - [GET /workflow](/api-reference/admin/workflows/list) — List workflows - [POST /workflow](/api-reference/admin/workflows/create) — Create workflow - [GET /workflow/{id}](/api-reference/admin/workflows/get) — Get workflow - [DELETE /workflow/{id}](/api-reference/admin/workflows/delete) — Delete workflow - [WorkflowRuns](/api-reference/admin/workflowruns) - [GET /workflow-run](/api-reference/admin/workflowruns/list) — List workflow runs - [GET /workflow-run/{id}](/api-reference/admin/workflowruns/get) — Get workflow run - [Platform assistant](/api-reference/admin/platform-assistant) - [POST /platform/mcp](/api-reference/admin/platform-assistant/mcp) — Platform MCP (JSON-RPC) - [GET /assistant/models](/api-reference/admin/platform-assistant/listModels) — List allowed assistant models - [GET /assistant/platform-mcp](/api-reference/admin/platform-assistant/getPlatformMcpInfo) — Get Platform MCP connection info - [GET /assistant/settings](/api-reference/admin/platform-assistant/getAssistantSettings) — Get team assistant settings - [PATCH /assistant/settings](/api-reference/admin/platform-assistant/patchAssistantSettings) — Update team assistant settings (team admin) - [POST /assistant/settings/test-key](/api-reference/admin/platform-assistant/testAssistantApiKey) — Test Anthropic API key (team admin) - [GET /assistant/status](/api-reference/admin/platform-assistant/assistantStatus) — Assistant availability for current team - [Passkeys](/api-reference/admin/passkeys) - [POST /auth/passkey/registration/options](/api-reference/admin/passkeys/registration-options) — Start passkey registration - [POST /auth/passkey/registration/verify](/api-reference/admin/passkeys/registration-verify) — Finish passkey registration - [GET /auth/passkey](/api-reference/admin/passkeys/list) — List your passkeys - [PATCH /auth/passkey/{id}](/api-reference/admin/passkeys/patch) — Rename a passkey - [DELETE /auth/passkey/{id}](/api-reference/admin/passkeys/delete) — Delete a passkey - [POST /auth/passkey/authentication/options](/api-reference/admin/passkeys/authentication-options) — Start passwordless passkey sign-in - [POST /auth/passkey/authentication/verify](/api-reference/admin/passkeys/authentication-verify) — Finish passwordless passkey sign-in - [Billing](/api-reference/admin/billing) - [GET /billing/summary](/api-reference/admin/billing/summary) — Get billing summary - [GET /billing/usage](/api-reference/admin/billing/usage) — Get billing usage for a month - [GET /billing/invoice](/api-reference/admin/billing/list) — List invoices - [GET /billing/invoice/{id}](/api-reference/admin/billing/get) — Get invoice - [POST /billing/portal-session](/api-reference/admin/billing/create_portal_session) — Create Stripe Customer Portal session - [POST /billing/checkout-setup-session](/api-reference/admin/billing/create_checkout_setup_session) — Create Stripe Checkout session to add a payment method - [Analytics](/api-reference/admin/analytics) - [GET /analytics/metrics](/api-reference/admin/analytics/metrics) — List analytics metrics - [GET /analytics/status](/api-reference/admin/analytics/status) — Get analytics status for an environment - [GET /analytics/dashboard](/api-reference/admin/analytics/dashboard) — Get an environment's analytics dashboard - [GET /analytics/timeseries](/api-reference/admin/analytics/timeseries) — Get an analytics time series - [GET /analytics/breakdown](/api-reference/admin/analytics/breakdown) — Get a paginated analytics breakdown --- # Ping Object > Source: https://truto.one/docs/api-reference/admin/ping/ Schema for the `Ping` resource in **Admin API**. ## Properties - **`message`** _(string)_ Always returns the string `pong` when the API is reachable. ## Methods - [GET /ping](/api-reference/admin/ping/ping) — Ping --- # Link token Object > Source: https://truto.one/docs/api-reference/admin/link-token/ Schema for the `Link token` resource in **Admin API**. ## Properties - **`link_token`** _(string)_ The link token that can be used to initiate a connection flow. ## Methods - [POST /link-token](/api-reference/admin/link-token/create) — Create link token --- # Session tokens Object > Source: https://truto.one/docs/api-reference/admin/session-tokens/ Schema for the `Session tokens` resource in **Admin API**. _No documented properties._ ## Methods - [POST /session-token](/api-reference/admin/session-tokens/create) — Create session token - [DELETE /session-token](/api-reference/admin/session-tokens/revoke) — Revoke session tokens - [POST /session-token/renew](/api-reference/admin/session-tokens/renew) — Renew session token - [GET /session-token/me](/api-reference/admin/session-tokens/me) — Introspect the current token --- # Link UI Object > Source: https://truto.one/docs/api-reference/admin/link-ui/ Schema for the `Link UI` resource in **Admin API**. _No documented properties._ ## Methods - [GET /link-ui/{id}/frame-ancestors](/api-reference/admin/link-ui/frame-ancestors) — Get widget frame ancestors --- # Integrated accounts Object > Source: https://truto.one/docs/api-reference/admin/integrated-accounts/ Schema for the `Integrated accounts` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the integrated account. - **`tenant_id`** _(string)_ The ID of the tenant. - **`environment_integration_id`** _(string)_ The ID of the environment integration (installed integration). - **`context`** _(object)_ The context of the integrated account. You can find these in the `Variables` section of an integrated account in the Truto UI. - **`status`** _(string)_ Status of the integrated account. - `active` - Everything is fine and the account should work - `connecting` - Post install and validation steps are being run - `post_install_error` - There was an error while running post install steps - `validation_error` - There was an error while running validation steps - `needs_reauth` - There was an error while refreshing the credentials in case of OAuth authentication or the credentials are no longer valid in other authentication methods. The integrated account needs to be reauthorized. Allowed: `active`, `connecting`, `post_install_error`, `validation_error`, `needs_reauth` - **`last_error`** _(string)_ The last error that occurred while running the post install or validation steps. - **`last_forbidden_error`** _(object)_ Details of the most recent `403 Forbidden` returned by the third-party API for this account, or `null` if the most recent call succeeded. Cleared automatically on the next successful call. - **`resource`** _(string)_ The third-party resource that was forbidden. - **`method`** _(string)_ The method that was attempted on that resource. - **`missing_scopes`** _(array)_ The scopes required by this resource and method that the provider did not confirm as granted. Present only when both halves of that comparison are known: the provider echoed the scopes it granted, **and** this resource and method declares required scopes. It is **absent** — not empty — otherwise, which includes `api_key` and OAuth1 connections (no scope grant exists), OAuth2 and `jwt_bearer` connections where the provider omits `scope` from its token response, resources and methods that declare no required scopes, and requirements that are not OAuth scopes at all (`refusal_basis: non_scope_requirement` — see `permission_vocabulary`), where no diff is run and `required_permissions` carries the answer instead. An empty array therefore means "no *all-of* scope is missing", while an absent field means "cannot be determined" — two different statements. Read `refusal_basis` for the one question this field cannot answer on its own, "was anything missing at all": an empty array sits beside a populated `missing_any_of_scopes` whenever the whole shortfall is an unmet any-of requirement, so on `refusal_basis: scopes_missing` an empty array does **not** mean every permission was granted. It means that on `refusal_basis: scopes_satisfied`, and only there. Do not default an absent `missing_scopes` to `[]` either: that reads back as "nothing is missing" about a request that was refused. Truto's comparison is an inference over integration configuration. The provider's own account of the refusal is the authoritative one, and Truto relays it without interpreting it: `raw_response` (the error body verbatim) and `message` (its human text) on the 403 itself, and a capped copy of the body on this record as `raw_response_excerpt`. `message` is not persisted, so re-run the call to see it. Truto deliberately does not lift a "code" or a "documentation link" out of that body. Which key in an arbitrary provider's error shape is the important one has no correct general answer, and a confidently wrong one placed above a correct body is the same failure as reporting a scope missing that was never checked. - **`refusal_basis`** _(string)_ Which of the states below produced this record, so a reader never has to infer it from the presence or emptiness of `missing_scopes`. Absent on rows recorded before Truto stored it — and on such a row an empty `missing_scopes` cannot be read as "compared, nothing missing", because it was also written when nothing had been compared at all. **An open set, and `x-extensible-enum` rather than `enum` says so to a code generator as well as to a reader.** Prose asking for a default branch is not something a generator reads, and a closed union here can be violated by design: the read path deliberately accepts an unrecognised value so a row written by a newer build stays readable after a rollback, and the older build then serves that value straight back on this field. The values below are what Truto writes today. Keep a default branch. The live `truto_error_insight.forbidden_error.value.refusal_basis` keeps a closed `enum`, and the asymmetry is the point: a running build always emits its own documented set, while a stored row can carry a value the build reading it never wrote. - **`description`** _(string)_ The sentence the live 403 carried, recorded so this row reads the same as the call did. - **`missing_any_of_scopes`** _(array)_ Scopes of which the operation needs *any one*, where the grant holds none. Kept apart from `missing_scopes` so alternatives are never reported as though all were required. - **`required_permissions`** _(array)_ What this operation requires, whether or not a comparison was possible. Always paired with `permission_vocabulary`, since the same string means "reconnect and grant this", "add this to your API key" or "ask an admin for this role" depending on which vocabulary it is written in. - **`required_any_of_permissions`** _(array)_ Permissions of which the operation needs *any one*, kept apart from `required_permissions` for the same reason. - **`permission_vocabulary`** _(string)_ Which vocabulary `required_permissions` is written in, and therefore what the remedy is. Only `oauth_scope` is fixed by reconnecting: `api_key_permission` is granted to the API key in the provider, and `role_label` in the provider's own admin console. `x-extensible-enum` for the same reason as `refusal_basis` above: this is a stored value, and a rollback can serve one written by a build that knew a fourth vocabulary. Keep a default branch. - **`raw_response_excerpt`** _(string)_ A capped copy of the integration's own error body, so this record shows what the provider said and not only what Truto inferred about it. Truncated with a trailing `… truncated` marker past 2,048 **bytes** of UTF-8, because this record is deserialized on every proxy and unified call that resolves the account and that cost is what the bound exists to control. Bytes, not characters: 2,048 characters of CJK is about 6 KB stored, so a character bound would charge one language three times what it charges another. Expect fewer characters than 2,048 for any non-ASCII body. The 2,048 covers the marker as well, so the stored value never exceeds it. **A truncated excerpt is not parseable.** It is a byte prefix of a serialized body with a marker on the end, so `JSON.parse` on this field throws whenever truncation happened — which the trailing `… truncated` is how you detect. Render it as text. An untruncated excerpt of a JSON body does parse, but nothing guarantees this field is JSON at all: a plain-text or HTML error body is stored exactly as it arrived. Absent when the refusal carried no body. Not forwarded to the connections widget: it is a raw provider string, which is what `connections.show_error_details` exists to keep away from an end user. Note that "every remote 403 carries an insight" and "every remote 403 leaves a record here" are different statements. A Proxy API **custom method** and a **Custom API** both carry the live insight, but a Custom API names no resource or method, and writing `{resource: "", method: ""}` would replace a record naming a real call with one naming none — so no record is written for those. Read the insight on the response for them. - **`occurred_at`** _(string)_ When the forbidden response was recorded. - **`last_action_run_result`** _(object)_ The results of the post install and validation steps that ran on the integrated account. - **`integration_override`** _(object)_ An optional config override applied for this integrated account only. Deep-merged on top of the integration config and the environment-level override at request time. - **`unified_model_override`** _(object)_ Account-scoped unified-mapping overrides, deep-merged on top of the environment and base mappings for this integrated account only. - **`features`** _(object)_ Platform features enabled on the integrated account. `super_query` holds the SuperQuery region once a sync job run with SuperQuery has run for the account. - **`created_at`** _(string)_ The date and time when the integrated account was created. - **`updated_at`** _(string)_ The date and time when the integrated account was last updated. - **`is_sandbox`** _(boolean)_ Whether the integrated account is in sandbox mode or not. Sandbox integrated accounts do not allow any "write" operations. - **`authentication_method`** _(string)_ Type of authentication used. Allowed: `oauth2`, `oauth`, `api_key`, `oauth2_client_credentials`, `keka_oauth`, `jwt_bearer`, `aws_sts` - **`region`** _(string)_ The region where the integrated account is placed. Allowed: `wnam`, `enam`, `apac`, `eu` ## Methods - [GET /integrated-account](/api-reference/admin/integrated-accounts/list) — List integrated accounts - [POST /integrated-account](/api-reference/admin/integrated-accounts/create) — Import integrated account - [GET /integrated-account/{id}](/api-reference/admin/integrated-accounts/get) — Get integrated account - [PATCH /integrated-account/{id}](/api-reference/admin/integrated-accounts/update) — Update integrated account - [DELETE /integrated-account/{id}](/api-reference/admin/integrated-accounts/delete) — Delete integrated account - [PATCH /integrated-account/{id}/credentials](/api-reference/admin/integrated-accounts/update-credentials) — Update integrated account credentials - [POST /integrated-account/bulk-delete](/api-reference/admin/integrated-accounts/bulk-delete) — Bulk delete integrated accounts - [POST /integrated-account/token](/api-reference/admin/integrated-accounts/create-token) — Create integrated account token - [POST /integrated-account/refresh-credentials](/api-reference/admin/integrated-accounts/refresh-credentials) — Refresh credentials - [POST /integrated-account/refresh-mapping-cache](/api-reference/admin/integrated-accounts/refresh-mapping-cache) — Refresh the mapping cache - [POST /integrated-account/form-token](/api-reference/admin/integrated-accounts/form-token) — Create post-connect form token - [POST /integrated-account/run-post-install-actions](/api-reference/admin/integrated-accounts/run-post-install-actions) — Run post install actions - [POST /integrated-account/{id}/validate](/api-reference/admin/integrated-accounts/validate) — Validate a connection now - [GET /integrated-account/{id}/tools](/api-reference/admin/integrated-accounts/tools) — (Deprecated) Get available tools for an integrated account - [GET /integrated-account/{id}/capabilities](/api-reference/admin/integrated-accounts/capabilities) — Get integrated account capabilities --- # MCP Object > Source: https://truto.one/docs/api-reference/admin/mcp/ Schema for the `MCP` resource in **Admin API**. ## Properties - **`id`** _(string)_ Unique identifier for the MCP server. - **`name`** _(string)_ Human-readable name for the MCP server. - **`integrated_account_id`** _(string)_ The integrated account this MCP server is bound to. - **`config`** _(object)_ Optional scoping for the MCP server. When omitted, all available tools for the integrated account are exposed. - **`methods`** _(array)_ Restrict the MCP server to these methods. Use a method name such as `list` or `get`, or one of the groups `read`, `write` and `custom`. Combined with `tags` using AND semantics. - **`tags`** _(array)_ Restrict the MCP server to tools whose effective tags (resource-level and optional resource.method tags) intersect these values. - **`tool_exposure`** _(string)_ How tools are exposed on `tools/list`. - `all` (default): every matching tool schema is listed. - `discovery`: only three meta-tools are listed (`search_tools`, `get_tool_schema`, `call_tool`). The client discovers and calls real tools through those. Allowed: `all`, `discovery` - **`require_api_token_auth`** _(boolean)_ When true, MCP requests also require a valid Truto API token in the Authorization Bearer header. - **`expires_at`** _(string)_ Optional expiry timestamp. When set, the MCP server's token is invalidated after this time. - **`created_by`** _(string)_ ID of the user who created the MCP server. - **`created_at`** _(string)_ Time at which the MCP server was created. - **`updated_at`** _(string)_ Time at which the MCP server was last updated. ## Methods - [GET /integrated-account/{integrated_account_id}/mcp](/api-reference/admin/mcp/list) — List MCP servers - [POST /integrated-account/{integrated_account_id}/mcp](/api-reference/admin/mcp/create) — Create MCP server - [GET /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/get) — Get MCP server - [PATCH /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/update) — Update MCP server - [DELETE /integrated-account/{integrated_account_id}/mcp/{id}](/api-reference/admin/mcp/delete) — Delete MCP server --- # Sync jobs Object > Source: https://truto.one/docs/api-reference/admin/sync-jobs/ Schema for the `Sync jobs` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the sync job. - **`integration_name`** _(string)_ The name of the integration that this sync job interacts with. - **`label`** _(string)_ A human-readable name for the sync job. - **`args_validation`** _(string)_ An optional JSONata expression evaluated against the run's `args` when a sync job run is created. Return an object with a `message` field to reject the args with a 400. - **`default_runtime_version`** _(integer)_ The runtime version that sync job runs use by default. Allowed: `1`, `2`, `3`, `4` - **`mutex_key`** _(string)_ An optional key, with `{{args.*}}` placeholders, that stops a new run from starting while a run with the same resolved key is still active. Applies on runtime version 4. - **`state_key`** _(string)_ An optional key, with `{{args.*}}` placeholders, that names the namespace the sync job's `get_state`, `update_state` and `delete_state` nodes read and write. Required for a sync job that uses those nodes. - **`delay_between_requests_ms`** _(integer)_ An optional delay, in milliseconds, between requests made by the sync job's runs on runtime version 4. - **`args_schema`** _(object, required)_ JSON schema defining the structure of the arguments that can be passed to the sync job. Same shape as `JsonSchemaObject` (top-level `{ type: "object", properties }`). - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`resources`** _(array)_ The resources to sync as part of the sync job. - **`name`** _(string)_ The name of the node. Required on runtime version 4, where `depends_on` and destinations refer to nodes by name. Keep names unique within a sync job. - **`type`** _(string)_ The node type. Required on runtime version 4. Each type reads its own fields; `resource`, `method`, `id`, `query` and `loop_on` apply to `request` nodes. Allowed: `request`, `transform`, `spool`, `add_context`, `destination`, `event`, `get_state`, `update_state`, `delete_state` - **`run_if`** _(string)_ A JSONata expression. On runtime version 4 the node runs only when it evaluates to a truthy value. - **`resource`** _(string)_ The name of the resource to sync. Required for `request` nodes and on runtime versions 1 to 3. For Unified APIs, it should be in the format `unified_api_name/resource_name`. For Proxy API, it can just be `resource_name`. - **`method`** _(string)_ The method to call on the resource. - **`id`** _(string)_ The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders. - **`query`** _(object)_ The query parameters to pass to the resource method. It supports placeholders for values. - **`loop_on`** _(string)_ When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called `user_ids` which is an array of strings, and you want to fetch each user's details, you can set this parameter to `args.user_ids` and the request will be repeated for each element in the `user_ids` array. - **`depends_on`** _(string)_ The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. `{{resources.crm.contacts.id}}` if depends on is `crm/contacts` resource. - **`persist`** _(boolean)_ Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to `true` to persist them. Unified API resources are always persisted. - **`environment_id`** _(string)_ The ID of the environment that this sync job belongs to. - **`created_at`** _(string)_ The date and time when the sync job was created. - **`updated_at`** _(string)_ The date and time when the sync job was last updated. ## Methods - [GET /sync-job](/api-reference/admin/sync-jobs/list) — List sync jobs - [POST /sync-job](/api-reference/admin/sync-jobs/create) — Create sync job - [GET /sync-job/{id}](/api-reference/admin/sync-jobs/get) — Get sync job - [PATCH /sync-job/{id}](/api-reference/admin/sync-jobs/update) — Update sync job - [DELETE /sync-job/{id}](/api-reference/admin/sync-jobs/delete) — Delete sync job --- # Sync job runs Object > Source: https://truto.one/docs/api-reference/admin/sync-job-runs/ Schema for the `Sync job runs` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the sync job run. - **`args`** _(object)_ The arguments passed to the sync job run. - **`resources`** _(array)_ The resources to sync as part of the sync job. - **`name`** _(string)_ The name of the node. Required on runtime version 4, where `depends_on` and destinations refer to nodes by name. Keep names unique within a sync job. - **`type`** _(string)_ The node type. Required on runtime version 4. Each type reads its own fields; `resource`, `method`, `id`, `query` and `loop_on` apply to `request` nodes. Allowed: `request`, `transform`, `spool`, `add_context`, `destination`, `event`, `get_state`, `update_state`, `delete_state` - **`run_if`** _(string)_ A JSONata expression. On runtime version 4 the node runs only when it evaluates to a truthy value. - **`resource`** _(string)_ The name of the resource to sync. Required for `request` nodes and on runtime versions 1 to 3. For Unified APIs, it should be in the format `unified_api_name/resource_name`. For Proxy API, it can just be `resource_name`. - **`method`** _(string)_ The method to call on the resource. - **`id`** _(string)_ The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders. - **`query`** _(object)_ The query parameters to pass to the resource method. It supports placeholders for values. - **`loop_on`** _(string)_ When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called `user_ids` which is an array of strings, and you want to fetch each user's details, you can set this parameter to `args.user_ids` and the request will be repeated for each element in the `user_ids` array. - **`depends_on`** _(string)_ The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. `{{resources.crm.contacts.id}}` if depends on is `crm/contacts` resource. - **`persist`** _(boolean)_ Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to `true` to persist them. Unified API resources are always persisted. - **`sync_job_id`** _(string)_ The ID of the sync job that this sync job run belongs to. - **`integrated_account_id`** _(string)_ The ID of the integrated account that this sync job run belongs to. - **`status`** _(string)_ The status of the sync job run. `created` - waiting to run, `running` - running, `rate_limited` - temporarily paused after an upstream rate-limit response and will resume automatically after backoff, `completed` - completed successfully, `failed` - failed, `stopped` - stopped by the user. Allowed: `created`, `running`, `rate_limited`, `completed`, `failed`, `stopped` - **`daemon_id`** _(string)_ The daemon_id attribute of a daemon that is running this sync job. - **`daemon_group_key`** _(string)_ The name of the daemon group that this sync job run should be assigned to. Used while creating a sync job run. Truto find a daemon in the group that is available to run the sync job. On runtime versions 1 to 3, specify exactly one of `daemon_group_key` (Daemon), `webhook_id` (RapidBridge), `datastore_id` or `super_query` while creating a Sync Job Run. - **`webhook_id`** _(string)_ The ID of the webhook where the sync job records need to be sent. On runtime versions 1 to 3, specify exactly one of `daemon_group_key` (Daemon), `webhook_id` (RapidBridge), `datastore_id` or `super_query` while creating a Sync Job Run. - **`error_handling`** _(string)_ Specifies the error handling strategy used for the sync job run. `fail_fast` - stop the sync job run as soon as an error is encountered, `ignore` - continue running the sync job run even if an error is encountered. In case of `ignore`, you'll receive `sync_job_run:record_error` events for each error encountered. In case of `batch`, you'll receive `sync_job_run:record_error` events with multiple errors batched into the errors array, this is only supported when the `version` used for Sync Job Run is 2. Allowed: `fail_fast`, `ignore`, `batch` - **`ignore_previous_run`** _(boolean)_ Specifies if the sync job run was started ignoring the previous run date. - **`version`** _(integer)_ The runtime version of the sync job run. Defaults to the sync job's `default_runtime_version`. Allowed: `1`, `2`, `3`, `4` - **`force`** _(boolean)_ Whether the run was started even though another run of the same sync job, integrated account and args was still active. - **`super_query`** _(string)_ The SuperQuery region the run's records are stored in, when the run uses SuperQuery as its destination. Allowed: `apac`, `wnam` - **`datastore_id`** _(string)_ The ID of the datastore the run's records are sent to, when the run uses a datastore as its destination. - **`events_to_send`** _(array)_ When set, only these `sync_job_run:*` and `record:*` events are sent for the run. When not set, every event is sent. - **`mutex_key`** _(string)_ The sync job's `mutex_key` with the run's args filled in. - **`state_key`** _(string)_ The sync job's `state_key` with the run's args filled in. Names the namespace the run's state nodes use. - **`resource_stats`** _(object)_ The statistics of the resources synced in the sync job run. This will have information around how many records were fetched and persisted by the sync job run -- grouped by the resource and method. The data is updated every 10 seconds while the sync job run is running. - **`created_at`** _(string)_ The date and time when the sync job run was created. - **`updated_at`** _(string)_ The date and time when the sync job run was last updated. - **`started_at`** _(string)_ The date and time when the sync job run was started. - **`finished_at`** _(string)_ The date and time when the sync job run was finished. - **`sync_job`** _(object)_ - **`id`** _(string)_ The ID of the sync job. - **`integration_name`** _(string)_ The name of the integration that this sync job interacts with. - **`label`** _(string)_ A human-readable name for the sync job. - **`args_validation`** _(string)_ An optional JSONata expression evaluated against the run's `args` when a sync job run is created. Return an object with a `message` field to reject the args with a 400. - **`default_runtime_version`** _(integer)_ The runtime version that sync job runs use by default. Allowed: `1`, `2`, `3`, `4` - **`mutex_key`** _(string)_ An optional key, with `{{args.*}}` placeholders, that stops a new run from starting while a run with the same resolved key is still active. Applies on runtime version 4. - **`state_key`** _(string)_ An optional key, with `{{args.*}}` placeholders, that names the namespace the sync job's `get_state`, `update_state` and `delete_state` nodes read and write. Required for a sync job that uses those nodes. - **`delay_between_requests_ms`** _(integer)_ An optional delay, in milliseconds, between requests made by the sync job's runs on runtime version 4. - **`args_schema`** _(object, required)_ JSON schema defining the structure of the arguments that can be passed to the sync job. Same shape as `JsonSchemaObject` (top-level `{ type: "object", properties }`). - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`resources`** _(array)_ The resources to sync as part of the sync job. - **`name`** _(string)_ The name of the node. Required on runtime version 4, where `depends_on` and destinations refer to nodes by name. Keep names unique within a sync job. - **`type`** _(string)_ The node type. Required on runtime version 4. Each type reads its own fields; `resource`, `method`, `id`, `query` and `loop_on` apply to `request` nodes. Allowed: `request`, `transform`, `spool`, `add_context`, `destination`, `event`, `get_state`, `update_state`, `delete_state` - **`run_if`** _(string)_ A JSONata expression. On runtime version 4 the node runs only when it evaluates to a truthy value. - **`resource`** _(string)_ The name of the resource to sync. Required for `request` nodes and on runtime versions 1 to 3. For Unified APIs, it should be in the format `unified_api_name/resource_name`. For Proxy API, it can just be `resource_name`. - **`method`** _(string)_ The method to call on the resource. - **`id`** _(string)_ The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders. - **`query`** _(object)_ The query parameters to pass to the resource method. It supports placeholders for values. - **`loop_on`** _(string)_ When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called `user_ids` which is an array of strings, and you want to fetch each user's details, you can set this parameter to `args.user_ids` and the request will be repeated for each element in the `user_ids` array. - **`depends_on`** _(string)_ The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. `{{resources.crm.contacts.id}}` if depends on is `crm/contacts` resource. - **`persist`** _(boolean)_ Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to `true` to persist them. Unified API resources are always persisted. - **`environment_id`** _(string)_ The ID of the environment that this sync job belongs to. - **`created_at`** _(string)_ The date and time when the sync job was created. - **`updated_at`** _(string)_ The date and time when the sync job was last updated. ## Methods - [GET /sync-job-run](/api-reference/admin/sync-job-runs/list) — List sync job runs - [POST /sync-job-run](/api-reference/admin/sync-job-runs/create) — Create sync job run - [GET /sync-job-run/{id}](/api-reference/admin/sync-job-runs/get) — Get sync job run - [DELETE /sync-job-run/{id}](/api-reference/admin/sync-job-runs/delete) — Stop sync job run --- # Sync job cron triggers Object > Source: https://truto.one/docs/api-reference/admin/sync-job-cron-triggers/ Schema for the `Sync job cron triggers` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the sync job cron trigger. - **`args`** _(object)_ The arguments passed to the sync job cron trigger. - **`resources`** _(array)_ The resources to sync as part of the sync job. - **`name`** _(string)_ The name of the node. Required on runtime version 4, where `depends_on` and destinations refer to nodes by name. Keep names unique within a sync job. - **`type`** _(string)_ The node type. Required on runtime version 4. Each type reads its own fields; `resource`, `method`, `id`, `query` and `loop_on` apply to `request` nodes. Allowed: `request`, `transform`, `spool`, `add_context`, `destination`, `event`, `get_state`, `update_state`, `delete_state` - **`run_if`** _(string)_ A JSONata expression. On runtime version 4 the node runs only when it evaluates to a truthy value. - **`resource`** _(string)_ The name of the resource to sync. Required for `request` nodes and on runtime versions 1 to 3. For Unified APIs, it should be in the format `unified_api_name/resource_name`. For Proxy API, it can just be `resource_name`. - **`method`** _(string)_ The method to call on the resource. - **`id`** _(string)_ The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders. - **`query`** _(object)_ The query parameters to pass to the resource method. It supports placeholders for values. - **`loop_on`** _(string)_ When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called `user_ids` which is an array of strings, and you want to fetch each user's details, you can set this parameter to `args.user_ids` and the request will be repeated for each element in the `user_ids` array. - **`depends_on`** _(string)_ The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. `{{resources.crm.contacts.id}}` if depends on is `crm/contacts` resource. - **`persist`** _(boolean)_ Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to `true` to persist them. Unified API resources are always persisted. - **`cron_expression`** _(string)_ The cron expression defining when the sync job should run, in UTC. - **`sync_job_id`** _(string)_ The ID of the sync job that this sync job cron trigger should run. - **`integrated_account_id`** _(string)_ The ID of the integrated account that this sync job cron trigger should run. - **`daemon_group_key`** _(string)_ The name of the daemon group that this sync job run should be assigned to. Used while creating a sync job run. Truto find a daemon in the group that is available to run the sync job. On runtime versions 1 to 3, specify exactly one of `daemon_group_key` (Daemon), `webhook_id` (RapidBridge) or `super_query`. - **`webhook_id`** _(string)_ The ID of the webhook where the sync job records need to be sent. On runtime versions 1 to 3, specify exactly one of `daemon_group_key` (Daemon), `webhook_id` (RapidBridge) or `super_query`. - **`super_query`** _(string)_ Store the records of the runs the trigger starts in SuperQuery in this region. On runtime versions 1 to 3, specify exactly one of `daemon_group_key` (Daemon), `webhook_id` (RapidBridge) or `super_query`. Allowed: `apac`, `wnam` - **`created_at`** _(string)_ The date and time when the sync job run was created. - **`updated_at`** _(string)_ The date and time when the sync job run was last updated. ## Methods - [GET /sync-job-cron-trigger](/api-reference/admin/sync-job-cron-triggers/list) — List sync job cron triggers - [POST /sync-job-cron-trigger](/api-reference/admin/sync-job-cron-triggers/create) — Create sync job cron triggers - [GET /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/get) — Get sync job cron trigger - [PATCH /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/update) — Update sync job cron trigger - [DELETE /sync-job-cron-trigger/{id}](/api-reference/admin/sync-job-cron-triggers/delete) — Delete sync job cron trigger --- # Sync Job Templates Object > Source: https://truto.one/docs/api-reference/admin/sync-job-templates/ Schema for the `Sync Job Templates` resource in **Admin API**. ## Properties - **`id`** _(string)_ The unique ID of the sync job template. - **`integration_name`** _(string)_ The integration name to which this template applies. Is null for default_runtime_version > 4. - **`label`** _(string)_ A short descriptor for the template. - **`description`** _(string)_ Optional longer description of what this template does. - **`args_schema`** _(object, required)_ Optional JSON schema describing arguments for the sync job. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`resources`** _(array)_ A list of sync job resources that define the steps. If empty, no default resources are set. - **`name`** _(string)_ The name of the node. Required on runtime version 4, where `depends_on` and destinations refer to nodes by name. Keep names unique within a sync job. - **`type`** _(string)_ The node type. Required on runtime version 4. Each type reads its own fields; `resource`, `method`, `id`, `query` and `loop_on` apply to `request` nodes. Allowed: `request`, `transform`, `spool`, `add_context`, `destination`, `event`, `get_state`, `update_state`, `delete_state` - **`run_if`** _(string)_ A JSONata expression. On runtime version 4 the node runs only when it evaluates to a truthy value. - **`resource`** _(string)_ The name of the resource to sync. Required for `request` nodes and on runtime versions 1 to 3. For Unified APIs, it should be in the format `unified_api_name/resource_name`. For Proxy API, it can just be `resource_name`. - **`method`** _(string)_ The method to call on the resource. - **`id`** _(string)_ The ID of the resource to sync. This is optional and can be used to sync a single resource. It also supports placeholders. - **`query`** _(object)_ The query parameters to pass to the resource method. It supports placeholders for values. - **`loop_on`** _(string)_ When a particular placeholder argument is an array and you want to repeat the request for each element in that array, you can set this parameter. For example, if you accept an argument called `user_ids` which is an array of strings, and you want to fetch each user's details, you can set this parameter to `args.user_ids` and the request will be repeated for each element in the `user_ids` array. - **`depends_on`** _(string)_ The resource that this resource depends on (parent resource). This is optional and can be used to sync a resource only after another resource has been synced. Each object synced for the parent resource is available as the resources object in placeholders for the child resource, e.g. `{{resources.crm.contacts.id}}` if depends on is `crm/contacts` resource. - **`persist`** _(boolean)_ Whether to persist the resource in the database or not in case of a Daemon sync job run or send as a payload in case of RapidBridge sync job run. The Proxy API resources are by default NOT persisted and this parameter can be set to `true` to persist them. Unified API resources are always persisted. - **`default_runtime_version`** _(number)_ The runtime version for any sync job that uses this template. - **`team_id`** _(string)_ The team that owns this template. - **`sharing`** _(string)_ The sharing policy of the template. Allowed: `allow`, `ask`, `deny` - **`created_at`** _(string)_ When the template was created. - **`updated_at`** _(string)_ When the template was last updated. ## Methods - [GET /sync-job-template](/api-reference/admin/sync-job-templates/list) — List sync job templates - [POST /sync-job-template](/api-reference/admin/sync-job-templates/create) — Create sync job template - [GET /sync-job-template/{id}](/api-reference/admin/sync-job-templates/get) — Get sync job template by ID - [PATCH /sync-job-template/{id}](/api-reference/admin/sync-job-templates/update) — Update sync job template - [DELETE /sync-job-template/{id}](/api-reference/admin/sync-job-templates/delete) — Delete sync job template --- # Webhooks Object > Source: https://truto.one/docs/api-reference/admin/webhooks/ Schema for the `Webhooks` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the webhook. - **`target_url`** _(string)_ The URL where the webhook should send the data. - **`is_active`** _(boolean)_ Whether the webhook is active or not. Inactive webhooks will not receive any data. - **`environment_id`** _(string)_ The ID of the environment that this webhook belongs to. - **`event_types`** _(array)_ The list of event types that the webhook is subscribed to. - **`created_at`** _(string)_ The date and time when the webhook was created. - **`updated_at`** _(string)_ The date and time when the webhook was last updated. ## Methods - [GET /webhook](/api-reference/admin/webhooks/list) — List webhooks - [POST /webhook](/api-reference/admin/webhooks/create) — Create webhook - [GET /webhook/{id}](/api-reference/admin/webhooks/get) — Get webhook - [PATCH /webhook/{id}](/api-reference/admin/webhooks/update) — Update webhook - [DELETE /webhook/{id}](/api-reference/admin/webhooks/delete) — Delete webhook - [POST /webhook/test](/api-reference/admin/webhooks/test) — Send test event --- # Unified Model Docs Object > Source: https://truto.one/docs/api-reference/admin/unified-model-docs/ Schema for the `Unified Model Docs` resource in **Admin API**. ## Properties - **`method`** _(string)_ The unified method this metadata describes. - **`schema`** _(object, required)_ The unified-model resource JSON schema. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`documentation_link`** _(string)_ Vendor documentation URL for this method, if set on the integration mapping. - **`response_schema`** _(object, required)_ A subset of `schema` containing only the fields actually populated by `response_mapping` for this integration. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`query_schema`** _(object, required)_ JSON-schema-style description of the supported query parameters for this method. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`request_body_schema`** _(object, required)_ JSON-schema-style description of the supported request body for this method. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`default_query`** _(object)_ Default query parameters always applied by the integration mapping. Values may be templated JSONata expressions. - **`default_body`** _(object)_ Default request body always applied by the integration mapping. Values may be templated JSONata expressions. Object or `null` (arrays are allowed at runtime but rare). ## Methods - [GET /unified/meta/{model_name}/{integration_name}](/api-reference/admin/unified-model-docs/get) — Get integration specific documentation --- # Batch Requests Object > Source: https://truto.one/docs/api-reference/admin/batch-requests/ Schema for the `Batch Requests` resource in **Admin API**. ## Properties - **`result`** _(object)_ Map of resource names to the records fetched for that resource. The key is the resource's `name` from the request body. - **`errors`** _(object)_ Map of resource names to errors encountered while processing that resource. Present only for resources that failed. ## Methods - [POST /batch-request](/api-reference/admin/batch-requests/create) — Execute a batch request --- # Datastores Object > Source: https://truto.one/docs/api-reference/admin/datastores/ Schema for the `Datastores` resource in **Admin API**. ## Properties - **`id`** _(string)_ The unique ID of the datastore. - **`type`** _(string)_ The datastore's backend type. Determines the shape of `config`. Allowed: `mongo_data_api`, `google_cloud_storage`, `s3`, `qdrant` - **`label`** _(string)_ A friendly label for identifying this datastore. - **`config`** _(object)_ Config object for the datastore connection (minus sensitive fields). The shape depends on `type`. _One of:_ - **Mongo Data Api** - **`data_source`** _(string)_ Name of the Atlas cluster (the Data API "data source"). - **`database`** _(string)_ - **`api_url`** _(string)_ Base URL of your Atlas Data API endpoint. - **`api_key`** _(string)_ Atlas Data API key. Treat as a secret. - **Google Cloud Storage** - **`bucket`** _(string)_ - **`credentials`** _(object, required)_ Service-account JSON used to authenticate against Google Cloud Storage. - **`type`** _(string)_ - **`project_id`** _(string)_ - **`private_key_id`** _(string)_ - **`private_key`** _(string)_ - **`client_email`** _(string)_ - **`client_id`** _(string)_ - **`auth_uri`** _(string)_ - **`token_uri`** _(string)_ - **`auth_provider_x509_cert_url`** _(string)_ - **`client_x509_cert_url`** _(string)_ - **`universe_domain`** _(string)_ - **S3** - **`access_key_id`** _(string)_ - **`secret_access_key`** _(string)_ Secret access key. Treat as a secret. - **`region`** _(string)_ - **`bucket`** _(string)_ - **`base_url`** _(string)_ Optional override for non-AWS S3 endpoints (e.g. R2, MinIO). - **Qdrant** - **`base_url`** _(string)_ - **`api_key`** _(string)_ Qdrant API key. Treat as a secret. - **`port`** _(integer)_ - **`collection`** _(string)_ - **`environment_id`** _(string)_ The environment to which this datastore belongs. - **`created_at`** _(string)_ Timestamp when the datastore record was created. - **`updated_at`** _(string)_ Timestamp when the datastore record was last updated. ## Methods - [GET /datastore](/api-reference/admin/datastores/list) — List datastores - [POST /datastore](/api-reference/admin/datastores/create) — Create a datastore - [GET /datastore/{id}](/api-reference/admin/datastores/get) — Get datastore - [PATCH /datastore/{id}](/api-reference/admin/datastores/update) — Update datastore - [DELETE /datastore/{id}](/api-reference/admin/datastores/delete) — Delete datastore --- # Documentation Object > Source: https://truto.one/docs/api-reference/admin/documentation/ Schema for the `Documentation` resource in **Admin API**. ## Properties - **`id`** _(string)_ - **`entity_id`** _(string)_ - **`entity_type`** _(string)_ Allowed: `integration`, `unified_model`, `environment_integration`, `environment_unified_model` - **`type`** _(string)_ Documentation row type. Per-method MCP tooling uses `description`, `tool_name`, `query_schema`, `body_schema`, and `response_schema`. Integration-wide rows include `readme`, `oauth_*`, and `note`. Allowed: `readme`, `note`, `end_user_guide`, `description`, `tool_name`, `query_schema`, `body_schema`, `response_schema`, `oauth_documentation_link`, `oauth_app_requires_verification`, `oauth_note` - **`content`** _(string)_ Row payload. For `tool_name`, a snake_case MCP tool name override (max 64 chars, `[a-z0-9_]`). For `description`, plain text. For `*_schema` types, YAML-encoded schema. - **`resource`** _(string)_ - **`method`** _(string)_ - **`authentication_method`** _(string)_ - **`integration_name`** _(string)_ - **`created_at`** _(string)_ - **`updated_at`** _(string)_ ## Methods - [GET /documentation](/api-reference/admin/documentation/list) — List documentation rows - [POST /documentation](/api-reference/admin/documentation/create) — Create a documentation row - [GET /documentation/{id}](/api-reference/admin/documentation/get) — Get a documentation row - [PATCH /documentation/{id}](/api-reference/admin/documentation/update) — Update a documentation row - [DELETE /documentation/{id}](/api-reference/admin/documentation/delete) — Delete a documentation row --- # Logs Object > Source: https://truto.one/docs/api-reference/admin/logs/ Schema for the `Logs` resource in **Admin API**. ## Properties ## Methods - [GET /log](/api-reference/admin/logs/list) — List logs --- # Tenants Object > Source: https://truto.one/docs/api-reference/admin/tenants/ Schema for the `Tenants` resource in **Admin API**. ## Properties - **`id`** _(string)_ The tenant identifier — caller-chosen and immutable once created. Composite primary key with `environment_id`, so the same value can exist independently in `development`, `staging`, and `production`. Free-form up to 255 characters: whatever you already use to identify a customer, including `/`, spaces and non-ASCII. The only values rejected are the ones no URL path segment can carry — control characters, leading or trailing whitespace, and the dot segments `.` and `..`. - **`environment_id`** _(string)_ The environment this tenant belongs to. - **`name`** _(string)_ Display name shown in the dashboard. Defaults to the tenant `id` on create if not supplied; can be edited later via `PATCH /tenant/{id}`. - **`metadata`** _(object)_ Free-form JSON object stored verbatim. Truto does not interpret this field — use it for tier, region, billing plan, or any other customer attribute your app cares about. - **`created_at`** _(string)_ The date and time when the tenant was created. - **`updated_at`** _(string)_ The date and time when the tenant was last updated. ## Methods - [GET /tenant](/api-reference/admin/tenants/list) — List tenants - [POST /tenant](/api-reference/admin/tenants/create) — Create tenant - [POST /tenant/bulk](/api-reference/admin/tenants/create-bulk) — Bulk create or upsert tenants - [GET /tenant/{id}](/api-reference/admin/tenants/get) — Get tenant - [PATCH /tenant/{id}](/api-reference/admin/tenants/update) — Update tenant - [DELETE /tenant/{id}](/api-reference/admin/tenants/delete) — Delete tenant --- # Installed Integrations - Environment Integrations Object > Source: https://truto.one/docs/api-reference/admin/installed-integrations-environment-integrations/ Schema for the `Installed Integrations - Environment Integrations` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the environment integration. - **`integration_id`** _(string)_ The ID of the integration this environment integration references. - **`environment_id`** _(string)_ The ID of the environment in which this integration is installed. - **`show_in_catalog`** _(boolean)_ Whether this integration is shown in the environment's catalog. - **`is_enabled`** _(boolean)_ Whether this integration is enabled in the environment. - **`created_at`** _(string)_ The date and time when the environment integration was created. - **`updated_at`** _(string)_ The date and time when the environment integration was last updated. - **`integration`** _(object)_ - **`id`** _(string)_ The ID of the integration. - **`name`** _(string)_ The name of the integration. - **`category`** _(string)_ The category of the integration. - **`is_beta`** _(boolean)_ Whether the integration is in beta or not. Beta integrations might not have been tested completely and are not recommended for production environments. - **`config`** _(object, required)_ The configuration object defining the underlying API of the integration. - **`base_url`** _(string)_ Default base URL prepended to every resource method's `path`. - **`label`** _(string)_ Human-readable name shown in the Truto Dashboard and Link UI. - **`logo`** _(string)_ URL to the integration logo (square, recommended 256x256). - **`icon`** _(string)_ URL to a smaller monochrome icon used in catalog listings. - **`headers`** _(object)_ Default HTTP headers merged into every outbound request. Values may be templated with JSONata placeholders. - **`query`** _(object)_ Default query-string params merged into every outbound request. - **`query_array_format`** _(string)_ Allowed: `comma`, `brackets`, `indices`, `repeat` - **`actions`** _(object)_ Named integration actions. Reserved keys (`post_install`, `post_connect_user_form`, `refresh_token`, `validation`) hook into specific platform lifecycle events; custom names are callable from the proxy/sync runtime. - **`credentials`** _(object)_ Either a single credential definition (when the integration only supports one auth format) or a map keyed by auth format (when an integration supports multiple, e.g. `api_key` and `oauth2`). For multi-format integrations, the customer picks one in the Connect UI. Each credential's `config.label` and `config.help_text` customize the auth-method card shown in the Connect UI. - **`authorization`** _(object)_ How Truto applies the resolved credential to outbound HTTP requests. The `format` discriminator selects which `config` shape applies. All string values support Truto placeholders (`{{path}}`) resolved against the runtime context. Common placeholder roots: `{{api_key}}` for fields collected at connect time, `{{oauth.token.access_token}}` for OAuth2 access tokens, `{{environment_variables.MY_KEY}}` for env-vars set at the environment-integration level. _One of:_ - **bearer** - **`format`** _(string)_ Allowed: `bearer` - **`config`** _(object, required)_ - **basic** - **`format`** _(string)_ Allowed: `basic` - **`config`** _(object)_ - **header** - **`format`** _(string)_ Allowed: `header` - **`config`** _(object)_ - **`pagination`** _(object)_ Pagination strategy for an integration or a single resource method. The `format` discriminator selects which `config` shape applies. _One of:_ - **page** - **`format`** _(string)_ Allowed: `page` - **`config`** _(object)_ Page-number pagination options. All fields optional; defaults shown. - **cursor** - **`format`** _(string)_ Allowed: `cursor` - **`config`** _(object, required)_ Cursor pagination options. - **link_header** - **`format`** _(string)_ Allowed: `link_header` - **`config`** _(object)_ - **offset** - **`format`** _(string)_ Allowed: `offset` - **`config`** _(object)_ - **range** - **`format`** _(string)_ Allowed: `range` - **`config`** _(object)_ - **dynamic** - **`format`** _(string)_ Allowed: `dynamic` - **`config`** _(object, required)_ - **`rate_limit`** _(object)_ How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response. - **`is_rate_limited`** _(string)_ JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to `status === 429`. Input: `IntegrationRateLimitExpressionContext`. Output: boolean. - **`retry_after_header_expression`** _(string)_ JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard `Retry-After` header. Input: `IntegrationRateLimitExpressionContext`. Output: number (seconds). - **`rate_limit_header_expression`** _(string)_ JSONata expression returning the current rate-limit window state. Truto forwards this as `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers in the proxy response. Input: `IntegrationRateLimitExpressionContext`. Output: `IntegrationRateLimitHeaderValues`. - **`resources`** _(object)_ Resource → method tree (e.g. `resources.users.list`). The inner key is one of the canonical methods (`list`, `get`, `create`, `update`, `delete`) or a custom method name. Each method definition matches `IntegrationResourceMethod`. - **`tool_tags`** _(object)_ Optional tag arrays keyed by resource name (`contacts`) or `resource.method` (`contacts.delete`). Method-level tags are unioned with resource-level tags when building MCP tools and filtering by MCP token `config.tags`. - **`webhook`** _(object)_ How Truto receives and verifies inbound webhooks for this integration. **Not** to be confused with `WebhookSchema` elsewhere in this spec, which describes Truto's _outbound_ webhook delivered to your application. - **`signature_verification`** _(object)_ Strategy used to verify the webhook signature before accepting it. Runs **after** `payload_transform` and **after** `handle_verification` returns `{ type: 'payload' }`. - **`handle_verification`** _(string)_ JSONata expression evaluated on **every** inbound webhook before signature verification. Use to: * Respond to handshake pings (return `{ type: 'verify', verification_response: { status_code, body, headers } }`). * Surface meta-events that should not fan out (return `{ type: 'meta' }`). * Update the integrated account context (return `{ type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }`). * Pass through to fan-out (return `{ type: 'payload' }` or omit entirely — defaults to `payload`). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookHandleVerificationResult`. - **`payload_transform`** _(string)_ JSONata expression that transforms the raw inbound payload **before** `handle_verification` and `signature_verification` see it. Use to normalize vendor-specific envelopes (e.g. unwrap a Salesforce `payloads[]` array, decode a base64 body). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookPayloadContext` (the same shape — what you return becomes the new payload). - **`error_expression`** _(string)_ Integration-wide JSONata expression evaluated on every response. Use to detect errors in successful (2xx) responses, normalize error messages, or transform "errors" with `< 400` status into successful responses. Overridden by per-method `IntegrationResourceMethod.error_expression` when set. Input: `IntegrationErrorExpressionContext`. Output: `IntegrationErrorExpressionResult` — return `null`/`undefined` to indicate "no error", or a `{ status, message?, headers?, metadata?, result? }` object. - **`browser_file_picker_requires_access_token`** _(boolean)_ This provider's **browser** file picker cannot run without the connected account's upstream `access_token`, so `GET /integrated-account/me` releases `context.oauth.token.access_token` — and nothing else — to a connect-flow integrated account token. Google Drive and Box need it; their picker SDKs take the token client-side. SharePoint, OneDrive and Dropbox authenticate by other means and must leave this unset. A `refresh_token` is never released, whatever this is set to. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`, so it cannot be switched on for a single environment or account. - **`use_static_gate`** _(boolean)_ Send every outbound request and token exchange for this integration through Truto's default Static Gate (fixed-IP proxy, configured on the worker), for vendors that allowlist Truto's IPs. An integrated account's own `context.truto_static_gate_id` takes precedence. If the flag is set but the worker has no gate configured, the request fails instead of going direct. The default gate only forwards to the host of the base integration's `base_url` and of its OAuth token, refresh and revoke URLs, and their subdomains (a placeholder in the host keeps only its static suffix, e.g. `{{x}}.api.gong.io` allows `*.api.gong.io`). A `base_url` or token host set through an override, or any other host, fails the request instead of going direct. OAuth 1.0a token calls cannot be sent through a gate, so an OAuth 1.0a connect on an integration with this flag fails instead of going direct. Only the root team can set, change or clear it, and a config update that omits it keeps the stored value. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`. - **`oauth_app_headers`** _(object)_ Headers built from the connected account's OAuth app and sent on every request, for providers that want the app's own key next to the user's token. Etsy, for example, needs `{ "x-api-key": "{{client.id}}:{{client.secret}}" }`. A value may use `{{client.id}}` and `{{client.secret}}` — the OAuth client the account's token was issued to, read and filled in as the token refresh does — and no other placeholder. Saving an integration fails with a 400 if a value uses any other placeholder, or if a header name is one that debug output echoes back (`x-truto-*`, `content-type`, `accept`, `user-agent` and similar). A header that can't be filled completely is left out: a client field it uses is unset, or is still a placeholder the account's context can't fill. Added after `authorization`, replacing a header of the same name in any letter case. Only accounts connected with `oauth2` get these headers, and a method with `no_auth` doesn't. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`. A header that uses `{{client.secret}}` is sent only to the sites of the requests configured by whoever set that secret: the integration, or an environment's override over it. An environment or account override that keeps that app but sends requests elsewhere (its own `base_url`, a method's URL, an `authorization` expression, a mapping's path) sends them without these headers. Through a Static Gate, the target URL counts. An account's own secret (in its `integration_override`, or filled in from its context) goes wherever its requests go. - **`team_id`** _(string)_ The ID of the team that owns this integration. - **`sharing`** _(string)_ The sharing policy of the integration. Allowed: `allow`, `ask`, `deny` - **`created_at`** _(string)_ The date and time when the integration was created. - **`updated_at`** _(string)_ The date and time when the integration was last updated. - **`installed_environment`** _(array)_ A list of environment IDs where this integration is installed. - **`team`** _(object)_ - **`id`** _(string)_ The ID of the team. - **`name`** _(string)_ The name of the team. - **`domain`** _(string)_ The domain of the team. - **`logo`** _(string)_ The URL of the team's logo. - **`is_verified`** _(boolean)_ Whether the team is verified or not. - **`is_white_label`** _(boolean)_ Whether the team is white-labeled or not. - **`tos_link`** _(string)_ A link to the team's Terms of Service, if available. - **`allow_impersonation`** _(boolean)_ Whether the team allows impersonation. - **`created_at`** _(string)_ The date and time when the team was created. - **`updated_at`** _(string)_ The date and time when the team was last updated. - **`override`** _(object)_ An optional config override applied for the integration at environment level. Deep-merged on top of the base `integration.config` at request time. - **`base_url`** _(string)_ - **`label`** _(string)_ - **`logo`** _(string)_ - **`icon`** _(string)_ - **`headers`** _(object)_ - **`query`** _(object)_ - **`query_array_format`** _(string)_ Allowed: `comma`, `brackets`, `indices`, `repeat` - **`actions`** _(object)_ - **`credentials`** _(object)_ - **`authorization`** _(object)_ How Truto applies the resolved credential to outbound HTTP requests. The `format` discriminator selects which `config` shape applies. All string values support Truto placeholders (`{{path}}`) resolved against the runtime context. Common placeholder roots: `{{api_key}}` for fields collected at connect time, `{{oauth.token.access_token}}` for OAuth2 access tokens, `{{environment_variables.MY_KEY}}` for env-vars set at the environment-integration level. _One of:_ - **bearer** - **`format`** _(string)_ Allowed: `bearer` - **`config`** _(object, required)_ - **basic** - **`format`** _(string)_ Allowed: `basic` - **`config`** _(object)_ - **header** - **`format`** _(string)_ Allowed: `header` - **`config`** _(object)_ - **`pagination`** _(object)_ Pagination strategy for an integration or a single resource method. The `format` discriminator selects which `config` shape applies. _One of:_ - **page** - **`format`** _(string)_ Allowed: `page` - **`config`** _(object)_ Page-number pagination options. All fields optional; defaults shown. - **cursor** - **`format`** _(string)_ Allowed: `cursor` - **`config`** _(object, required)_ Cursor pagination options. - **link_header** - **`format`** _(string)_ Allowed: `link_header` - **`config`** _(object)_ - **offset** - **`format`** _(string)_ Allowed: `offset` - **`config`** _(object)_ - **range** - **`format`** _(string)_ Allowed: `range` - **`config`** _(object)_ - **dynamic** - **`format`** _(string)_ Allowed: `dynamic` - **`config`** _(object, required)_ - **`rate_limit`** _(object)_ How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response. - **`is_rate_limited`** _(string)_ JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to `status === 429`. Input: `IntegrationRateLimitExpressionContext`. Output: boolean. - **`retry_after_header_expression`** _(string)_ JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard `Retry-After` header. Input: `IntegrationRateLimitExpressionContext`. Output: number (seconds). - **`rate_limit_header_expression`** _(string)_ JSONata expression returning the current rate-limit window state. Truto forwards this as `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers in the proxy response. Input: `IntegrationRateLimitExpressionContext`. Output: `IntegrationRateLimitHeaderValues`. - **`resources`** _(object)_ - **`tool_tags`** _(object)_ - **`webhook`** _(object)_ How Truto receives and verifies inbound webhooks for this integration. **Not** to be confused with `WebhookSchema` elsewhere in this spec, which describes Truto's _outbound_ webhook delivered to your application. - **`signature_verification`** _(object)_ Strategy used to verify the webhook signature before accepting it. Runs **after** `payload_transform` and **after** `handle_verification` returns `{ type: 'payload' }`. _One of:_ - **hmac** - **`format`** _(string)_ Allowed: `hmac` - **`config`** _(object, required)_ HMAC signature verification. Truto computes `hmac(algorithm, secret, signed_string)` and compares it (constant-time) with `compare_with`. - **basic** - **`format`** _(string)_ Allowed: `basic` - **`config`** _(object, required)_ HTTP Basic signature verification. Truto base64-encodes `username:password` and compares it with the second word of `compare_with` (i.e. `Authorization: Basic `). - **bearer** - **`format`** _(string)_ Allowed: `bearer` - **`config`** _(object, required)_ Bearer-token signature verification. Truto compares `secret` (constant-time) with the second word of `compare_with` (i.e. `Authorization: Bearer `). - **jwt** - **`format`** _(string)_ Allowed: `jwt` - **`config`** _(object, required)_ JWT signature verification, in one of two modes. **Shared secret** (set `secret`): Truto verifies that `compare_with` is a valid HS256 JWT signed with `secret`. **Issuer key set** (set `jwks_uri`): Truto verifies that `compare_with` is a JWT signed with an asymmetric key published at `jwks_uri`, then checks `issuer`, `audience` and the caller's identity. Use this for tokens such as the OIDC token on a Google Pub/Sub push subscription (`jwks_uri: https://www.googleapis.com/oauth2/v3/certs`, `issuer: https://accounts.google.com`). The `issuer`, `audience` and one of `email` or `subject` are all required, because the issuer signs a token for any caller who asks and a valid signature alone does not identify the sender. A block that omits them, uses a non-HTTPS `jwks_uri`, or sets a non-asymmetric `algorithm` is rejected with a 400 when it is saved (on the integration or on an environment-integration override), instead of failing every inbound webhook afterwards. - **`handle_verification`** _(string)_ JSONata expression evaluated on **every** inbound webhook before signature verification. Use to: * Respond to handshake pings (return `{ type: 'verify', verification_response: { status_code, body, headers } }`). * Surface meta-events that should not fan out (return `{ type: 'meta' }`). * Update the integrated account context (return `{ type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }`). * Pass through to fan-out (return `{ type: 'payload' }` or omit entirely — defaults to `payload`). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookHandleVerificationResult`. - **`payload_transform`** _(string)_ JSONata expression that transforms the raw inbound payload **before** `handle_verification` and `signature_verification` see it. Use to normalize vendor-specific envelopes (e.g. unwrap a Salesforce `payloads[]` array, decode a base64 body). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookPayloadContext` (the same shape — what you return becomes the new payload). - **`error_expression`** _(string)_ - **`description`** _(string)_ Environment-specific description shown in the catalog. - **`tags`** _(array)_ Environment-specific tags shown in the catalog. - **`is_beta`** _(boolean)_ Environment-specific beta flag shown in the catalog and Connect UI. Deep-merged onto `integration.is_beta` at request time. - **`environment_variables`** _(object)_ Free-form key/value pairs available to JSONata as `{{env.}}` for this integration in this environment. Values can be of any type (string, number, boolean, object, array). - **`link_ui_config`** _(object)_ Connections-widget-only configuration for this integration. Never merged into `integration.config`. - **`visible_when`** _(object)_ Restricts which tenants may see and connect this integration. Omitted or `null` means every tenant sees it, which is the default for every integration. - **`all_of`** _(array)_ Every condition must hold. - **`path`** _(string)_ A dotted path into `tenant.metadata`, at most four segments deep. - **`op`** _(string)_ Allowed: `in`, `not_in`, `exists`, `not_exists` - **`values`** _(array)_ Required for `in` and `not_in`; rejected for `exists` and `not_exists`. Values are compared as strings — a numeric or boolean metadata value matches its string form. - **`any_of`** _(array)_ At least one condition must hold. - **`path`** _(string)_ A dotted path into `tenant.metadata`, at most four segments deep. - **`op`** _(string)_ Allowed: `in`, `not_in`, `exists`, `not_exists` - **`values`** _(array)_ Required for `in` and `not_in`; rejected for `exists` and `not_exists`. Values are compared as strings — a numeric or boolean metadata value matches its string form. - **`group`** _(string)_ Overrides `integration.category` as this card's grouping key in the widget. - **`connect_label`** _(string)_ Overrides the widget's Connect button label for this integration. - **`configure_label`** _(string)_ Overrides the widget's Configure button label for this integration. ## Methods - [GET /environment-integration](/api-reference/admin/installed-integrations-environment-integrations/list) — List environment integrations - [POST /environment-integration](/api-reference/admin/installed-integrations-environment-integrations/create) — Create environment integration - [GET /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/get) — Get environment integration - [PATCH /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/update) — Update environment integration - [DELETE /environment-integration/{id}](/api-reference/admin/installed-integrations-environment-integrations/delete) — Delete environment integration --- # Integrations Object > Source: https://truto.one/docs/api-reference/admin/integrations/ Schema for the `Integrations` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the integration. - **`name`** _(string)_ The name of the integration. - **`category`** _(string)_ The category of the integration. - **`is_beta`** _(boolean)_ Whether the integration is in beta or not. Beta integrations might not have been tested completely and are not recommended for production environments. - **`config`** _(object, required)_ The configuration object defining the underlying API of the integration. - **`base_url`** _(string)_ Default base URL prepended to every resource method's `path`. - **`label`** _(string)_ Human-readable name shown in the Truto Dashboard and Link UI. - **`logo`** _(string)_ URL to the integration logo (square, recommended 256x256). - **`icon`** _(string)_ URL to a smaller monochrome icon used in catalog listings. - **`headers`** _(object)_ Default HTTP headers merged into every outbound request. Values may be templated with JSONata placeholders. - **`query`** _(object)_ Default query-string params merged into every outbound request. - **`query_array_format`** _(string)_ Allowed: `comma`, `brackets`, `indices`, `repeat` - **`actions`** _(object)_ Named integration actions. Reserved keys (`post_install`, `post_connect_user_form`, `refresh_token`, `validation`) hook into specific platform lifecycle events; custom names are callable from the proxy/sync runtime. - **`credentials`** _(object)_ Either a single credential definition (when the integration only supports one auth format) or a map keyed by auth format (when an integration supports multiple, e.g. `api_key` and `oauth2`). For multi-format integrations, the customer picks one in the Connect UI. Each credential's `config.label` and `config.help_text` customize the auth-method card shown in the Connect UI. - **`authorization`** _(object)_ How Truto applies the resolved credential to outbound HTTP requests. The `format` discriminator selects which `config` shape applies. All string values support Truto placeholders (`{{path}}`) resolved against the runtime context. Common placeholder roots: `{{api_key}}` for fields collected at connect time, `{{oauth.token.access_token}}` for OAuth2 access tokens, `{{environment_variables.MY_KEY}}` for env-vars set at the environment-integration level. _One of:_ - **bearer** - **`format`** _(string)_ Allowed: `bearer` - **`config`** _(object, required)_ - **basic** - **`format`** _(string)_ Allowed: `basic` - **`config`** _(object)_ - **header** - **`format`** _(string)_ Allowed: `header` - **`config`** _(object)_ - **`pagination`** _(object)_ Pagination strategy for an integration or a single resource method. The `format` discriminator selects which `config` shape applies. _One of:_ - **page** - **`format`** _(string)_ Allowed: `page` - **`config`** _(object)_ Page-number pagination options. All fields optional; defaults shown. - **cursor** - **`format`** _(string)_ Allowed: `cursor` - **`config`** _(object, required)_ Cursor pagination options. - **link_header** - **`format`** _(string)_ Allowed: `link_header` - **`config`** _(object)_ - **offset** - **`format`** _(string)_ Allowed: `offset` - **`config`** _(object)_ - **range** - **`format`** _(string)_ Allowed: `range` - **`config`** _(object)_ - **dynamic** - **`format`** _(string)_ Allowed: `dynamic` - **`config`** _(object, required)_ - **`rate_limit`** _(object)_ How Truto detects and reacts to upstream rate-limiting. All fields are JSONata expressions evaluated against the upstream response. - **`is_rate_limited`** _(string)_ JSONata expression returning a truthy value when the response should be treated as rate-limited. When omitted, Truto falls back to `status === 429`. Input: `IntegrationRateLimitExpressionContext`. Output: boolean. - **`retry_after_header_expression`** _(string)_ JSONata expression returning the seconds to wait before retrying. When omitted, Truto reads the standard `Retry-After` header. Input: `IntegrationRateLimitExpressionContext`. Output: number (seconds). - **`rate_limit_header_expression`** _(string)_ JSONata expression returning the current rate-limit window state. Truto forwards this as `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers in the proxy response. Input: `IntegrationRateLimitExpressionContext`. Output: `IntegrationRateLimitHeaderValues`. - **`resources`** _(object)_ Resource → method tree (e.g. `resources.users.list`). The inner key is one of the canonical methods (`list`, `get`, `create`, `update`, `delete`) or a custom method name. Each method definition matches `IntegrationResourceMethod`. - **`tool_tags`** _(object)_ Optional tag arrays keyed by resource name (`contacts`) or `resource.method` (`contacts.delete`). Method-level tags are unioned with resource-level tags when building MCP tools and filtering by MCP token `config.tags`. - **`webhook`** _(object)_ How Truto receives and verifies inbound webhooks for this integration. **Not** to be confused with `WebhookSchema` elsewhere in this spec, which describes Truto's _outbound_ webhook delivered to your application. - **`signature_verification`** _(object)_ Strategy used to verify the webhook signature before accepting it. Runs **after** `payload_transform` and **after** `handle_verification` returns `{ type: 'payload' }`. _One of:_ - **hmac** - **`format`** _(string)_ Allowed: `hmac` - **`config`** _(object, required)_ HMAC signature verification. Truto computes `hmac(algorithm, secret, signed_string)` and compares it (constant-time) with `compare_with`. - **basic** - **`format`** _(string)_ Allowed: `basic` - **`config`** _(object, required)_ HTTP Basic signature verification. Truto base64-encodes `username:password` and compares it with the second word of `compare_with` (i.e. `Authorization: Basic `). - **bearer** - **`format`** _(string)_ Allowed: `bearer` - **`config`** _(object, required)_ Bearer-token signature verification. Truto compares `secret` (constant-time) with the second word of `compare_with` (i.e. `Authorization: Bearer `). - **jwt** - **`format`** _(string)_ Allowed: `jwt` - **`config`** _(object, required)_ JWT signature verification, in one of two modes. **Shared secret** (set `secret`): Truto verifies that `compare_with` is a valid HS256 JWT signed with `secret`. **Issuer key set** (set `jwks_uri`): Truto verifies that `compare_with` is a JWT signed with an asymmetric key published at `jwks_uri`, then checks `issuer`, `audience` and the caller's identity. Use this for tokens such as the OIDC token on a Google Pub/Sub push subscription (`jwks_uri: https://www.googleapis.com/oauth2/v3/certs`, `issuer: https://accounts.google.com`). The `issuer`, `audience` and one of `email` or `subject` are all required, because the issuer signs a token for any caller who asks and a valid signature alone does not identify the sender. A block that omits them, uses a non-HTTPS `jwks_uri`, or sets a non-asymmetric `algorithm` is rejected with a 400 when it is saved (on the integration or on an environment-integration override), instead of failing every inbound webhook afterwards. - **`handle_verification`** _(string)_ JSONata expression evaluated on **every** inbound webhook before signature verification. Use to: * Respond to handshake pings (return `{ type: 'verify', verification_response: { status_code, body, headers } }`). * Surface meta-events that should not fan out (return `{ type: 'meta' }`). * Update the integrated account context (return `{ type: 'verify' \| 'payload' \| 'meta', update_context: { ... } }`). * Pass through to fan-out (return `{ type: 'payload' }` or omit entirely — defaults to `payload`). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookHandleVerificationResult`. - **`payload_transform`** _(string)_ JSONata expression that transforms the raw inbound payload **before** `handle_verification` and `signature_verification` see it. Use to normalize vendor-specific envelopes (e.g. unwrap a Salesforce `payloads[]` array, decode a base64 body). Input: `IntegrationWebhookPayloadContext`. Output: `IntegrationWebhookPayloadContext` (the same shape — what you return becomes the new payload). - **`error_expression`** _(string)_ Integration-wide JSONata expression evaluated on every response. Use to detect errors in successful (2xx) responses, normalize error messages, or transform "errors" with `< 400` status into successful responses. Overridden by per-method `IntegrationResourceMethod.error_expression` when set. Input: `IntegrationErrorExpressionContext`. Output: `IntegrationErrorExpressionResult` — return `null`/`undefined` to indicate "no error", or a `{ status, message?, headers?, metadata?, result? }` object. - **`browser_file_picker_requires_access_token`** _(boolean)_ This provider's **browser** file picker cannot run without the connected account's upstream `access_token`, so `GET /integrated-account/me` releases `context.oauth.token.access_token` — and nothing else — to a connect-flow integrated account token. Google Drive and Box need it; their picker SDKs take the token client-side. SharePoint, OneDrive and Dropbox authenticate by other means and must leave this unset. A `refresh_token` is never released, whatever this is set to. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`, so it cannot be switched on for a single environment or account. - **`use_static_gate`** _(boolean)_ Send every outbound request and token exchange for this integration through Truto's default Static Gate (fixed-IP proxy, configured on the worker), for vendors that allowlist Truto's IPs. An integrated account's own `context.truto_static_gate_id` takes precedence. If the flag is set but the worker has no gate configured, the request fails instead of going direct. The default gate only forwards to the host of the base integration's `base_url` and of its OAuth token, refresh and revoke URLs, and their subdomains (a placeholder in the host keeps only its static suffix, e.g. `{{x}}.api.gong.io` allows `*.api.gong.io`). A `base_url` or token host set through an override, or any other host, fails the request instead of going direct. OAuth 1.0a token calls cannot be sent through a gate, so an OAuth 1.0a connect on an integration with this flag fails instead of going direct. Only the root team can set, change or clear it, and a config update that omits it keeps the stored value. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`. - **`oauth_app_headers`** _(object)_ Headers built from the connected account's OAuth app and sent on every request, for providers that want the app's own key next to the user's token. Etsy, for example, needs `{ "x-api-key": "{{client.id}}:{{client.secret}}" }`. A value may use `{{client.id}}` and `{{client.secret}}` — the OAuth client the account's token was issued to, read and filled in as the token refresh does — and no other placeholder. Saving an integration fails with a 400 if a value uses any other placeholder, or if a header name is one that debug output echoes back (`x-truto-*`, `content-type`, `accept`, `user-agent` and similar). A header that can't be filled completely is left out: a client field it uses is unset, or is still a placeholder the account's context can't fill. Added after `authorization`, replacing a header of the same name in any letter case. Only accounts connected with `oauth2` get these headers, and a method with `no_auth` doesn't. Honoured only on the integration's own `config`: it is not part of `EnvironmentIntegrationConfig`, and it is stripped from an integrated account's `integration_override`. A header that uses `{{client.secret}}` is sent only to the sites of the requests configured by whoever set that secret: the integration, or an environment's override over it. An environment or account override that keeps that app but sends requests elsewhere (its own `base_url`, a method's URL, an `authorization` expression, a mapping's path) sends them without these headers. Through a Static Gate, the target URL counts. An account's own secret (in its `integration_override`, or filled in from its context) goes wherever its requests go. - **`team_id`** _(string)_ The ID of the team that owns this integration. - **`sharing`** _(string)_ The sharing policy of the integration. Allowed: `allow`, `ask`, `deny` - **`created_at`** _(string)_ The date and time when the integration was created. - **`updated_at`** _(string)_ The date and time when the integration was last updated. - **`installed_environment`** _(array)_ A list of environment IDs where this integration is installed. - **`team`** _(object)_ - **`id`** _(string)_ The ID of the team. - **`name`** _(string)_ The name of the team. - **`domain`** _(string)_ The domain of the team. - **`logo`** _(string)_ The URL of the team's logo. - **`is_verified`** _(boolean)_ Whether the team is verified or not. - **`is_white_label`** _(boolean)_ Whether the team is white-labeled or not. - **`tos_link`** _(string)_ A link to the team's Terms of Service, if available. - **`allow_impersonation`** _(boolean)_ Whether the team allows impersonation. - **`created_at`** _(string)_ The date and time when the team was created. - **`updated_at`** _(string)_ The date and time when the team was last updated. ## Methods - [GET /integration](/api-reference/admin/integrations/list) — List integrations - [POST /integration](/api-reference/admin/integrations/create) — Create integration - [GET /integration/{id}](/api-reference/admin/integrations/get) — Get integration - [PATCH /integration/{id}](/api-reference/admin/integrations/update) — Update integration - [DELETE /integration/{id}](/api-reference/admin/integrations/delete) — Delete integration - [GET /integration/{id}/tools](/api-reference/admin/integrations/tools) — (Deprecated) Get integration tools - [GET /integration/{id}/unified-apis](/api-reference/admin/integrations/unified-apis) — (Deprecated) Get unified APIs supported by an integration - [GET /integration/{id}/capabilities](/api-reference/admin/integrations/capabilities) — Get integration capabilities (proxy + unified + auth) --- # Api Tokens Object > Source: https://truto.one/docs/api-reference/admin/api-tokens/ Schema for the `Api Tokens` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the API token. - **`name`** _(string)_ A descriptive name for the token. - **`created_by`** _(string)_ The ID of the user who created this token. - **`environment_id`** _(string)_ The ID of the environment this token is scoped to. - **`created_at`** _(string)_ The date and time when the token was created. - **`updated_at`** _(string)_ The date and time when the token was last updated. - **`last_used_at`** _(string)_ Last time the token was used (UTC). Null until first use. - **`expires_at`** _(string)_ When the token stops working (UTC). Null for a token that does not expire. - **`whitelisted_ips`** _(array)_ IP addresses and CIDR ranges the token can be used from. Null when the token can be used from any IP address. ## Methods - [GET /api-token](/api-reference/admin/api-tokens/list) — List API tokens - [GET /api-token/{id}](/api-reference/admin/api-tokens/get) — Get API token --- # SSO Connections Object > Source: https://truto.one/docs/api-reference/admin/sso-connections/ Schema for the `SSO Connections` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the SSO connection. - **`team_id`** _(string)_ The ID of the team that owns this SSO connection. - **`protocol`** _(string)_ The SSO protocol used by this connection. Allowed: `saml`, `oidc` - **`is_active`** _(boolean)_ Whether this SSO connection is active. - **`enforced`** _(boolean)_ Whether SSO login is enforced for users on the connection's verified domains. - **`is_default`** _(boolean)_ Whether this is the team's default SSO connection. - **`config`** _(object)_ Non-secret protocol settings. Secret values (the OIDC client secret and SAML SP keys) are never returned. - **`idp_entity_id`** _(string)_ SAML IdP entity ID. - **`idp_sso_url`** _(string)_ SAML IdP single sign-on URL. - **`idp_x509_cert`** _(string)_ SAML IdP X.509 signing certificate (PEM). - **`issuer`** _(string)_ OIDC issuer URL. - **`client_id`** _(string)_ OIDC relying-party client ID. - **`discovery_url`** _(string)_ OIDC discovery document URL. - **`sign_authn_requests`** _(boolean)_ SAML only — sign SP-initiated AuthnRequests with the SP key (HTTP-Redirect binding). - **`allow_idp_initiated`** _(boolean)_ SAML only — accept unsolicited (IdP-initiated) responses at the ACS. Defaults to false (unsolicited responses rejected) when omitted. - **`default_role`** _(string)_ The role assigned to users provisioned through this connection. - **`default_environment_ids`** _(array)_ Environment IDs that provisioned users are granted access to by default. - **`created_at`** _(string)_ The date and time when the SSO connection was created. - **`updated_at`** _(string)_ The date and time when the SSO connection was last updated. ## Methods - [GET /sso-connection](/api-reference/admin/sso-connections/list) — List SSO connections - [POST /sso-connection](/api-reference/admin/sso-connections/create) — Create SSO connection - [GET /sso-connection/{id}](/api-reference/admin/sso-connections/get) — Get SSO connection - [PATCH /sso-connection/{id}](/api-reference/admin/sso-connections/update) — Update SSO connection - [DELETE /sso-connection/{id}](/api-reference/admin/sso-connections/delete) — Delete SSO connection - [GET /sso-connection/{id}/domains](/api-reference/admin/sso-connections/list-domains) — List SSO connection domains - [POST /sso-connection/{id}/domains](/api-reference/admin/sso-connections/add-domain) — Add SSO connection domain - [POST /sso-connection/{id}/domains/{domain}/verify](/api-reference/admin/sso-connections/verify) — Verify SSO connection domain - [DELETE /sso-connection/{id}/domains/{domain}](/api-reference/admin/sso-connections/remove-domain) — Remove SSO connection domain --- # SCIM Tokens Object > Source: https://truto.one/docs/api-reference/admin/scim-tokens/ Schema for the `SCIM Tokens` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the SCIM token. - **`team_id`** _(string)_ The ID of the team that owns this SCIM token. - **`name`** _(string)_ A descriptive name for the SCIM token. - **`created_by`** _(string)_ The ID of the user who created this token. - **`last_used_at`** _(string)_ The date and time the IdP last authenticated against /scim/v2 with this token. Null if never used. - **`created_at`** _(string)_ The date and time when the token was created. - **`updated_at`** _(string)_ The date and time when the token was last updated. ## Methods - [GET /scim-token](/api-reference/admin/scim-tokens/list) — List SCIM tokens - [POST /scim-token](/api-reference/admin/scim-tokens/create) — Create SCIM token - [GET /scim-token/{id}](/api-reference/admin/scim-tokens/get) — Get SCIM token - [DELETE /scim-token/{id}](/api-reference/admin/scim-tokens/delete) — Delete SCIM token --- # SCIM Groups Object > Source: https://truto.one/docs/api-reference/admin/scim-groups/ Schema for the `SCIM Groups` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the SCIM group. - **`team_id`** _(string)_ The ID of the team that owns this SCIM group. - **`external_id`** _(string)_ The group's identifier in the upstream identity provider. - **`display_name`** _(string)_ The human-readable name of the group, as pushed by the IdP. - **`member_count`** _(number)_ Number of users currently in this group. - **`created_at`** _(string)_ The date and time when the group was first provisioned. - **`updated_at`** _(string)_ The date and time when the group was last updated. ## Methods - [GET /scim-group](/api-reference/admin/scim-groups/list) — List SCIM groups --- # Group Mappings Object > Source: https://truto.one/docs/api-reference/admin/group-mappings/ Schema for the `Group Mappings` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the group mapping. - **`team_id`** _(string)_ The ID of the team that owns this group mapping. - **`scim_group_id`** _(string)_ The ID of the SCIM group this mapping applies to. - **`role`** _(string)_ The role granted to members of the mapped SCIM group. Null leaves the role unchanged. Allowed: `admin`, `member` - **`environment_ids`** _(array)_ Environment IDs that members of the mapped group are granted access to. - **`created_at`** _(string)_ The date and time when the group mapping was created. - **`updated_at`** _(string)_ The date and time when the group mapping was last updated. ## Methods - [GET /group-mapping](/api-reference/admin/group-mappings/list) — List group mappings - [POST /group-mapping](/api-reference/admin/group-mappings/create) — Create group mapping - [PATCH /group-mapping/{id}](/api-reference/admin/group-mappings/update) — Update group mapping - [DELETE /group-mapping/{id}](/api-reference/admin/group-mappings/delete) — Delete group mapping --- # Static Gates Object > Source: https://truto.one/docs/api-reference/admin/static-gates/ Schema for the `Static Gates` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the static gate. - **`name`** _(string)_ A descriptive name for the static gate. - **`domain`** _(string)_ The domain this static gate will proxy requests for. - **`created_by`** _(string)_ The ID of the user who created this static gate. - **`environment_id`** _(string)_ The ID of the environment this static gate is scoped to. - **`created_at`** _(string)_ The date and time when the static gate was created. - **`updated_at`** _(string)_ The date and time when the static gate was last updated. ## Methods - [GET /static-gate](/api-reference/admin/static-gates/list) — List static gates - [POST /static-gate](/api-reference/admin/static-gates/create) — Create static gate - [GET /static-gate/{id}](/api-reference/admin/static-gates/get) — Get static gate - [PATCH /static-gate/{id}](/api-reference/admin/static-gates/patch) — Update static gate - [DELETE /static-gate/{id}](/api-reference/admin/static-gates/delete) — Delete static gate --- # Observability destinations Object > Source: https://truto.one/docs/api-reference/admin/observability-destinations/ Schema for the `Observability destinations` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the observability destination. - **`environment_id`** _(string)_ The environment whose logs are forwarded. - **`type`** _(string)_ Destination type. Allowed: `datadog`, `splunk_hec`, `sentinel`, `otlp`, `elasticsearch`, `s3` - **`name`** _(string)_ Human-readable destination name. - **`is_active`** _(boolean)_ Whether forwarding is enabled. - **`config`** _(object)_ Non-secret destination configuration. Datadog: `site`, `tags`. Splunk HEC: `hec_url`, `index`, `source`, `sourcetype`. Microsoft Sentinel: `tenant_id`, `client_id`, `dce_endpoint`, `dcr_immutable_id`, `stream_name`, `cloud`. OTLP: `endpoint`, `resource_attributes`. Elasticsearch: `url`, `index`, `pipeline`. S3: `bucket`, `region`, `endpoint` (S3-compatible storage such as GCS or R2), `prefix`. All types accept a `log_types` filter. - **`created_at`** _(string)_ - **`updated_at`** _(string)_ ## Methods - [GET /observability-destination](/api-reference/admin/observability-destinations/list) — List observability destinations - [POST /observability-destination](/api-reference/admin/observability-destinations/create) — Create observability destination - [GET /observability-destination/{id}](/api-reference/admin/observability-destinations/get) — Get observability destination - [PATCH /observability-destination/{id}](/api-reference/admin/observability-destinations/update) — Update observability destination - [DELETE /observability-destination/{id}](/api-reference/admin/observability-destinations/delete) — Delete observability destination - [POST /observability-destination/{id}/test](/api-reference/admin/observability-destinations/test) — Test observability destination --- # Environments Object > Source: https://truto.one/docs/api-reference/admin/environments/ Schema for the `Environments` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the environment. - **`name`** _(string)_ The name of the environment. - **`team_id`** _(string)_ The ID of the team that owns this environment. - **`created_at`** _(string)_ The date and time when the environment was created. - **`updated_at`** _(string)_ The date and time when the environment was last updated. ## Methods - [GET /environment](/api-reference/admin/environments/list) — List environments --- # Unified Models Object > Source: https://truto.one/docs/api-reference/admin/unified-models/ Schema for the `Unified Models` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the unified model. - **`name`** _(string)_ The name of the unified model. - **`category`** _(string)_ The category of the unified model. - **`description`** _(string)_ A brief description of what this unified model represents. - **`team_id`** _(string)_ The ID of the team that owns this unified model. - **`sharing`** _(string)_ The sharing policy of the unified model. Allowed: `allow`, `ask`, `deny` - **`resources`** _(object)_ Map of resource name (e.g. `users`, `contacts`) → resource definition (`UnifiedModelResource`). - **`docs`** _(object)_ Per-resource documentation (pricing plan / scopes / instructions). - **`scopes`** _(object)_ Per-resource OAuth/permission scopes required to call its methods. - **`webhooks`** _(object)_ Per-resource webhook routing expression (JSONata that decides whether an inbound webhook should be delivered to this resource). - **`created_at`** _(string)_ The date and time when the unified model was created. - **`updated_at`** _(string)_ The date and time when the unified model was last updated. - **`version`** _(number)_ The current version of the unified model. - **`installed_environment`** _(array)_ A list of environment IDs where this unified model is installed. - **`team`** _(object)_ - **`id`** _(string)_ The ID of the team. - **`name`** _(string)_ The name of the team. - **`domain`** _(string)_ The domain of the team. - **`logo`** _(string)_ The URL of the team's logo. - **`is_verified`** _(boolean)_ Whether the team is verified or not. - **`is_white_label`** _(boolean)_ Whether the team is white-labeled or not. - **`tos_link`** _(string)_ A link to the team's Terms of Service, if available. - **`allow_impersonation`** _(boolean)_ Whether the team allows impersonation. - **`created_at`** _(string)_ The date and time when the team was created. - **`updated_at`** _(string)_ The date and time when the team was last updated. ## Methods - [GET /unified-model](/api-reference/admin/unified-models/list) — List unified models - [POST /unified-model](/api-reference/admin/unified-models/create) — Create unified model - [GET /unified-model/{id}](/api-reference/admin/unified-models/get) — Get unified model - [PATCH /unified-model/{id}](/api-reference/admin/unified-models/update) — Update unified model - [DELETE /unified-model/{id}](/api-reference/admin/unified-models/delete) — Delete unified model --- # Installed Unified Models - Environment Unified Models Object > Source: https://truto.one/docs/api-reference/admin/installed-unified-models-environment-unified-models/ Schema for the `Installed Unified Models - Environment Unified Models` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the environment-unified-model record. - **`unified_model_id`** _(string)_ The ID of the unified model being installed or overridden. - **`environment_id`** _(string)_ The ID of the environment where this unified model is installed. - **`override`** _(object)_ An optional object containing environment-level overrides for the unified model. Deep-merged on top of the base unified model. See `EnvironmentUnifiedModelOverride` for the typed shape. - **`resources`** _(object)_ Resource-level overrides keyed by resource name. A `null` value is a tombstone: it removes an inherited resource from this environment's effective unified model. Omitting the key cannot say that — overrides are deep-merged, so an absent key means "inherit from the base model". The tombstone is stripped while merging, so the resource is simply absent from the returned `unified_model` rather than present with a null value. - **`scopes`** _(object)_ Per-integration extra OAuth scopes appended to the base unified-model scopes. - **`webhooks`** _(object)_ Per-integration JSONata expressions that route inbound webhooks to unified-model resources. - **`docs`** _(object)_ Per-integration documentation overrides. - **`created_at`** _(string)_ Timestamp when this record was created. - **`updated_at`** _(string)_ Timestamp when this record was last updated. - **`unified_model`** _(object)_ - **`id`** _(string)_ The ID of the unified model. - **`name`** _(string)_ The name of the unified model. - **`category`** _(string)_ The category of the unified model. - **`description`** _(string)_ A brief description of what this unified model represents. - **`team_id`** _(string)_ The ID of the team that owns this unified model. - **`sharing`** _(string)_ The sharing policy of the unified model. Allowed: `allow`, `ask`, `deny` - **`resources`** _(object)_ Map of resource name (e.g. `users`, `contacts`) → resource definition (`UnifiedModelResource`). - **`docs`** _(object)_ Per-resource documentation (pricing plan / scopes / instructions). - **`scopes`** _(object)_ Per-resource OAuth/permission scopes required to call its methods. - **`webhooks`** _(object)_ Per-resource webhook routing expression (JSONata that decides whether an inbound webhook should be delivered to this resource). - **`created_at`** _(string)_ The date and time when the unified model was created. - **`updated_at`** _(string)_ The date and time when the unified model was last updated. - **`version`** _(number)_ The current version of the unified model. - **`installed_environment`** _(array)_ A list of environment IDs where this unified model is installed. - **`team`** _(object)_ - **`id`** _(string)_ The ID of the team. - **`name`** _(string)_ The name of the team. - **`domain`** _(string)_ The domain of the team. - **`logo`** _(string)_ The URL of the team's logo. - **`is_verified`** _(boolean)_ Whether the team is verified or not. - **`is_white_label`** _(boolean)_ Whether the team is white-labeled or not. - **`tos_link`** _(string)_ A link to the team's Terms of Service, if available. - **`allow_impersonation`** _(boolean)_ Whether the team allows impersonation. - **`created_at`** _(string)_ The date and time when the team was created. - **`updated_at`** _(string)_ The date and time when the team was last updated. ## Methods - [GET /environment-unified-model](/api-reference/admin/installed-unified-models-environment-unified-models/list) — List environment unified models - [POST /environment-unified-model](/api-reference/admin/installed-unified-models-environment-unified-models/create) — Create environment unified model - [GET /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/get) — Get environment unified model - [PATCH /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/update) — Update environment unified model - [DELETE /environment-unified-model/{id}](/api-reference/admin/installed-unified-models-environment-unified-models/delete) — Delete environment unified model --- # Unified Model Mappings Object > Source: https://truto.one/docs/api-reference/admin/unified-model-mappings/ Schema for the `Unified Model Mappings` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the resource-method mapping row. - **`unified_model_id`** _(string)_ The base unified model this mapping belongs to. - **`resource_name`** _(string)_ The unified resource this mapping serves (e.g. `contacts`). - **`integration_name`** _(string)_ The integration slug this mapping serves (e.g. `apollo`). - **`method_name`** _(string)_ The unified method this mapping serves (`list`, `get`, `create`, `update`, `delete`, or a custom method name). - **`config`** _(object)_ The mapping itself (JSONata expressions, resource/method routing, side loads, …). - **`static`** _(unknown)_ Static value returned for this method without making an HTTP call. - **`resource`** _(string | array | object)_ Integration resource to call. May be a single name, an array of resource fragments, or a `{ expression, resources }` object for dynamic dispatch. _One of:_ - **object** - **`expression`** _(string)_ - **`resources`** _(array)_ - **`method`** _(string | array | object)_ Integration method to call. _One of:_ - **object** - **`expression`** _(string)_ - **`methods`** _(array)_ - **`base_url_mapping`** _(string)_ - **`path_mapping`** _(string)_ - **`error_mapping`** _(string)_ - **`mapping_version`** _(number)_ - **`response_mapping_method`** _(string)_ Allowed: `array`, `item` - **`response_mapping`** _(string | object)_ JSONata expression (string) or object-form mapping. The object form is keyed by field name with values that may be JSONata strings, nested objects, or `JsonSchemaObjectProperties`. - **`documentation_link`** _(string)_ - **`related_resources`** _(string | array)_ - **`request_body_schema`** _(object)_ Object-form (v2) request body schema; values are partial JSON Schema entries. - **`request_body_mapping`** _(string | object)_ - **`query_mapping`** _(string | object)_ - **`query_schema`** _(string | object)_ - **`request_header_mapping`** _(string)_ - **`response_header_mapping`** _(string)_ - **`query`** _(object)_ Static query params merged into the integration request. - **`body`** _(object)_ Static body merged into the integration request. - **`before`** _(string | array)_ - **`after`** _(string | array)_ - **`is_partial_response`** _(boolean)_ - **`is_partial_expression`** _(string)_ - **`side_load`** _(object)_ - **`file_upload`** _(string | object | array)_ _One of:_ - **object** - **`file_upload`** _(string)_ Allowed: `multipart`, `base64`, `upload` - **`config`** _(object)_ Strategy-specific options (e.g. multipart field name, base64 wrapper key). - **`version`** _(number)_ Optimistic-concurrency version. Send the current value in a PATCH body; every write increments it. - **`created_at`** _(string)_ - **`updated_at`** _(string)_ ## Methods - [GET /unified-model-resource-method](/api-reference/admin/unified-model-mappings/list) — List unified model mappings - [POST /unified-model-resource-method](/api-reference/admin/unified-model-mappings/create) — Create unified model mapping - [GET /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/get) — Get unified model mapping - [PATCH /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/update) — Update unified model mapping - [DELETE /unified-model-resource-method/{id}](/api-reference/admin/unified-model-mappings/delete) — Delete unified model mapping --- # Installed Unified Models - Environment Unified Model Mappings Object > Source: https://truto.one/docs/api-reference/admin/installed-unified-models-environment-unified-model-mappings/ Schema for the `Installed Unified Models - Environment Unified Model Mappings` resource in **Admin API**. ## Properties - **`id`** _(string)_ The ID of the environment resource-method override row. - **`environment_unified_model_id`** _(string)_ The `environment_unified_model` record (environment + unified model pair) this override belongs to. - **`resource_name`** _(string)_ The unified resource this override serves (e.g. `contacts`). - **`integration_name`** _(string)_ The integration slug this override serves (e.g. `apollo`). - **`method_name`** _(string)_ The unified method this override serves (`list`, `get`, `create`, `update`, `delete`, or a custom method name). - **`config`** _(object)_ The override mapping, deep-merged on top of the base `unified_model_resource_method` config for the same (resource, integration, method) triple. - **`static`** _(unknown)_ Static value returned for this method without making an HTTP call. - **`resource`** _(string | array | object)_ Integration resource to call. May be a single name, an array of resource fragments, or a `{ expression, resources }` object for dynamic dispatch. _One of:_ - **object** - **`expression`** _(string)_ - **`resources`** _(array)_ - **`method`** _(string | array | object)_ Integration method to call. _One of:_ - **object** - **`expression`** _(string)_ - **`methods`** _(array)_ - **`base_url_mapping`** _(string)_ - **`path_mapping`** _(string)_ - **`error_mapping`** _(string)_ - **`mapping_version`** _(number)_ - **`response_mapping_method`** _(string)_ Allowed: `array`, `item` - **`response_mapping`** _(string | object)_ JSONata expression (string) or object-form mapping. The object form is keyed by field name with values that may be JSONata strings, nested objects, or `JsonSchemaObjectProperties`. - **`documentation_link`** _(string)_ - **`related_resources`** _(string | array)_ - **`request_body_schema`** _(object)_ Object-form (v2) request body schema; values are partial JSON Schema entries. - **`request_body_mapping`** _(string | object)_ - **`query_mapping`** _(string | object)_ - **`query_schema`** _(string | object)_ - **`request_header_mapping`** _(string)_ - **`response_header_mapping`** _(string)_ - **`query`** _(object)_ Static query params merged into the integration request. - **`body`** _(object)_ Static body merged into the integration request. - **`before`** _(string | array)_ - **`after`** _(string | array)_ - **`is_partial_response`** _(boolean)_ - **`is_partial_expression`** _(string)_ - **`side_load`** _(object)_ - **`file_upload`** _(string | object | array)_ _One of:_ - **object** - **`file_upload`** _(string)_ Allowed: `multipart`, `base64`, `upload` - **`config`** _(object)_ Strategy-specific options (e.g. multipart field name, base64 wrapper key). - **`version`** _(number)_ Optimistic-concurrency version. Send the current value in a PATCH body; every write increments it. - **`created_at`** _(string)_ - **`updated_at`** _(string)_ ## Methods - [GET /environment-unified-model-resource-method](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/list) — List environment unified model mappings - [POST /environment-unified-model-resource-method](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/create) — Create environment unified model mapping - [GET /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/get) — Get environment unified model mapping - [PATCH /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/update) — Update environment unified model mapping - [DELETE /environment-unified-model-resource-method/{id}](/api-reference/admin/installed-unified-models-environment-unified-model-mappings/delete) — Delete environment unified model mapping --- # Categories Object > Source: https://truto.one/docs/api-reference/admin/categories/ Schema for the `Categories` resource in **Admin API**. ## Properties - **`name`** _(string)_ The internal name/slug of the category. - **`label`** _(string)_ A user-facing label or descriptive name for the category. - **`created_at`** _(string)_ The date and time when the category was created. - **`updated_at`** _(string)_ The date and time when the category was last updated. ## Methods - [GET /category](/api-reference/admin/categories/list) — List categories --- # Sync Job Run State Object > Source: https://truto.one/docs/api-reference/admin/sync-job-run-state/ Schema for the `Sync Job Run State` resource in **Admin API**. ## Properties - **`key`** _(string)_ Key for this state entry. Unique within the namespace identified by `state_key`. - **`value`** _(string)_ The stored value. Encode structured data (for example, JSON) as a string before storing. - **`sync_job_run_id`** _(string)_ The ID of the sync job run that wrote this entry, if any. - **`created_at`** _(string)_ Time at which the state entry was first created. - **`updated_at`** _(string)_ Time at which the state entry was last updated. ## Methods - [GET /sync-job-run-state](/api-reference/admin/sync-job-run-state/list) — List sync job run states - [POST /sync-job-run-state](/api-reference/admin/sync-job-run-state/create) — Create sync job run state - [GET /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/get) — Get sync job run state - [PATCH /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/update) — Update sync job run state - [DELETE /sync-job-run-state/{id}](/api-reference/admin/sync-job-run-state/delete) — Delete sync job run state --- # Workflows Object > Source: https://truto.one/docs/api-reference/admin/workflows/ Schema for the `Workflows` resource in **Admin API**. ## Properties - **`id`** _(string)_ - **`environment_id`** _(string)_ - **`trigger_name`** _(string)_ - **`config`** _(object, required)_ Workflow execution configuration. - **`run_if`** _(string)_ JSONata condition evaluated before executing workflow steps. - **`steps`** _(array)_ - **`type`** _(string)_ Step execution type. Allowed: `run` - **`action`** _(string)_ Action executed by the step. - **`cron_expression`** _(string)_ Optional cron expression for scheduled execution, in UTC. When set, the step creates a sync job cron trigger instead of starting a run, so the trigger's check applies: the step fails if the expression doesn't parse or its next two runs are less than 5 minutes apart. - **`config`** _(string)_ JSONata expression evaluated at runtime to generate the step execution payload. - **`created_at`** _(string)_ - **`updated_at`** _(string)_ ## Methods - [GET /workflow](/api-reference/admin/workflows/list) — List workflows - [POST /workflow](/api-reference/admin/workflows/create) — Create workflow - [GET /workflow/{id}](/api-reference/admin/workflows/get) — Get workflow - [DELETE /workflow/{id}](/api-reference/admin/workflows/delete) — Delete workflow --- # WorkflowRuns Object > Source: https://truto.one/docs/api-reference/admin/workflowruns/ Schema for the `WorkflowRuns` resource in **Admin API**. ## Properties - **`id`** _(string)_ - **`workflow_id`** _(string)_ - **`environment_id`** _(string)_ - **`status`** _(string)_ Allowed: `created`, `running`, `completed`, `failed` - **`result`** _(object, required)_ - **`steps`** _(array)_ - **`type`** _(string)_ - **`action`** _(string)_ - **`success`** _(boolean)_ - **`error`** _(string)_ - **`result`** _(object)_ - **`success`** _(boolean)_ - **`error`** _(string)_ - **`retry_attempt`** _(number)_ - **`created_at`** _(string)_ - **`updated_at`** _(string)_ - **`started_at`** _(string)_ - **`finished_at`** _(string)_ ## Methods - [GET /workflow-run](/api-reference/admin/workflowruns/list) — List workflow runs - [GET /workflow-run/{id}](/api-reference/admin/workflowruns/get) — Get workflow run --- # Platform assistant Object > Source: https://truto.one/docs/api-reference/admin/platform-assistant/ Schema for the `Platform assistant` resource in **Admin API**. _No documented properties._ ## Methods - [POST /platform/mcp](/api-reference/admin/platform-assistant/mcp) — Platform MCP (JSON-RPC) - [GET /assistant/models](/api-reference/admin/platform-assistant/listModels) — List allowed assistant models - [GET /assistant/platform-mcp](/api-reference/admin/platform-assistant/getPlatformMcpInfo) — Get Platform MCP connection info - [GET /assistant/settings](/api-reference/admin/platform-assistant/getAssistantSettings) — Get team assistant settings - [PATCH /assistant/settings](/api-reference/admin/platform-assistant/patchAssistantSettings) — Update team assistant settings (team admin) - [POST /assistant/settings/test-key](/api-reference/admin/platform-assistant/testAssistantApiKey) — Test Anthropic API key (team admin) - [GET /assistant/status](/api-reference/admin/platform-assistant/assistantStatus) — Assistant availability for current team --- # Passkeys Object > Source: https://truto.one/docs/api-reference/admin/passkeys/ Schema for the `Passkeys` resource in **Admin API**. ## Properties - **`id`** _(string)_ The unique ID of the passkey. Use this to rename or delete it. - **`name`** _(string)_ User-supplied label, or `null` when the passkey was registered without one. - **`device_type`** _(string)_ `multiDevice` for a synced passkey (iCloud Keychain, Google Password Manager); `singleDevice` for a device-bound one (a security key, or a platform authenticator that does not sync). Allowed: `singleDevice`, `multiDevice`, `null` - **`backup_state`** _(boolean)_ Whether the credential is currently synced into a backup (the WebAuthn BS flag). Refreshed on every sign-in. - **`last_used_at`** _(string)_ ISO-8601 UTC timestamp of the last successful sign-in with this passkey; `null` if it has never been used. - **`created_at`** _(string)_ ISO-8601 UTC timestamp of registration. ## Methods - [POST /auth/passkey/registration/options](/api-reference/admin/passkeys/registration-options) — Start passkey registration - [POST /auth/passkey/registration/verify](/api-reference/admin/passkeys/registration-verify) — Finish passkey registration - [GET /auth/passkey](/api-reference/admin/passkeys/list) — List your passkeys - [PATCH /auth/passkey/{id}](/api-reference/admin/passkeys/patch) — Rename a passkey - [DELETE /auth/passkey/{id}](/api-reference/admin/passkeys/delete) — Delete a passkey - [POST /auth/passkey/authentication/options](/api-reference/admin/passkeys/authentication-options) — Start passwordless passkey sign-in - [POST /auth/passkey/authentication/verify](/api-reference/admin/passkeys/authentication-verify) — Finish passwordless passkey sign-in --- # Billing Object > Source: https://truto.one/docs/api-reference/admin/billing/ Schema for the `Billing` resource in **Admin API**. ## Properties - **`id`** _(string)_ Truto's id for the mirrored invoice row. - **`team_id`** _(string)_ - **`stripe_invoice_id`** _(string)_ - **`stripe_customer_id`** _(string)_ - **`source`** _(string)_ `automated` when Truto generated it from a plan; `stripe_manual` when it was raised by hand in Stripe. Allowed: `automated`, `stripe_manual` - **`status`** _(string)_ Raw Stripe invoice status. Allowed: `draft`, `open`, `paid`, `void`, `uncollectible` - **`number`** _(string)_ - **`currency`** _(string)_ - **`amount_due_cents`** _(integer)_ - **`amount_paid_cents`** _(integer)_ - **`amount_remaining_cents`** _(integer)_ - **`period_start`** _(string)_ - **`period_end`** _(string)_ - **`hosted_invoice_url`** _(string)_ Stripe-hosted page to view and pay the invoice. - **`invoice_pdf`** _(string)_ - **`stripe_created_at`** _(string)_ - **`finalized_at`** _(string)_ - **`paid_at`** _(string)_ - **`voided_at`** _(string)_ - **`attempt_count`** _(integer)_ - **`last_payment_error`** _(string)_ ## Methods - [GET /billing/summary](/api-reference/admin/billing/summary) — Get billing summary - [GET /billing/usage](/api-reference/admin/billing/usage) — Get billing usage for a month - [GET /billing/invoice](/api-reference/admin/billing/list) — List invoices - [GET /billing/invoice/{id}](/api-reference/admin/billing/get) — Get invoice - [POST /billing/portal-session](/api-reference/admin/billing/create_portal_session) — Create Stripe Customer Portal session - [POST /billing/checkout-setup-session](/api-reference/admin/billing/create_checkout_setup_session) — Create Stripe Checkout session to add a payment method --- # Analytics Object > Source: https://truto.one/docs/api-reference/admin/analytics/ Schema for the `Analytics` resource in **Admin API**. _No documented properties._ ## Methods - [GET /analytics/metrics](/api-reference/admin/analytics/metrics) — List analytics metrics - [GET /analytics/status](/api-reference/admin/analytics/status) — Get analytics status for an environment - [GET /analytics/dashboard](/api-reference/admin/analytics/dashboard) — Get an environment's analytics dashboard - [GET /analytics/timeseries](/api-reference/admin/analytics/timeseries) — Get an analytics time series - [GET /analytics/breakdown](/api-reference/admin/analytics/breakdown) — Get a paginated analytics breakdown --- # Unified Accounting API > Source: https://truto.one/docs/api-reference/unified-accounting-api/ Base URL: `https://api.truto.one/unified/accounting` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Accounts](/api-reference/unified-accounting-api/accounts) - [GET /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/get) — Get Accounts - [PATCH /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/update) — Update Accounts - [DELETE /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/delete) — Delete Accounts - [GET /unified/accounting/accounts](/api-reference/unified-accounting-api/accounts/list) — List Accounts - [POST /unified/accounting/accounts](/api-reference/unified-accounting-api/accounts/create) — Create Accounts - [Attachments](/api-reference/unified-accounting-api/attachments) - [POST /unified/accounting/attachments](/api-reference/unified-accounting-api/attachments/create) — Create Attachments - [GET /unified/accounting/attachments](/api-reference/unified-accounting-api/attachments/list) — List Attachments - [DELETE /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/delete) — Delete Attachments - [GET /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/get) — Get Attachments - [PATCH /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/update) — Update Attachments - [CompanyInfo](/api-reference/unified-accounting-api/companyinfo) - [GET /unified/accounting/company_info/{id}](/api-reference/unified-accounting-api/companyinfo/get) — Get Company info - [PATCH /unified/accounting/company_info/{id}](/api-reference/unified-accounting-api/companyinfo/update) — Update Company info - [GET /unified/accounting/company_info](/api-reference/unified-accounting-api/companyinfo/list) — List Company info - [Contacts](/api-reference/unified-accounting-api/contacts) - [GET /unified/accounting/contacts](/api-reference/unified-accounting-api/contacts/list) — List Contacts - [POST /unified/accounting/contacts](/api-reference/unified-accounting-api/contacts/create) — Create Contacts - [GET /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/get) — Get Contacts - [PATCH /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/update) — Update Contacts - [DELETE /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/delete) — Delete Contacts - [CreditNotes](/api-reference/unified-accounting-api/creditnotes) - [GET /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/get) — Get Credit notes - [DELETE /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/delete) — Delete Credit notes - [PATCH /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/update) — Update Credit notes - [GET /unified/accounting/credit_notes](/api-reference/unified-accounting-api/creditnotes/list) — List Credit notes - [POST /unified/accounting/credit_notes](/api-reference/unified-accounting-api/creditnotes/create) — Create Credit notes - [POST /unified/accounting/credit_notes/download](/api-reference/unified-accounting-api/creditnotes/download) — Download Credit notes - [Expenses](/api-reference/unified-accounting-api/expenses) - [GET /unified/accounting/expenses](/api-reference/unified-accounting-api/expenses/list) — List Expenses - [POST /unified/accounting/expenses](/api-reference/unified-accounting-api/expenses/create) — Create Expenses - [GET /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/get) — Get Expenses - [PATCH /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/update) — Update Expenses - [DELETE /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/delete) — Delete Expenses - [Invoices](/api-reference/unified-accounting-api/invoices) - [GET /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/get) — Get Invoices - [PATCH /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/update) — Update Invoices - [DELETE /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/delete) — Delete Invoices - [GET /unified/accounting/invoices](/api-reference/unified-accounting-api/invoices/list) — List Invoices - [POST /unified/accounting/invoices](/api-reference/unified-accounting-api/invoices/create) — Create Invoices - [POST /unified/accounting/invoices/download](/api-reference/unified-accounting-api/invoices/download) — Download Invoices - [POST /unified/accounting/invoices/send](/api-reference/unified-accounting-api/invoices/send) — Send Invoices - [Items](/api-reference/unified-accounting-api/items) - [GET /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/get) — Get Items - [PATCH /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/update) — Update Items - [DELETE /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/delete) — Delete Items - [GET /unified/accounting/items](/api-reference/unified-accounting-api/items/list) — List Items - [POST /unified/accounting/items](/api-reference/unified-accounting-api/items/create) — Create Items - [JournalEntries](/api-reference/unified-accounting-api/journalentries) - [GET /unified/accounting/journal_entries](/api-reference/unified-accounting-api/journalentries/list) — List Journal entries - [POST /unified/accounting/journal_entries](/api-reference/unified-accounting-api/journalentries/create) — Create Journal entries - [GET /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/get) — Get Journal entries - [PATCH /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/update) — Update Journal entries - [DELETE /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/delete) — Delete Journal entries - [Payments](/api-reference/unified-accounting-api/payments) - [GET /unified/accounting/payments](/api-reference/unified-accounting-api/payments/list) — List Payments - [POST /unified/accounting/payments](/api-reference/unified-accounting-api/payments/create) — Create Payments - [GET /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/get) — Get Payments - [PATCH /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/update) — Update Payments - [DELETE /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/delete) — Delete Payments - [POST /unified/accounting/payments/download](/api-reference/unified-accounting-api/payments/download) — Download Payments - [PurchaseOrders](/api-reference/unified-accounting-api/purchaseorders) - [GET /unified/accounting/purchase_orders](/api-reference/unified-accounting-api/purchaseorders/list) — List Purchase orders - [POST /unified/accounting/purchase_orders](/api-reference/unified-accounting-api/purchaseorders/create) — Create Purchase orders - [GET /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/get) — Get Purchase orders - [DELETE /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/delete) — Delete Purchase orders - [PATCH /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/update) — Update Purchase orders - [POST /unified/accounting/purchase_orders/download](/api-reference/unified-accounting-api/purchaseorders/download) — Download Purchase orders - [TaxRates](/api-reference/unified-accounting-api/taxrates) - [GET /unified/accounting/tax_rates](/api-reference/unified-accounting-api/taxrates/list) — List Tax rates - [POST /unified/accounting/tax_rates](/api-reference/unified-accounting-api/taxrates/create) — Create Tax rates - [GET /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/get) — Get Tax rates - [DELETE /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/delete) — Delete Tax rates - [PATCH /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/update) — Update Tax rates - [TrackingCategories](/api-reference/unified-accounting-api/trackingcategories) - [GET /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/get) — Get Tracking categories - [DELETE /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/delete) — Delete Tracking categories - [PATCH /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/update) — Update Tracking categories - [GET /unified/accounting/tracking_categories](/api-reference/unified-accounting-api/trackingcategories/list) — List Tracking categories - [POST /unified/accounting/tracking_categories](/api-reference/unified-accounting-api/trackingcategories/create) — Create Tracking categories - [Transactions](/api-reference/unified-accounting-api/transactions) - [GET /unified/accounting/transactions](/api-reference/unified-accounting-api/transactions/list) — List Transactions - [POST /unified/accounting/transactions](/api-reference/unified-accounting-api/transactions/create) — Create Transactions - [GET /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/get) — Get Transactions - [PATCH /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/update) — Update Transactions - [DELETE /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/delete) — Delete Transactions - [POST /unified/accounting/transactions/send](/api-reference/unified-accounting-api/transactions/send) — Send Transactions - [VendorCredits](/api-reference/unified-accounting-api/vendorcredits) - [GET /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/get) — Get Vendor credits - [DELETE /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/delete) — Delete Vendor credits - [PATCH /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/update) — Update Vendor credits - [GET /unified/accounting/vendor_credits](/api-reference/unified-accounting-api/vendorcredits/list) — List Vendor credits - [POST /unified/accounting/vendor_credits](/api-reference/unified-accounting-api/vendorcredits/create) — Create Vendor credits - [PaymentMethod](/api-reference/unified-accounting-api/paymentmethod) - [GET /unified/accounting/payment_method](/api-reference/unified-accounting-api/paymentmethod/list) — List Payment method - [POST /unified/accounting/payment_method](/api-reference/unified-accounting-api/paymentmethod/create) — Create Payment method - [GET /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/get) — Get Payment method - [DELETE /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/delete) — Delete Payment method - [PATCH /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/update) — Update Payment method - [Currencies](/api-reference/unified-accounting-api/currencies) - [GET /unified/accounting/currencies](/api-reference/unified-accounting-api/currencies/list) — List Currencies - [POST /unified/accounting/currencies](/api-reference/unified-accounting-api/currencies/create) — Create Currencies - [GET /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/get) — Get Currencies - [DELETE /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/delete) — Delete Currencies - [PATCH /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/update) — Update Currencies - [ContactGroups](/api-reference/unified-accounting-api/contactgroups) - [GET /unified/accounting/contact_groups](/api-reference/unified-accounting-api/contactgroups/list) — List Contact groups - [POST /unified/accounting/contact_groups](/api-reference/unified-accounting-api/contactgroups/create) — Create Contact groups - [GET /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/get) — Get Contact groups - [PATCH /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/update) — Update Contact groups - [DELETE /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/delete) — Delete Contact groups - [Employees](/api-reference/unified-accounting-api/employees) - [GET /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/get) — Get Employees - [DELETE /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/delete) — Delete Employees - [PATCH /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/update) — Update Employees - [GET /unified/accounting/employees](/api-reference/unified-accounting-api/employees/list) — List Employees - [POST /unified/accounting/employees](/api-reference/unified-accounting-api/employees/create) — Create Employees - [RepeatingTransactions](/api-reference/unified-accounting-api/repeatingtransactions) - [POST /unified/accounting/repeating_transactions](/api-reference/unified-accounting-api/repeatingtransactions/create) — Create Repeating transactions - [GET /unified/accounting/repeating_transactions](/api-reference/unified-accounting-api/repeatingtransactions/list) — List Repeating transactions - [DELETE /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/delete) — Delete Repeating transactions - [GET /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/get) — Get Repeating transactions - [PATCH /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/update) — Update Repeating transactions - [Budgets](/api-reference/unified-accounting-api/budgets) - [GET /unified/accounting/budgets](/api-reference/unified-accounting-api/budgets/list) — List Budgets - [POST /unified/accounting/budgets](/api-reference/unified-accounting-api/budgets/create) — Create Budgets - [GET /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/get) — Get Budgets - [PATCH /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/update) — Update Budgets - [DELETE /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/delete) — Delete Budgets - [Reports](/api-reference/unified-accounting-api/reports) - [GET /unified/accounting/reports](/api-reference/unified-accounting-api/reports/list) — List Reports - [PurchaseOrderRequisitions](/api-reference/unified-accounting-api/purchaseorderrequisitions) - [GET /unified/accounting/purchase_order_requisitions](/api-reference/unified-accounting-api/purchaseorderrequisitions/list) — List Purchase order requisitions - [POST /unified/accounting/purchase_order_requisitions](/api-reference/unified-accounting-api/purchaseorderrequisitions/create) — Create Purchase order requisitions - [GET /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/get) — Get Purchase order requisitions - [DELETE /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/delete) — Delete Purchase order requisitions - [PATCH /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/update) — Update Purchase order requisitions - [ShippingMethods](/api-reference/unified-accounting-api/shippingmethods) - [GET /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/get) — Get Shipping methods - [PATCH /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/update) — Update Shipping methods - [DELETE /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/delete) — Delete Shipping methods - [GET /unified/accounting/shipping_methods](/api-reference/unified-accounting-api/shippingmethods/list) — List Shipping methods - [POST /unified/accounting/shipping_methods](/api-reference/unified-accounting-api/shippingmethods/create) — Create Shipping methods - [ItemReceipts](/api-reference/unified-accounting-api/itemreceipts) - [GET /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/get) — Get Item receipts - [DELETE /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/delete) — Delete Item receipts - [PATCH /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/update) — Update Item receipts - [GET /unified/accounting/item_receipts](/api-reference/unified-accounting-api/itemreceipts/list) — List Item receipts - [POST /unified/accounting/item_receipts](/api-reference/unified-accounting-api/itemreceipts/create) — Create Item receipts --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/accounts/ Schema for the `Accounts` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the account - **`name`** _(string, required)_ The name of the account - **`description`** _(string)_ The description of the account - **`classification`** _(string)_ The classification of the account. If no clear mapping exists, then raw value is returned. Allowed: `asset`, `equity`, `expense`, `liability`, `revenue`, `bank` - **`type`** _(string)_ The more specific classification of the account Allowed: `fixed_asset`, `long_term_liability`, `equity`, `expense`, `bank`, `current`, `current_liability`, `other_income`, `direct_costs`, `other_expenses`, `income`, `other_asset` (+29 more) - **`status`** _(string)_ The status of the account. If no clear mapping exists, then raw value is returned. Allowed: `active`, `archived`, `pending` - **`current_balance`** _(number)_ The current balance of the account - **`currency`** _(string)_ The currency of the account - **`account_number`** _(string)_ Represents the bank account number if the account is of type bank account. - **`parent_account`** _(string)_ The ID of the parent account of the account - **`company`** _(string)_ The ID of the company the account belongs to - **`created_at`** _(string)_ This represents the date when the accounts was created - **`updated_at`** _(string)_ This represents the date when the accounts was updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/get) — Get Accounts - [PATCH /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/update) — Update Accounts - [DELETE /unified/accounting/accounts/{id}](/api-reference/unified-accounting-api/accounts/delete) — Delete Accounts - [GET /unified/accounting/accounts](/api-reference/unified-accounting-api/accounts/list) — List Accounts - [POST /unified/accounting/accounts](/api-reference/unified-accounting-api/accounts/create) — Create Accounts --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/attachments/ Schema for the `Attachments` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for attachment - **`file_name`** _(string)_ The name of the attachment - **`file_url`** _(string)_ The url of the attachment - **`file_size`** _(number)_ The size of the attachment - **`file_type`** _(string)_ The MIME type of the attachment - **`parent`** _(object)_ The parent object of the attachment - **`id`** _(string)_ The unique identifier for the parent - **`type`** _(string)_ The type of the parent - **`company`** _(string)_ The company the attachment belongs to - **`created_at`** _(string)_ This represents the date when the attachment was created - **`updated_at`** _(string)_ This represents the date when the attachment was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/accounting/attachments](/api-reference/unified-accounting-api/attachments/create) — Create Attachments - [GET /unified/accounting/attachments](/api-reference/unified-accounting-api/attachments/list) — List Attachments - [DELETE /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/delete) — Delete Attachments - [GET /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/get) — Get Attachments - [PATCH /unified/accounting/attachments/{id}](/api-reference/unified-accounting-api/attachments/update) — Update Attachments --- # CompanyInfo Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/companyinfo/ Schema for the `CompanyInfo` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for company info - **`name`** _(string)_ The name of the company - **`legal_name`** _(string)_ The legal name of the company - **`emails`** _(array)_ - **`email`** _(string)_ The company's email - **`type`** _(string)_ The company's email type - **`tax_number`** _(string)_ The tax number of the company - **`fiscal_year_end_month`** _(string)_ The fiscal year end month - **`fiscal_year_end_day`** _(string)_ The fiscal year end day - **`currency`** _(string)_ The currency of the company - **`urls`** _(array)_ The urls of the company - **`addresses`** _(array)_ The addresses of the company - **`street_1`** _(string)_ The street 1 address of the company - **`street_2`** _(string)_ The street 2 address of the company - **`city`** _(string)_ The city of the company - **`state`** _(string)_ The state of the company - **`country`** _(string)_ The country of the company - **`postal_code`** _(string)_ The postal code of the company - **`type`** _(string)_ The type of the address - **`phones`** _(array)_ The phone numbers of the company - **`number`** _(string)_ The phone number of the company - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of the phone number - **`created_at`** _(string)_ This represents the date when the company info was created - **`updated_at`** _(string)_ This represents the date when the company info was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/company_info/{id}](/api-reference/unified-accounting-api/companyinfo/get) — Get Company info - [PATCH /unified/accounting/company_info/{id}](/api-reference/unified-accounting-api/companyinfo/update) — Update Company info - [GET /unified/accounting/company_info](/api-reference/unified-accounting-api/companyinfo/list) — List Company info --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/contacts/ Schema for the `Contacts` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the contact - **`name`** _(string)_ The name of the contact - **`type`** _(string)_ The type of the contact Allowed: `customer`, `vendor` - **`emails`** _(array)_ The emails of the contact - **`email`** _(string)_ The email of the contact - **`type`** _(string)_ The type of the email - **`tax_number`** _(string)_ The tax number of the contact - **`status`** _(string)_ The status of the contact Allowed: `active`, `archived` - **`currency`** _(string)_ The currency of the contact - **`company`** _(string)_ The ID of company the contact belongs to - **`addresses`** _(array)_ The addresses of the contact - **`id`** _(string)_ The unique identifier for address - **`street_1`** _(string)_ The street 1 address of the contact - **`street_2`** _(string)_ The street 2 address of the contact - **`city`** _(string)_ The city of the contact - **`state`** _(string)_ The state of the contact - **`country`** _(string)_ The country of the contact - **`postal_code`** _(string)_ The postal code of the contact - **`type`** _(string)_ The type of the address - **`phones`** _(array)_ The phone numbers of the contact - **`number`** _(string)_ The phone number of the contact - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of the phone number - **`created_at`** _(string)_ This represents the date when the contact was created - **`updated_at`** _(string)_ This represents the date when the contact was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/contacts](/api-reference/unified-accounting-api/contacts/list) — List Contacts - [POST /unified/accounting/contacts](/api-reference/unified-accounting-api/contacts/create) — Create Contacts - [GET /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/get) — Get Contacts - [PATCH /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/update) — Update Contacts - [DELETE /unified/accounting/contacts/{id}](/api-reference/unified-accounting-api/contacts/delete) — Delete Contacts --- # CreditNotes Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/creditnotes/ Schema for the `CreditNotes` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for credit notes - **`number`** _(string)_ The number of the credit note - **`status`** _(string)_ The status of the credit note Allowed: `paid`, `submitted`, `authorised`, `voided` - **`transaction_date`** _(string)_ The transaction date of the credit note - **`contact`** _(string)_ The contact of the credit note - **`company`** _(string)_ The company of the credit note - **`total_amount`** _(number)_ The total amount of the credit note - **`remaining_credit`** _(number)_ The remaining credit of the credit note - **`line_items`** _(array)_ The line items of the credit note - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`currency`** _(string)_ The currency of the credit note - **`payments`** _(array)_ The payments of the credit note - **`created_at`** _(string)_ This represents the date when the credit note was created - **`updated_at`** _(string)_ This represents the date when the credit note was updated - **`tracking_categories`** _(array)_ Tracking categories of the credit notes - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/get) — Get Credit notes - [DELETE /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/delete) — Delete Credit notes - [PATCH /unified/accounting/credit_notes/{id}](/api-reference/unified-accounting-api/creditnotes/update) — Update Credit notes - [GET /unified/accounting/credit_notes](/api-reference/unified-accounting-api/creditnotes/list) — List Credit notes - [POST /unified/accounting/credit_notes](/api-reference/unified-accounting-api/creditnotes/create) — Create Credit notes - [POST /unified/accounting/credit_notes/download](/api-reference/unified-accounting-api/creditnotes/download) — Download Credit notes --- # Expenses Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/expenses/ Schema for the `Expenses` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for expenses - **`transaction_date`** _(string)_ The transaction date of the expense - **`contact`** _(string)_ The contact of the expense - **`company`** _(string)_ The company of the expense - **`currency`** _(string)_ The currency of the expense - **`exchange_rate`** _(number)_ The exchange rate of the expense - **`memo`** _(string)_ The memo of the expense - **`total_amount`** _(number)_ The total amount of the expense - **`line_items`** _(array)_ The line items of the expense - **`id`** _(string)_ The unique identifier for line items - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`account`** _(string)_ The account of the line item - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The tax rate of the line item - **`total_line_amount`** _(number)_ The total line amount of the line item - **`type`** _(string)_ The type of the line item - **`created_at`** _(string)_ This represents the date when the expense was created - **`updated_at`** _(string)_ This represents the date when the expense was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/expenses](/api-reference/unified-accounting-api/expenses/list) — List Expenses - [POST /unified/accounting/expenses](/api-reference/unified-accounting-api/expenses/create) — Create Expenses - [GET /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/get) — Get Expenses - [PATCH /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/update) — Update Expenses - [DELETE /unified/accounting/expenses/{id}](/api-reference/unified-accounting-api/expenses/delete) — Delete Expenses --- # Invoices Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/invoices/ Schema for the `Invoices` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for invoices - **`type`** _(string)_ The type of the invoice Allowed: `bill`, `invoice` - **`contact`** _(object)_ The contact for whom the invoice is raised. - **`id`** _(string)_ The unique identifier for the contact - **`name`** _(string)_ The name of the contact - **`type`** _(string)_ The type of the contact - vendor or customer. - **`number`** _(string)_ The number of the invoice - **`issue_date`** _(string)_ The issue date of the invoice - **`due_date`** _(string)_ The due date of the invoice - **`paid_on_date`** _(string)_ The paid on date of the invoice - **`memo`** _(string)_ The private note of the invoice - **`company`** _(string)_ The company the invoice belongs to - **`currency`** _(string)_ The currency of the invoice - **`exchange_rate`** _(number)_ The exchange rate of the invoice - **`total_discount`** _(number)_ The total discount of the invoice - **`sub_total`** _(number)_ The sub total of the invoice - **`total_tax_amount`** _(number)_ The total tax amount of the invoice - **`balance`** _(number)_ The remaining balance of the invoice - **`payments`** _(array)_ List of payment IDs associated with the invoice - **`line_items`** _(array)_ The line items of the invoice - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`status`** _(string)_ The status of the invoice Allowed: `draft`, `submitted`, `deleted`, `authorised`, `paid`, `voided` - **`created_at`** _(string)_ This represents the date when the invoice was created - **`updated_at`** _(string)_ This represents the date when the invoice was updated - **`urls`** _(array)_ The invoice URLs - **`url`** _(string)_ The invoice URL - **`type`** _(string)_ Type of invoice URL - **`tracking_categories`** _(array)_ Tracking categories of the invoices - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/get) — Get Invoices - [PATCH /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/update) — Update Invoices - [DELETE /unified/accounting/invoices/{id}](/api-reference/unified-accounting-api/invoices/delete) — Delete Invoices - [GET /unified/accounting/invoices](/api-reference/unified-accounting-api/invoices/list) — List Invoices - [POST /unified/accounting/invoices](/api-reference/unified-accounting-api/invoices/create) — Create Invoices - [POST /unified/accounting/invoices/download](/api-reference/unified-accounting-api/invoices/download) — Download Invoices - [POST /unified/accounting/invoices/send](/api-reference/unified-accounting-api/invoices/send) — Send Invoices --- # Items Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/items/ Schema for the `Items` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the item - **`name`** _(string)_ The name of the item - **`description`** _(string)_ The description of the item - **`status`** _(string)_ The status of the item. If no clear mapping exists, then raw value is returned Allowed: `active`, `archived` - **`quantity`** _(number)_ The quantity of the Item. - **`unit_price`** _(number)_ The unit price of the item - **`purchase_price`** _(number)_ The purchase price of the item - **`purchase_account`** _(string)_ The ID of the account used to record the purchase of the item - **`sales_account`** _(string)_ The ID of the account used to record the sale - **`asset_account`** _(string)_ The ID of the account used to record the asset - **`company`** _(string)_ The ID of the company the item belongs to - **`created_at`** _(string)_ This represents the date when the item was created - **`updated_at`** _(string)_ This represents the date when the item was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/get) — Get Items - [PATCH /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/update) — Update Items - [DELETE /unified/accounting/items/{id}](/api-reference/unified-accounting-api/items/delete) — Delete Items - [GET /unified/accounting/items](/api-reference/unified-accounting-api/items/list) — List Items - [POST /unified/accounting/items](/api-reference/unified-accounting-api/items/create) — Create Items --- # JournalEntries Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/journalentries/ Schema for the `JournalEntries` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for journal entries - **`payments`** _(array)_ The payments of the journal entry - **`id`** _(string)_ The unique identifier for payment - **`payment_for`** _(string)_ What entity was the payment for. Can be invoice or bill. Allowed: `invoice`, `bill` - **`contact`** _(object)_ The contact of the payment - **`id`** _(string)_ The ID of the contact - **`type`** _(string)_ The type of the contact. Can be customer or vendor. Allowed: `customer`, `vendor` - **`memo`** _(string)_ The private note of the journal entry - **`type`** _(string)_ The type of the journal entry Allowed: `ACCOUNTS_RECEIVABLE`, `ACCOUNTS_PAYABLE`, `GENERAL`, `STATISTICAL` - **`currency`** _(string)_ The currency of the journal entry - **`exchange_rate`** _(number)_ The exchange rate of the journal entry - **`company`** _(string)_ The company the journal entry belongs to - **`lines`** _(array)_ - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`created_at`** _(string)_ This represents the date when the journal entry was created - **`updated_at`** _(string)_ This represents the date when the journal entry was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/journal_entries](/api-reference/unified-accounting-api/journalentries/list) — List Journal entries - [POST /unified/accounting/journal_entries](/api-reference/unified-accounting-api/journalentries/create) — Create Journal entries - [GET /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/get) — Get Journal entries - [PATCH /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/update) — Update Journal entries - [DELETE /unified/accounting/journal_entries/{id}](/api-reference/unified-accounting-api/journalentries/delete) — Delete Journal entries --- # Payments Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/payments/ Schema for the `Payments` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for payments - **`payment_for`** _(string)_ What entity was the payment for. Can be invoice or bill. Allowed: `invoice`, `bill` - **`status`** _(string)_ The status of the payment. - **`transaction_date`** _(string)_ The transaction date of the payment - **`contact`** _(object)_ The contact of the payment - **`id`** _(string)_ The ID of the contact - **`type`** _(string)_ The type of the contact. Can be customer or vendor. Allowed: `customer`, `vendor` - **`account`** _(string)_ The ID of the account for the payment - **`invoice`** _(object)_ The invoice associated with the payment - **`id`** _(string)_ The ID of the invoice - **`type`** _(string)_ The type of the invoice Allowed: `invoice`, `bill` - **`currency`** _(string)_ The currency of the payment - **`exchange_rate`** _(number)_ The exchange rate of the payment - **`company`** _(string)_ The ID of the company the payment belongs to - **`total_amount`** _(number)_ The total amount of the payment - **`created_at`** _(string)_ This represents the date when the payment was created - **`updated_at`** _(string)_ This represents the date when the payment was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/payments](/api-reference/unified-accounting-api/payments/list) — List Payments - [POST /unified/accounting/payments](/api-reference/unified-accounting-api/payments/create) — Create Payments - [GET /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/get) — Get Payments - [PATCH /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/update) — Update Payments - [DELETE /unified/accounting/payments/{id}](/api-reference/unified-accounting-api/payments/delete) — Delete Payments - [POST /unified/accounting/payments/download](/api-reference/unified-accounting-api/payments/download) — Download Payments --- # PurchaseOrders Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/purchaseorders/ Schema for the `PurchaseOrders` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for purchase orders - **`status`** _(string)_ The status of the purchase order Allowed: `draft`, `submitted`, `authorised`, `billed`, `deleted` - **`issue_date`** _(string)_ The issue date of the purchase order - **`delivery_date`** _(string)_ The delivery date of the purchase order - **`delivery_address`** _(string)_ The delivery address of the purchase order - **`customer`** _(string)_ The customer contact making the purchase order - **`vendor`** _(string)_ The vendor contact fulfilling the purchase order - **`memo`** _(string)_ The memo of the purchase order - **`total_amount`** _(number)_ The total amount of the purchase order - **`currency`** _(string)_ The currency of the purchase order - **`exchange_rate`** _(number)_ The exchange rate of the purchase order - **`line_items`** _(array)_ - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`created_at`** _(string)_ This represents the date when the purchase order was created - **`updated_at`** _(string)_ This represents the date when the purchase order was updated - **`tracking_categories`** _(array)_ Tracking categories of the purchase order - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`employee`** _(object)_ Employee contact fulfilling the purchase order - **`id`** _(string)_ The unique identifier of an employee - **`name`** _(string)_ The employee's name - **`email`** _(string)_ The employee's email - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/purchase_orders](/api-reference/unified-accounting-api/purchaseorders/list) — List Purchase orders - [POST /unified/accounting/purchase_orders](/api-reference/unified-accounting-api/purchaseorders/create) — Create Purchase orders - [GET /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/get) — Get Purchase orders - [DELETE /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/delete) — Delete Purchase orders - [PATCH /unified/accounting/purchase_orders/{id}](/api-reference/unified-accounting-api/purchaseorders/update) — Update Purchase orders - [POST /unified/accounting/purchase_orders/download](/api-reference/unified-accounting-api/purchaseorders/download) — Download Purchase orders --- # TaxRates Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/taxrates/ Schema for the `TaxRates` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for tax rates - **`name`** _(string)_ The name of the tax rate - **`description`** _(string)_ The description of the tax rate - **`total_tax_rate`** _(number)_ The total tax rate of the tax rate - **`effective_tax_rate`** _(number)_ The effective tax rate of the tax rate - **`company`** _(string)_ The company the tax rate belongs to - **`created_at`** _(string)_ This represents the date when the tax rate was created - **`updated_at`** _(string)_ This represents the date when the tax rate was updated - **`status`** _(string)_ The status of the contact Allowed: `active`, `archived` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/tax_rates](/api-reference/unified-accounting-api/taxrates/list) — List Tax rates - [POST /unified/accounting/tax_rates](/api-reference/unified-accounting-api/taxrates/create) — Create Tax rates - [GET /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/get) — Get Tax rates - [DELETE /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/delete) — Delete Tax rates - [PATCH /unified/accounting/tax_rates/{id}](/api-reference/unified-accounting-api/taxrates/update) — Update Tax rates --- # TrackingCategories Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/trackingcategories/ Schema for the `TrackingCategories` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for tracking categories - **`name`** _(string)_ The name of the tracking category - **`status`** _(string)_ The status of the tracking category Allowed: `active`, `archived` - **`category_type`** _(string)_ The category type of the tracking category - **`parent_category`** _(string)_ The parent category of the tracking category - **`company`** _(string)_ The company the tracking category belongs to - **`options`** _(array)_ The options for the tracking category. Present in Xero - **`id`** _(string)_ The unique identifier for tracking option - **`name`** _(string)_ The name for tracking option - **`status`** _(string)_ The status for tracking option Allowed: `active`, `archived` - **`created_at`** _(string)_ This represents the date when the tracking category was created - **`updated_at`** _(string)_ This represents the date when the tracking category was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/get) — Get Tracking categories - [DELETE /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/delete) — Delete Tracking categories - [PATCH /unified/accounting/tracking_categories/{id}](/api-reference/unified-accounting-api/trackingcategories/update) — Update Tracking categories - [GET /unified/accounting/tracking_categories](/api-reference/unified-accounting-api/trackingcategories/list) — List Tracking categories - [POST /unified/accounting/tracking_categories](/api-reference/unified-accounting-api/trackingcategories/create) — Create Tracking categories --- # Transactions Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/transactions/ Schema for the `Transactions` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for transactions - **`number`** _(string)_ The number of the transaction - **`memo`** _(string)_ This represents memo / private note on the transaction. - **`transaction_type`** _(string)_ The type of the transaction Allowed: `refund`, `deposit`, `estimate`, `transfer`, `credit_card`, `spend`, `receive`, `receive_overpayment`, `receive_prepayment`, `spend_overpayment`, `spend_prepayment` - **`transaction_date`** _(string)_ The date upon which the transaction occurred - **`account`** _(string)_ The account which receives the transaction - **`account_from`** _(string)_ The account which initiates the transaction - **`contact`** _(string)_ The contact to whom the transaction relates to - **`total_amount`** _(string)_ The total amount of the transaction - **`currency`** _(string)_ The currency of the transaction - **`exchange_rate`** _(string)_ The exchange rate of the transaction - **`company`** _(string)_ The company the transaction belongs to - **`line_items`** _(array)_ - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`tracking_categories`** _(array)_ Tracking categories of the transaction - **`id`** _(string, required)_ The unique identifier for tracking categories - **`name`** _(string)_ The name of the tracking category - **`created_at`** _(string)_ This represents the date when the transaction was created - **`updated_at`** _(string)_ This represents the date when the transaction was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/transactions](/api-reference/unified-accounting-api/transactions/list) — List Transactions - [POST /unified/accounting/transactions](/api-reference/unified-accounting-api/transactions/create) — Create Transactions - [GET /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/get) — Get Transactions - [PATCH /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/update) — Update Transactions - [DELETE /unified/accounting/transactions/{id}](/api-reference/unified-accounting-api/transactions/delete) — Delete Transactions - [POST /unified/accounting/transactions/send](/api-reference/unified-accounting-api/transactions/send) — Send Transactions --- # VendorCredits Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/vendorcredits/ Schema for the `VendorCredits` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for vendor credits - **`number`** _(string)_ The number of the vendor credit - **`transaction_date`** _(string)_ The transaction date of the vendor credit - **`vendor`** _(string)_ The vendor that owes the refund - **`total_amount`** _(number)_ The total amount of the vendor credit - **`currency`** _(string)_ The currency of the vendor credit - **`exchange_rate`** _(number)_ The exchange rate of the vendor credit - **`company`** _(string)_ The company the vendor credit belongs to - **`line_items`** _(array)_ The line items of the invoice - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`created_at`** _(string)_ This represents the date when the vendor credit was created - **`updated_at`** _(string)_ This represents the date when the vendor credit was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/get) — Get Vendor credits - [DELETE /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/delete) — Delete Vendor credits - [PATCH /unified/accounting/vendor_credits/{id}](/api-reference/unified-accounting-api/vendorcredits/update) — Update Vendor credits - [GET /unified/accounting/vendor_credits](/api-reference/unified-accounting-api/vendorcredits/list) — List Vendor credits - [POST /unified/accounting/vendor_credits](/api-reference/unified-accounting-api/vendorcredits/create) — Create Vendor credits --- # PaymentMethod Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/paymentmethod/ Schema for the `PaymentMethod` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for payment method - **`name`** _(string)_ The name of the payment method - **`status`** _(string)_ The status of the payment method Allowed: `active`, `archived` - **`type`** _(string)_ The type of payment method Allowed: `credit_card`, `non_credit_card` - **`created_at`** _(string)_ This represents the date when the payment method was created - **`updated_at`** _(string)_ This represents the date when the payment method was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/payment_method](/api-reference/unified-accounting-api/paymentmethod/list) — List Payment method - [POST /unified/accounting/payment_method](/api-reference/unified-accounting-api/paymentmethod/create) — Create Payment method - [GET /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/get) — Get Payment method - [DELETE /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/delete) — Delete Payment method - [PATCH /unified/accounting/payment_method/{id}](/api-reference/unified-accounting-api/paymentmethod/update) — Update Payment method --- # Currencies Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/currencies/ Schema for the `Currencies` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for currency - **`name`** _(string)_ The name of the currency - **`code`** _(string)_ The code of the currency - **`status`** _(string)_ The status of the currency Allowed: `active`, `archived` - **`created_at`** _(string)_ This represents the date when the currency was created - **`updated_at`** _(string)_ This represents the date when the currency was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/currencies](/api-reference/unified-accounting-api/currencies/list) — List Currencies - [POST /unified/accounting/currencies](/api-reference/unified-accounting-api/currencies/create) — Create Currencies - [GET /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/get) — Get Currencies - [DELETE /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/delete) — Delete Currencies - [PATCH /unified/accounting/currencies/{id}](/api-reference/unified-accounting-api/currencies/update) — Update Currencies --- # ContactGroups Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/contactgroups/ Schema for the `ContactGroups` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for contact group - **`name`** _(string)_ The name of the contact group - **`status`** _(string)_ The status of the contact group Allowed: `active`, `archived` - **`created_at`** _(string)_ This represents the date when the contact group was created - **`updated_at`** _(string)_ This represents the date when the contact group was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/contact_groups](/api-reference/unified-accounting-api/contactgroups/list) — List Contact groups - [POST /unified/accounting/contact_groups](/api-reference/unified-accounting-api/contactgroups/create) — Create Contact groups - [GET /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/get) — Get Contact groups - [PATCH /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/update) — Update Contact groups - [DELETE /unified/accounting/contact_groups/{id}](/api-reference/unified-accounting-api/contactgroups/delete) — Delete Contact groups --- # Employees Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/employees/ Schema for the `Employees` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for employee - **`first_name`** _(string)_ The first name of the employee - **`last_name`** _(string)_ The last name of the employee - **`name`** _(string)_ The display name of the employee - **`emails`** _(array)_ The emails of the employee - **`email`** _(string)_ The email of the employee - **`type`** _(string)_ The type of the email - **`phones`** _(array)_ The phone numbers of employee - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone - **`addresses`** _(array)_ - **`street_1`** _(string)_ The street 1 of the address - **`street_2`** _(string)_ The street 2 of the address - **`city`** _(string)_ The city of the address - **`state`** _(string)_ The state of the address - **`country`** _(string)_ The country of the address - **`postal_code`** _(string)_ The postal code of the address - **`type`** _(string)_ The type of the address - **`created_at`** _(string)_ This represents the date when the employee was created - **`updated_at`** _(string)_ This represents the date when the employee was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/get) — Get Employees - [DELETE /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/delete) — Delete Employees - [PATCH /unified/accounting/employees/{id}](/api-reference/unified-accounting-api/employees/update) — Update Employees - [GET /unified/accounting/employees](/api-reference/unified-accounting-api/employees/list) — List Employees - [POST /unified/accounting/employees](/api-reference/unified-accounting-api/employees/create) — Create Employees --- # RepeatingTransactions Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/repeatingtransactions/ Schema for the `RepeatingTransactions` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for repeating transaction - **`name`** _(string)_ The name of the repeating transaction - **`entity`** _(object)_ The entity of the repeating transaction. The schema will be based on the type of entity, but `id` and `type` will always be present. - **`id`** _(string, required)_ The unique identifier for the entity - **`type`** _(string, required)_ The type of the entity Allowed: `invoice`, `purchase_order`, `vendor_credit`, `credit_note`, `journal_entry` - **`status`** _(boolean)_ The status of the repeating transaction Allowed: `active`, `archived` - **`recurring_type`** _(string)_ The recurring type of the repeating transaction Allowed: `unscheduled`, `automated`, `reminded` - **`interval_type`** _(string)_ The interval type of the repeating transaction Allowed: `daily`, `weekly`, `monthly`, `yearly` - **`interval_num`** _(number)_ The interval number of the repeating transaction. E.g., 1 (every 1 week), 2 (every 2 months), etc. - **`day_of_month`** _(number)_ The day of the month of the repeating transaction - **`month_of_year`** _(number)_ The month of the year of the repeating transaction - **`day_of_week`** _(number)_ The day of the week of the repeating transaction - **`week_of_month`** _(number)_ The week of the month of the repeating transaction - **`days_before`** _(number)_ The days before of the repeating transaction - **`start_date`** _(string)_ The start date for the repeating transaction - **`end_date`** _(string)_ The end date for the repeating transaction - **`max_occurrences`** _(number)_ The maximum number of occurrences for the repeating transaction - **`next_date`** _(string)_ The next date of the repeating transaction - **`prev_date`** _(string)_ The previous date of the repeating transaction - **`created_at`** _(string)_ Rhe date when the repeating transaction was created - **`updated_at`** _(string)_ The date when the repeating transaction was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/accounting/repeating_transactions](/api-reference/unified-accounting-api/repeatingtransactions/create) — Create Repeating transactions - [GET /unified/accounting/repeating_transactions](/api-reference/unified-accounting-api/repeatingtransactions/list) — List Repeating transactions - [DELETE /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/delete) — Delete Repeating transactions - [GET /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/get) — Get Repeating transactions - [PATCH /unified/accounting/repeating_transactions/{id}](/api-reference/unified-accounting-api/repeatingtransactions/update) — Update Repeating transactions --- # Budgets Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/budgets/ Schema for the `Budgets` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for budget - **`name`** _(string)_ The name of the budget - **`tracking_categories`** _(array)_ The tracking categories of the budget - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`status`** _(string)_ The status of the budget Allowed: `active`, `archived` - **`start_date`** _(string)_ The start date of the budget - **`end_date`** _(string)_ The end date of the budget - **`line_items`** _(array)_ The line items of the budget - **`account`** _(string)_ The ID of the account - **`amount`** _(string)_ The amount of the line item - **`note`** _(string)_ The note of the line item - **`date`** _(string)_ The date of the line item - **`created_at`** _(string)_ This represents the date when the budget was created - **`updated_at`** _(string)_ This represents the date when the budget was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/budgets](/api-reference/unified-accounting-api/budgets/list) — List Budgets - [POST /unified/accounting/budgets](/api-reference/unified-accounting-api/budgets/create) — Create Budgets - [GET /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/get) — Get Budgets - [PATCH /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/update) — Update Budgets - [DELETE /unified/accounting/budgets/{id}](/api-reference/unified-accounting-api/budgets/delete) — Delete Budgets --- # Reports Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/reports/ Schema for the `Reports` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for report - **`name`** _(string)_ The name of the report - **`company`** _(string)_ The company the report belongs to - **`start_date`** _(string)_ The start date of the report - **`end_date`** _(string)_ The end date of the report - **`currency`** _(string)_ The currency of the report - **`created_at`** _(string)_ This represents the date when the report was created - **`report_data`** _(object)_ The data of the report - **`columns`** _(array)_ The columns of the report - **`rows`** _(array)_ The rows of the report - **`data`** _(array)_ The data of the row. The data is in the same order as the columns. - **`rows`** _(array)_ The sub-rows of the row. They have the same schema as the parent row. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/reports](/api-reference/unified-accounting-api/reports/list) — List Reports --- # PurchaseOrderRequisitions Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/purchaseorderrequisitions/ Schema for the `PurchaseOrderRequisitions` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for purchase order requisition - **`status`** _(string)_ The status of the purchase order requisition Allowed: `draft`, `submitted`, `authorised`, `billed`, `deleted`, `delivered`, `partially_delivered` - **`issue_date`** _(string)_ The issue date of the purchase order requisition - **`delivery_date`** _(string)_ The delivery date of the purchase order requisition - **`delivery_address`** _(string)_ The delivery address of the purchase order requisition - **`customer`** _(string)_ The customer contact making the purchase order requisition - **`vendor`** _(string)_ The vendor contact fulfilling the purchase order requisition - **`memo`** _(string)_ The memo of the purchase order requisition - **`total_amount`** _(number)_ The total amount of the purchase order requisition - **`currency`** _(string)_ The currency of the purchase order requisition - **`exchange_rate`** _(number)_ The exchange rate of the purchase order requisition - **`line_items`** _(array)_ - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`account`** _(string)_ The ID of the account - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(number)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`total_line_amount`** _(number)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`tracking_categories`** _(array)_ Tracking categories of the line item - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`created_at`** _(string)_ This represents the date when the purchase order requisition was created - **`updated_at`** _(string)_ This represents the date when the purchase order requisition was updated - **`tracking_categories`** _(array)_ Tracking categories of the purchase order requisition - **`id`** _(string)_ The ID of the tracking category - **`name`** _(string)_ The name of the tracking category - **`option`** _(string)_ The option of the tracking category - **`employee`** _(object)_ Employee contact fulfilling the purchase order requisition - **`id`** _(string)_ The unique identifier of an employee - **`name`** _(string)_ The employee's name - **`email`** _(string)_ The employee's email - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/purchase_order_requisitions](/api-reference/unified-accounting-api/purchaseorderrequisitions/list) — List Purchase order requisitions - [POST /unified/accounting/purchase_order_requisitions](/api-reference/unified-accounting-api/purchaseorderrequisitions/create) — Create Purchase order requisitions - [GET /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/get) — Get Purchase order requisitions - [DELETE /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/delete) — Delete Purchase order requisitions - [PATCH /unified/accounting/purchase_order_requisitions/{id}](/api-reference/unified-accounting-api/purchaseorderrequisitions/update) — Update Purchase order requisitions --- # ShippingMethods Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/shippingmethods/ Schema for the `ShippingMethods` resource in **Unified Accounting API**. ## Properties - **`id`** _(string)_ The id of the shipping method - **`title`** _(string)_ The title of the shipping method - **`code`** _(string)_ The code of the shipping method - **`updated_at`** _(string)_ The last updated timestamp of the shipping method - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/get) — Get Shipping methods - [PATCH /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/update) — Update Shipping methods - [DELETE /unified/accounting/shipping_methods/{id}](/api-reference/unified-accounting-api/shippingmethods/delete) — Delete Shipping methods - [GET /unified/accounting/shipping_methods](/api-reference/unified-accounting-api/shippingmethods/list) — List Shipping methods - [POST /unified/accounting/shipping_methods](/api-reference/unified-accounting-api/shippingmethods/create) — Create Shipping methods --- # ItemReceipts Object > Source: https://truto.one/docs/api-reference/unified-accounting-api/itemreceipts/ Schema for the `ItemReceipts` resource in **Unified Accounting API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the item receipt - **`number`** _(string)_ The number of the item receipt - **`order_number`** _(string)_ The number of the purchase order the goods were received against - **`transaction_date`** _(string)_ The posting date of the item receipt - **`due_date`** _(string)_ The due date of the item receipt - **`vendor`** _(string)_ The vendor the goods were received from - **`vendor_name`** _(string)_ The name of the vendor - **`currency`** _(string)_ The currency of the item receipt - **`company`** _(string)_ The company the item receipt belongs to - **`line_items`** _(array)_ The lines of the item receipt - **`id`** _(string)_ The unique identifier for the line item - **`description`** _(string)_ The description of the line item - **`quantity`** _(number)_ The quantity received - **`unit_price`** _(number)_ The unit cost of the line item - **`type`** _(string)_ The type of the line item - **`updated_at`** _(string)_ The last updated timestamp of the item receipt - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/get) — Get Item receipts - [DELETE /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/delete) — Delete Item receipts - [PATCH /unified/accounting/item_receipts/{id}](/api-reference/unified-accounting-api/itemreceipts/update) — Update Item receipts - [GET /unified/accounting/item_receipts](/api-reference/unified-accounting-api/itemreceipts/list) — List Item receipts - [POST /unified/accounting/item_receipts](/api-reference/unified-accounting-api/itemreceipts/create) — Create Item receipts --- # Unified Ads Management API > Source: https://truto.one/docs/api-reference/unified-ads-management-api/ Base URL: `https://api.truto.one/unified/ads` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Accounts](/api-reference/unified-ads-management-api/accounts) - [GET /unified/ads/accounts](/api-reference/unified-ads-management-api/accounts/list) — List Accounts - [GET /unified/ads/accounts/{id}](/api-reference/unified-ads-management-api/accounts/get) — Get Accounts - [Campaigns](/api-reference/unified-ads-management-api/campaigns) - [GET /unified/ads/campaigns](/api-reference/unified-ads-management-api/campaigns/list) — List Campaigns - [POST /unified/ads/campaigns](/api-reference/unified-ads-management-api/campaigns/create) — Create Campaigns - [GET /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/get) — Get Campaigns - [PATCH /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/update) — Update Campaigns - [DELETE /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/delete) — Delete Campaigns - [AdGroups](/api-reference/unified-ads-management-api/adgroups) - [GET /unified/ads/ad_groups](/api-reference/unified-ads-management-api/adgroups/list) — List Ad groups - [POST /unified/ads/ad_groups](/api-reference/unified-ads-management-api/adgroups/create) — Create Ad groups - [GET /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/get) — Get Ad groups - [PATCH /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/update) — Update Ad groups - [DELETE /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/delete) — Delete Ad groups - [Ads](/api-reference/unified-ads-management-api/ads) - [GET /unified/ads/ads](/api-reference/unified-ads-management-api/ads/list) — List Ads - [POST /unified/ads/ads](/api-reference/unified-ads-management-api/ads/create) — Create Ads - [GET /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/get) — Get Ads - [DELETE /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/delete) — Delete Ads - [PATCH /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/update) — Update Ads - [Creatives](/api-reference/unified-ads-management-api/creatives) - [GET /unified/ads/creatives](/api-reference/unified-ads-management-api/creatives/list) — List Creatives - [POST /unified/ads/creatives](/api-reference/unified-ads-management-api/creatives/create) — Create Creatives - [GET /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/get) — Get Creatives - [PATCH /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/update) — Update Creatives - [DELETE /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/delete) — Delete Creatives - [Assets](/api-reference/unified-ads-management-api/assets) - [GET /unified/ads/assets](/api-reference/unified-ads-management-api/assets/list) — List Assets - [POST /unified/ads/assets](/api-reference/unified-ads-management-api/assets/create) — Create Assets - [CustomAudiences](/api-reference/unified-ads-management-api/customaudiences) - [GET /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/get) — Get Custom audiences - [PATCH /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/update) — Update Custom audiences - [DELETE /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/delete) — Delete Custom audiences - [POST /unified/ads/custom_audiences](/api-reference/unified-ads-management-api/customaudiences/create) — Create Custom audiences - [GET /unified/ads/custom_audiences](/api-reference/unified-ads-management-api/customaudiences/list) — List Custom audiences - [POST /unified/ads/custom_audiences/add_members](/api-reference/unified-ads-management-api/customaudiences/add_members) — Add Members Custom audiences - [POST /unified/ads/custom_audiences/remove_members](/api-reference/unified-ads-management-api/customaudiences/remove_members) — Remove Members Custom audiences --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/accounts/ Schema for the `Accounts` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the account. - **`name`** _(string)_ The name of the account. - **`currency_code`** _(string)_ The currency code for the account. - **`status`** _(string)_ The status of the account. Allowed: `active`, `inactive` - **`timezone`** _(object)_ The timezone for the account. - **`id`** _(string)_ The unique identifier for the timezone. - **`name`** _(string)_ The name of the timezone. - **`type`** _(array)_ The type of the account. - **`spend`** _(object)_ The spend for the account. - **`max_cap`** _(string)_ The cap amount for the account. - **`min_cap`** _(string)_ The min amount for the account. - **`max_shared_cap`** _(string)_ The max shared cap for the account. - **`min_shared_cap`** _(string)_ The min shared cap for the account. - **`spent`** _(string)_ The spend amount for the account. - **`balance`** _(string)_ The balance for the account. - **`daily_budget`** _(string)_ The daily budget for the account. - **`disable_reason`** _(string)_ The reason the account is disabled. - **`created_at`** _(string)_ The date and time the account was created. - **`updated_at`** _(string)_ The date and time the account was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/accounts](/api-reference/unified-ads-management-api/accounts/list) — List Accounts - [GET /unified/ads/accounts/{id}](/api-reference/unified-ads-management-api/accounts/get) — Get Accounts --- # Campaigns Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/campaigns/ Schema for the `Campaigns` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the campaign. - **`name`** _(string)_ The name of the campaign. - **`status`** _(string)_ The status of the campaign. Allowed: `active`, `inactive`, `draft`, `paused`, `deleted`, `archived`, `in_process`, `with_issues`, `completed`, `canceled`, `pending_deletion` - **`type`** _(string)_ The type of the campaign - **`account_id`** _(string)_ The unique identifier for the account. - **`labels`** _(array)_ The labels for the campaign. - **`id`** _(string)_ The unique identifier for the label. - **`name`** _(string)_ The name of the label. - **`objective`** _(string)_ The objective of the campaign. Allowed: `app_installs`, `brand_awareness`, `conversions`, `visits`, `job_applications`, `event_responses`, `lead_generation`, `link_clicks`, `local_awareness`, `messages`, `offer_claims`, `outcome_app_promotion` (+11 more) - **`bid_strategy`** _(object)_ The bid strategy for the campaign. - **`id`** _(string)_ The unique identifier for the bid strategy. - **`name`** _(string)_ The name of the bid strategy. Allowed: `lowest_cost_without_cap`, `lowest_cost_with_bid_cap`, `cost_cap` - **`buying_type`** _(string)_ The buying type for the campaign. Allowed: `auction`, `reserved` - **`budget`** _(object)_ The budget for the campaign. - **`id`** _(string)_ The unique identifier for the budget. - **`remaining`** _(string)_ The remaining budget for the campaign. - **`lifetime_max`** _(string)_ The max budget for the campaign. - **`daily_max`** _(string)_ The daily max budget for the campaign. - **`is_scheduling_enabled`** _(boolean)_ Whether budget scheduling is enabled for the campaign. - **`is_rebalance_enabled`** _(boolean)_ Whether budget rebalancing is enabled for the campaign. - **`is_shared`** _(boolean)_ Whether the budget is shared for the campaign with other campaigns. - **`spend`** _(object)_ The spend for the campaign. - **`max_cap`** _(string)_ The max cap spend for the campaign. - **`cap_enabled`** _(boolean)_ Whether the cap is enabled for the campaign. - **`primary_attribution`** _(string)_ The primary attribution for the campaign. - **`special_ad_categories`** _(array)_ The special ad categories for the campaign. - **`special_ad_category`** _(string)_ The special ad category for the campaign. Allowed: `credit`, `employment`, `housing`, `none`, `political`, `social_issues` - **`start_time`** _(string)_ The start time for the campaign. - **`stop_time`** _(string)_ The stop time for the campaign. - **`created_at`** _(string)_ The date and time the campaign was created. - **`updated_at`** _(string)_ The date and time the campaign was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/campaigns](/api-reference/unified-ads-management-api/campaigns/list) — List Campaigns - [POST /unified/ads/campaigns](/api-reference/unified-ads-management-api/campaigns/create) — Create Campaigns - [GET /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/get) — Get Campaigns - [PATCH /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/update) — Update Campaigns - [DELETE /unified/ads/campaigns/{id}](/api-reference/unified-ads-management-api/campaigns/delete) — Delete Campaigns --- # AdGroups Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/adgroups/ Schema for the `AdGroups` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the ad_group. - **`name`** _(string)_ The name of the ad_group. - **`status`** _(string)_ The status of the campaign. Allowed: `active`, `inactive`, `draft`, `paused`, `deleted`, `archived`, `in_process`, `with_issues`, `completed`, `canceled`, `pending_deletion` - **`account_id`** _(string)_ The unique identifier for the account. - **`campaign_id`** _(string)_ The unique identifier for the campaign. - **`labels`** _(array)_ The labels for the ad_group. - **`id`** _(string)_ The unique identifier for the label. - **`name`** _(string)_ The name of the label. - **`attribution_spec`** _(string)_ The attribution spec for the ad_group. - **`bid`** _(object)_ The bid for the ad_group. - **`adjustments`** _(object)_ The bid adjustments for the ad_group. - **`amount`** _(string)_ The bid amount for the ad_group. - **`constraints`** _(object)_ The bid constraints for the ad_group. - **`objective_values`** _(object)_ The bid values for different objectives of the ad_group. - **`strategy`** _(object)_ The bid strategy for the ad_group. - **`id`** _(string)_ The unique identifier for the bid strategy. - **`name`** _(string)_ The name of the bid strategy. - **`billing_event`** _(string)_ The billing event for the ad_group. Allowed: `app_installs`, `clicks`, `impressions`, `link_clicks`, `none`, `offer_claims`, `page_likes`, `post_engagement`, `video_views` - **`budget`** _(object)_ The budget for the ad_group. - **`lifetime_max`** _(string)_ The max budget for the ad_group. - **`daily_max`** _(string)_ The daily max budget for the ad_group. - **`daily_min`** _(string)_ The daily min budget for the ad_group. - **`spend`** _(object)_ The spend for the ad_group. - **`lifetime_max`** _(string)_ The max spend for the ad_group. - **`daily_min_cap`** _(string)_ The min cap spend for the ad_group. - **`daily_max_cap`** _(string)_ The max cap spend for the ad_group. - **`cap_enabled`** _(boolean)_ Whether the cap is enabled for the ad_group. - **`impressions`** _(object)_ The impressions for the ad_group. - **`daily_min`** _(string)_ The daily min impressions for the ad_group. - **`lifetime_max`** _(string)_ The max impressions for the ad_group. - **`destination`** _(object)_ The destination type for the ad_group. - **`id`** _(string)_ The unique identifier for the destination type. - **`name`** _(string)_ The name of the destination type. Allowed: `undefined`, `app`, `messenger`, `website`, `instagram_direct`, `on_ad`, `on_post`, `on_video`, `on_page`, `on_event` - **`start_time`** _(string)_ The start time for the ad_group. - **`stop_time`** _(string)_ The stop time for the ad_group. - **`issues`** _(array)_ The issues for the ad_group that prevented ads from being delivered. - **`code`** _(string)_ The code for the issue. - **`message`** _(string)_ The error message for the issue. - **`description`** _(string)_ The error summary for the issue. - **`level`** _(string)_ The level for the issue. - **`type`** _(string)_ The type for the issue. - **`optimization_goal`** _(string)_ The optimization goal for the ad_group. Allowed: `none`, `app_installs`, `ad_recall_lift`, `clicks`, `engaged_users`, `event_responses`, `impressions`, `lead_generation`, `quality_lead`, `link_clicks`, `offsite_conversions`, `page_likes` (+10 more) - **`promoted_object`** _(object)_ The promoted object for the ad_group. - **`targeting`** _(object)_ The targeting for the ad_group. - **`targeting_optimization_types`** _(array)_ - **`key`** _(string)_ The key for the targeting optimization type. - **`value`** _(string)_ The value for the targeting optimization type. - **`schedule`** _(object)_ The schedule for the ad_group. - **`start_time`** _(string)_ The start time for the ad_group. - **`end_time`** _(string)_ The end time for the ad_group. - **`days`** _(array)_ The days for the ad_group. - **`created_at`** _(string)_ The date and time the ad_group was created. - **`updated_at`** _(string)_ The date and time the ad_group was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/ad_groups](/api-reference/unified-ads-management-api/adgroups/list) — List Ad groups - [POST /unified/ads/ad_groups](/api-reference/unified-ads-management-api/adgroups/create) — Create Ad groups - [GET /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/get) — Get Ad groups - [PATCH /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/update) — Update Ad groups - [DELETE /unified/ads/ad_groups/{id}](/api-reference/unified-ads-management-api/adgroups/delete) — Delete Ad groups --- # Ads Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/ads/ Schema for the `Ads` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the ad. - **`name`** _(string)_ The name of the ad. - **`type`** _(string)_ The type of the ad - **`status`** _(string)_ The status of the ad. Allowed: `active`, `paused`, `deleted`, `archived`, `in_process`, `with_issues`, `campaign_paused`, `pending_review`, `disapproved`, `preapproved`, `pending_billing_info`, `adset_paused` - **`account_id`** _(string)_ The unique identifier for the account. - **`ad_group_id`** _(string)_ The unique identifier for the ad_group. - **`campaign_id`** _(string)_ The unique identifier for the campaign. - **`labels`** _(array)_ The labels for the ad. - **`id`** _(string)_ The unique identifier for the label. - **`name`** _(string)_ The name of the label. - **`schedule`** _(object)_ The schedule for the ad. - **`end_time`** _(string)_ The end time for the ad. - **`start_time`** _(string)_ The start time for the ad. - **`bid`** _(object)_ The bid for the ad. - **`adjustments`** _(object)_ The bid adjustments for the ad. - **`amount`** _(string)_ The bid amount for the ad. - **`constraints`** _(object)_ The bid constraints for the ad. - **`objective_values`** _(object)_ The bid values for different objectives of the ad. - **`strategy`** _(object)_ The bid strategy for the ad. - **`id`** _(string)_ The unique identifier for the bid strategy. - **`name`** _(string)_ The name of the bid strategy. - **`conversion_domain`** _(string)_ The conversion domain for the ad. - **`creative`** _(object)_ The creative for the ad. - **`creative_id`** _(array)_ The unique identifier for the creative. - **`issues`** _(array)_ The issues for the ad that prevented the ad from being delivered. - **`code`** _(string)_ The code for the issue. - **`message`** _(string)_ The error message for the issue. - **`description`** _(string)_ The error summary for the issue. - **`level`** _(string)_ The level for the issue. - **`type`** _(string)_ The type for the issue. - **`preview_url`** _(array)_ The preview URL for the ad. - **`url`** _(string)_ The URL for the preview. - **`type`** _(string)_ The type for the preview. - **`tracking_specs`** _(array)_ The tracking specs for the ad. - **`created_at`** _(string)_ The date and time the ad was created. - **`updated_at`** _(string)_ The date and time the ad was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/ads](/api-reference/unified-ads-management-api/ads/list) — List Ads - [POST /unified/ads/ads](/api-reference/unified-ads-management-api/ads/create) — Create Ads - [GET /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/get) — Get Ads - [DELETE /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/delete) — Delete Ads - [PATCH /unified/ads/ads/{id}](/api-reference/unified-ads-management-api/ads/update) — Update Ads --- # Creatives Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/creatives/ Schema for the `Creatives` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the creative. - **`name`** _(string)_ The name of the creative. - **`status`** _(string)_ The status of the creative. Allowed: `active`, `deleted`, `in_process`, `with_issues` - **`account_id`** _(string)_ The unique identifier for the account. - **`labels`** _(array)_ The labels for the creative. - **`id`** _(string)_ The unique identifier for the label. - **`name`** _(string)_ The name of the label. - **`applink_treatment`** _(string)_ The applink treatment for the creative. Allowed: `automatic`, `deeplink_with_appstore_fallback`, `deeplink_with_web_fallback`, `web_only` - **`authorization_category`** _(string)_ The authorization category for the creative. Allowed: `none`, `political` - **`body`** _(string)_ The body for the creative. - **`call_to_action_type`** _(string)_ The call to action type for the creative. Allowed: `open_link`, `like_page`, `shop_now`, `play_game`, `install_app`, `use_app`, `call`, `call_me`, `video_call`, `install_mobile_app`, `use_mobile_app`, `mobile_download` (+63 more) - **`image_crops`** _(object)_ The image crops for the creative. - **`image_hash`** _(string)_ The image hash for the creative. - **`image_url`** _(string)_ The image URL for the creative. - **`properties`** _(array)_ The properties for the creative. - **`id`** _(string)_ The unique identifier for the property. - **`type`** _(string)_ The type for the property. - **`url`** _(string)_ The URL for the property. - **`spec`** _(object)_ The spec for the creative. - **`interactive_components`** _(object)_ The interactive components for the creative. - **`urls`** _(array)_ The URLs for the creative. - **`id`** _(string)_ The unique identifier for the URL. - **`type`** _(string)_ The type for the URL. - **`url`** _(string)_ The URL for the URL. - **`created_at`** _(string)_ The date and time the creative was created. - **`updated_at`** _(string)_ The date and time the creative was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/creatives](/api-reference/unified-ads-management-api/creatives/list) — List Creatives - [POST /unified/ads/creatives](/api-reference/unified-ads-management-api/creatives/create) — Create Creatives - [GET /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/get) — Get Creatives - [PATCH /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/update) — Update Creatives - [DELETE /unified/ads/creatives/{id}](/api-reference/unified-ads-management-api/creatives/delete) — Delete Creatives --- # Assets Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/assets/ Schema for the `Assets` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the asset. - **`type`** _(string)_ The type of the asset. Allowed: `image`, `video` - **`account_id`** _(string)_ The unique identifier for the account. - **`creative_id`** _(array)_ The unique identifiers for the creatives. - **`hash`** _(string)_ The hash for the asset. - **`height`** _(integer)_ The height for the asset. - **`width`** _(integer)_ The width for the asset. - **`name`** _(string)_ The name for the asset. - **`original_height`** _(integer)_ The original height for the asset. - **`original_width`** _(integer)_ The original width for the asset. - **`status`** _(string)_ The status for the asset. Allowed: `active`, `deleted`, `internal` - **`urls`** _(array)_ The URLs for the asset. - **`id`** _(string)_ The unique identifier for the URL. - **`type`** _(string)_ The type for the URL. - **`url`** _(string)_ The URL for the URL. - **`created_at`** _(string)_ The date and time the asset was created. - **`updated_at`** _(string)_ The date and time the asset was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/assets](/api-reference/unified-ads-management-api/assets/list) — List Assets - [POST /unified/ads/assets](/api-reference/unified-ads-management-api/assets/create) — Create Assets --- # CustomAudiences Object > Source: https://truto.one/docs/api-reference/unified-ads-management-api/customaudiences/ Schema for the `CustomAudiences` resource in **Unified Ads Management API**. ## Properties - **`id`** _(string)_ The unique identifier for the custom audience. - **`name`** _(string)_ The name of the custom audience. - **`description`** _(string)_ The description of the custom audience. - **`type`** _(string)_ The type of custom audience. - **`source`** _(string)_ The source of custom audience. - **`status`** _(string)_ The status of the custom audience. Allowed: `active`, `inactive`, `archived`, `deleted`, `with_issues`, `in_progress`, `failed`, `expired` - **`account_id`** _(string)_ The unique identifier for the account. - **`members`** _(array)_ A list of audience members. - **`first_name`** _(string)_ - **`last_name`** _(string)_ - **`title`** _(string)_ - **`company`** _(string)_ - **`country`** _(string)_ - **`url`** _(string)_ - **`keyword`** _(string)_ - **`email`** _(string)_ - **`phone`** _(string)_ - **`application`** _(string)_ - **`location_category`** _(string)_ - **`google_advertiser_id`** _(string)_ - **`website`** _(string)_ - **`domain`** _(string)_ - **`organization_urn`** _(string)_ - **`linkedin_url`** _(string)_ - **`third_party_user_id`** _(string)_ - **`mobile_id`** _(string)_ - **`created_at`** _(string)_ The date and time the account was created. - **`updated_at`** _(string)_ The date and time the account was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/get) — Get Custom audiences - [PATCH /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/update) — Update Custom audiences - [DELETE /unified/ads/custom_audiences/{id}](/api-reference/unified-ads-management-api/customaudiences/delete) — Delete Custom audiences - [POST /unified/ads/custom_audiences](/api-reference/unified-ads-management-api/customaudiences/create) — Create Custom audiences - [GET /unified/ads/custom_audiences](/api-reference/unified-ads-management-api/customaudiences/list) — List Custom audiences - [POST /unified/ads/custom_audiences/add_members](/api-reference/unified-ads-management-api/customaudiences/add_members) — Add Members Custom audiences - [POST /unified/ads/custom_audiences/remove_members](/api-reference/unified-ads-management-api/customaudiences/remove_members) — Remove Members Custom audiences --- # Unified API > Source: https://truto.one/docs/api-reference/unified-api/ Base URL: `https://api.truto.one/unified/` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Unified Model Docs](/api-reference/unified-api/unified-model-docs) - [GET /unified/{model_name}/{resource_name}/{integration_name}/meta/{method}](/api-reference/unified-api/unified-model-docs/get-method-meta) — Get integration mapping metadata for a unified-model resource method --- # Unified Model Docs Object > Source: https://truto.one/docs/api-reference/unified-api/unified-model-docs/ Schema for the `Unified Model Docs` resource in **Unified API**. ## Properties - **`method`** _(string)_ The unified method this metadata describes. - **`schema`** _(object, required)_ The unified-model resource JSON schema. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`documentation_link`** _(string)_ Vendor documentation URL for this method, if set on the integration mapping. - **`response_schema`** _(object, required)_ A subset of `schema` containing only the fields actually populated by `response_mapping` for this integration. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`query_schema`** _(object, required)_ JSON-schema-style description of the supported query parameters for this method. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`request_body_schema`** _(object, required)_ JSON-schema-style description of the supported request body for this method. - **`type`** _(string)_ Allowed: `object` - **`$ref`** _(string)_ - **`properties`** _(object)_ Map of property name → `JsonSchemaObjectProperties`. - **`description`** _(string)_ - **`required`** _(boolean)_ - **`default`** _(unknown)_ - **`additionalProperties`** _(boolean)_ - **`default_query`** _(object)_ Default query parameters always applied by the integration mapping. Values may be templated JSONata expressions. - **`default_body`** _(object)_ Default request body always applied by the integration mapping. Values may be templated JSONata expressions. Object or `null` (arrays are allowed at runtime but rare). ## Methods - [GET /unified/{model_name}/{resource_name}/{integration_name}/meta/{method}](/api-reference/unified-api/unified-model-docs/get-method-meta) — Get integration mapping metadata for a unified-model resource method --- # Unified ATS API > Source: https://truto.one/docs/api-reference/unified-ats-api/ Base URL: `https://api.truto.one/unified/ats` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Activities](/api-reference/unified-ats-api/activities) - [GET /unified/ats/activities](/api-reference/unified-ats-api/activities/list) — List Activities - [POST /unified/ats/activities](/api-reference/unified-ats-api/activities/create) — Create Activities - [DELETE /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/delete) — Delete Activities - [GET /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/get) — Get Activities - [PATCH /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/update) — Update Activities - [Applications](/api-reference/unified-ats-api/applications) - [GET /unified/ats/applications](/api-reference/unified-ats-api/applications/list) — List Applications - [POST /unified/ats/applications](/api-reference/unified-ats-api/applications/create) — Create Applications - [GET /unified/ats/applications/{id}](/api-reference/unified-ats-api/applications/get) — Get Applications - [POST /unified/ats/applications/move-stage](/api-reference/unified-ats-api/applications/move-stage) — Move Stage Applications - [POST /unified/ats/applications/reject](/api-reference/unified-ats-api/applications/reject) — Reject Applications - [Attachments](/api-reference/unified-ats-api/attachments) - [POST /unified/ats/attachments/download](/api-reference/unified-ats-api/attachments/download) — Download Attachments - [GET /unified/ats/attachments](/api-reference/unified-ats-api/attachments/list) — List Attachments - [POST /unified/ats/attachments](/api-reference/unified-ats-api/attachments/create) — Create Attachments - [GET /unified/ats/attachments/{id}](/api-reference/unified-ats-api/attachments/get) — Get Attachments - [Candidates](/api-reference/unified-ats-api/candidates) - [GET /unified/ats/candidates](/api-reference/unified-ats-api/candidates/list) — List Candidates - [POST /unified/ats/candidates](/api-reference/unified-ats-api/candidates/create) — Create Candidates - [GET /unified/ats/candidates/{id}](/api-reference/unified-ats-api/candidates/get) — Get Candidates - [PATCH /unified/ats/candidates/{id}](/api-reference/unified-ats-api/candidates/update) — Update Candidates - [Departments](/api-reference/unified-ats-api/departments) - [GET /unified/ats/departments](/api-reference/unified-ats-api/departments/list) — List Departments - [GET /unified/ats/departments/{id}](/api-reference/unified-ats-api/departments/get) — Get Departments - [Eeocs](/api-reference/unified-ats-api/eeocs) - [GET /unified/ats/eeocs](/api-reference/unified-ats-api/eeocs/list) — List Eeocs - [GET /unified/ats/eeocs/{id}](/api-reference/unified-ats-api/eeocs/get) — Get Eeocs - [Interviews](/api-reference/unified-ats-api/interviews) - [GET /unified/ats/interviews](/api-reference/unified-ats-api/interviews/list) — List Interviews - [GET /unified/ats/interviews/{id}](/api-reference/unified-ats-api/interviews/get) — Get Interviews - [JobInterviewStages](/api-reference/unified-ats-api/jobinterviewstages) - [GET /unified/ats/job_interview_stages](/api-reference/unified-ats-api/jobinterviewstages/list) — List Job interview stages - [GET /unified/ats/job_interview_stages/{id}](/api-reference/unified-ats-api/jobinterviewstages/get) — Get Job interview stages - [Jobs](/api-reference/unified-ats-api/jobs) - [GET /unified/ats/jobs](/api-reference/unified-ats-api/jobs/list) — List Jobs - [POST /unified/ats/jobs](/api-reference/unified-ats-api/jobs/create) — Create Jobs - [GET /unified/ats/jobs/{id}](/api-reference/unified-ats-api/jobs/get) — Get Jobs - [PATCH /unified/ats/jobs/{id}](/api-reference/unified-ats-api/jobs/update) — Update Jobs - [JobFormFields](/api-reference/unified-ats-api/jobformfields) - [GET /unified/ats/job_form_fields](/api-reference/unified-ats-api/jobformfields/list) — List Job form fields - [Offers](/api-reference/unified-ats-api/offers) - [GET /unified/ats/offers](/api-reference/unified-ats-api/offers/list) — List Offers - [Offices](/api-reference/unified-ats-api/offices) - [GET /unified/ats/offices](/api-reference/unified-ats-api/offices/list) — List Offices - [GET /unified/ats/offices/{id}](/api-reference/unified-ats-api/offices/get) — Get Offices - [Organizations](/api-reference/unified-ats-api/organizations) - [GET /unified/ats/organizations](/api-reference/unified-ats-api/organizations/list) — List Organizations - [GET /unified/ats/organizations/{id}](/api-reference/unified-ats-api/organizations/get) — Get Organizations - [RejectReasons](/api-reference/unified-ats-api/rejectreasons) - [GET /unified/ats/reject_reasons](/api-reference/unified-ats-api/rejectreasons/list) — List Reject reasons - [Scorecards](/api-reference/unified-ats-api/scorecards) - [GET /unified/ats/scorecards](/api-reference/unified-ats-api/scorecards/list) — List Scorecards - [Tags](/api-reference/unified-ats-api/tags) - [GET /unified/ats/tags](/api-reference/unified-ats-api/tags/list) — List Tags - [Users](/api-reference/unified-ats-api/users) - [GET /unified/ats/users](/api-reference/unified-ats-api/users/list) — List Users - [GET /unified/ats/users/{id}](/api-reference/unified-ats-api/users/get) — Get Users --- # Activities Object > Source: https://truto.one/docs/api-reference/unified-ats-api/activities/ Schema for the `Activities` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The activity's unique identifier - **`candidate`** _(object)_ The activity's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`actor`** _(object)_ The activity's actor - **`id`** _(string)_ Unique identifier of the actor - **`type`** _(string)_ Type of the actor Allowed: `user`, `candidate` - **`activity_type`** _(string)_ The activity's type Allowed: `note`, `email` - **`from`** _(array)_ From email addresses if the activity_type is email - **`email`** _(string)_ Email of the sender - **`name`** _(string)_ Name of the sender - **`to`** _(array)_ - **`email`** _(string)_ Email of the recipient - **`name`** _(string)_ Name of the recipient - **`cc`** _(array)_ - **`email`** _(string)_ Email of the recipient - **`name`** _(string)_ Name of the recipient - **`subject`** _(string)_ The activity's subject - **`body`** _(string)_ The activity's body - **`visibility`** _(string)_ The activity's visibility Allowed: `private`, `public`, `admin_only` - **`updated_at`** _(string)_ The date and time of the activity's last update - **`created_at`** _(string)_ The date and time of the activity's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/activities](/api-reference/unified-ats-api/activities/list) — List Activities - [POST /unified/ats/activities](/api-reference/unified-ats-api/activities/create) — Create Activities - [DELETE /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/delete) — Delete Activities - [GET /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/get) — Get Activities - [PATCH /unified/ats/activities/{id}](/api-reference/unified-ats-api/activities/update) — Update Activities --- # Applications Object > Source: https://truto.one/docs/api-reference/unified-ats-api/applications/ Schema for the `Applications` resource in **Unified ATS API**. ## Properties - **`id`** _(string)_ The application's unique identifier - **`candidate`** _(object)_ The application's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`job`** _(object)_ The application's job - **`id`** _(string)_ Unique identifier of the job - **`applied_at`** _(string)_ The date and time of the application's creation - **`rejected_at`** _(string)_ The date and time of the application's rejection - **`source`** _(object)_ The application's source - **`id`** _(string)_ The application's source's unique identifier - **`name`** _(string)_ The application's source's name - **`credited_to`** _(object)_ The application's credited_to - **`id`** _(string)_ Unique identifier of the user - **`first_name`** _(string)_ First name of the user - **`last_name`** _(string)_ Last name of the user - **`emails`** _(array)_ - **`email`** _(string)_ Email of the user - **`type`** _(string)_ Type of the email - **`is_primary`** _(boolean)_ Whether the email is primary - **`current_stage`** _(object)_ The application's current_stage - **`id`** _(string)_ The application's current_stage's unique identifier - **`name`** _(string)_ The application's current_stage's name - **`job`** _(object)_ The application's current_stage's job - **`id`** _(string)_ Unique identifier of the job - **`created_at`** _(string)_ The date and time of the application's current_stage's creation - **`updated_at`** _(string)_ The date and time of the application's current_stage's last update - **`reject_reason`** _(string)_ The application's reject_reason - **`attachments`** _(array)_ The application's attachments - **`id`** _(string, required)_ The attachment's unique identifier - **`file_name`** _(string)_ The attachment's file_name - **`file_url`** _(string)_ The attachment's file_url - **`candidate`** _(object)_ The attachment's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`application`** _(object)_ The attachment's application - **`id`** _(string)_ Unique identifier of the application - **`job`** _(object)_ The attachment's job - **`id`** _(string)_ Unique identifier of the job - **`attachment_type`** _(string)_ The attachment's type - **`created_at`** _(string)_ The date and time of the attachment's creation - **`updated_at`** _(string)_ The date and time of the attachment's last update - **`created_at`** _(string)_ The date and time of the application's creation - **`updated_at`** _(string)_ The date and time of the application's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/applications](/api-reference/unified-ats-api/applications/list) — List Applications - [POST /unified/ats/applications](/api-reference/unified-ats-api/applications/create) — Create Applications - [GET /unified/ats/applications/{id}](/api-reference/unified-ats-api/applications/get) — Get Applications - [POST /unified/ats/applications/move-stage](/api-reference/unified-ats-api/applications/move-stage) — Move Stage Applications - [POST /unified/ats/applications/reject](/api-reference/unified-ats-api/applications/reject) — Reject Applications --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-ats-api/attachments/ Schema for the `Attachments` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The attachment's unique identifier - **`file_name`** _(string)_ The attachment's file_name - **`file_url`** _(string)_ The attachment's file_url - **`candidate`** _(object)_ The attachment's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`application`** _(object)_ The attachment's application - **`id`** _(string)_ Unique identifier of the application - **`job`** _(object)_ The attachment's job - **`id`** _(string)_ Unique identifier of the job - **`attachment_type`** _(string)_ The attachment's type Allowed: `resume`, `cover_letter`, `other` - **`created_at`** _(string)_ The date and time of the attachment's creation - **`updated_at`** _(string)_ The date and time of the attachment's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/ats/attachments/download](/api-reference/unified-ats-api/attachments/download) — Download Attachments - [GET /unified/ats/attachments](/api-reference/unified-ats-api/attachments/list) — List Attachments - [POST /unified/ats/attachments](/api-reference/unified-ats-api/attachments/create) — Create Attachments - [GET /unified/ats/attachments/{id}](/api-reference/unified-ats-api/attachments/get) — Get Attachments --- # Candidates Object > Source: https://truto.one/docs/api-reference/unified-ats-api/candidates/ Schema for the `Candidates` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The candidate's unique identifier - **`first_name`** _(string)_ The candidate's first_name - **`last_name`** _(string)_ The candidate's last_name - **`name`** _(string)_ The user's full name - **`company`** _(string)_ The candidate's company - **`title`** _(string)_ The candidate's title - **`last_interaction_at`** _(string)_ The candidate's last_interaction date - **`is_private`** _(string)_ Whether the candidate is_private - **`can_email`** _(boolean)_ Whether the candidate can email - **`locations`** _(array)_ The candidate's locations - **`phones`** _(array)_ The candidate's phone numbers - **`number`** _(string)_ The candidate's phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The candidate's phone number type - **`emails`** _(array)_ The candidate's emails - **`email`** _(string)_ The candidate's email - **`type`** _(string)_ The candidate's email type - **`urls`** _(array)_ The candidate's urls - **`url`** _(string)_ The candidate's URL - **`type`** _(string)_ The candidate's URL type - **`tags`** _(array)_ The candidate's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`applications`** _(array)_ The candidate's applications - **`id`** _(string)_ The application's unique identifier - **`candidate`** _(object)_ The application's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`job`** _(object)_ The application's job - **`id`** _(string)_ Unique identifier of the job - **`applied_at`** _(string)_ The date and time of the application's creation - **`rejected_at`** _(string)_ The date and time of the application's rejection - **`source`** _(object)_ The application's source - **`id`** _(string)_ The application's source's unique identifier - **`name`** _(string)_ The application's source's name - **`credited_to`** _(object)_ The application's credited_to - **`id`** _(string)_ Unique identifier of the user - **`first_name`** _(string)_ First name of the user - **`last_name`** _(string)_ Last name of the user - **`emails`** _(array)_ - **`email`** _(string)_ Email of the user - **`type`** _(string)_ Type of the email - **`is_primary`** _(boolean)_ Whether the email is primary - **`current_stage`** _(object)_ The application's current_stage - **`id`** _(string)_ The application's current_stage's unique identifier - **`name`** _(string)_ The application's current_stage's name - **`job`** _(object)_ The application's current_stage's job - **`id`** _(string)_ Unique identifier of the job - **`created_at`** _(string)_ The date and time of the application's current_stage's creation - **`updated_at`** _(string)_ The date and time of the application's current_stage's last update - **`reject_reason`** _(string)_ The application's reject_reason - **`attachments`** _(array)_ The application's attachments - **`id`** _(string, required)_ The attachment's unique identifier - **`file_name`** _(string)_ The attachment's file_name - **`file_url`** _(string)_ The attachment's file_url - **`candidate`** _(object)_ The attachment's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`application`** _(object)_ The attachment's application - **`id`** _(string)_ Unique identifier of the application - **`job`** _(object)_ The attachment's job - **`id`** _(string)_ Unique identifier of the job - **`attachment_type`** _(string)_ The attachment's type - **`created_at`** _(string)_ The date and time of the attachment's creation - **`updated_at`** _(string)_ The date and time of the attachment's last update - **`created_at`** _(string)_ The date and time of the application's creation - **`updated_at`** _(string)_ The date and time of the application's last update - **`attachments`** _(array)_ The candidate's attachments - **`id`** _(string, required)_ The attachment's unique identifier - **`file_name`** _(string)_ The attachment's file_name - **`file_url`** _(string)_ The attachment's file_url - **`candidate`** _(object)_ The attachment's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`application`** _(object)_ The attachment's application - **`id`** _(string)_ Unique identifier of the application - **`job`** _(object)_ The attachment's job - **`id`** _(string)_ Unique identifier of the job - **`attachment_type`** _(string)_ The attachment's type - **`created_at`** _(string)_ The date and time of the attachment's creation - **`updated_at`** _(string)_ The date and time of the attachment's last update - **`created_at`** _(string)_ The date and time of the phone number's creation - **`updated_at`** _(string)_ The date and time of the phone number's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/candidates](/api-reference/unified-ats-api/candidates/list) — List Candidates - [POST /unified/ats/candidates](/api-reference/unified-ats-api/candidates/create) — Create Candidates - [GET /unified/ats/candidates/{id}](/api-reference/unified-ats-api/candidates/get) — Get Candidates - [PATCH /unified/ats/candidates/{id}](/api-reference/unified-ats-api/candidates/update) — Update Candidates --- # Departments Object > Source: https://truto.one/docs/api-reference/unified-ats-api/departments/ Schema for the `Departments` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The department's unique identifier - **`name`** _(string)_ The department's name - **`parent`** _(object)_ - **`id`** _(string)_ The department's unique identifier - **`name`** _(string)_ The department's name - **`status`** _(string)_ The department's status Allowed: `active`, `inactive` - **`created_at`** _(string)_ The date and time of the department's creation - **`updated_at`** _(string)_ The date and time of the department's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/departments](/api-reference/unified-ats-api/departments/list) — List Departments - [GET /unified/ats/departments/{id}](/api-reference/unified-ats-api/departments/get) — Get Departments --- # Eeocs Object > Source: https://truto.one/docs/api-reference/unified-ats-api/eeocs/ Schema for the `Eeocs` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The eecoc's unique identifier - **`candidate`** _(object)_ The eecoc's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`submitted_at`** _(string)_ The eecoc's submitted_at date - **`race`** _(string)_ The candidate's race - **`gender`** _(string)_ The candidate's gender - **`veteran_status`** _(string)_ The candidate's veteran status - **`disability_status`** _(string)_ The candidate's disability status - **`created_at`** _(string)_ The date and time of the eecoc's creation - **`updated_at`** _(string)_ The date and time of the eecoc's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/eeocs](/api-reference/unified-ats-api/eeocs/list) — List Eeocs - [GET /unified/ats/eeocs/{id}](/api-reference/unified-ats-api/eeocs/get) — Get Eeocs --- # Interviews Object > Source: https://truto.one/docs/api-reference/unified-ats-api/interviews/ Schema for the `Interviews` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The interview's unique identifier - **`application`** _(object)_ The interview's application - **`id`** _(string)_ Unique identifier of the application - **`candidate`** _(object)_ The interview's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`job_interview_stage`** _(object)_ The interview's job interview stage - **`id`** _(string)_ Unique identifier of the job_interview_stage - **`organizer`** _(object)_ The interview's organizer - **`id`** _(string)_ Unique identifier of the user - **`interviewers`** _(array)_ The interview's interviewers - **`id`** _(string)_ Unique identifier of the user - **`location`** _(string)_ The interview's location - **`start_at`** _(string)_ The interview's start date - **`end_at`** _(string)_ The interview's end date - **`status`** _(string)_ The interview's status Allowed: `draft`, `scheduled`, `cancelled`, `awaiting_feedback`, `completed` - **`created_at`** _(string)_ The date and time of the interview's creation - **`updated_at`** _(string)_ The date and time of the interview's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/interviews](/api-reference/unified-ats-api/interviews/list) — List Interviews - [GET /unified/ats/interviews/{id}](/api-reference/unified-ats-api/interviews/get) — Get Interviews --- # JobInterviewStages Object > Source: https://truto.one/docs/api-reference/unified-ats-api/jobinterviewstages/ Schema for the `JobInterviewStages` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The job interview stage's unique identifier - **`name`** _(string)_ The job interview stage's name - **`status`** _(string)_ The job interview stage's status Allowed: `active`, `inactive` - **`job`** _(object)_ The job interview stage's job - **`id`** _(string)_ Unique identifier of the job - **`position`** _(integer)_ The job interview stage's position - **`created_at`** _(string)_ The date and time of the job interview stage's creation - **`updated_at`** _(string)_ The date and time of the job interview stage's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/job_interview_stages](/api-reference/unified-ats-api/jobinterviewstages/list) — List Job interview stages - [GET /unified/ats/job_interview_stages/{id}](/api-reference/unified-ats-api/jobinterviewstages/get) — Get Job interview stages --- # Jobs Object > Source: https://truto.one/docs/api-reference/unified-ats-api/jobs/ Schema for the `Jobs` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The job's unique identifier - **`name`** _(string)_ The job's name - **`description`** _(string)_ The job's description - **`code`** _(string)_ The job's code - **`requisition_id`** _(string)_ The job's requisition_id - **`status`** _(string)_ The job's status Allowed: `open`, `closed`, `draft`, `pending`, `archived` - **`locations`** _(array)_ The job's locations - **`job_posting_urls`** _(array)_ The job's job posting urls - **`url`** _(string)_ The job posting URL - **`type`** _(string)_ The job posting URL's type - **`confidential`** _(boolean)_ Whether the job is confidential or not - **`departments`** _(array)_ The job's department - **`id`** _(string)_ Unique identifier of the department - **`name`** _(string)_ The department's name - **`teams`** _(array)_ - **`offices`** _(array)_ The job's office - **`id`** _(string)_ Unique identifier of the office - **`name`** _(string)_ The office's name - **`hiring_managers`** _(array)_ The job's hiring managers - **`id`** _(string)_ Unique identifier of the user - **`name`** _(string)_ The user's name - **`recruiters`** _(array)_ The job's recruiters - **`id`** _(string)_ Unique identifier of the user - **`name`** _(string)_ The user's name - **`tags`** _(array)_ The job's tags - **`is_remote`** _(boolean)_ Whether the job is remote or not - **`job_type`** _(string)_ The job's type. Allowed: `full_time`, `part_time`, `contract`, `internship`, `temporary`, `volunteer`, `per_diem` - **`job_position_level`** _(string)_ The job's position level. - **`compensation`** _(object)_ - **`id`** _(string)_ The job's compensation unique identifier - **`currency`** _(string)_ The job's compensation currency - **`min`** _(number)_ The job's minimum compensation - **`max`** _(number)_ The job's maximum compensation - **`interval`** _(string)_ The job's compensation interval. If no clear mapping exists, then raw value is returned. Allowed: `yearly`, `monthly`, `weekly`, `daily`, `hourly`, `one_time`, `semi_monthly`, `bi_monthly`, `bi_weekly` - **`is_negotiable`** _(boolean)_ Whether the job's compensation is negotiable or not - **`notes`** _(string)_ The job's compensation notes - **`created_at`** _(string)_ The date and time of the job's creation - **`updated_at`** _(string)_ The date and time of the job's last update - **`closed_at`** _(string)_ The date and time of the job's closing - **`opened_at`** _(string)_ The date and time of the job's opening - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/jobs](/api-reference/unified-ats-api/jobs/list) — List Jobs - [POST /unified/ats/jobs](/api-reference/unified-ats-api/jobs/create) — Create Jobs - [GET /unified/ats/jobs/{id}](/api-reference/unified-ats-api/jobs/get) — Get Jobs - [PATCH /unified/ats/jobs/{id}](/api-reference/unified-ats-api/jobs/update) — Update Jobs --- # JobFormFields Object > Source: https://truto.one/docs/api-reference/unified-ats-api/jobformfields/ Schema for the `JobFormFields` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The form field's unique identifier - **`name`** _(string)_ The form field's name. Use this when submitting the application. - **`job`** _(object)_ The form field's job - **`id`** _(string)_ Unique identifier of the job - **`label`** _(string)_ The form field's label. - **`index`** _(integer)_ The form field's position inside a form. If `group_id` is present, the index is relative to the group. - **`is_required`** _(boolean)_ Whether the form field is required or not. - **`answer_visibility`** _(string)_ The form field's answer visibility inside the ATS. Allowed: `private`, `public` - **`description`** _(string)_ The form field's description. - **`type`** _(string)_ The form field's type. If no clear mapping exists, then raw value is returned. Allowed: `text`, `textarea`, `dropdown`, `file`, `radio`, `checkbox`, `date`, `number` - **`options`** _(array)_ The form field's options. Only present for dropdown, radio and checkbox types. - **`id`** _(string)_ The option's unique identifier - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`group_id`** _(string)_ The form field's group identifier. If present, the form field is part of a group. - **`group_name`** _(string)_ The form field's group name or label. If present, the form field is part of a group. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/job_form_fields](/api-reference/unified-ats-api/jobformfields/list) — List Job form fields --- # Offers Object > Source: https://truto.one/docs/api-reference/unified-ats-api/offers/ Schema for the `Offers` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The offer's unique identifier - **`application`** _(object)_ The offer's application - **`id`** _(string)_ Unique identifier of the application - **`candidate`** _(object)_ The offer's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`job`** _(object)_ The offer's job - **`id`** _(string)_ Unique identifier of the job - **`creator`** _(object)_ The offer's creator - **`id`** _(string)_ Unique identifier of the user - **`closed_at`** _(string)_ The offer's closed date - **`sent_at`** _(string)_ The offer's sent date - **`start_date`** _(string)_ The offer's start date - **`status`** _(string)_ The offer's status Allowed: `draft`, `approval_sent`, `approved`, `sent`, `sent_manually`, `opened`, `denied`, `signed`, `deprecated` - **`created_at`** _(string)_ The date and time of the offer's creation - **`updated_at`** _(string)_ The date and time of the offer's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/offers](/api-reference/unified-ats-api/offers/list) — List Offers --- # Offices Object > Source: https://truto.one/docs/api-reference/unified-ats-api/offices/ Schema for the `Offices` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The office's unique identifier - **`name`** _(string)_ The office's name - **`parent`** _(object)_ The office's parent - **`id`** _(string)_ Unique identifier of the office - **`location`** _(string)_ The office's location - **`is_remote`** _(boolean)_ Whether the office is remote or not - **`created_at`** _(string)_ The date and time of the office's creation - **`updated_at`** _(string)_ The date and time of the office's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/offices](/api-reference/unified-ats-api/offices/list) — List Offices - [GET /unified/ats/offices/{id}](/api-reference/unified-ats-api/offices/get) — Get Offices --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-ats-api/organizations/ Schema for the `Organizations` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`created_at`** _(string)_ Date and time when the organization was created. - **`updated_at`** _(string)_ Date and time when the organization was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/organizations](/api-reference/unified-ats-api/organizations/list) — List Organizations - [GET /unified/ats/organizations/{id}](/api-reference/unified-ats-api/organizations/get) — Get Organizations --- # RejectReasons Object > Source: https://truto.one/docs/api-reference/unified-ats-api/rejectreasons/ Schema for the `RejectReasons` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The reject reason's unique identifier - **`name`** _(string)_ The reject reason's name - **`created_at`** _(string)_ The date and time of the reject reason's creation - **`updated_at`** _(string)_ The date and time of the reject reason's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/reject_reasons](/api-reference/unified-ats-api/rejectreasons/list) — List Reject reasons --- # Scorecards Object > Source: https://truto.one/docs/api-reference/unified-ats-api/scorecards/ Schema for the `Scorecards` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The scorecard's unique identifier - **`application`** _(object)_ The scorecard's application - **`id`** _(string)_ Unique identifier of the application - **`candidate`** _(object)_ The scorecard's candidate - **`id`** _(string)_ Unique identifier of the candidate - **`interview`** _(object)_ The scorecard's interview - **`id`** _(string)_ Unique identifier of the interview - **`interviewer`** _(object)_ The scorecard's interviewer - **`id`** _(string)_ Unique identifier of the user - **`submitted_at`** _(string)_ The scorecard's submitted date - **`overall_recommendation`** _(string)_ The scorecard's overall recommendation - **`form_values`** _(array)_ The scorecard's form values - **`name`** _(string)_ The form field's name - **`label`** _(string)_ The form field's label - **`description`** _(string)_ The form field's description - **`value`** _(string)_ The form field's value - **`created_at`** _(string)_ The date and time of the scorecard's creation - **`updated_at`** _(string)_ The date and time of the scorecard's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/scorecards](/api-reference/unified-ats-api/scorecards/list) — List Scorecards --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-ats-api/tags/ Schema for the `Tags` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`created_at`** _(string)_ The date and time of the tag's creation - **`updated_at`** _(string)_ The date and time of the tag's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/tags](/api-reference/unified-ats-api/tags/list) — List Tags --- # Users Object > Source: https://truto.one/docs/api-reference/unified-ats-api/users/ Schema for the `Users` resource in **Unified ATS API**. ## Properties - **`id`** _(string, required)_ The user's unique identifier - **`first_name`** _(string)_ The user's first name - **`last_name`** _(string)_ The user's last name - **`name`** _(string)_ The user's full name - **`emails`** _(array)_ - **`email`** _(string)_ Email of the user - **`type`** _(string)_ Type of the email - **`is_primary`** _(boolean)_ Whether the email is primary - **`disabled`** _(boolean)_ The user's disabled status - **`access_role`** _(string)_ The user's access role - **`created_at`** _(string)_ The date and time of the user's creation - **`updated_at`** _(string)_ The date and time of the user's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ats/users](/api-reference/unified-ats-api/users/list) — List Users - [GET /unified/ats/users/{id}](/api-reference/unified-ats-api/users/get) — Get Users --- # Unified Calendar API > Source: https://truto.one/docs/api-reference/unified-calendar-api/ Base URL: `https://api.truto.one/unified/calendar` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Attachments](/api-reference/unified-calendar-api/attachments) - [GET /unified/calendar/attachments](/api-reference/unified-calendar-api/attachments/list) — List Attachments - [Calendars](/api-reference/unified-calendar-api/calendars) - [GET /unified/calendar/calendars](/api-reference/unified-calendar-api/calendars/list) — List Calendars - [POST /unified/calendar/calendars](/api-reference/unified-calendar-api/calendars/create) — Create Calendars - [GET /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/get) — Get Calendars - [PATCH /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/update) — Update Calendars - [DELETE /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/delete) — Delete Calendars - [Events](/api-reference/unified-calendar-api/events) - [GET /unified/calendar/events](/api-reference/unified-calendar-api/events/list) — List Events - [POST /unified/calendar/events](/api-reference/unified-calendar-api/events/create) — Create Events - [GET /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/get) — Get Events - [DELETE /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/delete) — Delete Events - [PATCH /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/update) — Update Events - [Availability](/api-reference/unified-calendar-api/availability) - [GET /unified/calendar/availability](/api-reference/unified-calendar-api/availability/list) — List Availability - [EventTypes](/api-reference/unified-calendar-api/eventtypes) - [GET /unified/calendar/event_types](/api-reference/unified-calendar-api/eventtypes/list) — List Event types - [GET /unified/calendar/event_types/{id}](/api-reference/unified-calendar-api/eventtypes/get) — Get Event types - [Contacts](/api-reference/unified-calendar-api/contacts) - [GET /unified/calendar/contacts](/api-reference/unified-calendar-api/contacts/list) — List Contacts - [Users](/api-reference/unified-calendar-api/users) - [GET /unified/calendar/users](/api-reference/unified-calendar-api/users/list) — List Users - [GET /unified/calendar/users/{id}](/api-reference/unified-calendar-api/users/get) — Get Users --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/attachments/ Schema for the `Attachments` resource in **Unified Calendar API**. ## Properties - **`id`** _(string)_ The unique identifier of the attachment. - **`name`** _(string)_ The name of the attachment. - **`event`** _(object)_ The event associated with the attachment. - **`id`** _(string)_ The unique identifier of the event. - **`title`** _(string)_ The title of the event. - **`mime_type`** _(string)_ The MIME type of the attachment. - **`url`** _(string)_ The URL of the attachment. - **`created_at`** _(string)_ The date when the attachment was created. - **`updated_at`** _(string)_ The date when the attachment was updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/attachments](/api-reference/unified-calendar-api/attachments/list) — List Attachments --- # Calendars Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/calendars/ Schema for the `Calendars` resource in **Unified Calendar API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the calendar. - **`name`** _(string)_ The name of the calendar. - **`description`** _(string)_ The description of the calendar. - **`location`** _(object)_ The location of the calendar. - **`id`** _(string)_ The unique identifier of the location. - **`name`** _(string)_ The name of the location. - **`status`** _(string)_ The status of the calendar. Allowed: `active`, `inactive` - **`visibility`** _(string)_ The visibility of the calendar. Allowed: `public`, `private` - **`is_default`** _(boolean)_ Indicates if the calendar is the default calendar of the user. - **`timezone`** _(string)_ The timezone of the calendar. - **`access_role`** _(object)_ The access role on the calendar for the authenticated user. - **`id`** _(string)_ The unique identifier of the access role. - **`name`** _(string)_ The name of the access role. Allowed: `owner`, `reader`, `writer`, `freebusy` - **`colors`** _(object)_ The colors associated with the calendar. - **`background`** _(string)_ The background color of the calendar. - **`foreground`** _(string)_ The foreground color of the calendar. - **`created_at`** _(string)_ The date when the calendar was created. - **`updated_at`** _(string)_ The date when the calendar was updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/calendars](/api-reference/unified-calendar-api/calendars/list) — List Calendars - [POST /unified/calendar/calendars](/api-reference/unified-calendar-api/calendars/create) — Create Calendars - [GET /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/get) — Get Calendars - [PATCH /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/update) — Update Calendars - [DELETE /unified/calendar/calendars/{id}](/api-reference/unified-calendar-api/calendars/delete) — Delete Calendars --- # Events Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/events/ Schema for the `Events` resource in **Unified Calendar API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the event. - **`calendar`** _(object)_ The calendar associated with the event. - **`id`** _(string)_ The unique identifier of the calendar. - **`name`** _(string)_ The name of the calendar. - **`title`** _(string, required)_ The title of the event. - **`description`** _(string)_ The description of the event. - **`location`** _(object)_ The location of the event. - **`id`** _(string)_ The unique identifier of the location. - **`name`** _(string)_ The name of the location. - **`address`** _(object)_ - **`street_1`** _(string)_ The first line of the street address. - **`street_2`** _(string)_ The second line of the street address. - **`city`** _(string)_ The city of the address. - **`state`** _(string)_ The state of the address. - **`country`** _(string)_ The country of the address. - **`postal_code`** _(string)_ The postal code of the address. - **`url`** _(string)_ The URL of the location. - **`coordinates`** _(object)_ - **`latitude`** _(number)_ The latitude of the location. - **`longitude`** _(number)_ The longitude of the location. - **`timezone`** _(string)_ The timezone of the event. - **`start_time`** _(string, required)_ The date and time when the event starts. - **`end_time`** _(string)_ The date and time when the event ends. - **`status`** _(string)_ The status of the event. Allowed: `confirmed`, `tentative`, `cancelled`, `draft` - **`attendees`** _(array)_ The attendees associated with the event. - **`person`** _(object)_ The person associated with the attendee. - **`id`** _(string)_ The unique identifier of the person. - **`name`** _(string)_ The name of the person. - **`emails`** _(array)_ The emails of the person. - **`email`** _(string)_ The email of the person. - **`type`** _(string)_ The type of the email. - **`is_optional`** _(boolean)_ Indicates if the attendance is optional. - **`is_self`** _(boolean)_ Indicates if the attendee is the authenticated user. - **`is_organizer`** _(boolean)_ Indicates if the attendee is the organizer of the event. - **`response`** _(object)_ The response of the attendee. - **`status`** _(string)_ The status of the response. Allowed: `needs_action`, `declined`, `tentative`, `accepted` - **`comment`** _(string)_ The comment of the response. - **`created_by`** _(object)_ The person who created the event. - **`id`** _(string)_ The unique identifier of the person. - **`name`** _(string)_ The name of the person. - **`emails`** _(array)_ The emails of the person. - **`email`** _(string)_ The email of the person. - **`type`** _(string)_ The type of the email. - **`organized_by`** _(object)_ The person who created the event. - **`id`** _(string)_ The unique identifier of the person. - **`name`** _(string)_ The name of the person. - **`emails`** _(array)_ The emails of the person. - **`email`** _(string)_ The email of the person. - **`type`** _(string)_ The type of the email. - **`type`** _(string)_ The type of the event. Allowed: `default`, `out_of_office`, `focus_time`, `working_location` - **`availability`** _(string)_ The availability of the user during the time period of the event. Allowed: `busy`, `free` - **`visibility`** _(string)_ The visibility of the event. Allowed: `calendar_default`, `public`, `private` - **`identifiers`** _(object)_ The identifiers associated with the event. - **`ical_uid`** _(string)_ The iCalendar UID of the event. - **`ical_sequence`** _(string)_ The iCalendar sequence of the event. - **`is_locked`** _(boolean)_ Indicates if the event is locked and cannot be modified. - **`urls`** _(object)_ The URLs associated with the event. - **`url`** _(string)_ The URL of the event. - **`type`** _(string)_ The type of the URL. - **`is_recurring`** _(boolean)_ Indicates if the event is recurring. - **`recurrence`** _(array)_ The recurrence of the event. List of RRULE, EXRULE, RDATE and EXDATE lines for a recurring event, as specified in RFC5545. - **`parent_event`** _(object)_ The parent event of a recurring event. - **`id`** _(string)_ The unique identifier of the parent event. - **`has_attachments`** _(boolean)_ Indicates if the event has attachments. - **`attachments`** _(array)_ The attachments associated with the event. - **`id`** _(string)_ The unique identifier of the attachment. - **`name`** _(string)_ The name of the attachment. - **`mime_type`** _(string)_ The MIME type of the attachment. - **`url`** _(string)_ The URL of the attachment. - **`created_at`** _(string)_ The date when the attachment was created. - **`updated_at`** _(string)_ The date when the attachment was updated. - **`guests_can_invite_others`** _(boolean)_ Indicates if guests can invite others to the event. - **`guests_can_modify`** _(boolean)_ Indicates if guests can modify the event. - **`guests_can_see_other_guests`** _(boolean)_ Indicates if guests can see other guests of the event. - **`event_type`** _(object)_ The event type object associated with the event. - **`id`** _(string)_ The unique identifier of the event type. - **`created_at`** _(string)_ The date when the event was created. - **`updated_at`** _(string)_ The date when the event was updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/events](/api-reference/unified-calendar-api/events/list) — List Events - [POST /unified/calendar/events](/api-reference/unified-calendar-api/events/create) — Create Events - [GET /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/get) — Get Events - [DELETE /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/delete) — Delete Events - [PATCH /unified/calendar/events/{id}](/api-reference/unified-calendar-api/events/update) — Update Events --- # Availability Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/availability/ Schema for the `Availability` resource in **Unified Calendar API**. ## Properties - **`calendar`** _(object)_ The calendar associated with the availability. - **`id`** _(string)_ The unique identifier of the calendar. - **`name`** _(string)_ The name of the calendar. - **`email`** _(string)_ The email of the person associated with the availability. - **`start_time`** _(string, required)_ The start date and time of the availability slot. - **`end_time`** _(string, required)_ The end date and time of the availability slot. - **`timezone`** _(string)_ The timezone of the availability slot. - **`availability`** _(string)_ The availability of the user during the time period of the availability slot. Allowed: `busy`, `free` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/availability](/api-reference/unified-calendar-api/availability/list) — List Availability --- # EventTypes Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/eventtypes/ Schema for the `EventTypes` resource in **Unified Calendar API**. ## Properties - **`id`** _(string, required)_ Unique identifier of the Event Type - **`name`** _(string)_ Slug or unique readable name of the Event Type - **`label`** _(string)_ Human readable name of the Event Type - **`status`** _(string)_ Status of the Event Type Allowed: `active`, `archived` - **`urls`** _(array)_ URLs associated with the Event Type - **`url`** _(string)_ - **`type`** _(string)_ The type of the URL Allowed: `scheduling` - **`color`** _(string)_ The color associated with this Event Type - **`duration`** _(number)_ The length of the Event scheduled using this Event Type in minutes - **`description`** _(string)_ The description of the Event Type - **`allow_scheduling`** _(boolean)_ Whether scheduling an Event is allowed using this Event Type - **`position`** _(number)_ The position of the Event Type on a listing page - **`form_fields`** _(array)_ Form fields associated with the Event Type - **`label`** _(string)_ Label used for the field - **`type`** _(string)_ The type of the form field Allowed: `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` - **`is_enabled`** _(boolean)_ Is the form field enabled? - **`is_required`** _(boolean)_ Is the form field required to be answered? - **`position`** _(number)_ Order of the field in the form - **`options`** _(array)_ The choices to be selected in case of multi-choice fields - **`label`** _(string)_ Human readable name for the choice - **`value`** _(string)_ The value for the choice - **`locations`** _(array)_ The location choices associated with the Event Type - **`id`** _(string)_ The unique identifier of the location. - **`name`** _(string)_ The name of the location. - **`address`** _(object)_ - **`street_1`** _(string)_ The first line of the street address. - **`street_2`** _(string)_ The second line of the street address. - **`city`** _(string)_ The city of the address. - **`state`** _(string)_ The state of the address. - **`country`** _(string)_ The country of the address. - **`postal_code`** _(string)_ The postal code of the address. - **`url`** _(string)_ The URL of the location. - **`coordinates`** _(object)_ - **`latitude`** _(number)_ The latitude of the location. - **`longitude`** _(number)_ The longitude of the location. - **`created_at`** _(string)_ The date and time at which this Event Type was created - **`updated_at`** _(string)_ The date and time at which this Event Type was last modified - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/event_types](/api-reference/unified-calendar-api/eventtypes/list) — List Event types - [GET /unified/calendar/event_types/{id}](/api-reference/unified-calendar-api/eventtypes/get) — Get Event types --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/contacts/ Schema for the `Contacts` resource in **Unified Calendar API**. ## Properties - **`id`** _(string, required)_ The contact's unique identifier - **`first_name`** _(string)_ The contact's first name - **`middle_name`** _(string)_ The contact's middle name - **`last_name`** _(string)_ The contact's last name - **`name`** _(string)_ The contact's full name - **`title`** _(string)_ The contact's job title - **`addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the address - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`email_addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the email addresses - **`email`** _(string)_ The email address - **`type`** _(string)_ The email address type - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`last_activity_at`** _(string)_ The date and time of the contact's last activity - **`created_at`** _(string)_ The date and time of the contact's creation - **`updated_at`** _(string)_ The date and time of the contact's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/contacts](/api-reference/unified-calendar-api/contacts/list) — List Contacts --- # Users Object > Source: https://truto.one/docs/api-reference/unified-calendar-api/users/ Schema for the `Users` resource in **Unified Calendar API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`external_id`** _(string)_ The external identifier for a user. This is set when the SCIM API is being used. - **`identifiers`** _(object)_ The identifiers of the user. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`title`** _(string)_ The title of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`group`** _(string)_ The role of the user in the group. This is available when the user can have different roles in different groups or teams in an application. - **`organization`** _(string)_ The role of the user in the organization. This is available when the user can have different roles in different organizations in an application. - **`workspace`** _(string)_ The role of the user in the workspace. This is available when the user can have different roles in different workspaces in an application. - **`user_type`** _(string)_ The type of user - **`licenses`** _(array)_ The licenses of the user or the products the user has access to - **`id`** _(string)_ The unique identifier for a license - **`name`** _(string)_ The name of the license - **`organization`** _(string)_ The unique identifier of the organization to which the license belongs - **`last_active_at`** _(string)_ The date and time the user was last active for the license - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`avatar`** _(string)_ The avatar of the user - **`timezone`** _(string)_ The timezone of the user - **`languages`** _(array)_ The languages preferred by the user - **`bio`** _(string)_ The bio of the user. Usually a short description set by the user about them. - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`urls`** _(array)_ The URLs of the user - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/calendar/users](/api-reference/unified-calendar-api/users/list) — List Users - [GET /unified/calendar/users/{id}](/api-reference/unified-calendar-api/users/get) — Get Users --- # Unified CI/CD API > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/ Base URL: `https://api.truto.one/unified/ci-cd` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Repos](/api-reference/unified-ci-cd-api/repos) - [GET /unified/ci-cd/repos](/api-reference/unified-ci-cd-api/repos/list) — List Repos - [GET /unified/ci-cd/repos/{id}](/api-reference/unified-ci-cd-api/repos/get) — Get Repos - [Branches](/api-reference/unified-ci-cd-api/branches) - [GET /unified/ci-cd/branches](/api-reference/unified-ci-cd-api/branches/list) — List Branches - [GET /unified/ci-cd/branches/{id}](/api-reference/unified-ci-cd-api/branches/get) — Get Branches - [PullRequests](/api-reference/unified-ci-cd-api/pullrequests) - [GET /unified/ci-cd/pull-requests/{id}](/api-reference/unified-ci-cd-api/pullrequests/get) — Get Pull requests - [GET /unified/ci-cd/pull-requests](/api-reference/unified-ci-cd-api/pullrequests/list) — List Pull requests - [Builds](/api-reference/unified-ci-cd-api/builds) - [GET /unified/ci-cd/builds](/api-reference/unified-ci-cd-api/builds/list) — List Builds - [GET /unified/ci-cd/builds/{id}](/api-reference/unified-ci-cd-api/builds/get) — Get Builds - [Jobs](/api-reference/unified-ci-cd-api/jobs) - [GET /unified/ci-cd/jobs](/api-reference/unified-ci-cd-api/jobs/list) — List Jobs - [GET /unified/ci-cd/jobs/{id}](/api-reference/unified-ci-cd-api/jobs/get) — Get Jobs - [Artifacts](/api-reference/unified-ci-cd-api/artifacts) - [GET /unified/ci-cd/artifacts](/api-reference/unified-ci-cd-api/artifacts/list) — List Artifacts - [GET /unified/ci-cd/artifacts/{id}](/api-reference/unified-ci-cd-api/artifacts/get) — Get Artifacts - [Caches](/api-reference/unified-ci-cd-api/caches) - [GET /unified/ci-cd/caches](/api-reference/unified-ci-cd-api/caches/list) — List Caches - [Workflow](/api-reference/unified-ci-cd-api/workflow) - [GET /unified/ci-cd/workflow](/api-reference/unified-ci-cd-api/workflow/list) — List Workflow - [GET /unified/ci-cd/workflow/{id}](/api-reference/unified-ci-cd-api/workflow/get) — Get Workflow - [Workspaces](/api-reference/unified-ci-cd-api/workspaces) - [GET /unified/ci-cd/workspaces](/api-reference/unified-ci-cd-api/workspaces/list) — List Workspaces - [GET /unified/ci-cd/workspaces/{id}](/api-reference/unified-ci-cd-api/workspaces/get) — Get Workspaces - [Organizations](/api-reference/unified-ci-cd-api/organizations) - [GET /unified/ci-cd/organizations](/api-reference/unified-ci-cd-api/organizations/list) — List Organizations - [BranchProtectionRules](/api-reference/unified-ci-cd-api/branchprotectionrules) - [GET /unified/ci-cd/branch-protection-rules](/api-reference/unified-ci-cd-api/branchprotectionrules/list) — List Branch protection rules - [Comments](/api-reference/unified-ci-cd-api/comments) - [GET /unified/ci-cd/comments](/api-reference/unified-ci-cd-api/comments/list) — List Comments - [Reviews](/api-reference/unified-ci-cd-api/reviews) - [GET /unified/ci-cd/reviews](/api-reference/unified-ci-cd-api/reviews/list) — List Reviews --- # Repos Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/repos/ Schema for the `Repos` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the repository - **`name`** _(string)_ The name of the repository - **`description`** _(string)_ The description of the repository - **`owner`** _(string)_ The owner of the repository - **`owner_type`** _(string)_ The type of the owner of the repository Allowed: `user`, `org` - **`visibility`** _(string)_ The visibility of the repository Allowed: `public`, `private`, `internal` - **`vcs_url`** _(string)_ The VCS URL of the repository - **`status`** _(string)_ The status of the repository Allowed: `active`, `inactive` - **`default_branch`** _(string)_ The default branch of the repository - **`created_at`** _(string)_ The date and time when the repository was created - **`updated_at`** _(string)_ The date and time when the repository was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/repos](/api-reference/unified-ci-cd-api/repos/list) — List Repos - [GET /unified/ci-cd/repos/{id}](/api-reference/unified-ci-cd-api/repos/get) — Get Repos --- # Branches Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/branches/ Schema for the `Branches` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the branch - **`name`** _(string, required)_ Name of the branch - **`repo`** _(string)_ The repository of the branch - **`last_commit`** _(string)_ The last commit of the branch - **`last_commit_by`** _(string)_ The last commit author of the branch - **`last_commit_message`** _(string)_ The last commit message of the branch - **`last_commit_at`** _(string)_ The date and time when the last commit was made - **`created_at`** _(string)_ The date and time when the branch was created - **`updated_at`** _(string)_ The date and time when the branch was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/branches](/api-reference/unified-ci-cd-api/branches/list) — List Branches - [GET /unified/ci-cd/branches/{id}](/api-reference/unified-ci-cd-api/branches/get) — Get Branches --- # PullRequests Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/pullrequests/ Schema for the `PullRequests` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the pull request - **`title`** _(string)_ The title of the pull request - **`number`** _(integer)_ The number of the pull request - **`description`** _(object)_ The description of the pull request - **`content`** _(string)_ The content of the body - **`format`** _(string)_ The format of the body Allowed: `markdown`, `html`, `plaintext` - **`status`** _(string)_ The status of the pull request Allowed: `open`, `closed`, `merged`, `locked` - **`base_branch`** _(object)_ The base branch of the pull request - **`id`** _(string)_ The unique identifier for the base branch - **`name`** _(string)_ The name of the base branch - **`last_commit`** _(string)_ The last commit of the base branch - **`head_branch`** _(object)_ The head branch of the pull request - **`id`** _(string)_ The unique identifier for the head branch - **`name`** _(string)_ The name of the head branch - **`last_commit`** _(string)_ The last commit of the head branch - **`author`** _(object)_ The author of the pull request - **`id`** _(string)_ The unique identifier for the author - **`username`** _(string)_ The username of the author - **`type`** _(string)_ The type of the author Allowed: `user`, `bot` - **`closed_at`** _(string)_ The date and time when the pull request was closed - **`merged_at`** _(string)_ The date and time when the pull request was merged - **`created_at`** _(string)_ The date and time when the pull request was created - **`updated_at`** _(string)_ The date and time when the pull request was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/pull-requests/{id}](/api-reference/unified-ci-cd-api/pullrequests/get) — Get Pull requests - [GET /unified/ci-cd/pull-requests](/api-reference/unified-ci-cd-api/pullrequests/list) — List Pull requests --- # Builds Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/builds/ Schema for the `Builds` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the build - **`name`** _(string)_ The name of the build - **`repo`** _(string)_ The repository of the build - **`branch`** _(string)_ The head branch of the build - **`commit`** _(string)_ The head commit of the build - **`trigger`** _(string)_ The trigger for the build - push, merge_request, api, cron, web or the raw response from the API - **`triggered_by`** _(string)_ The actor who triggered the build - **`triggered_by_type`** _(string)_ The type of the actor who triggered the build - user, bot or raw response from the API - **`conclusion`** _(string)_ The conclusion of the build - passed, failed, cancelled, timeout, skipped, retried, partial or the raw response from the API - **`workflow`** _(string)_ The workflow's unique identifier in the CI/CD - **`build`** _(string)_ The build's unique identifier in the CI/CD - **`status`** _(string)_ The status of the build - queued, in_progress, completed or the raw response from the API - **`created_at`** _(string)_ The date and time when the build was created - **`updated_at`** _(string)_ The date and time when the build was last updated - **`started_at`** _(string)_ The date and time when the build started - **`completed_at`** _(string)_ The date and time when the build finished - **`attempts`** _(integer)_ The number of attempts for the build - **`number`** _(integer)_ The run number of the build - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/builds](/api-reference/unified-ci-cd-api/builds/list) — List Builds - [GET /unified/ci-cd/builds/{id}](/api-reference/unified-ci-cd-api/builds/get) — Get Builds --- # Jobs Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/jobs/ Schema for the `Jobs` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the job - **`name`** _(string)_ The name of the job - **`build`** _(string)_ The build of the job - **`status`** _(string)_ The status of the job - queued, in_progress, completed or the raw response from the API - **`conclusion`** _(string)_ The conclusion of the job - passed, failed, cancelled, timeout, skipped, retried, partial or the raw response from the API - **`commit`** _(string)_ The commit of the job - **`branch`** _(string)_ The head branch of the job - **`attempts`** _(integer)_ The number of attempts for the job - **`created_at`** _(string)_ The date and time when the job was created - **`updated_at`** _(string)_ The date and time when the job was last updated - **`started_at`** _(string)_ The date and time when the job started - **`completed_at`** _(string)_ The date and time when the job completed - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/jobs](/api-reference/unified-ci-cd-api/jobs/list) — List Jobs - [GET /unified/ci-cd/jobs/{id}](/api-reference/unified-ci-cd-api/jobs/get) — Get Jobs --- # Artifacts Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/artifacts/ Schema for the `Artifacts` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the artifact - **`name`** _(string)_ The name of the artifact - **`workflow`** _(string)_ The workflow that the artifact belongs to - **`build`** _(string)_ The build that the artifact belongs to - **`size_in_bytes`** _(integer)_ The size of the artifact in bytes - **`download_url`** _(string)_ The URL to download the artifact - **`created_at`** _(string)_ The date and time when the artifact was created - **`updated_at`** _(string)_ The date and time when the artifact was last updated - **`expires_at`** _(string)_ The date and time when the artifact will expire - **`expired`** _(boolean)_ Whether the artifact is available for download - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/artifacts](/api-reference/unified-ci-cd-api/artifacts/list) — List Artifacts - [GET /unified/ci-cd/artifacts/{id}](/api-reference/unified-ci-cd-api/artifacts/get) — Get Artifacts --- # Caches Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/caches/ Schema for the `Caches` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the cache - **`branch`** _(string)_ The branch for the cache - **`key`** _(string)_ The key for the cache - **`version`** _(string)_ The version of the cache - **`created_at`** _(string)_ The date and time when the cache was created - **`updated_at`** _(string)_ The date and time when the cache was last updated - **`last_used_at`** _(string)_ The date and time when the cache was last used - **`size_in_bytes`** _(integer)_ The size of the cache in bytes - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/caches](/api-reference/unified-ci-cd-api/caches/list) — List Caches --- # Workflow Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/workflow/ Schema for the `Workflow` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the workflow - **`name`** _(string)_ The name of the workflow - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/workflow](/api-reference/unified-ci-cd-api/workflow/list) — List Workflow - [GET /unified/ci-cd/workflow/{id}](/api-reference/unified-ci-cd-api/workflow/get) — Get Workflow --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/workspaces/ Schema for the `Workspaces` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string)_ The ID of the workspace - **`name`** _(string)_ The name of the workspace - **`created_at`** _(string)_ The date and time the workspace was created - **`updated_at`** _(string)_ The date and time the workspace was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/workspaces](/api-reference/unified-ci-cd-api/workspaces/list) — List Workspaces - [GET /unified/ci-cd/workspaces/{id}](/api-reference/unified-ci-cd-api/workspaces/get) — Get Workspaces --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/organizations/ Schema for the `Organizations` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string)_ The ID of the organization - **`name`** _(string)_ The name of the organization - **`created_at`** _(string)_ The date and time the organization was created - **`updated_at`** _(string)_ The date and time the organization was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/organizations](/api-reference/unified-ci-cd-api/organizations/list) — List Organizations --- # BranchProtectionRules Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/branchprotectionrules/ Schema for the `BranchProtectionRules` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the protection rule - **`name`** _(string)_ The name or description of the protection rule - **`repos`** _(array, required)_ The repositories this rule applies to - **`id`** _(string)_ - **`pattern`** _(string, required)_ The branch/ref pattern this rule applies to - **`is_active`** _(boolean)_ Whether this protection rule is currently active - **`require_owner_approval`** _(boolean)_ Require approval from designated owners - **`required_checks`** _(array)_ List of required validations/checks - **`name`** _(string)_ - **`context`** _(string)_ - **`require_up_to_date`** _(boolean)_ - **`access_restrictions`** _(object)_ Restrictions on who can write to the branch - **`is_active`** _(boolean)_ Whether write restrictions are active - **`allowed_users`** _(array)_ List of user IDs allowed to write - **`id`** _(string)_ - **`allowed_groups`** _(array)_ List of group/team IDs allowed to write - **`id`** _(string)_ - **`allowed_roles`** _(array)_ List of role names allowed to write - **`id`** _(string)_ - **`integration_restrictions`** _(object)_ Restrictions on who can integrate/merge changes - **`is_active`** _(boolean)_ Whether integration restrictions are active - **`allowed_users`** _(array)_ List of user IDs allowed to integrate - **`id`** _(string)_ - **`allowed_groups`** _(array)_ List of group/team IDs allowed to integrate - **`id`** _(string)_ - **`allowed_roles`** _(array)_ List of role names allowed to integrate - **`id`** _(string)_ - **`allow_branch_deletion`** _(boolean)_ Allow the branch to be deleted - **`created_by`** _(object)_ User who created this protection rule - **`id`** _(string)_ - **`username`** _(string)_ - **`created_at`** _(string)_ When the rule was created - **`updated_at`** _(string)_ When the rule was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/branch-protection-rules](/api-reference/unified-ci-cd-api/branchprotectionrules/list) — List Branch protection rules --- # Comments Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/comments/ Schema for the `Comments` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the comment - **`pull_request`** _(object)_ The pull request that the comment belongs to - **`id`** _(string)_ The unique identifier for the pull request - **`number`** _(integer)_ The number of the pull request - **`body`** _(object)_ The body of the comment - **`content`** _(string)_ The content of the comment - **`format`** _(string)_ The format of the comment body Allowed: `markdown`, `html`, `plaintext` - **`author`** _(object)_ The author of the comment - **`id`** _(string)_ The unique identifier for the author - **`username`** _(string)_ The username of the author - **`type`** _(string)_ The type of the author Allowed: `user`, `bot` - **`type`** _(string)_ The type of the comment Allowed: `conversation_comment`, `review_comment` - **`parent`** _(object)_ The parent comment this is a reply to - **`id`** _(string)_ The unique identifier for the comment - **`path`** _(string)_ The file path the comment is associated with (for review comments) - **`line`** _(integer)_ The line number the comment is associated with (for review comments) - **`commit`** _(object)_ The commit the comment is associated with - **`id`** _(string)_ The SHA of the commit - **`created_at`** _(string)_ The date and time when the comment was created - **`updated_at`** _(string)_ The date and time when the comment was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/comments](/api-reference/unified-ci-cd-api/comments/list) — List Comments --- # Reviews Object > Source: https://truto.one/docs/api-reference/unified-ci-cd-api/reviews/ Schema for the `Reviews` resource in **Unified CI/CD API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the review - **`pull_request`** _(object)_ The pull request this review belongs to - **`id`** _(string)_ The unique identifier of the pull request - **`number`** _(integer)_ The number of the pull request - **`status`** _(string)_ The status of the review Allowed: `approved`, `suggested_changes`, `commented`, `dismissed`, `pending` - **`body`** _(object)_ The body of the review - **`content`** _(string)_ The content of the review body - **`format`** _(string)_ The format of the body Allowed: `markdown`, `html`, `plaintext` - **`author`** _(object)_ The author of the review - **`id`** _(string)_ The unique identifier for the author - **`username`** _(string)_ The username of the author - **`type`** _(string)_ The type of the author Allowed: `user`, `bot` - **`commit`** _(object)_ The commit that was reviewed - **`id`** _(string)_ The SHA of the commit - **`url`** _(string)_ The URL to view the commit in the browser - **`urls`** _(array)_ URLs associated with the review - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of the URL Allowed: `review`, `pull_request` - **`submitted_at`** _(string)_ The date and time when the review was submitted - **`created_at`** _(string)_ The date and time when the review was created - **`updated_at`** _(string)_ The date and time when the review was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ci-cd/reviews](/api-reference/unified-ci-cd-api/reviews/list) — List Reviews --- # Unified Cloud Infrastructure API > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/ Base URL: `https://api.truto.one/unified/cloud-infrastructure` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [PostureFindings](/api-reference/unified-cloud-infrastructure-api/posturefindings) - [GET /unified/cloud-infrastructure/posture_findings](/api-reference/unified-cloud-infrastructure-api/posturefindings/list) — List Posture findings - [SecurityProductStates](/api-reference/unified-cloud-infrastructure-api/securityproductstates) - [GET /unified/cloud-infrastructure/security_product_states](/api-reference/unified-cloud-infrastructure-api/securityproductstates/list) — List Security product states - [ThreatFindings](/api-reference/unified-cloud-infrastructure-api/threatfindings) - [GET /unified/cloud-infrastructure/threat_findings](/api-reference/unified-cloud-infrastructure-api/threatfindings/list) — List Threat findings - [HumanIdentities](/api-reference/unified-cloud-infrastructure-api/humanidentities) - [GET /unified/cloud-infrastructure/human_identities](/api-reference/unified-cloud-infrastructure-api/humanidentities/list) — List Human identities - [PasswordPolicies](/api-reference/unified-cloud-infrastructure-api/passwordpolicies) - [GET /unified/cloud-infrastructure/password_policies](/api-reference/unified-cloud-infrastructure-api/passwordpolicies/list) — List Password policies - [StaticCredentials](/api-reference/unified-cloud-infrastructure-api/staticcredentials) - [GET /unified/cloud-infrastructure/static_credentials](/api-reference/unified-cloud-infrastructure-api/staticcredentials/list) — List Static credentials - [AccessGrants](/api-reference/unified-cloud-infrastructure-api/accessgrants) - [GET /unified/cloud-infrastructure/access_grants](/api-reference/unified-cloud-infrastructure-api/accessgrants/list) — List Access grants - [PermissionDefinitions](/api-reference/unified-cloud-infrastructure-api/permissiondefinitions) - [GET /unified/cloud-infrastructure/permission_definitions](/api-reference/unified-cloud-infrastructure-api/permissiondefinitions/list) — List Permission definitions - [WorkloadIdentities](/api-reference/unified-cloud-infrastructure-api/workloadidentities) - [GET /unified/cloud-infrastructure/workload_identities](/api-reference/unified-cloud-infrastructure-api/workloadidentities/list) — List Workload identities - [Accounts](/api-reference/unified-cloud-infrastructure-api/accounts) - [GET /unified/cloud-infrastructure/accounts](/api-reference/unified-cloud-infrastructure-api/accounts/list) — List Accounts - [GET /unified/cloud-infrastructure/accounts/{id}](/api-reference/unified-cloud-infrastructure-api/accounts/get) — Get Accounts - [AccountGroupings](/api-reference/unified-cloud-infrastructure-api/accountgroupings) - [GET /unified/cloud-infrastructure/account_groupings](/api-reference/unified-cloud-infrastructure-api/accountgroupings/list) — List Account groupings - [ObjectStores](/api-reference/unified-cloud-infrastructure-api/objectstores) - [GET /unified/cloud-infrastructure/object_stores](/api-reference/unified-cloud-infrastructure-api/objectstores/list) — List Object stores - [GET /unified/cloud-infrastructure/object_stores/{id}](/api-reference/unified-cloud-infrastructure-api/objectstores/get) — Get Object stores - [RelationalDatabases](/api-reference/unified-cloud-infrastructure-api/relationaldatabases) - [GET /unified/cloud-infrastructure/relational_databases](/api-reference/unified-cloud-infrastructure-api/relationaldatabases/list) — List Relational databases - [DataSnapshots](/api-reference/unified-cloud-infrastructure-api/datasnapshots) - [GET /unified/cloud-infrastructure/data_snapshots](/api-reference/unified-cloud-infrastructure-api/datasnapshots/list) — List Data snapshots - [NetworkBoundaries](/api-reference/unified-cloud-infrastructure-api/networkboundaries) - [GET /unified/cloud-infrastructure/network_boundaries](/api-reference/unified-cloud-infrastructure-api/networkboundaries/list) — List Network boundaries - [FirewallRuleSets](/api-reference/unified-cloud-infrastructure-api/firewallrulesets) - [GET /unified/cloud-infrastructure/firewall_rule_sets](/api-reference/unified-cloud-infrastructure-api/firewallrulesets/list) — List Firewall rule sets - [NetworkLinks](/api-reference/unified-cloud-infrastructure-api/networklinks) - [GET /unified/cloud-infrastructure/network_links](/api-reference/unified-cloud-infrastructure-api/networklinks/list) — List Network links - [ManagedKeys](/api-reference/unified-cloud-infrastructure-api/managedkeys) - [GET /unified/cloud-infrastructure/managed_keys](/api-reference/unified-cloud-infrastructure-api/managedkeys/list) — List Managed keys - [AuditTrailConfigs](/api-reference/unified-cloud-infrastructure-api/audittrailconfigs) - [GET /unified/cloud-infrastructure/audit_trail_configs](/api-reference/unified-cloud-infrastructure-api/audittrailconfigs/list) — List Audit trail configs - [PolicyConstraints](/api-reference/unified-cloud-infrastructure-api/policyconstraints) - [GET /unified/cloud-infrastructure/policy_constraints](/api-reference/unified-cloud-infrastructure-api/policyconstraints/list) — List Policy constraints - [PolicyComplianceStates](/api-reference/unified-cloud-infrastructure-api/policycompliancestates) - [GET /unified/cloud-infrastructure/policy_compliance_states](/api-reference/unified-cloud-infrastructure-api/policycompliancestates/list) — List Policy compliance states - [ScanCoverages](/api-reference/unified-cloud-infrastructure-api/scancoverages) - [GET /unified/cloud-infrastructure/scan_coverages](/api-reference/unified-cloud-infrastructure-api/scancoverages/list) — List Scan coverages - [VulnerabilityFindings](/api-reference/unified-cloud-infrastructure-api/vulnerabilityfindings) - [GET /unified/cloud-infrastructure/vulnerability_findings](/api-reference/unified-cloud-infrastructure-api/vulnerabilityfindings/list) — List Vulnerability findings - [LogDestinations](/api-reference/unified-cloud-infrastructure-api/logdestinations) - [GET /unified/cloud-infrastructure/log_destinations](/api-reference/unified-cloud-infrastructure-api/logdestinations/list) — List Log destinations - [BlockVolumes](/api-reference/unified-cloud-infrastructure-api/blockvolumes) - [GET /unified/cloud-infrastructure/block_volumes](/api-reference/unified-cloud-infrastructure-api/blockvolumes/list) — List Block volumes - [DataWarehouses](/api-reference/unified-cloud-infrastructure-api/datawarehouses) - [GET /unified/cloud-infrastructure/data_warehouses](/api-reference/unified-cloud-infrastructure-api/datawarehouses/list) — List Data warehouses - [FileSystems](/api-reference/unified-cloud-infrastructure-api/filesystems) - [GET /unified/cloud-infrastructure/file_systems](/api-reference/unified-cloud-infrastructure-api/filesystems/list) — List File systems - [MessageQueues](/api-reference/unified-cloud-infrastructure-api/messagequeues) - [GET /unified/cloud-infrastructure/message_queues](/api-reference/unified-cloud-infrastructure-api/messagequeues/list) — List Message queues - [NosqlTables](/api-reference/unified-cloud-infrastructure-api/nosqltables) - [GET /unified/cloud-infrastructure/nosql_tables](/api-reference/unified-cloud-infrastructure-api/nosqltables/list) — List Nosql tables - [ComputeInstances](/api-reference/unified-cloud-infrastructure-api/computeinstances) - [GET /unified/cloud-infrastructure/compute_instances/{id}](/api-reference/unified-cloud-infrastructure-api/computeinstances/get) — Get Compute instances - [GET /unified/cloud-infrastructure/compute_instances](/api-reference/unified-cloud-infrastructure-api/computeinstances/list) — List Compute instances - [ServerlessFunctions](/api-reference/unified-cloud-infrastructure-api/serverlessfunctions) - [GET /unified/cloud-infrastructure/serverless_functions/{id}](/api-reference/unified-cloud-infrastructure-api/serverlessfunctions/get) — Get Serverless functions - [GET /unified/cloud-infrastructure/serverless_functions](/api-reference/unified-cloud-infrastructure-api/serverlessfunctions/list) — List Serverless functions - [InstanceGroups](/api-reference/unified-cloud-infrastructure-api/instancegroups) - [GET /unified/cloud-infrastructure/instance_groups/{id}](/api-reference/unified-cloud-infrastructure-api/instancegroups/get) — Get Instance groups - [GET /unified/cloud-infrastructure/instance_groups](/api-reference/unified-cloud-infrastructure-api/instancegroups/list) — List Instance groups - [MonitoringAlarms](/api-reference/unified-cloud-infrastructure-api/monitoringalarms) - [GET /unified/cloud-infrastructure/monitoring_alarms/{id}](/api-reference/unified-cloud-infrastructure-api/monitoringalarms/get) — Get Monitoring alarms - [GET /unified/cloud-infrastructure/monitoring_alarms](/api-reference/unified-cloud-infrastructure-api/monitoringalarms/list) — List Monitoring alarms - [NotificationTopics](/api-reference/unified-cloud-infrastructure-api/notificationtopics) - [GET /unified/cloud-infrastructure/notification_topics/{id}](/api-reference/unified-cloud-infrastructure-api/notificationtopics/get) — Get Notification topics - [GET /unified/cloud-infrastructure/notification_topics](/api-reference/unified-cloud-infrastructure-api/notificationtopics/list) — List Notification topics - [MachineImages](/api-reference/unified-cloud-infrastructure-api/machineimages) - [GET /unified/cloud-infrastructure/machine_images/{id}](/api-reference/unified-cloud-infrastructure-api/machineimages/get) — Get Machine images - [GET /unified/cloud-infrastructure/machine_images](/api-reference/unified-cloud-infrastructure-api/machineimages/list) — List Machine images - [ManagedInstances](/api-reference/unified-cloud-infrastructure-api/managedinstances) - [GET /unified/cloud-infrastructure/managed_instances](/api-reference/unified-cloud-infrastructure-api/managedinstances/list) — List Managed instances - [ContainerClusters](/api-reference/unified-cloud-infrastructure-api/containerclusters) - [GET /unified/cloud-infrastructure/container_clusters/{id}](/api-reference/unified-cloud-infrastructure-api/containerclusters/get) — Get Container clusters - [GET /unified/cloud-infrastructure/container_clusters](/api-reference/unified-cloud-infrastructure-api/containerclusters/list) — List Container clusters - [ContainerServices](/api-reference/unified-cloud-infrastructure-api/containerservices) - [GET /unified/cloud-infrastructure/container_services/{id}](/api-reference/unified-cloud-infrastructure-api/containerservices/get) — Get Container services - [GET /unified/cloud-infrastructure/container_services](/api-reference/unified-cloud-infrastructure-api/containerservices/list) — List Container services - [ContainerTaskDefinitions](/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions) - [GET /unified/cloud-infrastructure/container_task_definitions/{id}](/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions/get) — Get Container task definitions - [GET /unified/cloud-infrastructure/container_task_definitions](/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions/list) — List Container task definitions - [ContainerTasks](/api-reference/unified-cloud-infrastructure-api/containertasks) - [GET /unified/cloud-infrastructure/container_tasks/{id}](/api-reference/unified-cloud-infrastructure-api/containertasks/get) — Get Container tasks - [GET /unified/cloud-infrastructure/container_tasks](/api-reference/unified-cloud-infrastructure-api/containertasks/list) — List Container tasks - [KubernetesClusters](/api-reference/unified-cloud-infrastructure-api/kubernetesclusters) - [GET /unified/cloud-infrastructure/kubernetes_clusters/{id}](/api-reference/unified-cloud-infrastructure-api/kubernetesclusters/get) — Get Kubernetes clusters - [GET /unified/cloud-infrastructure/kubernetes_clusters](/api-reference/unified-cloud-infrastructure-api/kubernetesclusters/list) — List Kubernetes clusters - [KubernetesNodePools](/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools) - [GET /unified/cloud-infrastructure/kubernetes_node_pools/{id}](/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools/get) — Get Kubernetes node pools - [GET /unified/cloud-infrastructure/kubernetes_node_pools](/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools/list) — List Kubernetes node pools - [LoadBalancers](/api-reference/unified-cloud-infrastructure-api/loadbalancers) - [GET /unified/cloud-infrastructure/load_balancers/{id}](/api-reference/unified-cloud-infrastructure-api/loadbalancers/get) — Get Load balancers - [GET /unified/cloud-infrastructure/load_balancers](/api-reference/unified-cloud-infrastructure-api/loadbalancers/list) — List Load balancers - [CdnDistributions](/api-reference/unified-cloud-infrastructure-api/cdndistributions) - [GET /unified/cloud-infrastructure/cdn_distributions/{id}](/api-reference/unified-cloud-infrastructure-api/cdndistributions/get) — Get Cdn distributions - [GET /unified/cloud-infrastructure/cdn_distributions](/api-reference/unified-cloud-infrastructure-api/cdndistributions/list) — List Cdn distributions - [Certificates](/api-reference/unified-cloud-infrastructure-api/certificates) - [GET /unified/cloud-infrastructure/certificates/{id}](/api-reference/unified-cloud-infrastructure-api/certificates/get) — Get Certificates - [GET /unified/cloud-infrastructure/certificates](/api-reference/unified-cloud-infrastructure-api/certificates/list) — List Certificates - [CodeRepositories](/api-reference/unified-cloud-infrastructure-api/coderepositories) - [GET /unified/cloud-infrastructure/code_repositories/{id}](/api-reference/unified-cloud-infrastructure-api/coderepositories/get) — Get Code repositories - [GET /unified/cloud-infrastructure/code_repositories](/api-reference/unified-cloud-infrastructure-api/coderepositories/list) — List Code repositories --- # PostureFindings Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/posturefindings/ Schema for the `PostureFindings` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`finding_id`** _(string)_ The provider's own finding identifier, verbatim. - **`standard_id`** _(string)_ The benchmark this evaluation came from, as the provider emits it (e.g. a standards ARN or subscription id). Never normalized. - **`standard_version`** _(string)_ The benchmark version, e.g. '3.0.0'. On AWS this is parsed from the standard ARN, not returned directly; parsing failures are noted in unreadable_fields. - **`control_id`** _(string)_ The provider's own control identifier, unmodified — e.g. 'S3.8', 'IAM.1'. Never renamed, prefixed, or normalized. - **`status`** _(string)_ Outcome of the evaluation. not_applicable (skipped) is never reported as passed; unknown (could not check) is never reported as passed either. On AWS, NOT_AVAILABLE maps to not_applicable only when the reason is CONFIG_RETURNS_NOT_APPLICABLE — otherwise it maps to unknown, flagged in unreadable_fields. Allowed: `passed`, `failed`, `warning`, `not_applicable`, `unknown` - **`status_reason_codes`** _(array)_ The provider's own reason codes behind the status, verbatim. - **`severity`** _(string)_ Severity as the provider labelled it. On AWS, a passing finding is always 'INFORMATIONAL' — this reflects the outcome, not the control's real risk level. - **`resource_id`** _(string)_ The provider's own identifier for the resource evaluated — an ARN or resource id. - **`resource_type`** _(string)_ The provider's own type string for the evaluated resource. - **`first_observed_at`** _(string)_ When the problem was first detected. On AWS, FirstObservedAt resets on every compliance status transition, so CreatedAt is substituted instead — flagged in unreadable_fields. - **`last_observed_at`** _(string)_ When the finding was most recently seen. - **`created_at`** _(string)_ When the provider created the finding record. Dependable on all three providers, unlike first_observed_at. - **`title`** _(string)_ The provider's own title for the control or finding. - **`description`** _(string)_ The provider's own description of the control or finding. - **`remediation_text`** _(string)_ The provider's own remediation guidance for this finding. - **`remediation_url`** _(string)_ Link to the provider's remediation documentation. - **`workflow_status`** _(string)_ The triage state set in the provider console. On AWS this is Workflow.Status — not the deprecated WorkflowState field, whose enum values differ. Allowed: `new`, `notified`, `in_progress`, `resolved`, `suppressed`, `unknown` - **`suppressed`** _(boolean)_ Whether the finding is suppressed in the provider console. Derived from workflow_status. - **`record_state`** _(string)_ Whether the finding is active or archived. On AWS, not_applicable findings auto-archive after three days, so archived findings are included here too — filtering to active only would drop them. Allowed: `active`, `archived` - **`associated_standards`** _(array)_ Every benchmark this finding maps to, as provider standard identifiers. - **`product_name`** _(string)_ The product that produced the finding, verbatim as the provider names it - on AWS the Security Hub ProductName (e.g. 'Security Hub', 'IAM Access Analyzer', 'Inspector'), or 'IAM Access Analyzer' for a finding read from the analyzer directly. Security Hub carries copies of other products' findings, so this is how a reader that reads both avoids counting one twice. ## Methods - [GET /unified/cloud-infrastructure/posture_findings](/api-reference/unified-cloud-infrastructure-api/posturefindings/list) — List Posture findings --- # SecurityProductStates Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/securityproductstates/ Schema for the `SecurityProductStates` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`product_name`** _(string)_ Which product — for example 'securityhub', 'guardduty', 'inspector2', 'macie', 'config', 'accessanalyzer', 'defender-for-cloud', 'security-command-center'. - **`enabled`** _(boolean)_ Whether the product is enabled in this account and region. 'Not enabled' (e.g. a 404) maps to false, never unknown; a permission failure is left null and flagged in unreadable_fields. - **`status`** _(string)_ The provider's own status string, verbatim. Distinct from `enabled` — e.g. AWS Macie's PAUSED is enabled-but-suspended, not disabled. - **`tier`** _(string)_ Paid tier or edition, where the provider has one. AWS services are usage-priced with no tier concept, so this is always null there (not_supported_by_provider in unreadable_fields). - **`plan_name`** _(string)_ The specific plan, for providers with per-plan states (e.g. Azure Defender for Servers vs Storage). No AWS equivalent. Free-trial status is not represented here. - **`enabled_standards`** _(array)_ Which compliance benchmarks are subscribed, as provider identifiers. Security Hub only — other products' feature toggles go in enabled_features instead. - **`enabled_features`** _(array)_ Capability toggles the product exposes that are not compliance standards. - **`last_evaluated_at`** _(string)_ When the product last evaluated the estate. On AWS, only Config and Access Analyzer expose this; otherwise it's null (not_supported_by_provider) — never substituted with a config-change timestamp. - **`config_updated_at`** _(string)_ When the product's configuration last changed. Distinct from last_evaluated_at and never used as a stand-in for it. ## Methods - [GET /unified/cloud-infrastructure/security_product_states](/api-reference/unified-cloud-infrastructure-api/securityproductstates/list) — List Security product states --- # ThreatFindings Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/threatfindings/ Schema for the `ThreatFindings` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`finding_id`** _(string)_ The provider's own finding identifier. - **`category`** _(string)_ The provider's own category string, verbatim, with no mapping into a shared taxonomy. - **`type`** _(string)_ The provider's own finding type string, for example 'UnauthorizedAccess:EC2/SSHBruteForce'. Also the fallback for title, which is optional on AWS. - **`title`** _(string)_ Human-readable title of the alert. - **`severity`** _(number)_ Severity as the provider expresses it. On AWS GuardDuty this is a raw number (no label field); any label shown elsewhere is derived, not provider-native. - **`state`** _(string)_ Whether the alert is active or archived. On AWS this is derived from an optional field, so 'unknown' is a real, expected value. Allowed: `active`, `archived`, `resolved`, `unknown` - **`created_at`** _(string)_ When the alert was raised. - **`updated_at`** _(string)_ When the alert was last updated by the provider. - **`resource_id`** _(string)_ The affected resource. Where a finding affects several resources, the primary one is carried here and the rest remain in remote_data. - **`resource_type`** _(string)_ The provider's own type string for the affected resource. - **`count`** _(integer)_ How many times this alert pattern has repeated. - **`sample_evidence`** _(object)_ Provider-supplied evidence for the alert. Structure varies by provider and finding type — not a fixed schema. ## Methods - [GET /unified/cloud-infrastructure/threat_findings](/api-reference/unified-cloud-infrastructure-api/threatfindings/list) — List Threat findings --- # HumanIdentities Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/humanidentities/ Schema for the `HumanIdentities` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`identity_id`** _(string)_ The provider's own identifier for the identity. - **`identity_store`** _(string)_ Which identity store this row came from. On AWS, IAM users and Identity Center users share no identifiers and populate different subsets of fields. - **`display_name`** _(string)_ The person's display name. Null for AWS IAM users (they have no display name, only a user name and path), flagged not_supported_by_provider. - **`email_or_upn`** _(string)_ Email address or user principal name. AWS IAM users have no email attribute in the API, so this is null there unless the customer set it as a tag. - **`enabled`** _(boolean)_ Whether the identity can currently sign in. Read directly for Identity Center users; for AWS IAM users it is derived from having no login profile and no active access keys, and flagged as derived. - **`identity_type`** _(string)_ Whether this is a person, a service account, or an external guest. Allowed: `human`, `service`, `guest`, `external`, `unknown` - **`mfa_registered`** _(boolean)_ Whether this specific user has MFA registered (per user, not per account). Null with not_supported_by_provider for AWS Identity Center, which exposes no such field. - **`mfa_methods`** _(array)_ The registered MFA method types. On AWS these are inferred from the device serial number shape (not returned by the API) and marked derived; FIDO and TOTP cannot always be distinguished. - **`mfa_device_count`** _(integer)_ Number of MFA devices registered to this identity. - **`is_admin`** _(boolean)_ Whether this identity holds administrative privilege. Derived from attached permissions, since no provider exposes an admin flag directly. - **`admin_roles`** _(array)_ The administrative roles or policies behind is_admin, as provider references. - **`last_sign_in_at`** _(string)_ Last interactive console sign-in. On AWS, console-only, at five-minute granularity, with no tracking before 2014-10-20 and a gap in 2018; not available for Identity Center. Null forever for programmatic-only users -- do not read as 'never signed in'. - **`created_at`** _(string)_ When the identity was created. - **`group_memberships`** _(array)_ Group references for this identity. - **`has_console_access`** _(boolean)_ Whether the identity has interactive sign-in, distinct from programmatic-only access. On AWS derived from a 404 on GetLoginProfile; null on the Identity Center path (IAM-only concept). - **`has_static_credentials`** _(boolean)_ Whether the identity holds long-lived credentials. An IAM-only concept on AWS; null on the Identity Center path. ## Methods - [GET /unified/cloud-infrastructure/human_identities](/api-reference/unified-cloud-infrastructure-api/humanidentities/list) — List Human identities --- # PasswordPolicies Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/passwordpolicies/ Schema for the `PasswordPolicies` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`policy_id`** _(string)_ Provider reference for the policy, where one exists. - **`scope`** _(string)_ Whether the policy applies to an account, a tenant, an organisational unit, or a directory. Allowed: `account`, `organisation`, `grouping`, `tenant`, `directory` - **`scope_id`** _(string)_ The provider reference for the scope this policy applies to. - **`is_configured`** _(boolean)_ Whether a policy has actually been set. On AWS, no policy (404 from GetAccountPasswordPolicy) means provider defaults apply -- a weaker posture -- and this is false, never unknown. - **`minimum_length`** _(integer)_ Minimum password length. - **`reuse_prevention`** _(integer)_ How many previous passwords cannot be reused. - **`expiry_days`** _(integer)_ Maximum password age in days. Null with not_configured if the provider supports expiry but none is set; null with not_supported_by_provider if expiry doesn't exist at all. - **`hard_expiry`** _(boolean)_ Whether an expired password locks the user out rather than prompting a reset. - **`lockout_threshold`** _(integer)_ Failed sign-in attempts before lockout. AWS IAM has no such setting, so this is null with not_supported_by_provider -- never 0, which would misread as 'locks immediately'. - **`complexity_flags`** _(object)_ Which character classes are required, as provider-named booleans -- for example require_symbols, require_numbers, require_uppercase, require_lowercase. - **`require_symbols`** _(boolean)_ Whether at least one non-alphanumeric character is required. - **`require_numbers`** _(boolean)_ Whether at least one digit is required. - **`require_uppercase`** _(boolean)_ Whether at least one uppercase letter is required. - **`require_lowercase`** _(boolean)_ Whether at least one lowercase letter is required. - **`allow_users_to_change_password`** _(boolean)_ Whether users may change their own password without an administrator. - **`banned_password_protection`** _(boolean)_ Whether the provider blocks known-breached or banned passwords. Null with not_supported_by_provider on AWS IAM, which has no such feature. - **`field_configurable`** _(object)_ Per-field map of whether the customer can change that value, distinguishing 'fixed at 8' from 'set to 8'. On AWS the length floor is fixed at 6, reuse prevention capped at 24, and the symbol set fixed. - **`minimum_length`** _(boolean)_ Whether the customer can change the minimum length. - **`reuse_prevention`** _(boolean)_ Whether the customer can change how many previous passwords are remembered. - **`expiry_days`** _(boolean)_ Whether the customer can change the password expiry period. - **`hard_expiry`** _(boolean)_ Whether the customer can change whether an expired password locks the user out. - **`lockout_threshold`** _(boolean)_ Whether the customer can change the failed-sign-in lockout threshold. - **`banned_password_protection`** _(boolean)_ Whether the customer can change banned or breached password protection. - **`provenance`** _(string)_ Where this policy came from. 'static' means the values are transcribed from the provider's documentation, not read live -- true of AWS Identity Center, which exposes no policy API. Allowed: `live`, `static`, `default` ## Methods - [GET /unified/cloud-infrastructure/password_policies](/api-reference/unified-cloud-infrastructure-api/passwordpolicies/list) — List Password policies --- # StaticCredentials Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/staticcredentials/ Schema for the `StaticCredentials` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`credential_id`** _(string)_ The provider's own identifier for the credential. - **`principal`** _(object)_ The identity that holds this credential. - **`id`** _(string)_ The target's `id`. - **`principal_type`** _(string)_ Whether the holder is a human identity or a workload identity. Allowed: `human`, `workload`, `unknown` - **`credential_type`** _(string)_ What kind of credential this is. On AWS there are five distinct types and they answer different subsets of this resource. Allowed: `access_key`, `console_password`, `service_specific`, `ssh_public_key`, `x509_certificate`, `client_secret`, `service_account_key`, `other` - **`created_at`** _(string)_ When the credential was created. - **`enabled`** _(boolean)_ Whether the credential is currently active. - **`status`** _(string)_ The provider's own status string for the credential, verbatim. - **`last_used_at`** _(string)_ When the credential was last used (UTC). A null always has an unreadable_fields entry saying why: not_collected (not read on this request), not_configured (never used), permission_denied (the read returned nothing), collection_error (the answer was malformed), or not_supported_by_provider (the credential type has no last-use record). Never a bare null that could read as 'never used'. (AWS: IAM GetAccessKeyLastUsed, only access keys have it, tracked since 22 April 2015; read only with fields[]=last_used_at or fields[]=last_used_service, one call per key, and the all-users list then reads at most 10 users per page.) - **`last_used_service`** _(string)_ Which provider service last used the credential, where exposed. Null when never used or not read; unreadable_fields says which. (AWS: the ServiceName of IAM GetAccessKeyLastUsed, e.g. s3; read only with fields[]=last_used_service or fields[]=last_used_at.) - **`expires_at`** _(string)_ When the credential expires. AWS access keys never expire; X.509 certificate expiry exists but AWS won't return it (must be parsed from the PEM). Only service-specific credentials expose a real expiry field. ## Methods - [GET /unified/cloud-infrastructure/static_credentials](/api-reference/unified-cloud-infrastructure-api/staticcredentials/list) — List Static credentials --- # AccessGrants Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/accessgrants/ Schema for the `AccessGrants` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`grant_id`** _(string)_ Stable reference for this grant. Synthesized on AWS, which has no single grant identifier. - **`principal`** _(object)_ Who holds the grant. `user` resolves against human_identities and `workload_identity` against workload_identities. Null when `principal_type` is `group` or `external`, which have no resource in this family; the provider's id for those is kept in `remote_data.principal_arn`. - **`id`** _(string)_ The target's `id`. - **`principal_type`** _(string)_ What kind of principal holds it. Allowed: `user`, `group`, `workload_identity`, `external`, `unknown` - **`permission`** _(object)_ What was granted. Absent for a grant with no independently addressable policy — an AWS inline policy, which lives inside its principal. - **`id`** _(string)_ The target's `id`. - **`name`** _(string)_ What the provider calls it. - **`scope`** _(string)_ The provider reference for the exact thing the grant applies to. - **`scope_level`** _(string)_ How far the grant reaches, from organisation level down to a single resource. Allowed: `organisation`, `grouping`, `account`, `resource`, `unknown` - **`scope_id`** _(string)_ The provider reference for the scope node. - **`is_privileged`** _(boolean)_ Whether this grant confers administrative privilege. Derived by parsing the permission document. - **`grants_all_actions`** _(boolean)_ Whether the grant permits every action on every resource, derived from the permission document including the NotAction case. - **`assignment_type`** _(string)_ Whether the privilege is permanent, eligible (activated on request), or time-limited with an expiry. Allowed: `permanent`, `eligible`, `time_limited`, `unknown` - **`expires_at`** _(string)_ When the grant expires. AWS IAM attachments and Identity Center assignments are permanent until detached, so this is null with not_supported_by_provider there. Session duration bounds a credential, not this grant, and is not mapped here. - **`last_reviewed_at`** _(string)_ When this grant was last formally reviewed. AWS has no access-review or attestation concept, so this is always null there; see last_used_at for a related but different signal. - **`last_used_at`** _(string)_ When the granted access was last exercised. Not a substitute for last_reviewed_at. ## Methods - [GET /unified/cloud-infrastructure/access_grants](/api-reference/unified-cloud-infrastructure-api/accessgrants/list) — List Access grants --- # PermissionDefinitions Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/permissiondefinitions/ Schema for the `PermissionDefinitions` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`definition_id`** _(string)_ The provider's own identifier for the policy or role definition. - **`name`** _(string)_ The policy or role name as the provider names it. - **`is_custom`** _(boolean)_ Whether the customer authored this, as opposed to a provider-supplied built-in. - **`allowed_actions`** _(array)_ Permitted actions with wildcards intact, e.g. 's3:*' or 'ec2:Describe*' -- never expanded. An empty array means the document grants nothing; null means the document could not be read (see unreadable_fields). - **`denied_actions`** _(array)_ Explicitly denied actions, with wildcards intact. - **`not_actions`** _(array)_ Actions under a NotAction clause, kept separate from allowed_actions. Combined with Allow, this permits everything EXCEPT these actions -- the inverse of a normal action list. - **`not_resources`** _(array)_ Resources under a NotResource clause. Combined with Allow, this excludes these resources rather than including them. - **`resource_scope`** _(array)_ The resources the permissions apply to, with wildcards intact. - **`has_wildcard_action`** _(boolean)_ Whether any statement grants a bare action wildcard. Derived. - **`has_wildcard_resource`** _(boolean)_ Whether any statement applies to a bare resource wildcard. Derived. - **`raw_document`** _(string)_ The provider's raw policy document as a string, in its native encoding. AWS IAM documents are URL-encoded (RFC 3986); Organizations and Identity Center inline documents are plain JSON. - **`attachment_count`** _(integer)_ How many principals this definition is attached to as a grant, kept separate from permissions_boundary_usage_count (a restriction, not a grant). - **`permissions_boundary_usage_count`** _(integer)_ How many principals use this definition as a permissions boundary -- a restriction, not a grant. - **`assignment_count`** _(integer)_ Total assignments, where the provider exposes a single combined number. - **`created_at`** _(string)_ When the definition was created. - **`updated_at`** _(string)_ When the definition was last modified. ## Methods - [GET /unified/cloud-infrastructure/permission_definitions](/api-reference/unified-cloud-infrastructure-api/permissiondefinitions/list) — List Permission definitions --- # WorkloadIdentities Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/workloadidentities/ Schema for the `WorkloadIdentities` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`identity_id`** _(string)_ The provider's own identifier for the workload identity. - **`name`** _(string)_ The identity name as the provider names it. - **`identity_type`** _(string)_ Role, managed identity, service principal or service account. Allowed: `role`, `managed_identity`, `service_principal`, `service_account`, `other` - **`trusted_external_principals`** _(array)_ External accounts, services and federated issuers allowed to assume this identity, as provider principal strings. - **`trust_policy_document`** _(string)_ The raw trust or assume-role policy document, verbatim. - **`has_unconditional_wildcard_trust`** _(boolean)_ Whether the identity can be assumed by a bare wildcard principal with no condition -- wide open. Derived. - **`federated_credentials`** _(array)_ Federated access configuration assembled from the trust policy. - **`issuer`** _(string)_ The federated identity provider, without its URL scheme. - **`audience`** _(array)_ Audience values the trust policy accepts. - **`has_subject_condition`** _(boolean)_ Whether the trust is also scoped by subject. - **`has_subject_condition`** _(boolean)_ Whether a subject condition is present on the federated trust. Absence matters: a trust with no subject condition lets any subject from that issuer assume the identity -- e.g. any GitHub repository for a GitHub Actions provider. - **`permissions`** _(array)_ The permission definitions attached to this identity. - **`id`** _(string)_ The target's `id`. - **`inline_permission_count`** _(integer)_ How many inline permission documents are attached directly. - **`last_used_at`** _(string)_ When the identity was last used. On AWS the tracking window is about 400 days, so a null does not mean unused -- report as unknown, not dormant. - **`last_used_region`** _(string)_ Where the identity was last used, where the provider exposes it. - **`has_static_keys`** _(boolean)_ Whether the machine identity holds long-lived keys. Always false for AWS IAM roles, which have no long-term credentials -- a provider fact, not a data gap. - **`key_count`** _(integer)_ How many long-lived keys the identity holds. Always 0 for AWS IAM roles. - **`created_at`** _(string)_ When the identity was created. ## Methods - [GET /unified/cloud-infrastructure/workload_identities](/api-reference/unified-cloud-infrastructure-api/workloadidentities/list) — List Workload identities --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/accounts/ Schema for the `Accounts` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this account — the provider's own account number (AWS 12-digit id, Azure subscription id, GCP project id). Every other resource's `account` reference resolves against this. Use `provider_id` for the full ARN or self-link. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The account, subscription or project name. - **`state`** _(string)_ Lifecycle state of the account. On AWS this comes from Account.State, not the retired Account.Status field (which had no CLOSED value). Allowed: `pending`, `active`, `suspended`, `pending_closure`, `closed`, `unknown` - **`email`** _(string)_ The account's registered contact address, where the provider exposes it. - **`parent_grouping`** _(object)_ The organisational unit, folder or management group directly above this account. - **`id`** _(string)_ The target's `id`. - **`grouping_path`** _(string)_ The full hierarchy path from the organisation root down to this account, as a single string. - **`grouping_paths`** _(array)_ All hierarchy paths for this account, where a provider allows more than one. Never collapsed to a single value. - **`joined_at`** _(string)_ When the account joined the organisation. For an invited account this is the invitation acceptance date, which can be years after the account was actually created. - **`joined_method`** _(string)_ How the account entered the organisation, as the provider reports it. - **`created_at`** _(string)_ When the account was actually created. On AWS this requires a separate account-service call and is null unless that call was made; never back-filled from joined_at. - **`is_connected`** _(boolean)_ Whether Truto currently holds working credentials for this account. False for accounts discovered in the organisation but not reachable. - **`enabled_regions`** _(array)_ Regions (locations) the account can use right now, by the provider's own region code. On AWS: every region that is enabled by default or opted in, from EC2 DescribeRegions run as the account itself. Read on GET accounts/self, or GET accounts/{id} with account_id set to the same account; null on the organisation-wide list (see unreadable_fields). - **`root_user_mfa_registered`** _(boolean)_ Whether the account's root user (the account owner's sign-in, which IAM policies cannot restrict) has an MFA device registered. False also when the root user has no password at all, for example a member account whose root credentials were removed centrally (AWS Organizations centralized root access), where it is not by itself a finding. On providers with no root user (Azure, GCP) it is null with not_supported_by_provider. On AWS it is opt-in: read on GET accounts/{id} with fields[]=root_user_mfa_registered, as the account itself (accounts/self, or account_id={id}); otherwise, and on the list, null with not_collected (see unreadable_fields). (AWS: IAM GetAccountSummary AccountMFAEnabled) - **`root_user_has_static_credentials`** _(boolean)_ Whether the account's root user holds long-lived credentials (on AWS, access keys; signing certificates are not counted), which IAM policies cannot restrict. On providers with no root user (Azure, GCP) it is null with not_supported_by_provider. On AWS it is opt-in: read on GET accounts/{id} with fields[]=root_user_has_static_credentials, as the account itself (accounts/self, or account_id={id}); otherwise, and on the list, null with not_collected (see unreadable_fields). (AWS: IAM GetAccountSummary AccountAccessKeysPresent) ## Methods - [GET /unified/cloud-infrastructure/accounts](/api-reference/unified-cloud-infrastructure-api/accounts/list) — List Accounts - [GET /unified/cloud-infrastructure/accounts/{id}](/api-reference/unified-cloud-infrastructure-api/accounts/get) — Get Accounts --- # AccountGroupings Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/accountgroupings/ Schema for the `AccountGroupings` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, verbatim -- a full ARN, resource id, or self-link. Never truncated or normalised. Use it to find the object in the provider's console. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider gives none, the collector's queried region is used instead and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified -- for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them -- no case folding, key/value normalisation, or merging across providers. An empty object means no tags; unreadable tags appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider-supplied timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Additional detail on the reason, when there is any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`grouping_id`** _(string)_ The provider's own identifier for the grouping node. - **`name`** _(string)_ The name of this organisational unit, management group, or folder, as the provider names it. - **`grouping_type`** _(string)_ What kind of node this is. On AWS no field carries this directly -- it's derived from the identifier prefix and the operation that returned it, and flagged as derived. Allowed: `organisation`, `root`, `organisational_unit`, `management_group`, `folder` - **`grouping_type_source`** _(string)_ Whether grouping_type was read from the provider or derived. Allowed: `provider`, `derived` - **`parent`** _(object)_ The node directly above this one. Null for the organisation root. - **`id`** _(string)_ The target's `id`. - **`path`** _(string)_ Full path from the organisation root to this node. On AWS the root itself has no path field, so one is synthesized from the organisation and root identifiers. - **`child_accounts`** _(array)_ Accounts directly beneath this node. An empty array means it genuinely holds none; null means they were not collected. - **`id`** _(string)_ The target's `id`. - **`child_groupings`** _(array)_ Grouping nodes directly beneath this one. - **`id`** _(string)_ The target's `id`. - **`organization_id`** _(string)_ The organisation, tenant or GCP organisation this node belongs to. ## Methods - [GET /unified/cloud-infrastructure/account_groupings](/api-reference/unified-cloud-infrastructure-api/accountgroupings/list) — List Account groupings --- # ObjectStores Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/objectstores/ Schema for the `ObjectStores` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier. S3 returns an ARN only for directory buckets; for general-purpose buckets this is the canonical `arn::s3:::`, which is how AWS itself addresses the bucket. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`store_id`** _(string)_ The provider's own identifier for the store. - **`name`** _(string)_ The bucket or container name. - **`location`** _(string)_ Where the store's data physically sits. - **`public_access_blocked`** _(boolean)_ Whether public access is comprehensively blocked. True only when all four effective block-public-access flags are set (the more restrictive of account- and bucket-level config); a missing configuration counts as all-false. - **`anonymous_access_allowed`** _(boolean)_ Whether the store is effectively reachable without credentials. Computed from the provider's effective access rules, not a single flag. - **`policy_grants_anyone`** _(boolean)_ Whether the bucket policy grants access to anyone (distinct from account-level toggles, which can disagree). On AWS, cross-account access often can't read the policy body itself, so this may be marked permission_denied. - **`acl_grants_anyone`** _(boolean)_ Whether an ACL grants access to a public group, tracked separately from policy_grants_anyone since the two can differ. - **`acl_grants_authenticated_users`** _(boolean)_ Whether an ACL grants access to any authenticated account on the provider (not anonymous — requests must be signed, but any account on the provider qualifies). - **`effective_public_access_block`** _(object)_ The per-flag effective block configuration, combining account-level and store-level settings. - **`block_public_acls`** _(boolean)_ AWS BlockPublicAcls. Rejects new public ACLs on the store and its objects. - **`ignore_public_acls`** _(boolean)_ AWS IgnorePublicAcls. Ignores any public ACL already present. - **`block_public_policy`** _(boolean)_ AWS BlockPublicPolicy. Rejects a store policy that would grant public access. - **`restrict_public_buckets`** _(boolean)_ AWS RestrictPublicBuckets. Limits access under a public policy to principals in this account and AWS services. - **`encryption_key_type`** _(string)_ Who manages the encryption key. On AWS every bucket now gets default provider-side encryption, so 'none' is effectively obsolete; what matters is whether the key is customer_managed. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `customer_supplied`, `none`, `unknown` - **`encryption_key`** _(object)_ The key protecting the store, where a customer-managed one is configured. - **`id`** _(string)_ The target's `id`. - **`encryption_algorithm`** _(string)_ The provider's own algorithm string, verbatim. - **`versioning_enabled`** _(boolean)_ Whether object versioning is on. On AWS, a bucket that never had versioning enabled returns no status field, read as false rather than unknown. - **`object_lock_enabled`** _(boolean)_ Whether write-once retention is enabled on the store. - **`retention_policy_days`** _(integer)_ Default retention period applied to objects, in days. - **`retention_locked`** _(boolean)_ Whether the retention period cannot be shortened or removed. On AWS this maps to a COMPLIANCE-mode default rule, which only governs future objects, not what's already stored. - **`lifecycle_rules`** _(array)_ Lifecycle rules configured on the store. - **`id`** _(string)_ The provider's own rule id. - **`status`** _(string)_ Whether the rule is enabled. - **`prefix`** _(string)_ Object key prefix the rule applies to, if scoped. - **`expiration_days`** _(integer)_ Days after which matching objects expire. - **`access_logging_enabled`** _(boolean)_ Whether access logging is on. On AWS an unlogged bucket returns an empty document rather than an error, read as false. - **`min_tls_version`** _(string)_ Minimum TLS version accepted. AWS has no bucket-level setting — only a per-action policy condition, so requirements can vary by action. Null with not_supported_by_provider there. - **`replication_targets`** _(array)_ Destination stores this store replicates to, as provider references. The destination region is not returned by the provider. - **`replication_enabled`** _(boolean)_ Whether any replication rule is configured and enabled. - **`inventory_captured_at`** _(string)_ When the provider's own inventory (AWS Config: configurationItemCaptureTime) recorded the values on this row that came from it rather than from a live read. collected_at is when Truto read them. Null when no value on the row came from an inventory. ## Methods - [GET /unified/cloud-infrastructure/object_stores](/api-reference/unified-cloud-infrastructure-api/objectstores/list) — List Object stores - [GET /unified/cloud-infrastructure/object_stores/{id}](/api-reference/unified-cloud-infrastructure-api/objectstores/get) — Get Object stores --- # RelationalDatabases Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/relationaldatabases/ Schema for the `RelationalDatabases` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`db_id`** _(string)_ The provider's own identifier for the database. - **`topology`** _(string)_ Whether this row represents a cluster or a standalone instance. Allowed: `cluster`, `instance`, `unknown` - **`engine`** _(string)_ The database engine, as the provider names it. - **`engine_version`** _(string)_ The database engine version currently running. - **`engine_lifecycle_support`** _(string)_ The provider's support status for this engine version, where exposed. - **`location`** _(string)_ Where the database sits. - **`public_network_access`** _(boolean)_ The provider's public-network-access flag, not proven reachability: true doesn't mean reachable, and false doesn't mean safe — actual exposure also depends on routing. - **`allowed_networks`** _(array)_ Ingress rules that reach this database. - **`source_id`** _(string)_ The source range or security group allowed in. - **`protocol`** _(string)_ The protocol allowed. - **`from_port`** _(integer)_ Lowest port allowed. - **`to_port`** _(integer)_ Highest port allowed. - **`allow_all_ingress`** _(boolean)_ Whether any allowed network rule permits the whole internet. - **`attached_rule_sets`** _(array)_ The firewall rule sets attached to this database. - **`id`** _(string)_ The target's `id`. - **`encryption_at_rest`** _(boolean)_ Whether storage is encrypted at rest. - **`encryption_key_type`** _(string)_ Who manages the storage encryption key. AWS merges provider-managed and customer-managed into one value (only provider-owned is distinguishable); resolving further may yield permission_denied. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `none`, `unknown` - **`encryption_key`** _(object)_ The key protecting the database at rest. - **`id`** _(string)_ The target's `id`. - **`storage_encryption_type`** _(string)_ The provider's own storage encryption type string, verbatim. - **`backup_retention_days`** _(integer)_ How many days of backups are retained. - **`point_in_time_recovery`** _(boolean)_ Whether point-in-time restore is available. AWS has no such flag; this is derived from backup retention and cross-checked against latest_restorable_time. - **`latest_restorable_time`** _(string)_ The most recent point the database could be restored to. - **`deletion_protection`** _(boolean)_ Whether the database is protected against deletion. - **`high_availability_mode`** _(string)_ The database's high-availability topology, distinguishing standby, multi-AZ, and multi-region configurations. Allowed: `none`, `single_standby`, `multi_az_cluster`, `multi_region`, `zone_redundant`, `unknown` - **`min_tls_version`** _(string)_ Minimum TLS version accepted. Often not derivable on AWS: some engines have no true minimum, only an allow-list or independent toggles, and an absent parameter isn't the same as off. - **`tls_enforced`** _(boolean)_ Whether TLS is required for connections, independent of any minimum version floor. - **`audit_log_destinations`** _(array)_ Where audit and error logs are delivered. AWS creates the destination on first write, so a row here can name a log group that does not exist yet. - **`id`** _(string)_ The target's `id`. - **`replica_locations`** _(array)_ Regions holding replicas of this database. - **`replicas`** _(array)_ The replica databases themselves. - **`id`** _(string)_ The target's `id`. - **`global_cluster_id`** _(string)_ The global cluster this database belongs to, where it is part of one. - **`is_writer`** _(boolean)_ Whether this row is the writer of its cluster or global cluster. ## Methods - [GET /unified/cloud-infrastructure/relational_databases](/api-reference/unified-cloud-infrastructure-api/relationaldatabases/list) — List Relational databases --- # DataSnapshots Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/datasnapshots/ Schema for the `DataSnapshots` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`snapshot_id`** _(string)_ The provider's own identifier for the snapshot. - **`snapshot_family`** _(string)_ Which snapshot service this came from — block volume, database instance, database cluster, or disk. Encryption and sharing fields have different semantics per family. Allowed: `block_volume`, `database_instance`, `database_cluster`, `disk`, `other` - **`snapshot_type`** _(string)_ Whether the snapshot was taken manually or by automated backup. Automated snapshots can't be shared, so their sharing fields are set by construction, not read per-snapshot. Allowed: `manual`, `automated`, `unknown` - **`source_resource_id`** _(string)_ The database or volume this snapshot was taken from. - **`source_account_id`** _(string)_ The account that owns the source. On AWS this is parsed from the ARN, since neither database snapshot type carries an owner field. - **`created_at`** _(string)_ When the snapshot was taken. - **`location`** _(string)_ Where the snapshot currently sits (not its origin — a cross-region copy reports its current location). AWS returns no location for block-volume snapshots, so the queried region is used instead. - **`encrypted`** _(boolean)_ Whether the snapshot is encrypted. - **`encryption_key`** _(object)_ The key protecting the snapshot, where it is encrypted. - **`id`** _(string)_ The target's `id`. - **`shared_with_accounts`** _(array)_ Accounts this snapshot has been explicitly shared with. Empty means shared with nobody; null means the sharing attribute could not be read. - **`is_public`** _(boolean)_ Whether the snapshot is readable by any account on the provider. - **`sharing_readable`** _(boolean)_ Whether the per-snapshot sharing attribute was actually read. False means shared_with_accounts and is_public are inferred, not confirmed. - **`regional_public_access_block`** _(string)_ The account-and-region-wide snapshot sharing posture. Under a block-all-sharing setting, an already-public snapshot (is_public true) is effectively private and not actually exposed. - **`status`** _(string)_ The provider's own status string for the snapshot, verbatim. ## Methods - [GET /unified/cloud-infrastructure/data_snapshots](/api-reference/unified-cloud-infrastructure-api/datasnapshots/list) — List Data snapshots --- # NetworkBoundaries Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/networkboundaries/ Schema for the `NetworkBoundaries` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`boundary_id`** _(string)_ The provider's own identifier for the network. - **`name`** _(string)_ The network name. - **`scope_type`** _(string)_ Whether the network is regional or genuinely global. Allowed: `regional`, `global` - **`is_global`** _(boolean)_ True where the provider's network has no location at all. When true, the envelope region carries the literal string 'global' rather than a guessed region. - **`cidr_ranges`** _(array)_ The address ranges the network covers. - **`is_provider_default`** _(boolean)_ Whether this is the provider's automatically created default network. - **`subnets`** _(array)_ Subnets inside this boundary. Nested because a subnet is only meaningful within its boundary. - **`subnet_id`** _(string)_ The subnet's provider reference. - **`cidr`** _(string)_ The address range of the subnet. - **`availability_zone`** _(string)_ The zone the subnet sits in. - **`maps_public_ip_on_launch`** _(boolean)_ Whether instances launched here get a public IP automatically. - **`attached_rule_sets`** _(array)_ Firewall rule sets attached at the boundary level. - **`id`** _(string)_ The target's `id`. - **`flow_logs_enabled`** _(boolean)_ Whether flow logging is on for this boundary. Flow logs can attach at boundary, subnet, or interface level; true requires the log to be ACTIVE and actually delivering, not just present. - **`flow_log_aggregation_interval_seconds`** _(integer)_ How long the provider batches records before writing them — a batching window, not a sampling fraction. Not the same as flow_log_sampling_rate. - **`flow_log_sampling_rate`** _(number)_ What fraction of traffic is captured, where the provider samples. Null with not_supported_by_provider on AWS, which has no sampling rate field or setting. - **`has_route_to_internet`** _(boolean)_ Whether the boundary can reach the internet, accounting for subnets implicitly associated with the main route table (not just explicit associations). - **`internet_route_type`** _(string)_ What kind of internet path exists — an internet gateway (inbound-capable) is a different finding from outbound-only NAT, and the two are kept distinct. Allowed: `none`, `internet_gateway`, `nat_only`, `ipv6_egress_only`, `unknown` - **`block_public_access_state`** _(string)_ Whether a boundary-wide public-access block overrides routing. A boundary can have an internet gateway route and still be unreachable because of this. - **`flow_log_destinations`** _(array)_ The log stores this network's flow logs are delivered to, as references to log_destinations (AWS: VPC Flow Logs delivered to CloudWatch Logs; the log group ARN from logDestination, else the group named by logGroupName in the calling account and region). How long the records are kept is the target's retention_days. Only the flow logs that flow_logs_enabled counts (network-level, active and delivering). Delivery to an object store is in flow_log_object_stores; delivery to a streaming service (AWS: Amazon Data Firehose) has no unified resource and no reference. A target in another account resolves only when that account is connected too. Empty when there are none; null when the flow-log read was refused (unreadable_fields says so). - **`id`** _(string)_ The target's `id`. - **`flow_log_object_stores`** _(array)_ The object stores (buckets) this network's flow logs are delivered to, as references to object_stores (AWS: VPC Flow Logs delivered to S3; the bucket ARN from logDestination, without the key prefix that may follow it). How long the records are kept is the target's retention_policy_days and lifecycle_rules. Only the flow logs that flow_logs_enabled counts (network-level, active and delivering). Delivery to a log store is in flow_log_destinations; delivery to a streaming service (AWS: Amazon Data Firehose) has no unified resource and no reference. A bucket in another account resolves only when that account is connected too. Empty when there are none; null when the flow-log read was refused (unreadable_fields says so). - **`id`** _(string)_ The target's `id`. ## Methods - [GET /unified/cloud-infrastructure/network_boundaries](/api-reference/unified-cloud-infrastructure-api/networkboundaries/list) — List Network boundaries --- # FirewallRuleSets Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/firewallrulesets/ Schema for the `FirewallRuleSets` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`rule_set_id`** _(string)_ The provider's own identifier for the rule set. - **`name`** _(string)_ The rule set name. - **`scope_type`** _(string)_ Which firewall primitive this is — the primitives have different semantics and available fields. Allowed: `security_group`, `network_acl`, `firewall_policy`, `firewall_rule`, `unknown` - **`is_stateful`** _(boolean)_ Whether return traffic is implicitly allowed. - **`supports_deny`** _(boolean)_ Whether this primitive can express a deny at all. False for AWS security groups (allow-only), where the rule's 'allow' action is a structural constant, not read from the provider. - **`is_ordered`** _(boolean)_ Whether rule order determines evaluation. False for AWS security groups, an unordered set evaluated as a union — array position is not a priority. - **`attached_to`** _(array)_ What this rule set is attached to, as provider references: for a subnet-level rule set, its subnets; for an interface-level one (a security group), the network interfaces using it when it was read - observed, not configured (see observed_attachment_only). Null when it was not read; unreadable_fields says why. - **`attached_boundary`** _(object)_ The network boundary this rule set belongs to. - **`id`** _(string)_ The target's `id`. - **`observed_attachment_only`** _(boolean)_ True when attached_to was observed from live interfaces rather than read from configuration — a point-in-time observation, not a stable config fact. - **`rules`** _(array)_ The rules in this set. Shape varies by rule set kind: ordered network ACL rules carry rule_number, security group rules do not. - **`direction`** _(string)_ Whether the rule governs inbound or outbound traffic. - **`action`** _(string)_ Allow or deny. Always allow where the provider has no deny primitive. - **`protocol`** _(string)_ The protocol, or a value meaning all protocols. - **`from_port`** _(integer)_ Lowest port in the range. For ICMP this is the type, not a port. - **`to_port`** _(integer)_ Highest port in the range. For ICMP this is the code, not a port. - **`all_ports`** _(boolean)_ Whether the rule covers every port, making the port range meaningless. - **`port_semantics`** _(string)_ How to read from_port and to_port: as ports, or as ICMP type and code. - **`icmp_type_and_code`** _(string)_ The ICMP type and code, where the protocol is ICMP. - **`cidrs`** _(array)_ Address ranges the rule matches. - **`ipv6_cidrs`** _(array)_ IPv6 address ranges the rule matches. Kept separate from cidrs because a rule can carry both and the two are not interchangeable. - **`source_group_ids`** _(array)_ Other rule sets the rule matches, where the provider allows that. - **`prefix_list_ids`** _(array)_ Provider-managed address lists the rule matches. - **`rule_number`** _(integer)_ Evaluation order, where the provider orders rules. Absent for unordered rule sets. - **`egress`** _(boolean)_ Set by network ACLs to mark an outbound rule. - **`description`** _(string)_ Free-text note carried on the rule. - **`rule_count`** _(integer)_ How many rules this set contains. - **`descriptions_supported`** _(boolean)_ Whether this primitive has a per-rule description field at all — distinct from a rule having no description. AWS security group rules have one; network ACL entries do not. - **`has_open_ingress_from_anywhere`** _(boolean)_ Whether any rule permits inbound traffic from the whole internet. Derived. ## Methods - [GET /unified/cloud-infrastructure/firewall_rule_sets](/api-reference/unified-cloud-infrastructure-api/firewallrulesets/list) — List Firewall rule sets --- # NetworkLinks Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/networklinks/ Schema for the `NetworkLinks` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`link_id`** _(string)_ The provider's own identifier for the link. - **`link_type`** _(string)_ What kind of connection this is. Allowed: `peering`, `transit_attachment`, `shared_network`, `vpn`, `interconnect`, `other` - **`local_boundary`** _(object)_ The network on this side of the link. - **`id`** _(string)_ The target's `id`. - **`remote_boundary`** _(object)_ The network on the far side of the link. Resolves only when the far side is an account this connection also reads. - **`id`** _(string)_ The target's `id`. - **`remote_account_id`** _(string)_ The account owning the far side of the link. Local/remote are assigned by account ownership, not by which side initiated the connection. - **`remote_region`** _(string)_ The region on the far side of the link. - **`state`** _(string)_ The provider's own state string for the link, verbatim. - **`routes_installed`** _(boolean)_ Whether routes actually exist for this link. An active peering state doesn't mean routes were added — that's a separate, manual step on AWS. - **`allows_transit`** _(boolean)_ Whether traffic can transit to a third network through this link. Always false for AWS VPC peering. For transit gateways, it's derived from associations and propagations combined, not one attachment field. - **`route_exchange_settings`** _(object)_ Route exchange configuration, where the provider has one. AWS VPC peering has no real equivalent (only a DNS-resolution option survives); null with not_supported_by_provider there. - **`allow_dns_resolution_from_remote_vpc`** _(boolean)_ AWS allowDnsResolutionFromRemoteVpc. Whether the remote network can resolve private DNS on this side. This is DNS, not routing - AWS VPC peering exchanges no routes automatically. - **`default_route_table_association`** _(boolean)_ For transit gateways, whether attachments associate with the default route table automatically. With default_route_table_propagation both true, every attached network can reach every other. - **`default_route_table_propagation`** _(boolean)_ For transit gateways, whether attachment routes propagate into the default route table automatically. ## Methods - [GET /unified/cloud-infrastructure/network_links](/api-reference/unified-cloud-infrastructure-api/networklinks/list) — List Network links --- # ManagedKeys Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/managedkeys/ Schema for the `ManagedKeys` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`key_id`** _(string)_ The provider's own identifier for the key. - **`alias_names`** _(array)_ Human-readable aliases for the key. - **`key_type`** _(string)_ The key's cryptographic type, as the provider names it. - **`key_spec`** _(string)_ The provider's own key specification string, verbatim. - **`managed_by`** _(string)_ Who manages the key: the provider, the customer, or an external key store. Allowed: `provider`, `customer`, `external`, `unknown` - **`origin`** _(string)_ Where the key material came from — generated in the key service, imported, or held in an external or hardware key store. - **`rotation_enabled`** _(boolean)_ Whether automatic rotation is on. Null (not false) when rotation doesn't apply to the key type at all — e.g. asymmetric, HMAC, and custom-key-store keys. - **`rotation_applicable`** _(boolean)_ Whether rotation is a meaningful question for this key type, so a null rotation_enabled isn't mistaken for missing data. - **`rotation_period_days`** _(integer)_ How often the key rotates, in days. A key with no rotation period never rotates — distinct from a missing field, which unreadable_fields declares with not_configured. - **`next_rotation_at`** _(string)_ When the key is next due to rotate. - **`protection_level`** _(string)_ Whether key material is held in software or in a hardware security module. - **`state`** _(string)_ The provider's own key state string, verbatim. - **`scheduled_destroy_at`** _(string)_ When the key is scheduled for destruction, where deletion is pending. - **`deletion_window_days`** _(integer)_ How long the provider waits before destroying a key scheduled for deletion. - **`policy_grants_anyone`** _(boolean)_ Whether the key policy grants use to anyone. A heuristic (absence of a scoping condition on a wildcard principal), not a provider fact. Doesn't account for grants, a separate authorization path, and cross-account policy reads are commonly permission_denied. - **`policy_scoping_conditions`** _(array)_ The condition keys found scoping the key policy's wildcard principal, if any. - **`key_policy_document`** _(string)_ The raw key policy document, where it could be read. - **`container_protection_settings`** _(object)_ Settings on the vault or key ring that prevent accidental deletion — purge protection, soft delete, deletion prevention. - **`multi_region`** _(boolean)_ Whether this key is part of a multi-region key set. Rotation is a shared property configured only on the primary key in the set. ## Methods - [GET /unified/cloud-infrastructure/managed_keys](/api-reference/unified-cloud-infrastructure-api/managedkeys/list) — List Managed keys --- # AuditTrailConfigs Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/audittrailconfigs/ Schema for the `AuditTrailConfigs` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`config_id`** _(string)_ The provider's own identifier for the trail or logging configuration. - **`config_kind`** _(string)_ Which audit mechanism this row describes. Allowed: `trail`, `event_data_store`, `diagnostic_setting`, `log_sink`, `other` - **`scope_type`** _(string)_ The level the configuration applies at. Allowed: `organisation`, `grouping`, `account`, `resource`, `unknown` - **`scope_id`** _(string)_ The provider reference for the scope. - **`enabled`** _(boolean)_ Whether the trail is actually recording. A trail can look complete (multi-region, encrypted, validated) yet be fully stopped, so this must be checked separately from the trail's description. - **`is_logging`** _(boolean)_ The provider's raw logging flag, kept separate from `enabled`. A value of true does not prove logs are arriving — a trail writing to a deleted destination can still report true. - **`covers_all_regions`** _(boolean)_ Whether the configuration captures every region rather than just one. - **`covers_whole_organisation`** _(boolean)_ Whether the configuration applies across the organisation rather than a single account. - **`log_categories_enabled`** _(array)_ Which categories of event are recorded, as the provider names them. - **`management_events_included`** _(boolean)_ Whether control-plane events are recorded. Not the whole answer on its own — see excluded_management_event_sources. - **`excluded_management_event_sources`** _(array)_ Management event sources excluded from the trail. Coverage is incomplete even when management_events_included is true, if sources appear here. - **`data_access_logging_by_service`** _(array)_ Per-service data-plane logging coverage, as the selectors that produced the answer. - **`type`** _(string)_ The resource type the selector matches. - **`values`** _(array)_ The selector values recorded for that type. - **`data_event_selector_type`** _(string)_ Which selector dialect produced data_access_logging_by_service. 'classic' lists resource types explicitly; 'advanced' is a predicate language that can't be fully evaluated offline. Allowed: `classic`, `advanced`, `none`, `unknown` - **`data_access_inference_confidence`** _(string)_ How confident Truto is in data_access_logging_by_service: exact, inferred, or unknown. Allowed: `exact`, `inferred`, `unknown` - **`destination`** _(object)_ Where the audit records are delivered. - **`id`** _(string)_ The target's `id`. - **`destination_type`** _(string)_ What kind of destination that is, as the provider names it. - **`tamper_evidence_enabled`** _(boolean)_ Whether the trail is cryptographically protected against alteration. Distinct from deletion protection: preventing deletion does not prove records weren't altered. - **`log_file_validation_enabled`** _(boolean)_ The provider's own integrity validation flag, carried separately. - **`encryption_key`** _(object)_ The customer-managed key protecting the audit records. Absent means the provider's own key. - **`id`** _(string)_ The target's `id`. ## Methods - [GET /unified/cloud-infrastructure/audit_trail_configs](/api-reference/unified-cloud-infrastructure-api/audittrailconfigs/list) — List Audit trail configs --- # PolicyConstraints Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/policyconstraints/ Schema for the `PolicyConstraints` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`policy_id`** _(string)_ The provider's own identifier for the policy. - **`policy_name`** _(string)_ The policy name as the provider names it. - **`display_name`** _(string)_ A friendlier name, distinct from policy_name, where the provider provides one. AWS service control policies have none, so this falls back to policy_name. - **`policy_type`** _(string)_ Which preventative policy mechanism this is, as the provider names it. - **`effect`** _(string)_ Whether the policy blocks, allows, or merely audits the action. AWS SCPs support only allow/deny (never audit) and effect is per statement, not per policy, since one policy can mix both. Allowed: `deny`, `allow`, `audit`, `modify`, `mixed`, `unknown` - **`supports_audit_mode`** _(boolean)_ Whether this policy mechanism can express a report-only mode at all. False here means audit mode doesn't exist for it, not that the customer chose not to use it. - **`scope_type`** _(string)_ The level this row's scope node sits at. Allowed: `organisation`, `grouping`, `account`, `resource`, `unknown` - **`scope_id`** _(string)_ The node this row reports the policy as applying to. - **`inherited_from`** _(object)_ The node the policy is actually attached to, when that differs from the node this row reports it for. - **`id`** _(string)_ The target's `id`. - **`is_inherited`** _(boolean)_ Whether this row is an inherited application rather than a direct attachment. - **`parameters`** _(object)_ Parameter values supplied when the policy is instantiated per assignment. Null with not_supported_by_provider for AWS service control policies, which are never parameterized. - **`allowed_values`** _(array)_ Values the policy permits, where the provider exposes them as structured data. Null (not guessed) for AWS service control policies, which don't expose this. - **`denied_values`** _(array)_ Values the policy forbids, on the same terms as allowed_values. - **`enforced`** _(boolean)_ Whether the policy is actually in force. AWS has no enabled toggle; this is derived from the policy type being enabled at the org root and the policy having at least one target. - **`has_local_override`** _(boolean)_ Whether a sub-account has opted out of an organisation-wide rule. Always false for AWS service control policies, which intersect and never allow a child to relax a parent. - **`policy_document`** _(string)_ The raw policy document, in the provider's native encoding. AWS SCP content is plain JSON (unlike IAM policy documents); decoding it as IAM will mangle it. ## Methods - [GET /unified/cloud-infrastructure/policy_constraints](/api-reference/unified-cloud-infrastructure-api/policyconstraints/list) — List Policy constraints --- # PolicyComplianceStates Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/policycompliancestates/ Schema for the `PolicyComplianceStates` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`policy_id`** _(string)_ The rule or policy this state belongs to. - **`policy_name`** _(string)_ The rule name as the provider names it. - **`scope_id`** _(string)_ The account, node or resource scope this state was evaluated for. - **`compliance_state`** _(string)_ The evaluation outcome. insufficient_data is distinct from compliant — one provider allows this value in results but rejects it as a filter. Allowed: `compliant`, `non_compliant`, `insufficient_data`, `not_applicable`, `unknown` - **`compliant_resource_count`** _(integer)_ How many resources satisfy the rule. - **`non_compliant_resource_count`** _(integer)_ How many resources violate the rule. See count_capped: the provider may return a ceiling rather than a true count. - **`count_capped`** _(boolean)_ Whether the counts are a provider-imposed ceiling rather than an exact count. - **`non_compliant_resource_ids`** _(array)_ The resources violating the rule. Only collected when opted in — see resource_ids_collected. - **`resource_ids_collected`** _(boolean)_ Whether non_compliant_resource_ids was actually gathered. False means an empty list reflects a collection choice, not a clean result. - **`last_evaluated_at`** _(string)_ When the rule was last evaluated by the provider, never Truto's fetch time. On AWS this comes from a separate evaluation-status call. - **`last_successful_evaluation_at`** _(string)_ The last evaluation that actually succeeded, as distinct from the last invocation. ## Methods - [GET /unified/cloud-infrastructure/policy_compliance_states](/api-reference/unified-cloud-infrastructure-api/policycompliancestates/list) — List Policy compliance states --- # ScanCoverages Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/scancoverages/ Schema for the `ScanCoverages` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`coverage_id`** _(string)_ Stable reference for this coverage row. - **`scanner_name`** _(string)_ Which scanning product this coverage describes. - **`resource_type`** _(string)_ The resource type being scanned, as the provider names it. - **`scan_type`** _(string)_ What kind of scan this is — for example package, code, network or data. - **`resources_in_scope`** _(integer)_ How many resources of this type exist in the account and region. - **`resources_scanned`** _(integer)_ How many of them the scanner actually covers. - **`resources_not_scanned`** _(integer)_ How many resources are not covered by the scanner. - **`coverage_percent`** _(number)_ Scanned as a proportion of in-scope, where both counts are known. Derived. - **`last_scan_at`** _(string)_ When the scanner last ran for this resource type. - **`counts_capped`** _(boolean)_ Whether the provider returned a ceiling rather than true counts — coverage_percent should not be read as exact in that case. - **`resource_id`** _(string)_ Per-resource rows only (granularity=resource): the covered resource, as the provider names it. Absent on aggregate rows. - **`scan_status`** _(string)_ Per-resource rows only: whether the scanner covers this resource. not_covered means its findings, or their absence, say nothing about it. covered includes a resource still waiting for its first scan, which has no result yet - scan_status_reason says which (on AWS PENDING_INITIAL_SCAN versus SUCCESSFUL). Absent on aggregate rows. Allowed: `covered`, `not_covered`, `unknown` - **`scan_status_reason`** _(string)_ Per-resource rows only: the provider's own reason for scan_status, verbatim (on AWS e.g. SUCCESSFUL, PENDING_INITIAL_SCAN, UNMANAGED_EC2_INSTANCE, UNSUPPORTED_RUNTIME, EXCLUDED_BY_TAG). ## Methods - [GET /unified/cloud-infrastructure/scan_coverages](/api-reference/unified-cloud-infrastructure-api/scancoverages/list) — List Scan coverages --- # VulnerabilityFindings Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/vulnerabilityfindings/ Schema for the `VulnerabilityFindings` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier — a full ARN, resource id, or self-link — passed through verbatim, never truncated or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is. 'global' marks resources with no region (e.g. IAM, a GCP VPC network). If the provider returns no location, the queried region is substituted and flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — e.g. 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them, with no case folding or normalization. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with offset. Not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`finding_id`** _(string)_ The provider's own identifier for the finding. - **`vulnerability_id`** _(string)_ The provider's own vulnerability identifier, verbatim. Distinct from cve_id, since not every finding has a CVE. - **`cve_id`** _(string)_ The CVE identifier, where the vulnerability has one. - **`title`** _(string)_ The provider's own title for the vulnerability. - **`severity`** _(string)_ Severity as the provider labelled it, verbatim. - **`cvss_score`** _(number)_ The CVSS base score. - **`epss_score`** _(number)_ Exploit prediction score, where the provider supplies one. - **`affected_resource_id`** _(string)_ The resource carrying the vulnerability. - **`resource_type`** _(string)_ The provider's own type string for the affected resource. - **`package_name`** _(string)_ The vulnerable package. - **`package_version`** _(string)_ The installed version of the vulnerable package. - **`file_path`** _(string)_ Where the vulnerable package was found on the resource, if the scanner reports it. - **`first_observed_at`** _(string)_ When the vulnerability was first detected. - **`last_observed_at`** _(string)_ When the vulnerability was most recently seen. - **`fix_available`** _(boolean)_ Whether a fix exists. Distinguishes 'not patched yet' from 'nothing to patch to'. - **`fixed_version`** _(string)_ The version that resolves the vulnerability. - **`state`** _(string)_ Whether the finding is still open. Allowed: `active`, `suppressed`, `closed`, `unknown` - **`exploit_available`** _(boolean)_ Whether a known exploit exists, where the provider reports it. - **`scanner_name`** _(string)_ Which scanning product produced this finding. - **`remediation_text`** _(string)_ The provider's remediation guidance. - **`affected_resource_unqualified_id`** _(string)_ affected_resource_id without a version or alias qualifier, for joining to the resource inventory. On AWS it differs only for Lambda, where Inspector names the qualified ARN (...:function:Name:$LATEST); otherwise it equals affected_resource_id. ## Methods - [GET /unified/cloud-infrastructure/vulnerability_findings](/api-reference/unified-cloud-infrastructure-api/vulnerabilityfindings/list) — List Vulnerability findings --- # LogDestinations Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/logdestinations/ Schema for the `LogDestinations` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Stable identifier for this destination. - **`provider_id`** _(string)_ The provider's own unbroken identifier for the destination. - **`provider`** _(string)_ Which cloud this came from. - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the destination is. 'global' for genuinely global resources. - **`native_type`** _(string)_ The provider's own type string. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them. - **`collected_at`** _(string)_ When this was actually read, not when it was asked for. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`destination_id`** _(string)_ The destination's provider reference. - **`destination_type`** _(string)_ What kind of sink this is: log_group, storage_bucket, workspace or log_sink. - **`name`** _(string)_ The destination's name as the customer sees it. - **`location`** _(string)_ Where the logs physically sit. Equal to region for a regional sink. - **`retention_days`** _(integer)_ How many days logs are kept. Null when the provider keeps them indefinitely - read retention_is_indefinite before treating null as unknown. - **`retention_is_indefinite`** _(boolean)_ Whether logs are kept forever because no retention period is set. True is a real answer, not a missing one. - **`retention_locked`** _(boolean)_ Whether retention can no longer be shortened or the logs deleted. - **`encryption_key`** _(object)_ The customer-managed key protecting the logs. Null means the provider's own key. - **`id`** _(string)_ The target's `id`. - **`per_table_retention`** _(array)_ Per-table retention overrides where the provider supports them. - **`table`** _(string)_ The table or stream the override applies to. - **`retention_days`** _(integer)_ Days kept for that table, overriding the destination default. - **`deletion_protection_enabled`** _(boolean)_ Whether the destination itself is protected from deletion. - **`stored_bytes`** _(integer)_ Bytes currently held, where the provider reports it. - **`log_class`** _(string)_ The provider's storage class for this destination, which can change what is queryable. - **`created_at`** _(string)_ When the destination was created, UTC ISO 8601. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/cloud-infrastructure/log_destinations](/api-reference/unified-cloud-infrastructure-api/logdestinations/list) — List Log destinations --- # BlockVolumes Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/blockvolumes/ Schema for the `BlockVolumes` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`volume_id`** _(string)_ The provider's own identifier for the volume, verbatim (an EBS vol- id, an Azure managed disk name, a GCP persistent disk name). On AWS, data_snapshots.source_resource_id holds this same vol- id for snapshots taken from the volume. - **`status`** _(string)_ The provider's own status string for the volume, verbatim (on AWS: creating, available, in-use, deleting, deleted or error). - **`attached`** _(boolean)_ Whether the volume is attached to at least one virtual machine or provider-managed host right now. An attachment still being made or removed counts as attached; false means the volume is unattached. - **`attachments`** _(array)_ Where the volume is attached. Empty means unattached. A volume with multi-attach turned on can list several. - **`instance_id`** _(string)_ The attached virtual machine, as the provider identifies it (an EC2 i- id, an Azure VM resource id, a GCP instance self-link). Null when the volume is attached to a provider-managed host the customer does not own, such as an AWS Fargate task; associated_resource_id then names what it serves. - **`associated_resource_id`** _(string)_ What the volume serves when it is attached to a provider-managed host instead of a customer virtual machine - on AWS, the ARN of the ECS or Fargate task. Null for an ordinary virtual machine attachment. - **`state`** _(string)_ The provider's own attachment state string, verbatim (on AWS: attaching, attached, detaching, detached or busy). - **`delete_on_termination`** _(boolean)_ Whether the volume is deleted when the virtual machine it is attached to is terminated. False means the volume and its data outlive the machine. - **`encryption_at_rest`** _(boolean)_ Whether the volume's data is encrypted at rest. - **`encryption_key_type`** _(string)_ Who manages the key that encrypts the volume. provider_owned: a key the provider holds outside the customer's account, with no key object the customer can see. provider_managed: the provider's default key that lives inside the customer's key service but that the customer cannot manage (for example an AWS managed aws/ key). customer_managed: a key the customer creates and controls in the key service. customer_supplied: raw key material the customer passes in with each request and the provider does not store (GCP CSEK). none: not encrypted at rest. unknown: encrypted, but who manages the key was not resolved - unreadable_fields says why. On AWS, DescribeVolumes names the key ARN but not whether it is the AWS managed aws/ebs key or a customer managed key, so an encrypted EBS volume reads unknown here; join encryption_key.id to managed_keys (managed_by) to resolve it. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `customer_supplied`, `none`, `unknown` - **`encryption_key`** _(object)_ The key that protects the volume at rest. Null when the volume is not encrypted, or when the provider names no key object the customer can see. - **`id`** _(string)_ The target's `id`. ## Methods - [GET /unified/cloud-infrastructure/block_volumes](/api-reference/unified-cloud-infrastructure-api/blockvolumes/list) — List Block volumes --- # DataWarehouses Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/datawarehouses/ Schema for the `DataWarehouses` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`warehouse_id`** _(string)_ The provider's own identifier for the data warehouse, verbatim (a Redshift cluster identifier, an Azure Synapse dedicated SQL pool name, a BigQuery dataset id). - **`status`** _(string)_ The provider's own status string for the data warehouse, verbatim (on AWS Redshift, for example available, paused, modifying or resizing). - **`public_network_access`** _(boolean)_ The provider's public-network-access flag, not proven reachability: true doesn't mean reachable, and false doesn't mean safe — actual exposure also depends on routing. - **`encryption_at_rest`** _(boolean)_ Whether the data warehouse's stored data is encrypted at rest. - **`encryption_key_type`** _(string)_ Who manages the key that encrypts the data warehouse at rest. provider_owned: a key the provider holds outside the customer's account, with no key object the customer can see. provider_managed: the provider's default key that lives inside the customer's key service but that the customer cannot manage (for example an AWS managed aws/ key). customer_managed: a key the customer creates and controls in the key service. none: not encrypted at rest. unknown: encrypted, but who manages the key was not resolved - unreadable_fields says why. On AWS, DescribeClusters names a KMS key ARN without saying whether it is the AWS managed aws/redshift key or a customer managed key (join encryption_key.id to managed_keys (managed_by) to resolve it), and names no key at all for the AWS owned default key. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `none`, `unknown` - **`encryption_key`** _(object)_ The key that protects the data warehouse at rest. Null when it is not encrypted, or when the provider names no key object the customer can see (for example an AWS owned key). - **`id`** _(string)_ The target's `id`. - **`backup_retention_days`** _(integer)_ How many days the provider keeps automatic (scheduled) snapshots or backups. 0 means automatic snapshots are turned off. On AWS Redshift this is AutomatedSnapshotRetentionPeriod. - **`manual_snapshot_retention_days`** _(integer)_ How many days a manual snapshot is kept by default before the provider deletes it. -1 means manual snapshots are kept until someone deletes them (the AWS default). This is the default for new manual snapshots only; snapshots already taken keep their own retention. On AWS Redshift this is ManualSnapshotRetentionPeriod. ## Methods - [GET /unified/cloud-infrastructure/data_warehouses](/api-reference/unified-cloud-infrastructure-api/datawarehouses/list) — List Data warehouses --- # FileSystems Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/filesystems/ Schema for the `FileSystems` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`file_system_id`** _(string)_ The provider's own identifier for the file system, verbatim (an EFS fs- id, an Azure file share name, a GCP Filestore instance name). - **`status`** _(string)_ The provider's own lifecycle state string for the file system, verbatim (on AWS EFS: creating, available, updating, deleting, deleted or error). - **`encryption_at_rest`** _(boolean)_ Whether the file system's data is encrypted at rest. Encryption in transit is a separate, client-side mount setting and is not reported here. - **`encryption_key_type`** _(string)_ Who manages the key that encrypts the file system at rest. provider_owned: a key the provider holds outside the customer's account, with no key object the customer can see. provider_managed: the provider's default key that lives inside the customer's key service but that the customer cannot manage (for example an AWS managed aws/ key). customer_managed: a key the customer creates and controls in the key service. none: not encrypted at rest. unknown: encrypted, but who manages the key was not resolved - unreadable_fields says why. On AWS, DescribeFileSystems names the key ARN but not whether it is the AWS managed aws/elasticfilesystem key or a customer managed key, so an encrypted EFS file system reads unknown here; join encryption_key.id to managed_keys (managed_by) to resolve it. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `none`, `unknown` - **`encryption_key`** _(object)_ The key that protects the file system at rest. Null when the file system is not encrypted, or when the provider names no key object the customer can see. - **`id`** _(string)_ The target's `id`. - **`automatic_backups_enabled`** _(boolean)_ Whether the provider's own automatic backup of this file system is on. On AWS this is the EFS backup policy (backups by AWS Backup's default plan): true only when its status is ENABLED, so a policy that is still turning on (ENABLING) reads false. A separate backup plan the customer built in AWS Backup can still cover a file system that reads false; that is not checked here. - **`backup_policy_status`** _(string)_ The provider's own automatic-backup status string, verbatim (on AWS EFS: ENABLED, ENABLING, DISABLED or DISABLING). Null when no backup policy exists or it could not be read - see unreadable_fields. ## Methods - [GET /unified/cloud-infrastructure/file_systems](/api-reference/unified-cloud-infrastructure-api/filesystems/list) — List File systems --- # MessageQueues Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/messagequeues/ Schema for the `MessageQueues` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The queue's name, as the provider shows it. - **`encryption_at_rest`** _(boolean)_ Whether messages are encrypted at rest. False only when the provider reports no server-side encryption at all. - **`encryption_key_type`** _(string)_ Who manages the key protecting messages at rest. provider_owned: a key the service holds outside the customer's key management service (SQS-managed SSE). provider_managed: a provider-created key inside the customer's account (aws/sqs). customer_managed: a key the customer creates and controls. none: no server-side encryption. unknown when the key is in the customer's key service but its owner could not be read - see unreadable_fields. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `none`, `unknown` - **`encryption_key`** _(object)_ The key protecting messages at rest, where it is a key in the customer's own key management service and its id could be resolved. - **`id`** _(string)_ The target's `id`. - **`policy_grants_anyone`** _(boolean)_ Whether the queue's access policy grants access to anyone. A heuristic (an Allow on a wildcard principal with no scoping condition), not a provider fact. Deny statements are not evaluated, so a policy that allows anyone and then denies everything outside a network boundary still reads true. - **`policy_scoping_conditions`** _(array)_ The condition keys found scoping the access policy's wildcard-principal Allow statements, if any. - **`dead_letter_queue`** _(object)_ The queue that receives the messages this queue could not get processed after max_delivery_attempts deliveries (its dead-letter queue), as a reference to that queue's own row (AWS SQS: RedrivePolicy.deadLetterTargetArn). Null when none is set. On GCP Pub/Sub the dead-letter target is a topic (deadLetterPolicy.deadLetterTopic), not a queue, so this is null there. On Azure Service Bus every queue has a built-in dead-letter sub-queue that is not a row of its own, so this names a queue only when dead-lettered messages are forwarded to one (ForwardDeadLetteredMessagesTo), and is null otherwise. When the queue's settings could not be read, unreadable_fields says so. - **`id`** _(string)_ The target's `id`. - **`max_delivery_attempts`** _(integer)_ How many times a message is delivered without being processed before it is moved to the dead-letter queue (AWS SQS: RedrivePolicy.maxReceiveCount; GCP Pub/Sub: deadLetterPolicy.maxDeliveryAttempts; Azure Service Bus: MaxDeliveryCount, set on every queue, after which messages go to its built-in dead-letter sub-queue). Null when none is set. When the queue's settings could not be read, unreadable_fields says so. ## Methods - [GET /unified/cloud-infrastructure/message_queues](/api-reference/unified-cloud-infrastructure-api/messagequeues/list) — List Message queues --- # NosqlTables Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/nosqltables/ Schema for the `NosqlTables` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The table's name, as the provider shows it. - **`state`** _(string)_ The provider's own table state string, verbatim. - **`encryption_at_rest`** _(boolean)_ Whether table data is encrypted at rest. On AWS this is always true: DynamoDB encrypts every table and it cannot be turned off, so the question that matters is encryption_key_type. - **`encryption_key_type`** _(string)_ Who manages the key protecting the table at rest. provider_owned: a multi-tenant key the service holds outside the customer's key management service (the DynamoDB default). provider_managed: a provider-created key inside the customer's account (aws/dynamodb). customer_managed: a key the customer creates and controls. unknown when the key is in the customer's key service but its owner could not be read - see unreadable_fields. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `none`, `unknown` - **`encryption_key`** _(object)_ The key protecting the table at rest, where it is a key in the customer's own key management service. Null for a provider-owned key, which has no managed_keys row. - **`id`** _(string)_ The target's `id`. - **`point_in_time_recovery`** _(boolean)_ Whether point-in-time restore is enabled for the table. - **`backup_retention_days`** _(integer)_ How many days of continuous backups are kept, i.e. how far back point-in-time recovery reaches. 0 when point-in-time recovery is off. On-demand backups are kept until deleted and are not counted here. - **`latest_restorable_time`** _(string)_ The most recent point the table could be restored to. - **`deletion_protection`** _(boolean)_ Whether the table is protected against deletion. - **`replica_locations`** _(array)_ Regions, other than this table's own, holding replicas of this table. An empty array means the table is not replicated. - **`replicas`** _(array)_ The replica tables themselves, one per region in replica_locations. - **`id`** _(string)_ The target's `id`. ## Methods - [GET /unified/cloud-infrastructure/nosql_tables](/api-reference/unified-cloud-infrastructure-api/nosqltables/list) — List Nosql tables --- # ComputeInstances Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/computeinstances/ Schema for the `ComputeInstances` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`instance_id`** _(string)_ The provider's own identifier for the machine, verbatim (an EC2 i- id, an Azure VM resource id, a GCP instance id). - **`name`** _(string)_ The display name: on AWS the Name tag, which is optional, so null means the instance has no Name tag. - **`state`** _(string)_ Lifecycle state, normalised. On AWS shutting-down is 'terminating'. Terminated EC2 instances stay listed for about an hour. The provider's own value is in remote_data. Allowed: `pending`, `running`, `stopping`, `stopped`, `terminating`, `terminated`, `unknown` - **`instance_type`** _(string)_ The provider's size or machine type, verbatim (t3.micro, Standard_D2s_v3, e2-medium). - **`os_family`** _(string)_ Operating system family. linux_unix covers Linux and other Unix-like systems; unknown when the provider does not say. The provider's own value is in remote_data. Allowed: `windows`, `linux_unix`, `macos`, `unknown` - **`private_ip_addresses`** _(array)_ Every private IPv4 address on any of the machine's network interfaces. - **`public_ip_addresses`** _(array)_ Every public IPv4 address on any network interface, including addresses on secondary private IPs. Empty means no public IPv4. - **`ipv6_addresses`** _(array)_ IPv6 addresses on any network interface. These are globally unique; whether they are reachable from the internet depends on routing and firewall rules. - **`has_public_ip`** _(boolean)_ Whether any network interface has a public IPv4 address. - **`network_boundary`** _(object)_ The VPC / virtual network the machine sits in. - **`id`** _(string)_ The target's `id`. - **`subnet_id`** _(string)_ The subnet of the primary network interface, verbatim. - **`availability_zone`** _(string)_ The zone the machine runs in. - **`attached_rule_sets`** _(array)_ Security groups on the machine and on every one of its network interfaces. - **`id`** _(string)_ The target's `id`. - **`machine_identity_id`** _(string)_ The identity the machine runs as, verbatim: on AWS the instance profile ARN (an instance profile holds one IAM role; it is not the role ARN workload_identities is keyed on), on Azure the managed identity, on GCP the service account. Null when the machine has none. - **`metadata_service`** _(object)_ The instance metadata service (IMDS) settings. Null when the provider did not return them - see unreadable_fields. - **`enabled`** _(boolean)_ Whether the metadata endpoint answers at all. - **`token_required`** _(boolean)_ Whether every metadata request must carry a session token. On AWS true is IMDSv2-only (httpTokens required); false still answers IMDSv1 requests without a token. - **`hop_limit`** _(integer)_ How many network hops a metadata response may travel. Above 1, containers on the host can reach the endpoint. - **`image_id`** _(string)_ The image the machine was launched from, verbatim (an AMI id on AWS). - **`image`** _(object)_ The image the machine was launched from. machine_images lists only images the account owns, so an Amazon, Marketplace or other shared image does not resolve there; GET machine_images/{id} still reads it. - **`id`** _(string)_ The target's `id`. - **`launched_at`** _(string)_ When the machine last started. On AWS this moves on every stop and start, so it is not a creation date. - **`is_managed`** _(boolean)_ Whether a fleet-management service (AWS Systems Manager, Azure Arc or Update Manager, GCP VM Manager) currently registers the machine as a managed node. On AWS, Systems Manager does not report stopped instances, so a stopped instance reads false even when it is registered. Read on GET only. - **`managed_instance`** _(object)_ The managed-node record for this machine, when is_managed is true. Read on GET only. - **`id`** _(string)_ The target's `id`. ## Methods - [GET /unified/cloud-infrastructure/compute_instances/{id}](/api-reference/unified-cloud-infrastructure-api/computeinstances/get) — Get Compute instances - [GET /unified/cloud-infrastructure/compute_instances](/api-reference/unified-cloud-infrastructure-api/computeinstances/list) — List Compute instances --- # ServerlessFunctions Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/serverlessfunctions/ Schema for the `ServerlessFunctions` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The function's name, verbatim. - **`runtime`** _(string)_ The language runtime identifier, verbatim (nodejs22.x, python3.12). Null for a container-image function, which has no managed runtime. - **`handler`** _(string)_ The entry point the platform calls. Null for a container-image function. - **`package_type`** _(string)_ How the code is packaged: a zip archive or a container image. The provider's own value is in remote_data. Allowed: `archive`, `container_image`, `unknown` - **`memory_mb`** _(integer)_ Memory available to the function, in MB. - **`timeout_seconds`** _(integer)_ How long one invocation may run before it is stopped. - **`architectures`** _(array)_ Instruction set architectures, verbatim (x86_64, arm64). - **`execution_role`** _(object)_ The identity the function runs as (on AWS the execution role). - **`id`** _(string)_ The target's `id`. - **`environment_variable_names`** _(array)_ Names of the environment variables set on the function. Values are never read into this row or into remote_data, because they often hold credentials. - **`encryption_key`** _(object)_ The customer managed key that encrypts the function's environment variables. Null when the provider's default key is used. - **`id`** _(string)_ The target's `id`. - **`network_boundary`** _(object)_ The VPC / virtual network the function is attached to. Null when it runs on the provider network with no VPC attachment. - **`id`** _(string)_ The target's `id`. - **`subnet_ids`** _(array)_ Subnets of the VPC attachment. Empty with no VPC attachment. - **`attached_rule_sets`** _(array)_ Security groups of the VPC attachment. - **`id`** _(string)_ The target's `id`. - **`tracing_enabled`** _(boolean)_ Whether active request tracing is on (on AWS, X-Ray Active mode). - **`dead_letter_target_id`** _(string)_ Where failed asynchronous invocations go (an SQS queue or SNS topic ARN on AWS). Null when none is set. - **`layers`** _(array)_ Layer ARNs attached to the function. - **`log_destination`** _(object)_ The log group the function writes to (on AWS the CloudWatch Logs group from its logging configuration, by default /aws/lambda/). The provider creates it on the first invocation, so this can name a log group that does not exist yet. - **`id`** _(string)_ The target's `id`. - **`state`** _(string)_ Lifecycle state, normalised. pending: being created or having resources set up; active: ready to invoke; inactive: idle long enough that the provider reclaimed its resources (the next invocation re-activates it); failed: creation or a resource update failed. Read on GET (on AWS the list does not return it). The provider's own value is in remote_data. Allowed: `pending`, `active`, `inactive`, `failed`, `unknown` - **`code_sha256`** _(string)_ Hash of the deployment package, as the provider reports it. ## Methods - [GET /unified/cloud-infrastructure/serverless_functions/{id}](/api-reference/unified-cloud-infrastructure-api/serverlessfunctions/get) — Get Serverless functions - [GET /unified/cloud-infrastructure/serverless_functions](/api-reference/unified-cloud-infrastructure-api/serverlessfunctions/list) — List Serverless functions --- # InstanceGroups Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/instancegroups/ Schema for the `InstanceGroups` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The group's name, verbatim. - **`min_size`** _(integer)_ Fewest machines the group keeps. - **`max_size`** _(integer)_ Most machines the group may run. - **`desired_size`** _(integer)_ How many machines the group is trying to run right now. - **`availability_zones`** _(array)_ Zones the group may launch into. - **`subnet_ids`** _(array)_ Subnets the group launches into. - **`health_check_types`** _(array)_ Health checks that decide when a machine is replaced, normalised. instance: the provider's machine status checks (on AWS EC2); load_balancer: load balancer target health (ELB); service_network: service network target health (VPC Lattice); block_volume: attached volume health (EBS). instance alone means a machine failing a load balancer check is not replaced. The provider's own value is in remote_data. - **`health_check_grace_period_seconds`** _(integer)_ How long a new machine is spared from health checks. - **`launch_template_id`** _(string)_ The launch template the group launches from (on AWS an lt- id, also when it comes from a mixed instances policy). Null when the group uses a legacy launch configuration. - **`launch_template_version`** _(string)_ The template version the group uses, verbatim ($Latest, $Default or a number on AWS). - **`uses_legacy_launch_configuration`** _(boolean)_ Whether the group launches from a legacy launch definition the provider no longer extends (an AWS launch configuration). False on providers without one. - **`instances`** _(array)_ Machines currently in the group. - **`instance`** _(object)_ The machine. - **`id`** _(string)_ The target's `id`. - **`instance_id`** _(string)_ The machine's own id, verbatim. - **`availability_zone`** _(string)_ Zone the machine runs in. - **`instance_type`** _(string)_ Machine type, verbatim. - **`health_status`** _(string)_ The group's health verdict for the machine. The provider's own value is in remote_data. Allowed: `healthy`, `unhealthy`, `unknown` - **`lifecycle_state`** _(string)_ Where the machine is in the group lifecycle, normalised. pending and terminating include their lifecycle-hook wait steps; warm_pool: a pre-initialised machine in the warm pool; standby: taken out of service but kept in the group. The provider's own value is in remote_data. Allowed: `pending`, `in_service`, `standby`, `detaching`, `detached`, `terminating`, `terminated`, `warm_pool`, `unknown` - **`protected_from_scale_in`** _(boolean)_ Whether scale-in may not remove this machine. - **`load_balancer_target_ids`** _(array)_ Load balancer target groups (ARNs) and classic load balancer names the group registers its machines with. - **`suspended_processes`** _(array)_ Scaling processes that are suspended, verbatim (Launch, Terminate, HealthCheck, ReplaceUnhealthy ... on AWS). A suspended HealthCheck or ReplaceUnhealthy stops unhealthy machines being replaced. - **`service_role`** _(object)_ The identity the scaling service acts as (on AWS the service-linked role). - **`id`** _(string)_ The target's `id`. - **`status`** _(string)_ deleting while the group is being deleted; null otherwise. The provider's own value is in remote_data. Allowed: `deleting`, `unknown` ## Methods - [GET /unified/cloud-infrastructure/instance_groups/{id}](/api-reference/unified-cloud-infrastructure-api/instancegroups/get) — Get Instance groups - [GET /unified/cloud-infrastructure/instance_groups](/api-reference/unified-cloud-infrastructure-api/instancegroups/list) — List Instance groups --- # MonitoringAlarms Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/monitoringalarms/ Schema for the `MonitoringAlarms` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The alarm's name, verbatim. - **`alarm_type`** _(string)_ metric: watches one metric or a metric expression. composite: combines other alarms through a rule. The list reads one type per call (alarm_type query parameter). The provider's own value is in remote_data. Allowed: `metric`, `composite` - **`description`** _(string)_ The alarm's description, verbatim. - **`state`** _(string)_ Current alarm state. The provider's own value is in remote_data. Allowed: `ok`, `alarm`, `insufficient_data`, `unknown` - **`state_reason`** _(string)_ Why the alarm is in its state, as the provider words it. - **`state_updated_at`** _(string)_ When the state last changed. - **`actions_enabled`** _(boolean)_ Whether the alarm runs its actions. False means it changes state silently. - **`metrics`** _(array)_ What a metric alarm watches: one entry for a single-metric alarm, or every metric and expression of a metric-math alarm. Empty for a composite alarm. - **`id`** _(string)_ The entry's id inside a metric-math alarm. Null for a single-metric alarm. - **`expression`** _(string)_ A metric-math expression. Null for a plain metric. - **`namespace`** _(string)_ Metric namespace, verbatim (AWS/EC2, or a log metric filter's namespace). - **`name`** _(string)_ Metric name, verbatim. - **`dimensions`** _(object)_ Dimension name to value, exactly as set. - **`statistic`** _(string)_ Statistic or percentile, verbatim (Average, Sum, p99 ...). - **`period_seconds`** _(integer)_ Aggregation period in seconds. - **`returns_data`** _(boolean)_ Whether this entry is the value the alarm evaluates. - **`comparison_operator`** _(string)_ How the value is compared, normalised. outside_band, below_band and above_band compare against an anomaly-detection band instead of a threshold. Null for a composite alarm. The provider's own value is in remote_data. Allowed: `greater_than_or_equal`, `greater_than`, `less_than`, `less_than_or_equal`, `outside_band`, `below_band`, `above_band`, `unknown` - **`threshold`** _(number)_ The threshold. Null for a composite alarm, or a band alarm that compares against another metric. - **`evaluation_periods`** _(integer)_ How many periods are evaluated. - **`datapoints_to_alarm`** _(integer)_ How many breaching periods within evaluation_periods make the alarm fire. - **`period_seconds`** _(integer)_ Evaluation period of a single-metric alarm. - **`treat_missing_data`** _(string)_ What missing data points count as. missing: the alarm looks further back for enough points; ignore: the current state is kept. Null for a composite alarm. The provider's own value is in remote_data. Allowed: `missing`, `not_breaching`, `breaching`, `ignore`, `unknown` - **`rule`** _(string)_ A composite alarm's rule expression, verbatim. Null for a metric alarm. - **`actions`** _(array)_ What the alarm does on each state change. - **`on_state`** _(string)_ The state change that triggers this action. The provider's own value is in remote_data. Allowed: `alarm`, `ok`, `insufficient_data` - **`target_id`** _(string)_ The action target, verbatim (an ARN on AWS). - **`target_type`** _(string)_ What kind of target it is. notification_topic: a pub/sub topic (SNS); scaling_policy: an autoscaling policy; instance_action: stop, terminate, reboot or recover a machine; incident_management: an OpsItem or incident; function: a serverless function. The provider's own value is in remote_data. Allowed: `notification_topic`, `scaling_policy`, `instance_action`, `incident_management`, `function`, `other` - **`notification_topic`** _(object)_ The topic, when target_type is notification_topic. - **`id`** _(string)_ The target's `id`. - **`has_confirmed_subscriber`** _(boolean)_ For a notification topic: whether it has at least one confirmed subscription. Null for other targets, and for a topic that was not read: one in another account, or a read that failed (for an ALARM-state topic the notifies_confirmed_subscriber entry in unreadable_fields says which). Read on GET, or on the list with fields[]=notifies_confirmed_subscriber. - **`notifies_confirmed_subscriber`** _(boolean)_ Whether the alarm, when it fires, reaches at least one person or system: actions are enabled and at least one ALARM-state action is a notification topic with a confirmed subscription. False when actions are disabled or no ALARM-state action is a topic. Null when a topic could not be read. Read on GET, or on the list with fields[]=notifies_confirmed_subscriber. ## Methods - [GET /unified/cloud-infrastructure/monitoring_alarms/{id}](/api-reference/unified-cloud-infrastructure-api/monitoringalarms/get) — Get Monitoring alarms - [GET /unified/cloud-infrastructure/monitoring_alarms](/api-reference/unified-cloud-infrastructure-api/monitoringalarms/list) — List Monitoring alarms --- # NotificationTopics Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/notificationtopics/ Schema for the `NotificationTopics` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The topic's name, verbatim. - **`is_fifo`** _(boolean)_ Whether the topic is a FIFO (ordered, exactly-once) topic. - **`display_name`** _(string)_ The sender name shown on email notifications. Null when none is set. - **`encryption_at_rest`** _(boolean)_ Whether messages are encrypted at rest with a key the customer can see. - **`encryption_key_type`** _(string)_ Who manages the key that encrypts the topic. provider_managed: the provider's default key inside the customer's key service (on AWS the AWS managed alias/aws/sns key). customer_managed: a key the customer creates and controls. none: not encrypted at rest. unknown: encrypted, but the provider named a bare key id or key ARN, which does not say who manages it; join encryption_key.id to managed_keys (managed_by) to resolve it. Null when the topic attributes were not read. The provider's own value is in remote_data. Allowed: `provider_managed`, `provider_owned`, `customer_managed`, `customer_supplied`, `none`, `unknown` - **`encryption_key`** _(object)_ The key that encrypts the topic. Null when not encrypted, or when the provider names only an alias or bare key id - see unreadable_fields. - **`id`** _(string)_ The target's `id`. - **`subscriptions_confirmed`** _(integer)_ Confirmed subscriptions: endpoints that will receive messages. - **`subscriptions_pending`** _(integer)_ Subscriptions waiting for the endpoint to confirm. They receive nothing until then. - **`has_confirmed_subscriber`** _(boolean)_ Whether at least one subscription is confirmed. False means a message published to the topic reaches no one. ## Methods - [GET /unified/cloud-infrastructure/notification_topics/{id}](/api-reference/unified-cloud-infrastructure-api/notificationtopics/get) — Get Notification topics - [GET /unified/cloud-infrastructure/notification_topics](/api-reference/unified-cloud-infrastructure-api/notificationtopics/list) — List Notification topics --- # MachineImages Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/machineimages/ Schema for the `MachineImages` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`image_id`** _(string)_ The provider's own image id, verbatim (an ami- id on AWS). - **`name`** _(string)_ The image's name, verbatim. - **`description`** _(string)_ The image's description, verbatim. - **`state`** _(string)_ Image state, normalised. disabled: kept but cannot be launched; deregistered: deleted (the provider shows it for a short while). The provider's own value is in remote_data. Allowed: `pending`, `available`, `failed`, `disabled`, `deregistered`, `unknown` - **`is_public`** _(boolean)_ Whether anyone, in any account, can launch the image. - **`shared_with_accounts`** _(array)_ Accounts the image is shared with. Not collected on AWS (see unreadable_fields). - **`architecture`** _(string)_ Instruction set architecture, verbatim (x86_64, arm64). - **`os_family`** _(string)_ Operating system family. linux_unix covers Linux and other Unix-like systems; unknown when the provider does not say. The provider's own value is in remote_data. Allowed: `windows`, `linux_unix`, `macos`, `unknown` - **`root_device_type`** _(string)_ What the root disk is. block_volume: a persistent block volume (EBS on AWS); instance_store: a disk on the host, lost when the machine stops. The provider's own value is in remote_data. Allowed: `block_volume`, `instance_store`, `unknown` - **`virtualization_type`** _(string)_ Virtualization type, verbatim (hvm, paravirtual on AWS). - **`boot_mode`** _(string)_ Firmware the image boots with. uefi_preferred: UEFI where the machine type supports it, else BIOS. Null when the image does not set one. The provider's own value is in remote_data. Allowed: `bios`, `uefi`, `uefi_preferred`, `unknown` - **`requires_metadata_token`** _(boolean)_ Whether machines launched from the image require metadata-service session tokens by default (on AWS, imdsSupport v2.0). - **`encryption_at_rest`** _(boolean)_ Whether every disk snapshot in the image is encrypted. Null for an image with no snapshot-backed disk (instance-store). - **`source_image_id`** _(string)_ The image this one was copied from, verbatim. Null when it was not copied. - **`deprecated_at`** _(string)_ When the image is or was deprecated. Null when no deprecation is set. - **`last_launched_at`** _(string)_ When a machine was last launched from the image, as the provider records it (on AWS this lags by up to 24 hours). ## Methods - [GET /unified/cloud-infrastructure/machine_images/{id}](/api-reference/unified-cloud-infrastructure-api/machineimages/get) — Get Machine images - [GET /unified/cloud-infrastructure/machine_images](/api-reference/unified-cloud-infrastructure-api/machineimages/list) — List Machine images --- # ManagedInstances Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/managedinstances/ Schema for the `ManagedInstances` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`node_id`** _(string)_ The managed node's id, verbatim (an EC2 i- id or a hybrid mi- id on AWS). - **`compute_instance`** _(object)_ The virtual machine this node is, when it is one of the provider's own machines. Null for an on-premises or other-cloud node. - **`id`** _(string)_ The target's `id`. - **`name`** _(string)_ The node name, else the computer name the agent reports. - **`computer_name`** _(string)_ The host name the agent reports. - **`agent_status`** _(string)_ Whether the agent is checking in. connection_lost: it stopped checking in; inactive: a hybrid node that is deregistered or not running. The provider's own value is in remote_data. Allowed: `online`, `connection_lost`, `inactive`, `unknown` - **`last_seen_at`** _(string)_ When the agent last checked in. - **`agent_version`** _(string)_ Agent version, verbatim. - **`agent_is_latest`** _(boolean)_ Whether the agent is the newest version the provider offers. - **`os_family`** _(string)_ Operating system family. linux_unix covers Linux and other Unix-like systems; unknown when the provider does not say. The provider's own value is in remote_data. Allowed: `windows`, `linux_unix`, `macos`, `unknown` - **`os_name`** _(string)_ OS name, verbatim. - **`os_version`** _(string)_ OS version, verbatim. - **`ip_address`** _(string)_ IP address the agent reports. - **`association_status`** _(string)_ Combined status of the configuration associations applied to the node. The provider's own value is in remote_data. Allowed: `success`, `failed`, `pending`, `unknown` ## Methods - [GET /unified/cloud-infrastructure/managed_instances](/api-reference/unified-cloud-infrastructure-api/managedinstances/list) — List Managed instances --- # ContainerClusters Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/containerclusters/ Schema for the `ContainerClusters` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The cluster name, verbatim. - **`status`** _(string)_ Lifecycle state, normalised. On AWS ECS: PROVISIONING is creating, DEPROVISIONING is deleting, INACTIVE is deleted (a deleted cluster stays listed for a while). provider_status has the provider's value verbatim. Allowed: `creating`, `active`, `deleting`, `deleted`, `failed`, `unknown` - **`provider_status`** _(string)_ The provider's own lifecycle state string, verbatim (on AWS ECS: ACTIVE, PROVISIONING, DEPROVISIONING, FAILED, INACTIVE). - **`monitoring_enabled`** _(boolean)_ Whether the provider's container monitoring is on for the cluster. On AWS this is CloudWatch Container Insights: true when the containerInsights setting is enabled or enhanced. - **`monitoring_level`** _(string)_ The provider's own monitoring setting, verbatim (on AWS ECS: the containerInsights value - enabled, enhanced or disabled). - **`exec_logging`** _(string)_ How interactive exec sessions into containers are logged, the provider's own value verbatim (on AWS ECS: the ECS Exec logging setting - DEFAULT, NONE or OVERRIDE). Null when the cluster has no exec configuration - see unreadable_fields. - **`exec_encryption_key`** _(object)_ The key that encrypts exec session data between the client and the container. Null when none is set. - **`id`** _(string)_ The target's `id`. - **`capacity_providers`** _(array)_ Names of the capacity pools attached to the cluster, verbatim. On AWS ECS: capacity providers - FARGATE, FARGATE_SPOT, or customer-named Auto Scaling group and Managed Instances providers. - **`active_service_count`** _(integer)_ Number of services in an active state. - **`running_task_count`** _(integer)_ Number of tasks in the running state. - **`pending_task_count`** _(integer)_ Number of tasks in the pending state. - **`registered_instance_count`** _(integer)_ Number of container instances (servers) registered to the cluster. 0 for serverless-only clusters. ## Methods - [GET /unified/cloud-infrastructure/container_clusters/{id}](/api-reference/unified-cloud-infrastructure-api/containerclusters/get) — Get Container clusters - [GET /unified/cloud-infrastructure/container_clusters](/api-reference/unified-cloud-infrastructure-api/containerclusters/list) — List Container clusters --- # ContainerServices Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/containerservices/ Schema for the `ContainerServices` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The service name, verbatim. - **`status`** _(string)_ State, normalised. On AWS ECS: DRAINING (the service is being deleted) is deleting, INACTIVE is deleted. provider_status has the provider's value verbatim. Allowed: `active`, `deleting`, `deleted`, `unknown` - **`provider_status`** _(string)_ The provider's own state string, verbatim (on AWS ECS: ACTIVE, DRAINING or INACTIVE). - **`cluster`** _(object)_ The container cluster this object runs in. - **`id`** _(string)_ The target's `id`. - **`task_definition`** _(object)_ The task definition revision the service runs. GET container_task_definitions with this id to read that exact revision. - **`id`** _(string)_ The target's `id`. - **`compute_type`** _(string)_ Where the tasks run, normalised. serverless: the provider runs the machines (AWS Fargate, Azure Container Apps consumption, GCP Cloud Run). customer_managed_servers: servers in the customer's account that the customer runs (on AWS ECS: EC2 container instances). provider_managed_servers: servers in the customer's account that the provider patches and scales (on AWS: ECS Managed Instances). external_servers: the customer's own servers outside the cloud (on AWS: ECS Anywhere). unknown: the service uses capacity providers whose kind is not read here (only FARGATE and FARGATE_SPOT are known to be serverless), or no launch type and no strategy (the cluster default applies) - see unreadable_fields. Allowed: `serverless`, `customer_managed_servers`, `provider_managed_servers`, `external_servers`, `unknown` - **`provider_launch_type`** _(string)_ The provider's own launch type, verbatim (on AWS ECS: EC2, FARGATE, EXTERNAL or MANAGED_INSTANCES). Null when the service uses a capacity provider strategy instead - see capacity_providers. - **`capacity_providers`** _(array)_ Capacity pools in the service's capacity provider strategy, verbatim (on AWS ECS: FARGATE, FARGATE_SPOT or customer-named providers). Empty when the service uses a launch type. - **`platform_version`** _(string)_ The serverless platform version, verbatim (AWS Fargate only). - **`desired_size`** _(integer)_ Number of tasks the service is meant to keep running. - **`running_count`** _(integer)_ Number of tasks in the running state. - **`pending_count`** _(integer)_ Number of tasks in the pending state. - **`assign_public_ip`** _(boolean)_ Whether tasks get a public IP address on their network interface. Null when the service does not use per-task networking (awsvpc), where the host's network decides. - **`subnet_ids`** _(array)_ Subnets the tasks are placed in (per-task networking, awsvpc). - **`attached_rule_sets`** _(array)_ The firewall rule sets (security groups) attached to the tasks' network interfaces (awsvpc networking). - **`id`** _(string)_ The target's `id`. - **`exec_enabled`** _(boolean)_ Whether interactive exec into the running containers is turned on (on AWS: ECS Exec, enableExecuteCommand). - **`load_balancer_target_ids`** _(array)_ Load balancer target groups (ARNs) the service registers its tasks with. ## Methods - [GET /unified/cloud-infrastructure/container_services/{id}](/api-reference/unified-cloud-infrastructure-api/containerservices/get) — Get Container services - [GET /unified/cloud-infrastructure/container_services](/api-reference/unified-cloud-infrastructure-api/containerservices/list) — List Container services --- # ContainerTaskDefinitions Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions/ Schema for the `ContainerTaskDefinitions` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The task definition name, shared by all its revisions (on AWS ECS: the family). - **`revision`** _(integer)_ The revision number within the definition. - **`status`** _(string)_ State of this revision, normalised. inactive: deregistered - tasks already running keep it, but no new task or service can start from it. deleting: on AWS ECS, DELETE_IN_PROGRESS. provider_status has the provider's value verbatim. Allowed: `active`, `inactive`, `deleting`, `unknown` - **`provider_status`** _(string)_ The provider's own status string, verbatim (on AWS ECS: ACTIVE, INACTIVE or DELETE_IN_PROGRESS). - **`task_role`** _(object)_ The role the containers' application code runs as. - **`id`** _(string)_ The target's `id`. - **`execution_role`** _(object)_ The role the container agent uses to pull images and read secrets for the task. - **`id`** _(string)_ The target's `id`. - **`network_mode`** _(string)_ Container networking, normalised. per_task_interface: every task gets its own network interface, subnet and security groups (on AWS ECS: awsvpc). bridge: containers reach the network through a virtual bridge on the host (on AWS ECS: bridge, and default on Windows). host: containers use the host's network directly. none: no external networking. Null when not set (on AWS ECS the Linux default is then bridge). provider_network_mode has the value verbatim. Allowed: `per_task_interface`, `bridge`, `host`, `none`, `unknown` - **`provider_network_mode`** _(string)_ The networking mode, verbatim (on AWS ECS: awsvpc, bridge, host, none or default). Null when not set. - **`compatible_compute_types`** _(array)_ The compute types (as in container_services.compute_type) the definition is validated to run on. On AWS ECS from requiresCompatibilities, verbatim in remote_data. serverless: the provider runs the machines (AWS Fargate, Azure Container Apps consumption, GCP Cloud Run). customer_managed_servers: servers in the customer's account that the customer runs (on AWS ECS: EC2 container instances). provider_managed_servers: servers in the customer's account that the provider patches and scales (on AWS: ECS Managed Instances). external_servers: the customer's own servers outside the cloud (on AWS: ECS Anywhere). - **`cpu`** _(string)_ Task-level CPU, verbatim. - **`memory`** _(string)_ Task-level memory, verbatim. - **`shares_host_pid`** _(boolean)_ Whether the containers share the host's process namespace, so they can see and signal every process on the host (on AWS ECS: pidMode host). False when not set: the provider default is a private namespace. - **`shares_host_ipc`** _(boolean)_ Whether the containers share the host's IPC namespace (shared memory, semaphores) (on AWS ECS: ipcMode host). Null when not set: the container host's Docker daemon setting then decides. - **`containers`** _(array)_ The containers in the definition. - **`name`** _(string)_ Container name. - **`image`** _(string)_ Image reference, verbatim. - **`essential`** _(boolean)_ Whether the task stops when this container stops. - **`privileged`** _(boolean)_ Whether the container runs with elevated host privileges. Null when not set (the provider default is false). - **`read_only_root_filesystem`** _(boolean)_ Whether the root file system is read-only. Null when not set (the provider default is false). - **`user`** _(string)_ The user the container runs as, verbatim. Null when not set (the image default, often root). - **`environment_variable_names`** _(array)_ NAMES of the plain-text environment variables. Values are never returned. - **`secrets`** _(array)_ Variables injected from a secret store, as references: the variable name and the secret or parameter it is read from. No secret value is ever returned. - **`name`** _(string)_ The environment variable name. - **`source`** _(string)_ Where the value is read from, verbatim (on AWS: a Secrets Manager secret ARN or an SSM parameter ARN or name). - **`environment_files`** _(array)_ Environment files loaded into the container, as object references (on AWS: S3 object ARNs). File contents are never read. - **`log_driver`** _(string)_ The log driver, verbatim (on AWS ECS: awslogs, awsfirelens, splunk, ...). Null when not set. - **`log_destination`** _(object)_ Where the container's output is logged (on AWS: the CloudWatch Logs log group, when the log driver is awslogs; its ARN is built from awslogs-group, awslogs-region or the definition's region, and the definition's account). Null for other log drivers. - **`id`** _(string)_ The target's `id`. - **`repository_credentials`** _(string)_ Reference to the secret holding private registry credentials (on AWS: a Secrets Manager secret ARN). - **`added_capabilities`** _(array)_ Linux kernel capabilities added to the container. - **`port_mappings`** _(array)_ Ports the container exposes. - **`container_port`** _(integer)_ Container port. - **`host_port`** _(integer)_ Host port, when mapped. - **`protocol`** _(string)_ tcp or udp. ## Methods - [GET /unified/cloud-infrastructure/container_task_definitions/{id}](/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions/get) — Get Container task definitions - [GET /unified/cloud-infrastructure/container_task_definitions](/api-reference/unified-cloud-infrastructure-api/containertaskdefinitions/list) — List Container task definitions --- # ContainerTasks Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/containertasks/ Schema for the `ContainerTasks` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`task_id`** _(string)_ The task id (the last segment of the provider id). - **`cluster`** _(object)_ The container cluster this object runs in. - **`id`** _(string)_ The target's `id`. - **`task_definition`** _(object)_ The task definition revision the task was started from. - **`id`** _(string)_ The target's `id`. - **`service`** _(object)_ The service that started the task, when a service did. On AWS ECS built from the task's group (service:) and cluster as the long-format service ARN, arn::ecs:::service//; a service created before its account moved to long ARNs has a short ARN without the cluster, which this does not match. - **`id`** _(string)_ The target's `id`. - **`status`** _(string)_ The task's last known state, normalised as compute_instances.state is. On AWS ECS: PROVISIONING, PENDING and ACTIVATING are pending; DEACTIVATING, STOPPING and DEPROVISIONING are stopping; STOPPED and DELETED are stopped. provider_status has the value verbatim. Allowed: `pending`, `running`, `stopping`, `stopped`, `unknown` - **`provider_status`** _(string)_ The task's last known state, verbatim (on AWS ECS lastStatus: PROVISIONING, PENDING, ACTIVATING, RUNNING, DEACTIVATING, STOPPING, DEPROVISIONING, STOPPED, DELETED). - **`desired_status`** _(string)_ The state the orchestrator is driving the task to, normalised. provider_desired_status has the value verbatim. Allowed: `pending`, `running`, `stopped`, `unknown` - **`provider_desired_status`** _(string)_ The state the orchestrator is driving the task to, verbatim (on AWS ECS: PENDING, RUNNING or STOPPED). - **`health_status`** _(string)_ Health of the essential containers, normalised. unknown also covers containers without a health check. provider_health_status has the value verbatim. Allowed: `healthy`, `unhealthy`, `unknown` - **`provider_health_status`** _(string)_ Health of the essential containers, verbatim (on AWS ECS: HEALTHY, UNHEALTHY or UNKNOWN). - **`compute_type`** _(string)_ Where the task runs, normalised. serverless: the provider runs the machines (AWS Fargate, Azure Container Apps consumption, GCP Cloud Run). customer_managed_servers: servers in the customer's account that the customer runs (on AWS ECS: EC2 container instances). provider_managed_servers: servers in the customer's account that the provider patches and scales (on AWS: ECS Managed Instances). external_servers: the customer's own servers outside the cloud (on AWS: ECS Anywhere). Allowed: `serverless`, `customer_managed_servers`, `provider_managed_servers`, `external_servers`, `unknown` - **`provider_launch_type`** _(string)_ The provider's own launch type, verbatim (on AWS ECS: EC2, FARGATE, EXTERNAL or MANAGED_INSTANCES). - **`capacity_provider`** _(string)_ The capacity pool that placed the task, verbatim (on AWS ECS: the capacity provider name). - **`platform_version`** _(string)_ The serverless platform version (AWS Fargate only). - **`exec_enabled`** _(boolean)_ Whether interactive exec into the containers is turned on. - **`availability_zone`** _(string)_ Availability zone the task runs in. - **`subnet_id`** _(string)_ Subnet of the task's network interface (awsvpc networking). - **`private_ip_address`** _(string)_ Private IPv4 address of the task's network interface (awsvpc networking). - **`started_at`** _(string)_ When the task started running. - **`stopped_at`** _(string)_ When the task stopped. Null while running. - **`stop_cause`** _(string)_ Why the task stopped, normalised. Null while the task runs. On AWS ECS: TaskFailedToStart is failed_to_start, EssentialContainerExited is container_exited, UserInitiated is user_initiated, ServiceSchedulerInitiated is orchestrator_initiated, SpotInterruption and TerminationNotice are capacity_reclaimed. provider_stop_code has the value verbatim; stoppedReason in remote_data has the provider's own words. Allowed: `failed_to_start`, `container_exited`, `user_initiated`, `orchestrator_initiated`, `capacity_reclaimed`, `unknown` - **`provider_stop_code`** _(string)_ Why the task stopped, verbatim (on AWS ECS stopCode: TaskFailedToStart, EssentialContainerExited, UserInitiated, ServiceSchedulerInitiated, SpotInterruption, TerminationNotice). - **`containers`** _(array)_ The containers in the task. - **`name`** _(string)_ Container name. - **`image`** _(string)_ Image reference, verbatim. - **`image_digest`** _(string)_ The resolved image digest the container runs. - **`status`** _(string)_ Container state, normalised. Verbatim in remote_data (on AWS ECS: containers[].lastStatus). Allowed: `pending`, `running`, `stopped`, `unknown` - **`health_status`** _(string)_ Container health, normalised. Verbatim in remote_data (on AWS ECS: containers[].healthStatus). Allowed: `healthy`, `unhealthy`, `unknown` - **`overridden_environment_variable_names`** _(array)_ NAMES of environment variables set by start-time overrides for this container. Values are never returned. ## Methods - [GET /unified/cloud-infrastructure/container_tasks/{id}](/api-reference/unified-cloud-infrastructure-api/containertasks/get) — Get Container tasks - [GET /unified/cloud-infrastructure/container_tasks](/api-reference/unified-cloud-infrastructure-api/containertasks/list) — List Container tasks --- # KubernetesClusters Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/kubernetesclusters/ Schema for the `KubernetesClusters` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The cluster name, verbatim. - **`status`** _(string)_ Lifecycle state, normalised. pending: a cluster registered from outside the provider that has not connected yet (on AWS: EKS Connector). provider_status has the provider's value verbatim. Allowed: `creating`, `active`, `updating`, `deleting`, `failed`, `pending`, `unknown` - **`provider_status`** _(string)_ The provider's own lifecycle state string, verbatim (on AWS EKS: CREATING, ACTIVE, DELETING, FAILED, UPDATING, PENDING). - **`kubernetes_version`** _(string)_ The Kubernetes minor version of the control plane, verbatim (for example 1.31). - **`platform_version`** _(string)_ The provider's own platform revision of the control plane, verbatim (on AWS: eks.N). - **`version_support_type`** _(string)_ The provider's support tier for the Kubernetes version, verbatim (on AWS EKS: STANDARD or EXTENDED - EXTENDED is billed extended support after standard support ends). - **`endpoint_public_access`** _(boolean)_ Whether the Kubernetes API endpoint is reachable from the internet. Reachability still depends on public_access_cidrs. - **`endpoint_private_access`** _(boolean)_ Whether the Kubernetes API endpoint is reachable from inside the cluster's network. - **`public_access_cidrs`** _(array)_ CIDR blocks allowed to reach the public endpoint. ["0.0.0.0/0"] means any address. - **`secrets_encryption_enabled`** _(boolean)_ Whether Kubernetes secrets are envelope-encrypted with a key the customer controls (on AWS: an encryptionConfig covering "secrets"). - **`secrets_encryption_key`** _(object)_ The key that envelope-encrypts Kubernetes secrets. Null when secrets encryption is off. - **`id`** _(string)_ The target's `id`. - **`control_plane_log_types`** _(array)_ Control-plane log types that are being exported, verbatim (on AWS EKS: api, audit, authenticator, controllerManager, scheduler). Empty means none. - **`authentication_mode`** _(string)_ How the cluster authenticates IAM principals, verbatim (on AWS EKS: API, API_AND_CONFIG_MAP or CONFIG_MAP). - **`network_boundary`** _(object)_ The network the cluster runs in. - **`id`** _(string)_ The target's `id`. - **`subnet_ids`** _(array)_ Subnets the control plane places its network interfaces in. - **`attached_rule_sets`** _(array)_ The firewall rule sets (security groups) on the control plane network interfaces, including the cluster security group the provider creates. - **`id`** _(string)_ The target's `id`. - **`oidc_issuer`** _(string)_ The OIDC issuer URL for workload identity federation. - **`service_role`** _(object)_ The role the control plane uses to manage provider resources. - **`id`** _(string)_ The target's `id`. - **`deletion_protection`** _(boolean)_ Whether the cluster is protected against deletion. - **`health_issue_codes`** _(array)_ Codes of the provider's current health issues for the cluster. Empty means healthy. ## Methods - [GET /unified/cloud-infrastructure/kubernetes_clusters/{id}](/api-reference/unified-cloud-infrastructure-api/kubernetesclusters/get) — Get Kubernetes clusters - [GET /unified/cloud-infrastructure/kubernetes_clusters](/api-reference/unified-cloud-infrastructure-api/kubernetesclusters/list) — List Kubernetes clusters --- # KubernetesNodePools Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools/ Schema for the `KubernetesNodePools` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The node pool name, verbatim. - **`status`** _(string)_ State, normalised. failed: creating or deleting the pool failed (on AWS EKS: CREATE_FAILED, DELETE_FAILED). degraded: the pool runs but has a health issue - see health_issue_codes. provider_status has the provider's value verbatim. Allowed: `creating`, `active`, `updating`, `deleting`, `failed`, `degraded`, `unknown` - **`provider_status`** _(string)_ The provider's own state string, verbatim (on AWS EKS: CREATING, ACTIVE, UPDATING, DELETING, CREATE_FAILED, DELETE_FAILED, DEGRADED). - **`cluster`** _(object)_ The Kubernetes cluster the pool belongs to. - **`id`** _(string)_ The target's `id`. - **`kubernetes_version`** _(string)_ The Kubernetes version of the nodes, verbatim. It can lag the cluster's kubernetes_version after a control-plane upgrade. - **`node_image_version`** _(string)_ The node image release, verbatim (on AWS EKS: the AMI release version, for example 1.31.0-20241011). - **`node_image_type`** _(string)_ The node image family, verbatim (on AWS EKS: the AMI type, for example AL2023_x86_64_STANDARD, BOTTLEROCKET_ARM_64, CUSTOM). - **`capacity_type`** _(string)_ How the nodes are bought, normalised. spot: spare capacity the provider can take back at short notice (Azure Spot, GCP Spot VMs). reserved_capacity: capacity booked ahead for a fixed period (on AWS: EC2 Capacity Blocks, CAPACITY_BLOCK). provider_capacity_type has the value verbatim. Allowed: `on_demand`, `spot`, `reserved_capacity`, `unknown` - **`provider_capacity_type`** _(string)_ How the nodes are bought, verbatim (on AWS EKS: ON_DEMAND, SPOT or CAPACITY_BLOCK). - **`instance_types`** _(array)_ Instance types the pool launches. - **`disk_size_gb`** _(integer)_ Root volume size in GiB. Null when a launch template sets the disk. - **`min_size`** _(integer)_ Minimum node count. - **`max_size`** _(integer)_ Maximum node count. - **`desired_size`** _(integer)_ Desired node count. - **`remote_access_enabled`** _(boolean)_ Whether SSH (RDP on Windows) access to the nodes is configured with a key. - **`remote_access_open_to_internet`** _(boolean)_ True when remote access is configured with a key but no source rule sets: the provider then opens the port to 0.0.0.0/0. - **`remote_access_source_rule_sets`** _(array)_ The firewall rule sets (security groups) allowed to reach the nodes over SSH/RDP. - **`id`** _(string)_ The target's `id`. - **`node_role`** _(object)_ The role the nodes run as. - **`id`** _(string)_ The target's `id`. - **`subnet_ids`** _(array)_ Subnets the nodes are placed in. - **`launch_template_id`** _(string)_ The launch template the pool uses, when one is set. - **`health_issue_codes`** _(array)_ Codes of the provider's current health issues for the pool. Empty means healthy. ## Methods - [GET /unified/cloud-infrastructure/kubernetes_node_pools/{id}](/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools/get) — Get Kubernetes node pools - [GET /unified/cloud-infrastructure/kubernetes_node_pools](/api-reference/unified-cloud-infrastructure-api/kubernetesnodepools/list) — List Kubernetes node pools --- # LoadBalancers Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/loadbalancers/ Schema for the `LoadBalancers` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The load balancer name, verbatim. - **`load_balancer_type`** _(string)_ What the load balancer balances, normalised. application: HTTP and HTTPS requests, layer 7 (AWS Application Load Balancer, Azure Application Gateway, GCP Application Load Balancer). network: TCP, UDP and TLS connections, layer 4 (AWS Network Load Balancer, Azure Load Balancer, GCP Network Load Balancer). gateway: transparent traffic to inline network appliances (AWS and Azure Gateway Load Balancer). provider_load_balancer_type has the value verbatim. Allowed: `application`, `network`, `gateway`, `unknown` - **`provider_load_balancer_type`** _(string)_ The provider's own type, verbatim (on AWS ELBv2: application, network or gateway). - **`internet_facing`** _(boolean)_ Whether the load balancer has public addresses (on AWS: Scheme internet-facing). The provider flag, not proven reachability. - **`dns_name`** _(string)_ The DNS name clients connect to. - **`state`** _(string)_ State, normalised. creating: being set up (on AWS: provisioning). degraded: serving but impaired (on AWS: active_impaired). provider_state has the provider's value verbatim. Allowed: `creating`, `active`, `degraded`, `failed`, `unknown` - **`provider_state`** _(string)_ The provider's own state string, verbatim (on AWS: active, provisioning, active_impaired, failed). - **`ip_address_type`** _(string)_ ipv4, dualstack or dualstack-without-public-ipv4, verbatim. - **`network_boundary`** _(object)_ The network the load balancer runs in. - **`id`** _(string)_ The target's `id`. - **`subnet_ids`** _(array)_ Subnets the load balancer has nodes in. - **`attached_rule_sets`** _(array)_ The firewall rule sets (security groups) on the load balancer. Empty for load balancers that take none (gateway, and network load balancers created without). - **`id`** _(string)_ The target's `id`. - **`listeners`** _(array)_ Every listener on the load balancer. Null when the listeners could not be read - see unreadable_fields; an empty array means none. - **`id`** _(string)_ The listener's provider id (ARN). - **`port`** _(integer)_ The port clients connect to. - **`protocol`** _(string)_ The client-side protocol, verbatim (HTTP, HTTPS, TCP, TLS, UDP, TCP_UDP, GENEVE, QUIC, TCP_QUIC). - **`tls_policy`** _(string)_ The TLS security policy name, verbatim (on AWS: SslPolicy, e.g. ELBSecurityPolicy-TLS13-1-2-2021-06). Null for listeners that do not terminate TLS. - **`tls_protocols`** _(array)_ The TLS protocol versions the policy accepts, verbatim (TLSv1, TLSv1.1, TLSv1.2, TLSv1.3), read from the policy itself. - **`min_tls_version`** _(string)_ The lowest TLS version the policy accepts, as major.minor (1.0, 1.1, 1.2, 1.3). - **`certificates`** _(array)_ The default certificate(s) the listener serves (on AWS: ACM certificates). A certificate the provider keeps outside its certificate manager (on AWS: an IAM server certificate) is not a certificates object: it is left out here, flagged in unreadable_fields and kept in remote_data. Additional SNI certificates are not listed. - **`id`** _(string)_ The target's `id`. - **`default_action_types`** _(array)_ Types of the default actions, verbatim (forward, redirect, fixed-response, authenticate-oidc, authenticate-cognito). - **`redirects_to_https`** _(boolean)_ For an HTTP listener, whether its default action redirects to HTTPS. Null for other protocols. - **`mutual_authentication_mode`** _(string)_ Mutual TLS mode, verbatim (off, passthrough, verify). Null when not reported. ## Methods - [GET /unified/cloud-infrastructure/load_balancers/{id}](/api-reference/unified-cloud-infrastructure-api/loadbalancers/get) — Get Load balancers - [GET /unified/cloud-infrastructure/load_balancers](/api-reference/unified-cloud-infrastructure-api/loadbalancers/list) — List Load balancers --- # CdnDistributions Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/cdndistributions/ Schema for the `CdnDistributions` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`distribution_id`** _(string)_ The provider's short id for the distribution, verbatim (on AWS: E1U5RQF7T870K0). - **`domain_name`** _(string)_ The provider-assigned domain name (on AWS: dxxxx.cloudfront.net). - **`aliases`** _(array)_ Alternate domain names (CNAMEs) the distribution serves. - **`status`** _(string)_ Deployment state, normalised. deploying: a configuration change is still reaching the edge locations (on AWS: InProgress). provider_status has the provider's value verbatim. Allowed: `deployed`, `deploying`, `unknown` - **`provider_status`** _(string)_ The provider's own deployment state, verbatim (on AWS: Deployed or InProgress). - **`enabled`** _(boolean)_ Whether the distribution serves traffic. - **`viewer_protocol_policy`** _(string)_ The default behavior's viewer protocol policy, verbatim (on AWS: allow-all, redirect-to-https or https-only). - **`https_required`** _(boolean)_ True when the default behavior and every other cache behavior redirect to or require HTTPS (no behavior allows plain HTTP). - **`tls_policy`** _(string)_ The viewer TLS security policy, verbatim (on AWS: MinimumProtocolVersion, e.g. TLSv1.2_2021). - **`min_tls_version`** _(string)_ The lowest TLS version viewers can use, as major.minor (1.0, 1.1, 1.2, 1.3), or ssl3. When the distribution uses the provider's default certificate, this is the provider's fixed policy for it, not tls_policy. - **`certificate`** _(object)_ The certificate served to viewers, when it is a managed certificate (on AWS: an ACM certificate, always in us-east-1). Null for the provider's default certificate or an IAM server certificate. - **`id`** _(string)_ The target's `id`. - **`certificate_source`** _(string)_ Where the certificate served to viewers comes from, normalised. certificate_manager: the provider's certificate manager (on AWS: ACM - see certificate). uploaded: uploaded to the provider outside its certificate manager (on AWS: an IAM server certificate). provider_default: the provider's shared default certificate (on AWS: *.cloudfront.net). provider_certificate_source has the provider's term. Allowed: `certificate_manager`, `uploaded`, `provider_default`, `unknown` - **`provider_certificate_source`** _(string)_ The provider's own term for the certificate source (on AWS: acm, iam or cloudfront, the values of the deprecated ViewerCertificate.CertificateSource, read from which certificate field is set). - **`web_firewall_id`** _(string)_ The web application firewall attached, verbatim (on AWS: a WAFv2 web ACL ARN or a WAF Classic web ACL id). Null when none. - **`geo_restriction_type`** _(string)_ none, whitelist or blacklist, verbatim. - **`http_version`** _(string)_ Highest HTTP version served, verbatim (http1.1, http2, http3, http2and3). - **`ipv6_enabled`** _(boolean)_ Whether IPv6 is enabled. - **`price_class`** _(string)_ Edge location price class, verbatim. - **`logging_enabled`** _(boolean)_ Whether standard access logging is on. Read on GET only - see unreadable_fields on the list. - **`logging_destination`** _(string)_ Where standard access logs go (on AWS: the S3 bucket domain name). Read on GET only. - **`default_root_object`** _(string)_ The object served for the root URL. Read on GET only. - **`origins`** _(array)_ Where the distribution fetches content from. Custom header VALUES (often an origin-verification secret) are never returned - only header names. - **`id`** _(string)_ The origin id within the distribution. - **`domain_name`** _(string)_ The origin domain name. - **`origin_type`** _(string)_ s3, custom or vpc. - **`access_control`** _(string)_ For s3 origins: origin_access_control, origin_access_identity, or none (the bucket must then be readable by anyone the bucket policy allows). - **`protocol_policy`** _(string)_ For custom origins: http-only, match-viewer or https-only, verbatim. - **`tls_protocols`** _(array)_ For custom origins: TLS/SSL versions used to the origin, verbatim (SSLv3, TLSv1, TLSv1.1, TLSv1.2). - **`custom_header_names`** _(array)_ Names of custom headers sent to the origin. Values are never returned. ## Methods - [GET /unified/cloud-infrastructure/cdn_distributions/{id}](/api-reference/unified-cloud-infrastructure-api/cdndistributions/get) — Get Cdn distributions - [GET /unified/cloud-infrastructure/cdn_distributions](/api-reference/unified-cloud-infrastructure-api/cdndistributions/list) — List Cdn distributions --- # Certificates Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/certificates/ Schema for the `Certificates` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`domain_name`** _(string)_ The primary domain name (subject CN). - **`subject_alternative_names`** _(array)_ Subject alternative names. On the list at most the first 100 - see unreadable_fields. - **`status`** _(string)_ Status, normalised. failed also covers a validation that timed out (on AWS: VALIDATION_TIMED_OUT). provider_status has the provider's value verbatim. Allowed: `pending_validation`, `issued`, `inactive`, `expired`, `revoked`, `failed`, `unknown` - **`provider_status`** _(string)_ The provider's own status, verbatim (on AWS: PENDING_VALIDATION, ISSUED, INACTIVE, EXPIRED, VALIDATION_TIMED_OUT, REVOKED, FAILED). - **`issuance`** _(string)_ provider_issued: a public certificate issued and renewed by the provider. imported: a certificate the customer imported (no managed renewal). private_ca: issued by a private CA the customer runs. Allowed: `provider_issued`, `imported`, `private_ca` - **`key_algorithm`** _(string)_ The key algorithm, verbatim (on AWS: RSA_2048, EC_prime256v1, ...). - **`signature_algorithm`** _(string)_ The signature algorithm, verbatim (e.g. SHA256WITHRSA). Read on GET only. - **`not_before`** _(string)_ Start of validity. - **`expires_at`** _(string)_ End of validity (NotAfter). - **`in_use`** _(boolean)_ Whether any provider resource uses the certificate. - **`in_use_by`** _(array)_ Provider ids (ARNs) of the resources using it. Read on GET only. - **`renewal_eligible`** _(boolean)_ Whether the provider can renew the certificate by itself (on AWS: RenewalEligibility ELIGIBLE). Verbatim in remote_data. - **`renewal_status`** _(string)_ The provider's managed renewal, normalised. pending: renewal is queued (on AWS: PENDING_AUTO_RENEWAL). Read on GET only; null when no renewal has run. provider_renewal_status has the value verbatim. Allowed: `pending`, `pending_validation`, `succeeded`, `failed`, `unknown` - **`provider_renewal_status`** _(string)_ The provider's managed-renewal status, verbatim (on AWS: PENDING_AUTO_RENEWAL, PENDING_VALIDATION, SUCCESS, FAILED). Read on GET only; null when no renewal has run. - **`exported`** _(boolean)_ Whether the private key has been exported. - **`export_enabled`** _(boolean)_ Whether the certificate may be exported with its private key. - **`managing_service`** _(string)_ The provider service that manages the certificate and its renewal, verbatim (on AWS: CLOUDFRONT). Null when the customer manages it. ## Methods - [GET /unified/cloud-infrastructure/certificates/{id}](/api-reference/unified-cloud-infrastructure-api/certificates/get) — Get Certificates - [GET /unified/cloud-infrastructure/certificates](/api-reference/unified-cloud-infrastructure-api/certificates/list) — List Certificates --- # CodeRepositories Object > Source: https://truto.one/docs/api-reference/unified-cloud-infrastructure-api/coderepositories/ Schema for the `CodeRepositories` resource in **Unified Cloud Infrastructure API**. ## Properties - **`id`** _(string, required)_ Truto's stable unified identifier for this object. Opaque; use provider_id to address the object in the provider's own console or API. - **`provider_id`** _(string)_ The provider's own identifier, passed through verbatim — a full ARN, resource id, or self-link. Never truncated, prefixed, or normalized. - **`provider`** _(string)_ Which cloud this object was read from. Allowed: `aws`, `azure`, `gcp` - **`account`** _(string)_ The account, subscription or project this object belongs to. - **`region`** _(string)_ Where the object is located. 'global' denotes genuinely global resources (e.g. IAM, GCP VPC networks) rather than a guessed region. A substituted region (when none is derivable) is flagged in unreadable_fields. - **`native_type`** _(string)_ The provider's own type string, unmodified — for example 'AWS::S3::Bucket', 'aws_iam_role', 'Microsoft.Sql/servers'. Used for display and drill-down. - **`tags`** _(object)_ Key-value pairs exactly as the customer set them: no case folding, key/value normalization, or merging of separate provider concepts. An empty object means no tags; tags that could not be read appear in unreadable_fields instead. - **`collected_at`** _(string)_ When Truto actually read this object from the provider, in UTC ISO 8601 with the offset present — not the request time, and not a provider timestamp. - **`updated_at`** _(string)_ When the object was last modified at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`created_at`** _(string)_ When the object was created at the provider, in UTC ISO 8601. Null when the provider does not record one - see unreadable_fields. - **`unreadable_fields`** _(array)_ Fields on this object that could not be read, and why. An empty array means everything was read. Use this to tell a real value from a missing one. - **`field`** _(string)_ The property on this resource that could not be read. - **`reason`** _(string)_ Why the field could not be read. available_on_get: Not read on list to keep the list fast; call GET for this resource's id to get it. Allowed: `not_supported_by_provider`, `not_configured`, `permission_denied`, `not_collected`, `collection_error`, `partially_collected`, `available_on_get` - **`detail`** _(string)_ Explanation of the reason, where one adds anything. - **`remote_data`** _(object)_ Raw data returned from the remote API call. - **`name`** _(string)_ The repository name, verbatim. - **`repository_id`** _(string)_ The provider's own repository id (on AWS: a UUID), distinct from the ARN in id. - **`default_branch`** _(string)_ The default branch name. Null for an empty repository. - **`encryption_key`** _(object)_ The customer-visible key that encrypts the repository (on AWS: the KMS key, as a key ARN). On AWS it is the AWS managed key aws/codecommit unless a customer managed key was chosen; join to managed_keys to tell which. - **`id`** _(string)_ The target's `id`. - **`clone_url_http`** _(string)_ HTTPS clone URL. - **`clone_url_ssh`** _(string)_ SSH clone URL. ## Methods - [GET /unified/cloud-infrastructure/code_repositories/{id}](/api-reference/unified-cloud-infrastructure-api/coderepositories/get) — Get Code repositories - [GET /unified/cloud-infrastructure/code_repositories](/api-reference/unified-cloud-infrastructure-api/coderepositories/list) — List Code repositories --- # Unified Conferencing API > Source: https://truto.one/docs/api-reference/unified-conferencing-api/ Base URL: `https://api.truto.one/unified/conferencing` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Transcripts](/api-reference/unified-conferencing-api/transcripts) - [GET /unified/conferencing/transcripts](/api-reference/unified-conferencing-api/transcripts/list) — List Transcripts - [GET /unified/conferencing/transcripts/{id}](/api-reference/unified-conferencing-api/transcripts/get) — Get Transcripts - [Attendees](/api-reference/unified-conferencing-api/attendees) - [GET /unified/conferencing/attendees](/api-reference/unified-conferencing-api/attendees/list) — List Attendees - [GET /unified/conferencing/attendees/{id}](/api-reference/unified-conferencing-api/attendees/get) — Get Attendees - [POST /unified/conferencing/attendees/summary](/api-reference/unified-conferencing-api/attendees/summary) — Summary Attendees - [TranscriptEntries](/api-reference/unified-conferencing-api/transcriptentries) - [GET /unified/conferencing/transcript_entries](/api-reference/unified-conferencing-api/transcriptentries/list) — List Transcript entries - [GET /unified/conferencing/transcript_entries/{id}](/api-reference/unified-conferencing-api/transcriptentries/get) — Get Transcript entries - [Meetings](/api-reference/unified-conferencing-api/meetings) - [GET /unified/conferencing/meetings](/api-reference/unified-conferencing-api/meetings/list) — List Meetings - [GET /unified/conferencing/meetings/{id}](/api-reference/unified-conferencing-api/meetings/get) — Get Meetings --- # Transcripts Object > Source: https://truto.one/docs/api-reference/unified-conferencing-api/transcripts/ Schema for the `Transcripts` resource in **Unified Conferencing API**. ## Properties - **`id`** _(string)_ The unique identifier for transcript - **`meeting`** _(object)_ The transcript's meeting - **`id`** _(string)_ The unique identifier for a meeting - **`entries`** _(array)_ List of sentences in the transcript of the meeting - **`id`** _(string)_ The unique identifier for an entry - **`speaker_id`** _(string)_ The unique identifier for a speaker - **`speaker_type`** _(string)_ The type of the speaker. Can be either `user` or `guest`. - **`speaker_name`** _(string)_ The speaker of the sentence - **`text`** _(string)_ The text of the sentence - **`raw_text`** _(string)_ The raw text of the sentence - **`start_time`** _(number)_ The start of the sentence in the number of seconds from the start of the meeting - **`end_time`** _(number)_ The end of the sentence in the number of seconds from the start of the meeting - **`start_time`** _(number)_ The start time of the transcript - **`end_time`** _(number)_ The end time of the transcript - **`external_id`** _(string)_ The identifier assigned by the source system for this transcript record. - **`transcript_url`** _(string)_ A URL to download or view the generated transcript document, where available. - **`status`** _(string)_ Processing status of the transcript. Allowed: `processing`, `completed` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conferencing/transcripts](/api-reference/unified-conferencing-api/transcripts/list) — List Transcripts - [GET /unified/conferencing/transcripts/{id}](/api-reference/unified-conferencing-api/transcripts/get) — Get Transcripts --- # Attendees Object > Source: https://truto.one/docs/api-reference/unified-conferencing-api/attendees/ Schema for the `Attendees` resource in **Unified Conferencing API**. ## Properties - **`id`** _(string)_ The unique identifier for an attendee - **`name`** _(string)_ Name of the attendee - **`email`** _(string)_ Email of the attendee - **`is_host`** _(boolean)_ Whether the attendee is the host of the meeting - **`type`** _(string)_ Type of the attendee. Can be either `user` or `guest`. - **`meeting`** _(object)_ The attendee's meeting - **`id`** _(string)_ The unique identifier for a meeting - **`start_time`** _(string)_ Time when the participant first joined the meeting in ISO 8601 format - **`end_time`** _(string)_ Time when the participant left the meeting for the last time in ISO 8601 format - **`user`** _(object)_ The internal user account linked to this attendee, where the attendee is a known/authenticated user rather than a guest. - **`id`** _(string)_ The unique identifier for a user. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conferencing/attendees](/api-reference/unified-conferencing-api/attendees/list) — List Attendees - [GET /unified/conferencing/attendees/{id}](/api-reference/unified-conferencing-api/attendees/get) — Get Attendees - [POST /unified/conferencing/attendees/summary](/api-reference/unified-conferencing-api/attendees/summary) — Summary Attendees --- # TranscriptEntries Object > Source: https://truto.one/docs/api-reference/unified-conferencing-api/transcriptentries/ Schema for the `TranscriptEntries` resource in **Unified Conferencing API**. ## Properties - **`id`** _(string)_ The unique identifier for an entry - **`speaker_id`** _(string)_ The unique identifier for a speaker - **`speaker_type`** _(string)_ The type of the speaker. Can be either `user` or `guest`. - **`speaker_name`** _(string)_ The speaker of the sentence - **`text`** _(string)_ The text of the sentence - **`raw_text`** _(string)_ The raw text of the sentence - **`start_time`** _(number)_ The start of the sentence in the number of seconds from the start of the meeting - **`end_time`** _(number)_ The end of the sentence in the number of seconds from the start of the meeting - **`transcript`** _(object)_ The entries transcript - **`id`** _(string)_ The unique identifier for the transcript - **`meeting`** _(object)_ The transcript's entry meeting - **`id`** _(string)_ The unique identifier for a meeting - **`external_id`** _(string)_ The identifier assigned by the source system for this transcript entry. - **`language`** _(string)_ The language of the spoken text in this entry, as an ISO 639-2B code (e.g. eng, fre, spa). - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conferencing/transcript_entries](/api-reference/unified-conferencing-api/transcriptentries/list) — List Transcript entries - [GET /unified/conferencing/transcript_entries/{id}](/api-reference/unified-conferencing-api/transcriptentries/get) — Get Transcript entries --- # Meetings Object > Source: https://truto.one/docs/api-reference/unified-conferencing-api/meetings/ Schema for the `Meetings` resource in **Unified Conferencing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a meeting - **`title`** _(string)_ Title of the meeting - **`attendees`** _(array)_ List of attendees - **`id`** _(string)_ The unique identifier for an attendee - **`name`** _(string)_ Name of the attendee - **`email`** _(string)_ Email of the attendee - **`is_host`** _(boolean)_ Whether the attendee is the host of the meeting - **`type`** _(string)_ Type of the attendee. Can be either `user` or `guest`. - **`start_time`** _(string)_ Time when the participant first joined the meeting in ISO 8601 format - **`end_time`** _(string)_ Time when the participant left the meeting for the last time in ISO 8601 format - **`duration`** _(integer)_ Duration of the meeting in seconds - **`start_time`** _(string)_ Start time of the meeting in ISO 8601 format - **`end_time`** _(string)_ End time of the meeting in ISO 8601 format - **`audio_recording_url`** _(string)_ URL of the audio recording of the meeting - **`video_recording_url`** _(string)_ URL of the video recording of the meeting - **`status`** _(string)_ Status of the meeting - **`topics`** _(array)_ List of topics discussed in the meeting - **`type`** _(string)_ Type of the meeting - **`transcript`** _(array)_ List of transcripts of the meeting - **`id`** _(string)_ The unique identifier for transcript - **`entries`** _(array)_ List of sentences in the transcript of the meeting - **`id`** _(string)_ The unique identifier for an entry - **`speaker_id`** _(string)_ The unique identifier for a speaker - **`speaker_type`** _(string)_ The type of the speaker. Can be either `user` or `guest`. - **`speaker_name`** _(string)_ The speaker of the sentence - **`text`** _(string)_ The text of the sentence - **`raw_text`** _(string)_ The raw text of the sentence - **`start_time`** _(number)_ The start of the sentence in the number of seconds from the start of the meeting - **`end_time`** _(number)_ The end of the sentence in the number of seconds from the start of the meeting - **`start_time`** _(number)_ The start time of the transcript - **`end_time`** _(number)_ The end time of the transcript - **`created_at`** _(string)_ Creation time of the meeting - **`updated_at`** _(string)_ Last updated time of the meeting - **`meeting_url`** _(string)_ URL of the meeting - **`external_id`** _(string)_ The identifier assigned by the source system for this meeting. - **`space`** _(object)_ The persistent meeting room/space this meeting instance belongs to, where the provider supports recurring meeting spaces. - **`id`** _(string)_ The unique identifier for the meeting space. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conferencing/meetings](/api-reference/unified-conferencing-api/meetings/list) — List Meetings - [GET /unified/conferencing/meetings/{id}](/api-reference/unified-conferencing-api/meetings/get) — Get Meetings --- # Unified Conversational Intelligence API > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/ Base URL: `https://api.truto.one/unified/conversational-intelligence` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Meetings](/api-reference/unified-conversational-intelligence-api/meetings) - [GET /unified/conversational-intelligence/meetings/{id}](/api-reference/unified-conversational-intelligence-api/meetings/get) — Get Meetings - [GET /unified/conversational-intelligence/meetings](/api-reference/unified-conversational-intelligence-api/meetings/list) — List Meetings - [POST /unified/conversational-intelligence/meetings/extensive](/api-reference/unified-conversational-intelligence-api/meetings/extensive) — Extensive Meetings - [Users](/api-reference/unified-conversational-intelligence-api/users) - [GET /unified/conversational-intelligence/users](/api-reference/unified-conversational-intelligence-api/users/list) — List Users - [GET /unified/conversational-intelligence/users/{id}](/api-reference/unified-conversational-intelligence-api/users/get) — Get Users - [Transcripts](/api-reference/unified-conversational-intelligence-api/transcripts) - [GET /unified/conversational-intelligence/transcripts](/api-reference/unified-conversational-intelligence-api/transcripts/list) — List Transcripts - [Scorecards](/api-reference/unified-conversational-intelligence-api/scorecards) - [GET /unified/conversational-intelligence/scorecards](/api-reference/unified-conversational-intelligence-api/scorecards/list) — List Scorecards - [ScorecardTemplates](/api-reference/unified-conversational-intelligence-api/scorecardtemplates) - [GET /unified/conversational-intelligence/scorecard-templates](/api-reference/unified-conversational-intelligence-api/scorecardtemplates/list) — List Scorecard templates - [Activity](/api-reference/unified-conversational-intelligence-api/activity) - [GET /unified/conversational-intelligence/activity](/api-reference/unified-conversational-intelligence-api/activity/list) — List Activity - [Interactions](/api-reference/unified-conversational-intelligence-api/interactions) - [GET /unified/conversational-intelligence/interactions](/api-reference/unified-conversational-intelligence-api/interactions/list) — List Interactions --- # Meetings Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/meetings/ Schema for the `Meetings` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a meeting - **`title`** _(string)_ Title of the meeting - **`attendees`** _(array)_ List of attendees - **`id`** _(string)_ The unique identifier for an attendee - **`name`** _(string)_ Name of the attendee - **`email`** _(string)_ Email of the attendee - **`is_host`** _(boolean)_ Whether the attendee is the host of the meeting - **`type`** _(string)_ Type of the attendee. Can be either `user` or `guest`. - **`title`** _(string)_ Job title of the attendee - **`phone`** _(string)_ Phone number of the attendee - **`affiliation`** _(string)_ Whether the attendee is internal (company) or external. Populated by detailed call analysis. - **`talk_time`** _(number)_ Total time the attendee spoke, in seconds. Populated by detailed call analysis. - **`duration`** _(integer)_ Duration of the meeting in seconds - **`start_time`** _(string)_ Start time of the meeting in ISO 8601 format - **`end_time`** _(string)_ End time of the meeting in ISO 8601 format - **`audio_recording_url`** _(string)_ URL of the audio recording of the meeting - **`video_recording_url`** _(string)_ URL of the video recording of the meeting - **`status`** _(string)_ Status of the meeting - **`topics`** _(array)_ List of topics discussed in the meeting - **`type`** _(string)_ Type of the meeting - **`transcript`** _(array)_ List of sentences in the transcript of the meeting - **`speaker_id`** _(string)_ The unique identifier for a speaker - **`speaker_type`** _(string)_ The type of the speaker. Can be either `user` or `guest`. - **`speaker_name`** _(string)_ The speaker of the sentence - **`text`** _(string)_ The text of the sentence - **`raw_text`** _(string)_ The raw text of the sentence - **`start`** _(number)_ The start of the sentence in the number of seconds from the start of the meeting - **`end`** _(number)_ The end of the sentence in the number of seconds from the start of the meeting - **`created_at`** _(string)_ Creation time of the meeting - **`updated_at`** _(string)_ Last updated time of the meeting - **`meeting_url`** _(string)_ URL of the meeting - **`calender_event`** _(string)_ The unique identifier of the meeting in Google or Outlook Calendar - **`is_private`** _(boolean)_ Whether the meeting/call is marked private. Private meetings should typically be excluded from detailed content and transcript retrieval. - **`host`** _(object)_ The user who hosted the meeting - **`id`** _(string)_ The unique identifier for a user - **`direction`** _(string)_ The direction of the call (e.g. Inbound, Outbound, Conference) - **`scope`** _(string)_ Whether the meeting was internal-only or included external participants Allowed: `internal`, `external`, `unknown` - **`language`** _(string)_ The language spoken in the meeting, as an ISO 639-2B code (e.g. eng, fre, spa) - **`workspace`** _(object)_ The workspace the meeting belongs to - **`id`** _(string)_ The unique identifier for a workspace - **`topic_durations`** _(array)_ Time spent on each topic discussed in the meeting. Populated by detailed call analysis. - **`name`** _(string)_ The name of the topic - **`duration`** _(integer)_ Time spent on this topic, in seconds - **`trackers`** _(array)_ Tracked keywords/phrases and how often and when they occurred. Populated by detailed call analysis. - **`id`** _(string)_ The unique identifier for the tracker - **`name`** _(string)_ The name of the tracker - **`type`** _(string)_ The tracker type, e.g. `keyword` or `smart` - **`count`** _(integer)_ The number of times the tracker's terms occurred in the meeting - **`occurrences`** _(array)_ Timing and speaker for each occurrence of the tracker - **`start_time`** _(number)_ Seconds from the start of the meeting when the term was said - **`speaker_id`** _(string)_ The unique identifier of the speaker who said the term - **`interaction_metrics`** _(array)_ Call-level interaction statistics (e.g. Longest Monologue, Interactivity, Patience). Populated by detailed call analysis. - **`name`** _(string)_ The name of the metric - **`value`** _(number)_ The value of the metric - **`question_counts`** _(object)_ Number of questions asked during the meeting, broken down by speaker affiliation. Populated by detailed call analysis. - **`internal`** _(integer)_ Number of questions asked by company speakers - **`external`** _(integer)_ Number of questions asked by non-company speakers - **`video_stats`** _(array)_ Time spent on each video segment type (e.g. presentation, webcam). Populated by detailed call analysis. - **`name`** _(string)_ The video segment type, e.g. Presentation, Webcam - **`duration`** _(number)_ Total duration of this segment type, in seconds - **`comments`** _(array)_ Public comments left on the meeting. Populated by detailed call analysis. - **`id`** _(string)_ The unique identifier for the comment - **`text`** _(string)_ The comment text - **`commenter`** _(object)_ The user who wrote the comment - **`id`** _(string)_ The unique identifier for a user - **`start_time`** _(number)_ Seconds from the start of the meeting the comment refers to - **`end_time`** _(number)_ Seconds from the start of the meeting the comment's reference ends - **`posted_at`** _(string)_ When the comment was posted - **`in_reply_to`** _(string)_ The identifier of the comment this is a reply to, if any - **`is_during_call`** _(boolean)_ Whether the comment was written during the call, as opposed to after - **`highlights`** _(array)_ Highlighted moments and action items/next steps detected in the meeting. Populated by detailed call analysis. - **`speaker_id`** _(string)_ The unique identifier of the speaker for this highlight - **`text`** _(string)_ The highlighted snippet - **`start_time`** _(number)_ Seconds from the start of the meeting the snippet starts - **`end_time`** _(number)_ Seconds from the start of the meeting the snippet ends - **`external_id`** _(string)_ The identifier assigned by the source system for this meeting record. - **`space`** _(object)_ The persistent meeting room/space this meeting instance belongs to, where the provider supports recurring meeting spaces. - **`id`** _(string)_ The unique identifier for the meeting space. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/meetings/{id}](/api-reference/unified-conversational-intelligence-api/meetings/get) — Get Meetings - [GET /unified/conversational-intelligence/meetings](/api-reference/unified-conversational-intelligence-api/meetings/list) — List Meetings - [POST /unified/conversational-intelligence/meetings/extensive](/api-reference/unified-conversational-intelligence-api/meetings/extensive) — Extensive Meetings --- # Users Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/users/ Schema for the `Users` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`name`** _(string)_ Name of the user - **`emails`** _(array)_ List of email addresses of the user - **`email`** _(string)_ Email address of the user - **`is_primary`** _(boolean)_ Whether the email address is the primary email address of the user - **`created_at`** _(string)_ Creation time of the user - **`updated_at`** _(string)_ Last updated time of the user - **`first_name`** _(string)_ The given/first name of the user. - **`last_name`** _(string)_ The family/last name of the user. - **`is_terms_accepted`** _(boolean)_ Whether the user has accepted the source system's terms of service. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/users](/api-reference/unified-conversational-intelligence-api/users/list) — List Users - [GET /unified/conversational-intelligence/users/{id}](/api-reference/unified-conversational-intelligence-api/users/get) — Get Users --- # Transcripts Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/transcripts/ Schema for the `Transcripts` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string)_ The unique identifier for transcript - **`meeting`** _(object)_ The transcript's meeting - **`id`** _(string)_ The unique identifier for a meeting - **`entries`** _(array)_ List of sentences in the transcript of the meeting - **`id`** _(string)_ The unique identifier for an entry - **`speaker_id`** _(string)_ The unique identifier for a speaker - **`speaker_type`** _(string)_ The type of the speaker. Can be either `user` or `guest`. - **`speaker_name`** _(string)_ The speaker of the sentence - **`text`** _(string)_ The text of the sentence - **`raw_text`** _(string)_ The raw text of the sentence - **`start_time`** _(number)_ The start of the sentence in the number of seconds from the start of the meeting - **`end_time`** _(number)_ The end of the sentence in the number of seconds from the start of the meeting - **`start_time`** _(number)_ The start time of the transcript - **`end_time`** _(number)_ The end time of the transcript - **`external_id`** _(string)_ The identifier assigned by the source system for this transcript record. - **`transcript_url`** _(string)_ A URL to download or view the generated transcript document, where available. - **`status`** _(string)_ Processing status of the transcript. Allowed: `processing`, `completed` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/transcripts](/api-reference/unified-conversational-intelligence-api/transcripts/list) — List Transcripts --- # Scorecards Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/scorecards/ Schema for the `Scorecards` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the scorecard submission - **`meeting`** _(object)_ The meeting or call that was reviewed - **`id`** _(string, required)_ The unique identifier for the meeting - **`start_time`** _(string)_ Start time of the meeting in ISO 8601 format - **`scorecard_template`** _(object)_ The scorecard template that was used for the review - **`id`** _(string)_ The unique identifier for the scorecard template - **`name`** _(string)_ Name of the scorecard template - **`reviewee`** _(object)_ The user whose performance was reviewed - **`id`** _(string)_ The unique identifier for the reviewee - **`name`** _(string)_ Name of the reviewee - **`email`** _(string)_ Email of the reviewee - **`reviewer`** _(object)_ The user who performed the review - **`id`** _(string)_ The unique identifier for the reviewer - **`name`** _(string)_ Name of the reviewer - **`email`** _(string)_ Email of the reviewer - **`review_method`** _(string)_ How the scorecard was completed. Can be `manual`, `automatic`, or `both`. - **`overall_score`** _(number)_ Overall numeric score for the review, when provided by the source - **`overall_recommendation`** _(string)_ Overall qualitative recommendation or summary for the review - **`visibility`** _(string)_ Visibility of the scorecard in the source system - **`initiative`** _(object)_ Coaching or quality initiative associated with the scorecard, when applicable - **`id`** _(string)_ The unique identifier for the initiative - **`name`** _(string)_ Name of the initiative - **`answers`** _(array)_ The answers submitted for the scorecard - **`field`** _(object)_ - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name - **`label`** _(string)_ The field's label - **`type`** _(string)_ The field's type. If no clear mapping exists, then the raw value is returned. Allowed: `statement`, `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` (+5 more) - **`field_group`** _(object)_ The field's group identifier. If present, the field is part of a group. - **`id`** _(string)_ The field group's identifier - **`name`** _(string)_ The field group's name - **`label`** _(string)_ The field group's label - **`value`** _(string)_ The value for the field submitted - **`submitted_at`** _(string)_ When the scorecard was submitted or last answered - **`reviewed_at`** _(string)_ When the review was completed - **`created_at`** _(string)_ Creation time of the scorecard record - **`updated_at`** _(string)_ Last updated time of the scorecard record - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/scorecards](/api-reference/unified-conversational-intelligence-api/scorecards/list) — List Scorecards --- # ScorecardTemplates Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/scorecardtemplates/ Schema for the `ScorecardTemplates` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the scorecard template - **`name`** _(string)_ Name of the scorecard template - **`type`** _(string)_ The type of the scorecard template in the source system - **`enabled`** _(boolean)_ Whether the scorecard template is enabled in the source system - **`review_method`** _(string)_ Default review method for the template. Can be `manual`, `automatic`, or `both`. - **`fields`** _(array)_ The scorecard fields - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`placeholder`** _(string)_ The field's placeholder - **`description`** _(string)_ The field's description - **`position`** _(number)_ The index position of field in the scorecard template. - **`type`** _(string)_ The field's type. If no clear mapping exists, then raw value is returned. Allowed: `statement`, `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` (+5 more) - **`format`** _(string)_ The format of the field. Allowed: `url`, `email`, `password` - **`validation`** _(string)_ The validation string for the field. - **`range`** _(object)_ The range applicable for field types number, rating, scale. - **`min`** _(number)_ The minimum range for the field. - **`min_label`** _(number)_ The label for the minimum range of the field. - **`max`** _(number)_ The maximum range for the field. - **`max_label`** _(number)_ The label for the maximum range of the field. - **`is_required`** _(boolean)_ Whether the field is required - **`is_overall`** _(boolean)_ Whether this field is the overall summary question - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`field_group`** _(object)_ The field's group identifier. If present, the field is part of a group. - **`id`** _(string)_ The field groups's identifier - **`name`** _(string)_ The field groups's name - **`label`** _(string)_ The field groups's label - **`rows`** _(array)_ The field's rows. If present, the field's type is matrix - **`label`** _(string)_ The row's label - **`value`** _(string)_ The row's value - **`description`** _(string)_ The row's description - **`columns`** _(array)_ The field's columns. If present, the field's type is matrix - **`label`** _(string)_ The column's label - **`value`** _(string)_ The column's value - **`description`** _(string)_ The column's description - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`workspace`** _(object)_ The workspace to which the scorecard template belongs. - **`id`** _(string)_ The unique identifier of the workspace. - **`name`** _(string)_ The name of the workspace. - **`created_by`** _(object)_ User who last updated the scorecard template in the source system. - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`created_at`** _(string)_ Creation time of the scorecard template - **`updated_at`** _(string)_ Last updated time of the scorecard template - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/scorecard-templates](/api-reference/unified-conversational-intelligence-api/scorecardtemplates/list) — List Scorecard templates --- # Activity Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/activity/ Schema for the `Activity` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the activity record - **`user`** _(object)_ The user the activity record belongs to - **`id`** _(string, required)_ The unique identifier for the user - **`name`** _(string)_ Name of the user - **`emails`** _(array)_ List of email addresses of the user - **`email`** _(string)_ Email address of the user - **`is_primary`** _(boolean)_ Whether the email address is the primary email address of the user - **`start_time`** _(string)_ Start of the aggregation period in ISO 8601 format - **`end_time`** _(string)_ End of the aggregation period in ISO 8601 format - **`aggregation_period`** _(string)_ Granularity of the aggregation. Can be `day`, `week`, `month`, or `total`. Allowed: `day`, `week`, `month`, `total` - **`metrics`** _(object)_ Aggregated platform activity counts for the user in the period - **`calls_hosted`** _(integer)_ Number of calls or meetings hosted by the user - **`calls_attended`** _(integer)_ Number of calls or meetings attended by the user - **`calls_listened_own`** _(integer)_ Number of the user's own calls listened to - **`calls_listened_others`** _(integer)_ Number of other users' calls listened to - **`feedback_given`** _(integer)_ Number of times the user gave feedback on calls - **`feedback_received`** _(integer)_ Number of times the user received feedback on calls - **`feedback_requested`** _(integer)_ Number of times the user requested feedback on calls - **`comments_given`** _(integer)_ Number of comments given on calls - **`comments_received`** _(integer)_ Number of comments received on calls - **`calls_shared_internally`** _(integer)_ Number of calls shared internally - **`calls_shared_externally`** _(integer)_ Number of calls shared externally - **`scorecards_filled`** _(integer)_ Number of scorecards completed by the user as reviewer - **`scorecards_received`** _(integer)_ Number of scorecards received by the user as reviewee - **`calls_marked_feedback_given`** _(integer)_ Number of calls marked as feedback given - **`calls_marked_feedback_received`** _(integer)_ Number of calls marked as feedback received - **`created_at`** _(string)_ When the activity record was created in the source system - **`updated_at`** _(string)_ When the activity record was last updated in the source system - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/activity](/api-reference/unified-conversational-intelligence-api/activity/list) — List Activity --- # Interactions Object > Source: https://truto.one/docs/api-reference/unified-conversational-intelligence-api/interactions/ Schema for the `Interactions` resource in **Unified Conversational Intelligence API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the interaction record - **`user`** _(object)_ The user the interaction record belongs to - **`id`** _(string, required)_ The unique identifier for the user - **`name`** _(string)_ Name of the user - **`emails`** _(array)_ List of email addresses of the user - **`email`** _(string)_ Email address of the user - **`is_primary`** _(boolean)_ Whether the email address is the primary email address of the user - **`start_time`** _(string)_ Start of the aggregation period in ISO 8601 format - **`end_time`** _(string)_ End of the aggregation period in ISO 8601 format - **`timezone`** _(string)_ Time zone used for the aggregation period in the source system - **`aggregation_period`** _(string)_ Granularity of the aggregation. Allowed: `day`, `week`, `month`, `total` - **`metrics`** _(object)_ Standard interaction metrics for the user in the period - **`longest_monologue`** _(number)_ Longest monologue duration or score for the user in the period - **`longest_customer_story`** _(number)_ Longest customer story duration or score for the user in the period - **`interactivity`** _(number)_ Interactivity score for the user in the period - **`patience`** _(number)_ Patience score for the user in the period - **`question_rate`** _(number)_ Question rate for the user in the period - **`additional_metrics`** _(array)_ Additional interaction metrics from the source when they do not map to the standard metrics object. Use for forward-compatible or vendor-specific metrics. - **`name`** _(string)_ Name of the interaction metric in the source system - **`value`** _(number)_ Value of the interaction metric - **`created_at`** _(string)_ When the interaction record was created in the source system - **`updated_at`** _(string)_ When the interaction record was last updated in the source system - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/conversational-intelligence/interactions](/api-reference/unified-conversational-intelligence-api/interactions/list) — List Interactions --- # Unified CRM API > Source: https://truto.one/docs/api-reference/unified-crm-api/ Base URL: `https://api.truto.one/unified/crm` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Accounts](/api-reference/unified-crm-api/accounts) - [GET /unified/crm/accounts](/api-reference/unified-crm-api/accounts/list) — List Accounts - [POST /unified/crm/accounts](/api-reference/unified-crm-api/accounts/create) — Create Accounts - [GET /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/get) — Get Accounts - [DELETE /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/delete) — Delete Accounts - [PATCH /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/update) — Update Accounts - [POST /unified/crm/accounts/merge](/api-reference/unified-crm-api/accounts/merge) — Merge Accounts - [POST /unified/crm/accounts/batch-delete](/api-reference/unified-crm-api/accounts/batch-delete) — Batch Delete Accounts - [Contacts](/api-reference/unified-crm-api/contacts) - [GET /unified/crm/contacts](/api-reference/unified-crm-api/contacts/list) — List Contacts - [POST /unified/crm/contacts](/api-reference/unified-crm-api/contacts/create) — Create Contacts - [GET /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/get) — Get Contacts - [DELETE /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/delete) — Delete Contacts - [PATCH /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/update) — Update Contacts - [POST /unified/crm/contacts/merge](/api-reference/unified-crm-api/contacts/merge) — Merge Contacts - [POST /unified/crm/contacts/batch-delete](/api-reference/unified-crm-api/contacts/batch-delete) — Batch Delete Contacts - [EngagementTypes](/api-reference/unified-crm-api/engagementtypes) - [GET /unified/crm/engagement_types](/api-reference/unified-crm-api/engagementtypes/list) — List Engagement types - [POST /unified/crm/engagement_types](/api-reference/unified-crm-api/engagementtypes/create) — Create Engagement types - [GET /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/get) — Get Engagement types - [PATCH /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/update) — Update Engagement types - [DELETE /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/delete) — Delete Engagement types - [Engagements](/api-reference/unified-crm-api/engagements) - [GET /unified/crm/engagements](/api-reference/unified-crm-api/engagements/list) — List Engagements - [POST /unified/crm/engagements](/api-reference/unified-crm-api/engagements/create) — Create Engagements - [GET /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/get) — Get Engagements - [PATCH /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/update) — Update Engagements - [DELETE /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/delete) — Delete Engagements - [Leads](/api-reference/unified-crm-api/leads) - [GET /unified/crm/leads](/api-reference/unified-crm-api/leads/list) — List Leads - [POST /unified/crm/leads](/api-reference/unified-crm-api/leads/create) — Create Leads - [GET /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/get) — Get Leads - [PATCH /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/update) — Update Leads - [DELETE /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/delete) — Delete Leads - [Notes](/api-reference/unified-crm-api/notes) - [GET /unified/crm/notes](/api-reference/unified-crm-api/notes/list) — List Notes - [POST /unified/crm/notes](/api-reference/unified-crm-api/notes/create) — Create Notes - [GET /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/get) — Get Notes - [PATCH /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/update) — Update Notes - [DELETE /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/delete) — Delete Notes - [Opportunities](/api-reference/unified-crm-api/opportunities) - [GET /unified/crm/opportunities](/api-reference/unified-crm-api/opportunities/list) — List Opportunities - [POST /unified/crm/opportunities](/api-reference/unified-crm-api/opportunities/create) — Create Opportunities - [GET /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/get) — Get Opportunities - [DELETE /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/delete) — Delete Opportunities - [PATCH /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/update) — Update Opportunities - [Stages](/api-reference/unified-crm-api/stages) - [GET /unified/crm/stages](/api-reference/unified-crm-api/stages/list) — List Stages - [POST /unified/crm/stages](/api-reference/unified-crm-api/stages/create) — Create Stages - [GET /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/get) — Get Stages - [PATCH /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/update) — Update Stages - [DELETE /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/delete) — Delete Stages - [Tasks](/api-reference/unified-crm-api/tasks) - [GET /unified/crm/tasks](/api-reference/unified-crm-api/tasks/list) — List Tasks - [POST /unified/crm/tasks](/api-reference/unified-crm-api/tasks/create) — Create Tasks - [GET /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/get) — Get Tasks - [DELETE /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/delete) — Delete Tasks - [PATCH /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/update) — Update Tasks - [Users](/api-reference/unified-crm-api/users) - [GET /unified/crm/users](/api-reference/unified-crm-api/users/list) — List Users - [POST /unified/crm/users](/api-reference/unified-crm-api/users/create) — Create Users - [GET /unified/crm/users/{id}](/api-reference/unified-crm-api/users/get) — Get Users - [DELETE /unified/crm/users/{id}](/api-reference/unified-crm-api/users/delete) — Delete Users - [PATCH /unified/crm/users/{id}](/api-reference/unified-crm-api/users/update) — Update Users - [Fields](/api-reference/unified-crm-api/fields) - [GET /unified/crm/fields](/api-reference/unified-crm-api/fields/list) — List Fields - [POST /unified/crm/fields](/api-reference/unified-crm-api/fields/create) — Create Fields - [GET /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/get) — Get Fields - [PATCH /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/update) — Update Fields - [DELETE /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/delete) — Delete Fields - [FieldGroups](/api-reference/unified-crm-api/fieldgroups) - [GET /unified/crm/field_groups](/api-reference/unified-crm-api/fieldgroups/list) — List Field groups - [POST /unified/crm/field_groups](/api-reference/unified-crm-api/fieldgroups/create) — Create Field groups - [GET /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/get) — Get Field groups - [PATCH /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/update) — Update Field groups - [DELETE /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/delete) — Delete Field groups - [Views](/api-reference/unified-crm-api/views) - [GET /unified/crm/views](/api-reference/unified-crm-api/views/list) — List Views - [Pipelines](/api-reference/unified-crm-api/pipelines) - [GET /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/get) — Get Pipelines - [PATCH /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/update) — Update Pipelines - [DELETE /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/delete) — Delete Pipelines - [GET /unified/crm/pipelines](/api-reference/unified-crm-api/pipelines/list) — List Pipelines - [POST /unified/crm/pipelines](/api-reference/unified-crm-api/pipelines/create) — Create Pipelines - [Projects](/api-reference/unified-crm-api/projects) - [GET /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/get) — Get Projects - [DELETE /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/delete) — Delete Projects - [PATCH /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/update) — Update Projects - [POST /unified/crm/projects](/api-reference/unified-crm-api/projects/create) — Create Projects - [GET /unified/crm/projects](/api-reference/unified-crm-api/projects/list) — List Projects - [Workspaces](/api-reference/unified-crm-api/workspaces) - [GET /unified/crm/workspaces](/api-reference/unified-crm-api/workspaces/list) — List Workspaces - [Associations](/api-reference/unified-crm-api/associations) - [POST /unified/crm/associations](/api-reference/unified-crm-api/associations/create) — Create Associations - [LineItems](/api-reference/unified-crm-api/lineitems) - [GET /unified/crm/line_items/{id}](/api-reference/unified-crm-api/lineitems/get) — Get Line items - [GET /unified/crm/line_items](/api-reference/unified-crm-api/lineitems/list) — List Line items - [Quotes](/api-reference/unified-crm-api/quotes) - [GET /unified/crm/quotes/{id}](/api-reference/unified-crm-api/quotes/get) — Get Quotes - [GET /unified/crm/quotes](/api-reference/unified-crm-api/quotes/list) — List Quotes - [Products](/api-reference/unified-crm-api/products) - [GET /unified/crm/products/{id}](/api-reference/unified-crm-api/products/get) — Get Products - [GET /unified/crm/products](/api-reference/unified-crm-api/products/list) — List Products - [Conversations](/api-reference/unified-crm-api/conversations) - [GET /unified/crm/conversations](/api-reference/unified-crm-api/conversations/list) — List Conversations - [GET /unified/crm/conversations/{id}](/api-reference/unified-crm-api/conversations/get) — Get Conversations - [Messages](/api-reference/unified-crm-api/messages) - [GET /unified/crm/messages](/api-reference/unified-crm-api/messages/list) — List Messages - [POST /unified/crm/messages/get_original_content](/api-reference/unified-crm-api/messages/get_original_content) — Get Original Content Messages - [GET /unified/crm/messages/{id}](/api-reference/unified-crm-api/messages/get) — Get Messages --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-crm-api/accounts/ Schema for the `Accounts` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The account's unique identifier - **`owner`** _(object)_ The account's owner - **`id`** _(string)_ The owner's unique identifier - **`name`** _(string)_ The account's name - **`description`** _(string)_ The account's description - **`industry`** _(string)_ The account's industry - **`website`** _(string)_ The account's website - **`number_of_employees`** _(integer)_ The account's number of employees - **`addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the address - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`urls`** _(array)_ The account's urls - **`url`** _(string)_ The account's URL - **`type`** _(string)_ The account's URL type - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`custom_fields`** _(object)_ All the custom fields present on the account - **`last_activity_at`** _(string)_ The date and time of the account's last activity - **`updated_at`** _(string)_ The date and time of the account's last update - **`created_at`** _(string)_ The date and time of the account's creation - **`deleted`** _(boolean)_ Flag for deleted records - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/accounts](/api-reference/unified-crm-api/accounts/list) — List Accounts - [POST /unified/crm/accounts](/api-reference/unified-crm-api/accounts/create) — Create Accounts - [GET /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/get) — Get Accounts - [DELETE /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/delete) — Delete Accounts - [PATCH /unified/crm/accounts/{id}](/api-reference/unified-crm-api/accounts/update) — Update Accounts - [POST /unified/crm/accounts/merge](/api-reference/unified-crm-api/accounts/merge) — Merge Accounts - [POST /unified/crm/accounts/batch-delete](/api-reference/unified-crm-api/accounts/batch-delete) — Batch Delete Accounts --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-crm-api/contacts/ Schema for the `Contacts` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The contact's unique identifier - **`first_name`** _(string)_ The contact's first name - **`last_name`** _(string)_ The contact's last name - **`name`** _(string)_ The contact's full name - **`title`** _(string)_ The contact's job title - **`account`** _(object)_ The contact's account - **`id`** _(string)_ The account's unique identifier - **`name`** _(string)_ The account's name - **`addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the address - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`email_addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the email addresses - **`email`** _(string)_ The email address - **`type`** _(string)_ The email address type - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`custom_fields`** _(object)_ All the custom fields present on the contact - **`last_activity_at`** _(string)_ The date and time of the contact's last activity - **`created_at`** _(string)_ The date and time of the contact's creation - **`updated_at`** _(string)_ The date and time of the contact's last update - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`owner`** _(object)_ The account's owner - **`id`** _(string)_ The owner's unique identifier - **`urls`** _(array)_ The contact's urls - **`url`** _(string)_ The contact's URL - **`type`** _(string)_ The contact's URL type - **`deleted`** _(boolean)_ Flag for deleted records - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/contacts](/api-reference/unified-crm-api/contacts/list) — List Contacts - [POST /unified/crm/contacts](/api-reference/unified-crm-api/contacts/create) — Create Contacts - [GET /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/get) — Get Contacts - [DELETE /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/delete) — Delete Contacts - [PATCH /unified/crm/contacts/{id}](/api-reference/unified-crm-api/contacts/update) — Update Contacts - [POST /unified/crm/contacts/merge](/api-reference/unified-crm-api/contacts/merge) — Merge Contacts - [POST /unified/crm/contacts/batch-delete](/api-reference/unified-crm-api/contacts/batch-delete) — Batch Delete Contacts --- # EngagementTypes Object > Source: https://truto.one/docs/api-reference/unified-crm-api/engagementtypes/ Schema for the `EngagementTypes` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The engagement type's unique identifier - **`type`** _(string)_ The engagement type's type - **`name`** _(string)_ The engagement type's name - **`created_at`** _(string)_ The date and time of the engagement type's creation - **`updated_at`** _(string)_ The date and time of the engagement type's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/engagement_types](/api-reference/unified-crm-api/engagementtypes/list) — List Engagement types - [POST /unified/crm/engagement_types](/api-reference/unified-crm-api/engagementtypes/create) — Create Engagement types - [GET /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/get) — Get Engagement types - [PATCH /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/update) — Update Engagement types - [DELETE /unified/crm/engagement_types/{id}](/api-reference/unified-crm-api/engagementtypes/delete) — Delete Engagement types --- # Engagements Object > Source: https://truto.one/docs/api-reference/unified-crm-api/engagements/ Schema for the `Engagements` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The engagement's unique identifier - **`owner`** _(object)_ The engagement's owner - **`id`** _(string)_ The owner's unique identifier - **`content`** _(string)_ The engagement's content - **`subject`** _(string)_ The engagement's subject - **`direction`** _(string)_ The engagement's direction - **`engagement_type`** _(string)_ The engagement's type - call, email, meeting or raw response - **`internal_notes`** _(string)_ The engagement's internal notes - **`notes`** _(array)_ The engagement's notes - **`id`** _(string)_ The note's unique identifier - **`status`** _(string)_ The engagement's status - **`start_time`** _(string)_ The engagement's start time - **`end_time`** _(string)_ The engagement's end time - **`duration`** _(string)_ The engagement's duration - **`project`** _(object)_ The engagement's project - **`id`** _(string)_ The project's unique identifier - **`account`** _(object)_ The engagement's account - **`id`** _(string)_ The account's unique identifier - **`contact`** _(array)_ The engagement's contacts - **`id`** _(string)_ The contact's unique identifier - **`opportunity`** _(array)_ The engagement's opportunity - **`id`** _(string)_ The opportunity's unique identifier - **`lead`** _(array)_ The engagement's lead - **`id`** _(string)_ The lead's unique identifier - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`outcome`** _(string)_ The result of the engagement. For calls, this is the call disposition (for example, connected, no_answer, left_voicemail, busy, wrong_number). For meetings, this is the meeting outcome (for example, completed, no_show, rescheduled, canceled). Values are normalized to lowercase snake_case where possible; provider-specific labels may be returned when no standard mapping exists. - **`recording_url`** _(string)_ A URL to access the call or meeting recording when available from the CRM. May be a direct media URL or a CRM-hosted review page, depending on the provider. - **`transcript`** _(string)_ The full text transcript of the call or meeting when available from the CRM. Structured or speaker-segmented transcripts are flattened to plain text in this field. - **`custom_fields`** _(object)_ All the custom fields present on the engagement - **`created_at`** _(string)_ The date and time of the engagement's creation - **`updated_at`** _(string)_ The date and time of the engagement's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/engagements](/api-reference/unified-crm-api/engagements/list) — List Engagements - [POST /unified/crm/engagements](/api-reference/unified-crm-api/engagements/create) — Create Engagements - [GET /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/get) — Get Engagements - [PATCH /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/update) — Update Engagements - [DELETE /unified/crm/engagements/{id}](/api-reference/unified-crm-api/engagements/delete) — Delete Engagements --- # Leads Object > Source: https://truto.one/docs/api-reference/unified-crm-api/leads/ Schema for the `Leads` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The lead' unique identifier - **`owner`** _(object)_ The lead's owner - **`id`** _(string)_ The lead's owner's unique identifier - **`lead_source`** _(string)_ The lead's source - **`lead_type`** _(string)_ The lead's type - **`status`** _(string)_ The lead's status - **`title`** _(string)_ The lead's title - **`contact`** _(object)_ The contact associated with the lead - **`id`** _(string)_ The contact's unique identifier - **`account`** _(object)_ The lead's account - **`id`** _(string)_ The account's unique identifier - **`first_name`** _(string)_ The lead's first name - **`last_name`** _(string)_ The lead's last name - **`addresses`** _(array)_ - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`email_addresses`** _(array)_ - **`email`** _(string)_ The email address - **`type`** _(string)_ The email address type - **`phone_numbers`** _(array)_ - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`custom_fields`** _(object)_ All the custom fields present on the lead - **`last_activity_at`** _(string)_ The date and time of the lead's last activity - **`created_at`** _(string)_ The date and time of the lead's creation - **`updated_at`** _(string)_ The date and time of the lead's last update - **`converted_at`** _(string)_ The date and time of the lead's conversion - **`converted_contact`** _(string)_ The lead's converted contact - **`converted_account`** _(string)_ The lead's converted account - **`urls`** _(array)_ The lead's urls - **`url`** _(string)_ The lead's URL - **`type`** _(string)_ The lead's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/leads](/api-reference/unified-crm-api/leads/list) — List Leads - [POST /unified/crm/leads](/api-reference/unified-crm-api/leads/create) — Create Leads - [GET /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/get) — Get Leads - [PATCH /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/update) — Update Leads - [DELETE /unified/crm/leads/{id}](/api-reference/unified-crm-api/leads/delete) — Delete Leads --- # Notes Object > Source: https://truto.one/docs/api-reference/unified-crm-api/notes/ Schema for the `Notes` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The note's unique identifier - **`title`** _(string)_ The note's title - **`owner`** _(object)_ The note's owner - **`id`** _(string)_ The note's owner's unique identifier - **`content`** _(string)_ The note's content - **`contact`** _(array)_ The note's contact - **`id`** _(string)_ The contact's unique identifier - **`account`** _(object)_ The note's account - **`id`** _(string)_ The account's unique identifier - **`opportunity`** _(array)_ The note's opportunities - **`id`** _(string)_ The opportunity's unique identifier - **`lead`** _(array)_ The note's leads - **`id`** _(string)_ The lead's unique identifier - **`visibility`** _(string)_ The note's visibility Allowed: `public`, `private` - **`created_at`** _(string)_ The date and time of the note's creation - **`updated_at`** _(string)_ The date and time of the note's last update - **`urls`** _(array)_ The note's urls - **`url`** _(string)_ The note's URL - **`type`** _(string)_ The note's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/notes](/api-reference/unified-crm-api/notes/list) — List Notes - [POST /unified/crm/notes](/api-reference/unified-crm-api/notes/create) — Create Notes - [GET /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/get) — Get Notes - [PATCH /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/update) — Update Notes - [DELETE /unified/crm/notes/{id}](/api-reference/unified-crm-api/notes/delete) — Delete Notes --- # Opportunities Object > Source: https://truto.one/docs/api-reference/unified-crm-api/opportunities/ Schema for the `Opportunities` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The opportunity's unique identifier - **`name`** _(string)_ The opportunity's name - **`description`** _(string)_ The opportunity's description - **`amount`** _(number)_ The opportunity's amount - **`currency`** _(string)_ The amount attribute's currency - **`owner`** _(object)_ The opportunity's owner - **`id`** _(string)_ The opportunity's owner's unique identifier - **`account`** _(object)_ The opportunity's account - **`id`** _(string)_ The account's unique identifier - **`contact`** _(array)_ The opportunity's contacts - **`id`** _(string)_ The contact's unique identifier - **`stage`** _(object)_ The opportunity's stage - **`id`** _(string)_ The stage's unique identifier - **`name`** _(string)_ The stage's name - **`status`** _(string)_ The opportunity's status - **`tags`** _(array)_ The opportunity's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`custom_fields`** _(object)_ All the custom fields present on the opportunity - **`last_activity_at`** _(string)_ The date and time of the opportunity's last activity - **`close_date`** _(string)_ The date and time of the opportunity's close date - **`created_at`** _(string)_ The date and time of the opportunity's creation - **`updated_at`** _(string)_ The date and time of the opportunity's last update - **`urls`** _(array)_ The opportunity's urls - **`url`** _(string)_ The opportunity's URL - **`type`** _(string)_ The opportunity's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/opportunities](/api-reference/unified-crm-api/opportunities/list) — List Opportunities - [POST /unified/crm/opportunities](/api-reference/unified-crm-api/opportunities/create) — Create Opportunities - [GET /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/get) — Get Opportunities - [DELETE /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/delete) — Delete Opportunities - [PATCH /unified/crm/opportunities/{id}](/api-reference/unified-crm-api/opportunities/update) — Update Opportunities --- # Stages Object > Source: https://truto.one/docs/api-reference/unified-crm-api/stages/ Schema for the `Stages` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The stage's unique identifier - **`name`** _(string)_ The stage's name - **`position`** _(number)_ The order of stage in the pipeline - **`status`** _(string)_ The status of the stage Allowed: `active`, `inactive` - **`pipeline`** _(object)_ The pipeline this stage is part of - **`id`** _(string)_ The pipeline's unique identifier - **`name`** _(string)_ The name of the pipeline - **`created_at`** _(string)_ The date and time of the stage's creation - **`updated_at`** _(string)_ The date and time of the stage's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/stages](/api-reference/unified-crm-api/stages/list) — List Stages - [POST /unified/crm/stages](/api-reference/unified-crm-api/stages/create) — Create Stages - [GET /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/get) — Get Stages - [PATCH /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/update) — Update Stages - [DELETE /unified/crm/stages/{id}](/api-reference/unified-crm-api/stages/delete) — Delete Stages --- # Tasks Object > Source: https://truto.one/docs/api-reference/unified-crm-api/tasks/ Schema for the `Tasks` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The task's unique identifier - **`subject`** _(string)_ The task's subject - **`content`** _(string)_ The task's content - **`type`** _(object)_ The task's type - **`id`** _(string)_ The type's unique identifier - **`name`** _(string)_ The type's name - **`owner`** _(object)_ The task's owner - **`id`** _(string)_ The owner's unique identifier - **`name`** _(string)_ The owner's name - **`account`** _(object)_ The task's account - **`id`** _(string)_ The account's unique identifier - **`contact`** _(array)_ The task's contact - **`id`** _(string)_ The contact's unique identifier - **`name`** _(string)_ The contact's name - **`opportunity`** _(array)_ The task's opportunity - **`id`** _(string)_ The opportunity's unique identifier - **`name`** _(string)_ The opportunity's name - **`lead`** _(array)_ The task's lead - **`id`** _(string)_ The lead's unique identifier - **`name`** _(string)_ The lead's name - **`completed_at`** _(string)_ The date and time of the task's completion - **`due_date`** _(string)_ The date and time of the task's due date - **`status`** _(string)_ The task's status Allowed: `open`, `completed` - **`created_at`** _(string)_ The date and time of the task's creation - **`updated_at`** _(string)_ The date and time of the task's last update - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`urls`** _(array)_ The task's urls - **`url`** _(string)_ The task's URL - **`type`** _(string)_ The task's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/tasks](/api-reference/unified-crm-api/tasks/list) — List Tasks - [POST /unified/crm/tasks](/api-reference/unified-crm-api/tasks/create) — Create Tasks - [GET /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/get) — Get Tasks - [DELETE /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/delete) — Delete Tasks - [PATCH /unified/crm/tasks/{id}](/api-reference/unified-crm-api/tasks/update) — Update Tasks --- # Users Object > Source: https://truto.one/docs/api-reference/unified-crm-api/users/ Schema for the `Users` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The user's unique identifier - **`name`** _(string)_ The user's name - **`email`** _(string)_ The user's email - **`is_active`** _(boolean)_ Whether the user is active - **`created_at`** _(string)_ The date and time of the user's creation - **`updated_at`** _(string)_ The date and time of the user's last update - **`urls`** _(array)_ The user's urls - **`url`** _(string)_ The user's URL - **`type`** _(string)_ The user's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/users](/api-reference/unified-crm-api/users/list) — List Users - [POST /unified/crm/users](/api-reference/unified-crm-api/users/create) — Create Users - [GET /unified/crm/users/{id}](/api-reference/unified-crm-api/users/get) — Get Users - [DELETE /unified/crm/users/{id}](/api-reference/unified-crm-api/users/delete) — Delete Users - [PATCH /unified/crm/users/{id}](/api-reference/unified-crm-api/users/update) — Update Users --- # Fields Object > Source: https://truto.one/docs/api-reference/unified-crm-api/fields/ Schema for the `Fields` resource in **Unified CRM API**. ## Properties - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`description`** _(string)_ The field's description - **`type`** _(string)_ The field's type Allowed: `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file`, `address` - **`is_hidden`** _(boolean)_ Whether the field is hidden - **`is_unique`** _(boolean)_ Whether the field is unique - **`is_required`** _(boolean)_ Whether the field is required - **`is_editable`** _(boolean)_ Whether the field is editable - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`is_hidden`** _(boolean)_ Whether the option is hidden - **`is_user_defined`** _(boolean)_ Whether the field is user defined - **`entity_type`** _(string)_ The entity type the field belongs to Allowed: `contact`, `account`, `opportunity` - **`reference_entity`** _(string)_ The entity type this field references to Allowed: `contact`, `account`, `opportunity`, `lead` - **`field_groups`** _(array)_ - **`id`** _(string)_ The field group's unique identifier - **`name`** _(string)_ The field group's name - **`created_at`** _(string)_ The date and time of the field's creation - **`updated_at`** _(string)_ The date and time of the field's last update - **`urls`** _(array)_ The field's urls - **`url`** _(string)_ The field's URL - **`type`** _(string)_ The field's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/fields](/api-reference/unified-crm-api/fields/list) — List Fields - [POST /unified/crm/fields](/api-reference/unified-crm-api/fields/create) — Create Fields - [GET /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/get) — Get Fields - [PATCH /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/update) — Update Fields - [DELETE /unified/crm/fields/{id}](/api-reference/unified-crm-api/fields/delete) — Delete Fields --- # FieldGroups Object > Source: https://truto.one/docs/api-reference/unified-crm-api/fieldgroups/ Schema for the `FieldGroups` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The field group's unique identifier - **`name`** _(string, required)_ The field group's name. Used in other resources to reference the field group. - **`label`** _(string)_ The field group's descriptive label - **`description`** _(string)_ The field group's description - **`entity_type`** _(string)_ The entity type the field group belongs to Allowed: `contact`, `account`, `opportunity` - **`status`** _(string)_ The field group's status Allowed: `active`, `inactive` - **`created_at`** _(string)_ The date and time of the field group's creation - **`updated_at`** _(string)_ The date and time of the field group's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/field_groups](/api-reference/unified-crm-api/fieldgroups/list) — List Field groups - [POST /unified/crm/field_groups](/api-reference/unified-crm-api/fieldgroups/create) — Create Field groups - [GET /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/get) — Get Field groups - [PATCH /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/update) — Update Field groups - [DELETE /unified/crm/field_groups/{id}](/api-reference/unified-crm-api/fieldgroups/delete) — Delete Field groups --- # Views Object > Source: https://truto.one/docs/api-reference/unified-crm-api/views/ Schema for the `Views` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The view's unique identifier - **`name`** _(string)_ The view's name - **`entity`** _(string)_ The entity the view belongs to Allowed: `contact`, `account`, `opportunity` - **`created_at`** _(string)_ The date and time of the view's creation - **`updated_at`** _(string)_ The date and time of the view's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/views](/api-reference/unified-crm-api/views/list) — List Views --- # Pipelines Object > Source: https://truto.one/docs/api-reference/unified-crm-api/pipelines/ Schema for the `Pipelines` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the pipeline - **`name`** _(string)_ The name of the pipeline - **`entity`** _(string)_ The entity associated with the pipeline Allowed: `contact`, `account`, `opportunity` - **`stages`** _(array)_ The stages associated with the pipeline - **`id`** _(string)_ The unique identifier for the stage - **`name`** _(string)_ The name of the stage - **`status`** _(string)_ The status of the entity at the stage - **`pipeline`** _(object)_ The pipeline associated with the stage - **`id`** _(string)_ The unique identifier for the pipeline - **`created_at`** _(string)_ The date and time when the pipeline was created - **`updated_at`** _(string)_ The date and time when the pipeline was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/get) — Get Pipelines - [PATCH /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/update) — Update Pipelines - [DELETE /unified/crm/pipelines/{id}](/api-reference/unified-crm-api/pipelines/delete) — Delete Pipelines - [GET /unified/crm/pipelines](/api-reference/unified-crm-api/pipelines/list) — List Pipelines - [POST /unified/crm/pipelines](/api-reference/unified-crm-api/pipelines/create) — Create Pipelines --- # Projects Object > Source: https://truto.one/docs/api-reference/unified-crm-api/projects/ Schema for the `Projects` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The project's unique identifier - **`name`** _(string)_ The project's name - **`description`** _(string)_ The project's description - **`amount`** _(number)_ The project's amount - **`currency`** _(string)_ The amount attribute's currency - **`owner`** _(object)_ The project's owner - **`id`** _(string)_ The owner's unique identifier - **`name`** _(string)_ The owner name - **`account`** _(object)_ The project's account - **`id`** _(string)_ The account's unique identifier - **`name`** _(string)_ The account name - **`contact`** _(array)_ The project's contacts - **`id`** _(string)_ The contact's unique identifier - **`name`** _(string)_ The contact name - **`opportunity`** _(array)_ The project's opportunity - **`id`** _(string)_ The opportunity's unique identifier - **`name`** _(string)_ The opportunity name - **`stage`** _(object)_ The project's stage - **`id`** _(string)_ The stage's unique identifier - **`name`** _(string)_ The stage's name - **`status`** _(string)_ The project's status - **`tags`** _(array)_ The project's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`last_activity_at`** _(string)_ The date and time of the project's last activity - **`close_date`** _(string)_ The date and time of the project's close date - **`created_at`** _(string)_ The date and time of the project's creation - **`updated_at`** _(string)_ The date and time of the project's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/get) — Get Projects - [DELETE /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/delete) — Delete Projects - [PATCH /unified/crm/projects/{id}](/api-reference/unified-crm-api/projects/update) — Update Projects - [POST /unified/crm/projects](/api-reference/unified-crm-api/projects/create) — Create Projects - [GET /unified/crm/projects](/api-reference/unified-crm-api/projects/list) — List Projects --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-crm-api/workspaces/ Schema for the `Workspaces` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The workspace's unique identifier - **`name`** _(string)_ The workspace's name - **`description`** _(string)_ The workspace's description - **`updated_at`** _(string)_ The date and time of the workspace's last update - **`created_at`** _(string)_ The date and time of the workspace's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/workspaces](/api-reference/unified-crm-api/workspaces/list) — List Workspaces --- # Associations Object > Source: https://truto.one/docs/api-reference/unified-crm-api/associations/ Schema for the `Associations` resource in **Unified CRM API**. ## Properties - **`entity_id`** _(string)_ The unique identifier for the entity. - **`entity`** _(string)_ The type of the entity. - **`associations`** _(object)_ - **`acocunts`** _(array)_ - **`id`** _(string)_ - **`contacts`** _(array)_ - **`id`** _(string)_ - **`leads`** _(array)_ - **`id`** _(string)_ - **`opportunities`** _(array)_ - **`id`** _(string)_ - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/crm/associations](/api-reference/unified-crm-api/associations/create) — Create Associations --- # LineItems Object > Source: https://truto.one/docs/api-reference/unified-crm-api/lineitems/ Schema for the `LineItems` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The line item's unique identifier - **`name`** _(string)_ The line item's name - **`description`** _(string)_ The line item's description - **`amount`** _(number)_ The line item's amount - **`quantity`** _(number)_ The line item's quantity - **`currency`** _(string)_ The amount attribute's currency - **`product`** _(object)_ The product associated with the line item - **`id`** _(string)_ The unique identifier - **`opportunity`** _(array)_ The line item's opportunities - **`id`** _(string)_ The opportunity's unique identifier - **`account`** _(object)_ The account associated with the line item - **`id`** _(string)_ The unique identifier - **`owner`** _(object)_ The line item's owner - **`id`** _(string)_ The unique identifier - **`created_at`** _(string)_ The date and time of the line item's creation - **`updated_at`** _(string)_ The date and time of the line item's last update - **`custom_fields`** _(object)_ Custom fields for the line item - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/line_items/{id}](/api-reference/unified-crm-api/lineitems/get) — Get Line items - [GET /unified/crm/line_items](/api-reference/unified-crm-api/lineitems/list) — List Line items --- # Quotes Object > Source: https://truto.one/docs/api-reference/unified-crm-api/quotes/ Schema for the `Quotes` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The quote's unique identifier - **`name`** _(string)_ The quote's title/name - **`status`** _(string)_ The quote's status - **`amount`** _(number)_ The quote's amount - **`currency`** _(string)_ The amount attribute's currency - **`expiration_date`** _(string)_ The quote's expiration date - **`opportunity`** _(array)_ The quote's opportunities - **`id`** _(string)_ The opportunity's unique identifier - **`owner`** _(object)_ The quote's owner - **`id`** _(string)_ The unique identifier - **`created_at`** _(string)_ The date and time of the quote's creation - **`updated_at`** _(string)_ The date and time of the quote's last update - **`custom_fields`** _(object)_ Custom fields for the quote - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/quotes/{id}](/api-reference/unified-crm-api/quotes/get) — Get Quotes - [GET /unified/crm/quotes](/api-reference/unified-crm-api/quotes/list) — List Quotes --- # Products Object > Source: https://truto.one/docs/api-reference/unified-crm-api/products/ Schema for the `Products` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The product's unique identifier - **`name`** _(string)_ The product's name - **`description`** _(string)_ The product's description - **`price`** _(number)_ The product's price - **`sku`** _(string)_ The product's SKU - **`created_at`** _(string)_ The date and time of the product's creation - **`updated_at`** _(string)_ The date and time of the product's last update - **`custom_fields`** _(object)_ Custom fields for the product - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/products/{id}](/api-reference/unified-crm-api/products/get) — Get Products - [GET /unified/crm/products](/api-reference/unified-crm-api/products/list) — List Products --- # Conversations Object > Source: https://truto.one/docs/api-reference/unified-crm-api/conversations/ Schema for the `Conversations` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The conversation's unique identifier - **`status`** _(string)_ The conversation's status - **`channel`** _(string)_ The conversation channel (live chat, email, Messenger, WhatsApp, forms, etc.) - **`assignee`** _(object)_ The agent/user assigned to the conversation - **`id`** _(string)_ The unique identifier - **`ticket`** _(object)_ The ticket associated with the conversation - **`id`** _(string)_ The ticket's unique identifier - **`inbox_id`** _(string)_ The inbox this conversation belongs to - **`latest_message_preview`** _(string)_ Preview text of the latest message - **`created_at`** _(string)_ The date and time of the conversation's creation - **`updated_at`** _(string)_ The date and time of the conversation's last update - **`closed_at`** _(string)_ The date and time the conversation was closed - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/conversations](/api-reference/unified-crm-api/conversations/list) — List Conversations - [GET /unified/crm/conversations/{id}](/api-reference/unified-crm-api/conversations/get) — Get Conversations --- # Messages Object > Source: https://truto.one/docs/api-reference/unified-crm-api/messages/ Schema for the `Messages` resource in **Unified CRM API**. ## Properties - **`id`** _(string, required)_ The message's unique identifier - **`conversation`** _(object)_ The parent conversation - **`id`** _(string)_ The unique identifier - **`content`** _(string)_ The message body/content - **`direction`** _(string)_ The message direction (inbound/outbound) - **`channel`** _(string)_ The channel the message was sent on - **`sender_type`** _(string)_ The type of sender (agent, visitor, bot, etc.) - **`created_at`** _(string)_ The date and time of the message's creation - **`updated_at`** _(string)_ The date and time of the message's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/crm/messages](/api-reference/unified-crm-api/messages/list) — List Messages - [POST /unified/crm/messages/get_original_content](/api-reference/unified-crm-api/messages/get_original_content) — Get Original Content Messages - [GET /unified/crm/messages/{id}](/api-reference/unified-crm-api/messages/get) — Get Messages --- # Unified E-Commerce API > Source: https://truto.one/docs/api-reference/unified-e-commerce-api/ Base URL: `https://api.truto.one/unified/ecommerce` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Orders](/api-reference/unified-e-commerce-api/orders) - [GET /unified/ecommerce/orders](/api-reference/unified-e-commerce-api/orders/list) — List Orders - [GET /unified/ecommerce/orders/{id}](/api-reference/unified-e-commerce-api/orders/get) — Get Orders - [Products](/api-reference/unified-e-commerce-api/products) - [GET /unified/ecommerce/products](/api-reference/unified-e-commerce-api/products/list) — List Products - [POST /unified/ecommerce/products](/api-reference/unified-e-commerce-api/products/create) — Create Products - [GET /unified/ecommerce/products/{id}](/api-reference/unified-e-commerce-api/products/get) — Get Products - [Customers](/api-reference/unified-e-commerce-api/customers) - [GET /unified/ecommerce/customers](/api-reference/unified-e-commerce-api/customers/list) — List Customers - [GET /unified/ecommerce/customers/{id}](/api-reference/unified-e-commerce-api/customers/get) — Get Customers --- # Orders Object > Source: https://truto.one/docs/api-reference/unified-e-commerce-api/orders/ Schema for the `Orders` resource in **Unified E-Commerce API**. ## Properties - **`id`** _(string, required)_ The unique identifier for an order - **`order_number`** _(string)_ The order number for an order - **`currency`** _(string)_ The currency associated for amount of an order - **`exchange_rate`** _(string)_ The exchange rate for an order's transaction when the currency is different from the store's default currency. - **`discounts`** _(array)_ The discounts for an order - **`code`** _(string)_ The code used to apply the discount - **`amount`** _(string)_ The fixed amount of the discount - **`percentage`** _(string)_ The percentage of discount - **`sub_total`** _(string)_ The sub-total amount for an order - **`shipping_cost`** _(string)_ The shipping cost for an order - **`total_discount`** _(string)_ The total discount for an order - **`total_tax`** _(string)_ The total tax for an order - **`total_amount`** _(string)_ The total amount for an order - **`status`** _(string)_ The status for an order. If no clear mapping exists, then raw value is returned. Allowed: `active`, `completed`, `cancelled`, `archived`, `pending` - **`payment_status`** _(string)_ The payment status for an order. If no clear mapping exists, then raw value is returned. Allowed: `pending`, `authorized`, `paid`, `partial`, `refunded`, `voided`, `cancelled`, `unknown` - **`fulfillment_status`** _(string)_ The fullfillment status for an order. If no clear mapping exists, then raw value is returned. Allowed: `pending`, `partial`, `delivered`, `cancelled` - **`payment_method`** _(string)_ The payment method used for this order - **`customer`** _(object)_ The customer this order is linked to - **`id`** _(string)_ The unique identifier for customer - **`first_name`** _(string)_ The first name of customer - **`last_name`** _(string)_ The last name of customer - **`name`** _(string)_ The full name of customer - **`company_name`** _(string)_ The company name of customer - **`emails`** _(array)_ The emails of customer - **`email`** _(string)_ The email of the customer - **`type`** _(string)_ The type of email - **`is_primary`** _(boolean)_ The status of email - **`phones`** _(array)_ The phone numbers of customer - **`number`** _(string)_ The number of phone - **`type`** _(string)_ The type of phone - **`billing_address`** _(object)_ The billing address for an order - **`street_1`** _(string)_ The first line of billing address - **`street_2`** _(string)_ The second line of billing address - **`company_name`** _(string)_ The company name of customer - **`city`** _(string)_ The city of the billing address - **`state`** _(string)_ The state/province of the billng address - **`postal_code`** _(string)_ The postal code of the billing address - **`country`** _(string)_ The country of the billing address - **`shipping_address`** _(object)_ The shipping address for an order - **`street_1`** _(string)_ The first line of shipping address - **`street_2`** _(string)_ The second line of shipping address - **`company_name`** _(string)_ The company name of customer - **`city`** _(string)_ The city of the shipping address - **`state`** _(string)_ The state/province of the shipping address - **`postal_code`** _(string)_ The postal code of the shipping address - **`country`** _(string)_ The country of the shipping address - **`tracking`** _(object)_ The tracking details for an order - **`provider`** _(string, required)_ The name of carrier handling the shipment - **`number`** _(string, required)_ The tracking number of shipment - **`url`** _(string)_ The url of tracking page - **`updated_at`** _(string)_ The date and time of last parcel update - **`line_items`** _(array)_ The line items for an order - **`name`** _(string, required)_ The name of the line item - **`quantity`** _(string, required)_ The quantity of the line item - **`total_amount`** _(string)_ The total amount of the line item - **`id`** _(string)_ The id of the line item - **`product_id`** _(string)_ The product id of the line item - **`variant_id`** _(string)_ The variant id of the line item - **`sku`** _(string)_ The sku of the line item - **`description`** _(string)_ The description of the line item - **`options`** _(array)_ The options for line item - **`id`** _(string)_ The unique identifier for options - **`name`** _(string)_ The name for options - **`value`** _(string)_ The value for options - **`unit_price`** _(string)_ The unit price of the line item - **`tax_rate`** _(string)_ The tax rate of the line item - **`tax_amount`** _(string)_ The tax amount of the line item - **`discounts`** _(array)_ The discounts for line item - **`code`** _(string)_ The used for discounts - **`amount`** _(string)_ The fixed amount for discounts - **`percentage`** _(string)_ The percentage of discounts - **`note`** _(string)_ The note for an order - **`created_at`** _(string)_ The date and time when order was created - **`updated_at`** _(string)_ The date and time when order was updated - **`type`** _(string)_ The type of the order - **`shipping_methods`** _(object)_ The shipping methods that are associated with the Order. - **`submitted_date`** _(string)_ - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ecommerce/orders](/api-reference/unified-e-commerce-api/orders/list) — List Orders - [GET /unified/ecommerce/orders/{id}](/api-reference/unified-e-commerce-api/orders/get) — Get Orders --- # Products Object > Source: https://truto.one/docs/api-reference/unified-e-commerce-api/products/ Schema for the `Products` resource in **Unified E-Commerce API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a product - **`name`** _(string)_ The name of a product - **`description`** _(string)_ The description of a product - **`status`** _(string)_ The status of a product. If no clear mapping exists, then raw value is returned. Allowed: `active`, `inactive` - **`price`** _(string)_ The price of a product - **`sku`** _(string)_ The sku of a product - **`inventory_quantity`** _(string)_ The quantity of a product in stock - **`images`** _(array)_ The images of a product - **`id`** _(string)_ The unique identifier of an image of a product - **`url`** _(string)_ The url of an image of product - **`weight`** _(string)_ The weight of a product - **`weight_unit`** _(string)_ The weight unit of a product - **`options`** _(array)_ The options of a product - **`id`** _(string)_ The unique identifier of an option of a product - **`name`** _(string)_ The name of option for product - **`values`** _(array)_ The values of option for product - **`variants`** _(array)_ The options of a product - **`id`** _(string)_ The unique identifier of a variant of a product - **`name`** _(string)_ The name of variant for product - **`price`** _(string)_ The price of variant for product - **`sku`** _(string)_ The sku of variant for product - **`inventory_quantity`** _(string)_ The quantity of variant for product in stock - **`weight`** _(string)_ The weight of variant - **`options`** _(array)_ The options for variant - **`id`** _(string)_ The unique identifier for option of variant - **`name`** _(string)_ The name for option of variant - **`value`** _(string)_ The value for option of variant - **`images`** _(array)_ The images for variant - **`id`** _(string)_ The unique identifier for image of variant - **`url`** _(string)_ The url of image of variant - **`tags`** _(array)_ The tags of a product - **`categories`** _(array)_ The categories of a product - **`id`** _(string)_ The unique identifier of a category of product - **`name`** _(string)_ The name of category for product - **`created_at`** _(string)_ The date and time when product was created - **`updated_at`** _(string)_ The date and time when product was updated - **`notes`** _(string)_ The notes related to the product, if any. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ecommerce/products](/api-reference/unified-e-commerce-api/products/list) — List Products - [POST /unified/ecommerce/products](/api-reference/unified-e-commerce-api/products/create) — Create Products - [GET /unified/ecommerce/products/{id}](/api-reference/unified-e-commerce-api/products/get) — Get Products --- # Customers Object > Source: https://truto.one/docs/api-reference/unified-e-commerce-api/customers/ Schema for the `Customers` resource in **Unified E-Commerce API**. ## Properties - **`id`** _(string)_ The unique identifier for customer - **`first_name`** _(string)_ The first name of customer - **`last_name`** _(string)_ The last name of customer - **`name`** _(string)_ The full name of customer - **`company_name`** _(string)_ The company name of customer - **`status`** _(string)_ The status of customer. If no clear mapping exists, then raw value is returned. Allowed: `active`, `inactive` - **`currency`** _(string)_ The currency associated to customer - **`emails`** _(array)_ The emails of customer - **`email`** _(string, required)_ The email of the customer - **`type`** _(string)_ The type of email - **`is_primary`** _(boolean)_ The status of email - **`phones`** _(array)_ The phone numbers of customer - **`number`** _(string, required)_ The number of phone - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone - **`addresses`** _(array)_ The addresses of a customer - **`type`** _(string)_ The type of an address of a customer - **`id`** _(string)_ The unique identifier of an address of a customer - **`street_1`** _(string)_ The first line of address of a customer - **`street_2`** _(string)_ The second line of address of a customer - **`city`** _(string)_ The city of the address of a customer - **`state`** _(string)_ The state/province of the address of a customer - **`postal_code`** _(string)_ The postal code of the address of a customer - **`country`** _(string)_ The country of the address of a customer - **`orders`** _(array)_ The orders of customer - **`id`** _(string)_ The id of orders of the customer - **`total`** _(string)_ The total amount of orders of email - **`status`** _(string)_ The status of orders of the customer - **`created_at`** _(string)_ The date and time when customer was created - **`updated_at`** _(string)_ The date and time when customer was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ecommerce/customers](/api-reference/unified-e-commerce-api/customers/list) — List Customers - [GET /unified/ecommerce/customers/{id}](/api-reference/unified-e-commerce-api/customers/get) — Get Customers --- # Unified E-Signature API > Source: https://truto.one/docs/api-reference/unified-e-signature-api/ Base URL: `https://api.truto.one/unified/e-signature` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Groups](/api-reference/unified-e-signature-api/groups) - [GET /unified/e-signature/groups](/api-reference/unified-e-signature-api/groups/list) — List Groups - [GET /unified/e-signature/groups/{id}](/api-reference/unified-e-signature-api/groups/get) — Get Groups - [Users](/api-reference/unified-e-signature-api/users) - [GET /unified/e-signature/users](/api-reference/unified-e-signature-api/users/list) — List Users - [GET /unified/e-signature/users/{id}](/api-reference/unified-e-signature-api/users/get) — Get Users - [DELETE /unified/e-signature/users/{id}](/api-reference/unified-e-signature-api/users/delete) — Delete Users - [Workflows](/api-reference/unified-e-signature-api/workflows) - [GET /unified/e-signature/workflows](/api-reference/unified-e-signature-api/workflows/list) — List Workflows - [POST /unified/e-signature/workflows](/api-reference/unified-e-signature-api/workflows/create) — Create Workflows - [GET /unified/e-signature/workflows/{id}](/api-reference/unified-e-signature-api/workflows/get) — Get Workflows - [PATCH /unified/e-signature/workflows/{id}](/api-reference/unified-e-signature-api/workflows/update) — Update Workflows - [POST /unified/e-signature/workflows/cancel](/api-reference/unified-e-signature-api/workflows/cancel) — Cancel Workflows - [Templates](/api-reference/unified-e-signature-api/templates) - [GET /unified/e-signature/templates](/api-reference/unified-e-signature-api/templates/list) — List Templates - [GET /unified/e-signature/templates/{id}](/api-reference/unified-e-signature-api/templates/get) — Get Templates - [SigningRequests](/api-reference/unified-e-signature-api/signingrequests) - [GET /unified/e-signature/signing_requests](/api-reference/unified-e-signature-api/signingrequests/list) — List Signing requests - [POST /unified/e-signature/signing_requests](/api-reference/unified-e-signature-api/signingrequests/create) — Create Signing requests - [GET /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/get) — Get Signing requests - [PATCH /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/update) — Update Signing requests - [DELETE /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/delete) — Delete Signing requests - [POST /unified/e-signature/signing_requests/get_embed_url](/api-reference/unified-e-signature-api/signingrequests/get_embed_url) — Get Embed Url Signing requests - [POST /unified/e-signature/signing_requests/download](/api-reference/unified-e-signature-api/signingrequests/download) — Download Signing requests - [POST /unified/e-signature/signing_requests/remove_participants](/api-reference/unified-e-signature-api/signingrequests/remove_participants) — Remove Participants Signing requests - [Documents](/api-reference/unified-e-signature-api/documents) - [GET /unified/e-signature/documents](/api-reference/unified-e-signature-api/documents/list) — List Documents - [POST /unified/e-signature/documents](/api-reference/unified-e-signature-api/documents/create) — Create Documents - [GET /unified/e-signature/documents/{id}](/api-reference/unified-e-signature-api/documents/get) — Get Documents - [DELETE /unified/e-signature/documents/{id}](/api-reference/unified-e-signature-api/documents/delete) — Delete Documents - [POST /unified/e-signature/documents/download](/api-reference/unified-e-signature-api/documents/download) — Download Documents - [WebForms](/api-reference/unified-e-signature-api/webforms) - [GET /unified/e-signature/web_forms/{id}](/api-reference/unified-e-signature-api/webforms/get) — Get Web forms - [GET /unified/e-signature/web_forms](/api-reference/unified-e-signature-api/webforms/list) — List Web forms - [Contacts](/api-reference/unified-e-signature-api/contacts) - [GET /unified/e-signature/contacts](/api-reference/unified-e-signature-api/contacts/list) — List Contacts - [GET /unified/e-signature/contacts/{id}](/api-reference/unified-e-signature-api/contacts/get) — Get Contacts - [Collections](/api-reference/unified-e-signature-api/collections) - [GET /unified/e-signature/collections](/api-reference/unified-e-signature-api/collections/list) — List Collections - [GET /unified/e-signature/collections/{id}](/api-reference/unified-e-signature-api/collections/get) — Get Collections - [Fields](/api-reference/unified-e-signature-api/fields) - [GET /unified/e-signature/fields](/api-reference/unified-e-signature-api/fields/list) — List Fields - [FieldGroups](/api-reference/unified-e-signature-api/fieldgroups) - [GET /unified/e-signature/field_groups](/api-reference/unified-e-signature-api/fieldgroups/list) — List Field groups - [Stages](/api-reference/unified-e-signature-api/stages) - [GET /unified/e-signature/stages](/api-reference/unified-e-signature-api/stages/list) — List Stages - [DocumentFields](/api-reference/unified-e-signature-api/documentfields) - [GET /unified/e-signature/document_fields](/api-reference/unified-e-signature-api/documentfields/list) — List Document fields - [POST /unified/e-signature/document_fields](/api-reference/unified-e-signature-api/documentfields/create) — Create Document fields - [DELETE /unified/e-signature/document_fields/{id}](/api-reference/unified-e-signature-api/documentfields/delete) — Delete Document fields - [SigningRequestStatuses](/api-reference/unified-e-signature-api/signingrequeststatuses) - [GET /unified/e-signature/signing_request_statuses](/api-reference/unified-e-signature-api/signingrequeststatuses/list) — List Signing request statuses --- # Groups Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/groups/ Schema for the `Groups` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the group. - **`name`** _(string)_ The name of the group. - **`type`** _(string)_ The type of the group. - **`created_at`** _(string)_ The date and time when the group was created. - **`updated_at`** _(string)_ The date and time when the group was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/groups](/api-reference/unified-e-signature-api/groups/list) — List Groups - [GET /unified/e-signature/groups/{id}](/api-reference/unified-e-signature-api/groups/get) — Get Groups --- # Users Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/users/ Schema for the `Users` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`title`** _(string)_ The title of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`group`** _(string)_ The role of the user in the group. This is available when the user can have different roles in different groups or teams in an application. - **`organization`** _(string)_ The role of the user in the organization. This is available when the user can have different roles in different organizations in an application. - **`workspace`** _(string)_ The role of the user in the workspace. This is available when the user can have different roles in different workspaces in an application. - **`organizations`** _(array)_ The organizations of the user - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`workspace`** _(object)_ The workspace of the user - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`organization`** _(string)_ The unique identifier of the organization to which the workspace belongs - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`avatar`** _(string)_ The avatar of the user - **`timezone`** _(string)_ The timezone of the user - **`languages`** _(array)_ The languages preferred by the user - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`urls`** _(array)_ The URLs of the user - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/users](/api-reference/unified-e-signature-api/users/list) — List Users - [GET /unified/e-signature/users/{id}](/api-reference/unified-e-signature-api/users/get) — Get Users - [DELETE /unified/e-signature/users/{id}](/api-reference/unified-e-signature-api/users/delete) — Delete Users --- # Workflows Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/workflows/ Schema for the `Workflows` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the workflow. - **`name`** _(string)_ The name of the workflow. - **`description`** _(string)_ The description of the workflow. - **`type`** _(string)_ The type of the workflow. - **`status`** _(string)_ The status of the workflow. Allowed: `active`, `inactive`, `draft`, `hidden` - **`created_by`** _(object)_ The user who created the workflow. - **`id`** _(string)_ The unique identifier of the user. - **`name`** _(string)_ The name of the user. - **`created_at`** _(string)_ The date and time when the workflow was created. - **`updated_at`** _(string)_ The date and time when the workflow was last updated. - **`stage`** _(object)_ The stage of the workflow. - **`id`** _(string)_ The unique identifier of the stage. - **`name`** _(string)_ The name of the stage. - **`custom_fields`** _(object)_ All the custom fields present on the workflow - **`urls`** _(array)_ The workflow's urls - **`url`** _(string)_ The workflow's URL - **`type`** _(string)_ The workflow's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/workflows](/api-reference/unified-e-signature-api/workflows/list) — List Workflows - [POST /unified/e-signature/workflows](/api-reference/unified-e-signature-api/workflows/create) — Create Workflows - [GET /unified/e-signature/workflows/{id}](/api-reference/unified-e-signature-api/workflows/get) — Get Workflows - [PATCH /unified/e-signature/workflows/{id}](/api-reference/unified-e-signature-api/workflows/update) — Update Workflows - [POST /unified/e-signature/workflows/cancel](/api-reference/unified-e-signature-api/workflows/cancel) — Cancel Workflows --- # Templates Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/templates/ Schema for the `Templates` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the template. - **`name`** _(string)_ The name of the template. - **`description`** _(string)_ The description of the template. - **`type`** _(string)_ The type of the template. - **`locale`** _(string)_ The locale of the template. - **`created_at`** _(string)_ The date and time when the template was created. - **`updated_at`** _(string)_ The date and time when the template was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/templates](/api-reference/unified-e-signature-api/templates/list) — List Templates - [GET /unified/e-signature/templates/{id}](/api-reference/unified-e-signature-api/templates/get) — Get Templates --- # SigningRequests Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/signingrequests/ Schema for the `SigningRequests` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the signing request. - **`name`** _(string)_ The name of the signing request. This is usually the email subject that goes as part of the signing request. - **`description`** _(string)_ Human readable description of the signing request. This is usually the email body that goes as part of the signing request. - **`type`** _(string)_ The type of the signing request. - **`status`** _(object)_ The status of the signing request. - **`id`** _(string)_ - **`name`** _(string)_ - **`cancellation_reason`** _(string)_ If the signing request is voided or cancelled, the reason is specified here. - **`collections`** _(array)_ The collections of the signing request. - **`id`** _(string)_ The unique identifier of the collection. - **`name`** _(string)_ The name of the collection. - **`groups`** _(array)_ The groups of the signing request. - **`id`** _(string)_ The unique identifier of the group. - **`type`** _(string)_ The type of the group. - **`participants`** _(array)_ The participants of the signing request. - **`id`** _(string)_ The unique identifier of the participant. - **`name`** _(string)_ The name of the participant. - **`emails`** _(array)_ The emails of the participant. - **`email`** _(string)_ The email address of the participant. - **`is_signer`** _(boolean)_ Specifies whether the participant is a signer of the document. - **`routing_order`** _(number)_ The routing order of the participant. - **`urls`** _(array)_ The urls of the signing_request - **`url`** _(string)_ The url of the signing_request - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_at`** _(string)_ The date and time when the signing request was created. - **`updated_at`** _(string)_ The date and time when the signing request was last updated. - **`last_activity_at`** _(string)_ The date and time when the signing request was last updated. - **`expires_at`** _(string)_ The date and time when the signing request expires. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/signing_requests](/api-reference/unified-e-signature-api/signingrequests/list) — List Signing requests - [POST /unified/e-signature/signing_requests](/api-reference/unified-e-signature-api/signingrequests/create) — Create Signing requests - [GET /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/get) — Get Signing requests - [PATCH /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/update) — Update Signing requests - [DELETE /unified/e-signature/signing_requests/{id}](/api-reference/unified-e-signature-api/signingrequests/delete) — Delete Signing requests - [POST /unified/e-signature/signing_requests/get_embed_url](/api-reference/unified-e-signature-api/signingrequests/get_embed_url) — Get Embed Url Signing requests - [POST /unified/e-signature/signing_requests/download](/api-reference/unified-e-signature-api/signingrequests/download) — Download Signing requests - [POST /unified/e-signature/signing_requests/remove_participants](/api-reference/unified-e-signature-api/signingrequests/remove_participants) — Remove Participants Signing requests --- # Documents Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/documents/ Schema for the `Documents` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the document. - **`name`** _(string)_ The name of the document. - **`signing_request`** _(object)_ The signing request associated with the document - **`id`** _(unknown)_ - **`urls`** _(array)_ The urls of the document - **`url`** _(string)_ The url of the document - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_by`** _(object)_ The user who created the document. - **`id`** _(string)_ The unique identifier of the user. - **`name`** _(string)_ The name of the user. - **`emails`** _(array)_ The emails of the user. - **`email`** _(string)_ The email address of the user. - **`status`** _(string)_ The status of the document. - **`scope`** _(string)_ The scope of the document. - **`created_at`** _(string)_ The date and time when the document was created. - **`updated_at`** _(string)_ The date and time when the document was last updated. - **`last_activity_at`** _(string)_ The date and time when the document was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/documents](/api-reference/unified-e-signature-api/documents/list) — List Documents - [POST /unified/e-signature/documents](/api-reference/unified-e-signature-api/documents/create) — Create Documents - [GET /unified/e-signature/documents/{id}](/api-reference/unified-e-signature-api/documents/get) — Get Documents - [DELETE /unified/e-signature/documents/{id}](/api-reference/unified-e-signature-api/documents/delete) — Delete Documents - [POST /unified/e-signature/documents/download](/api-reference/unified-e-signature-api/documents/download) — Download Documents --- # WebForms Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/webforms/ Schema for the `WebForms` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier of the web form. - **`name`** _(string)_ The name of the web form. - **`groups`** _(array)_ The groups of the web form. - **`id`** _(string)_ The unique identifier of the group. - **`type`** _(string)_ The type of the group. - **`created_by`** _(object)_ The user who created the web form. - **`id`** _(string)_ The unique identifier of the user. - **`name`** _(string)_ The name of the user. - **`emails`** _(array)_ The emails of the user. - **`email`** _(string)_ The email address of the user. - **`owner`** _(object)_ The owner of the web form. - **`id`** _(string)_ The unique identifier of the owner. - **`name`** _(string)_ The name of the owner. - **`emails`** _(array)_ The emails of the owner. - **`email`** _(string)_ The email address of the owner. - **`status`** _(string)_ The status of the web form. - **`urls`** _(array)_ The URLs of the web form. - **`url`** _(string)_ The URL of the web form. - **`created_at`** _(string)_ The date and time when the web form was created. - **`updated_at`** _(string)_ The date and time when the web form was last updated. - **`last_activity_at`** _(string)_ The date and time when the web form was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/web_forms/{id}](/api-reference/unified-e-signature-api/webforms/get) — Get Web forms - [GET /unified/e-signature/web_forms](/api-reference/unified-e-signature-api/webforms/list) — List Web forms --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/contacts/ Schema for the `Contacts` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string, required)_ The contact's unique identifier - **`first_name`** _(string)_ The contact's first name - **`last_name`** _(string)_ The contact's last name - **`name`** _(string)_ The contact's full name - **`title`** _(string)_ The contact's job title - **`account`** _(object)_ The contact's account - **`id`** _(string)_ The account's unique identifier - **`name`** _(string)_ The account's name - **`addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the address - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`email_addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the email addresses - **`email`** _(string)_ The email address - **`type`** _(string)_ The email address type - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`last_activity_at`** _(string)_ The date and time of the contact's last activity - **`created_at`** _(string)_ The date and time of the contact's creation - **`updated_at`** _(string)_ The date and time of the contact's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/contacts](/api-reference/unified-e-signature-api/contacts/list) — List Contacts - [GET /unified/e-signature/contacts/{id}](/api-reference/unified-e-signature-api/contacts/get) — Get Contacts --- # Collections Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/collections/ Schema for the `Collections` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the collection - **`name`** _(string)_ The name of the collection - **`description`** _(string)_ The description of the collection - **`type`** _(string)_ The type of the collection - **`parent`** _(object)_ The parent of the collection - **`id`** _(string)_ The unique identifier for the parent - **`type`** _(string)_ The type of the parent - **`urls`** _(array)_ The urls of the collection - **`url`** _(string)_ The url of the collection - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_at`** _(string)_ The date and time the collection was created - **`updated_at`** _(string)_ The date and time the collection was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/collections](/api-reference/unified-e-signature-api/collections/list) — List Collections - [GET /unified/e-signature/collections/{id}](/api-reference/unified-e-signature-api/collections/get) — Get Collections --- # Fields Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/fields/ Schema for the `Fields` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`description`** _(string)_ The field's description - **`type`** _(string)_ The field's type Allowed: `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file`, `address` - **`is_hidden`** _(boolean)_ Whether the field is hidden - **`is_unique`** _(boolean)_ Whether the field is unique - **`is_required`** _(boolean)_ Whether the field is required - **`is_editable`** _(boolean)_ Whether the field is editable - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`is_hidden`** _(boolean)_ Whether the option is hidden - **`is_user_defined`** _(boolean)_ Whether the field is user defined - **`entity_type`** _(string)_ The entity type the field belongs to Allowed: `workflow`, `template` - **`field_groups`** _(array)_ - **`id`** _(string)_ The field group's unique identifier - **`name`** _(string)_ The field group's name - **`created_at`** _(string)_ The date and time of the field's creation - **`updated_at`** _(string)_ The date and time of the field's last update - **`urls`** _(array)_ The field's urls - **`url`** _(string)_ The field's URL - **`type`** _(string)_ The field's URL type - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/fields](/api-reference/unified-e-signature-api/fields/list) — List Fields --- # FieldGroups Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/fieldgroups/ Schema for the `FieldGroups` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string, required)_ The field group's unique identifier - **`name`** _(string, required)_ The field group's name. Used in other resources to reference the field group. - **`label`** _(string)_ The field group's descriptive label - **`description`** _(string)_ The field group's description - **`entity_type`** _(string)_ The entity type the field group belongs to Allowed: `template`, `workflow` - **`status`** _(string)_ The field group's status Allowed: `active`, `inactive` - **`created_at`** _(string)_ The date and time of the field group's creation - **`updated_at`** _(string)_ The date and time of the field group's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/field_groups](/api-reference/unified-e-signature-api/fieldgroups/list) — List Field groups --- # Stages Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/stages/ Schema for the `Stages` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string, required)_ The stage's unique identifier - **`name`** _(string)_ The stage's name - **`status`** _(string)_ The status of the stage Allowed: `active`, `inactive` - **`created_at`** _(string)_ The date and time of the stage's creation - **`updated_at`** _(string)_ The date and time of the stage's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/stages](/api-reference/unified-e-signature-api/stages/list) — List Stages --- # DocumentFields Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/documentfields/ Schema for the `DocumentFields` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier for the document field - **`label`** _(string)_ Human readable name for the field - **`type`** _(string)_ The type of the field Allowed: `signature`, `initials`, `full_name`, `signing_date`, `company_name`, `title`, `text`, `email` - **`is_read_only`** _(boolean)_ Specifies if the field can be edited by the participants - **`is_required`** _(boolean)_ Specifies if the field is required to be filled by the participants to complete the signing request - **`document`** _(object)_ The document on which the field is found - **`id`** _(string)_ The unique identifier for the document - **`page_number`** _(string)_ The page number of which the field is found inside the document - **`position`** _(object)_ - **`x`** _(string)_ The X-axis coordinate position for the field - **`y`** _(string)_ The Y-axis coordinate position for the field - **`signing_request`** _(object)_ The signing request on which the field is found - **`id`** _(string)_ The unique identifier for the signing request - **`participant`** _(object)_ The participant who needs to fill this field - **`id`** _(string)_ The unique identifier of the participant - **`created_at`** _(string)_ The date and time when the document field was created - **`updated_at`** _(string)_ The date and time when the document field was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/document_fields](/api-reference/unified-e-signature-api/documentfields/list) — List Document fields - [POST /unified/e-signature/document_fields](/api-reference/unified-e-signature-api/documentfields/create) — Create Document fields - [DELETE /unified/e-signature/document_fields/{id}](/api-reference/unified-e-signature-api/documentfields/delete) — Delete Document fields --- # SigningRequestStatuses Object > Source: https://truto.one/docs/api-reference/unified-e-signature-api/signingrequeststatuses/ Schema for the `SigningRequestStatuses` resource in **Unified E-Signature API**. ## Properties - **`id`** _(string)_ The unique identifier for the status - **`name`** _(string)_ Human readable name of the status - **`created_at`** _(string)_ The date and time when the status was created. - **`updated_at`** _(string)_ The date and time when the status was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/e-signature/signing_request_statuses](/api-reference/unified-e-signature-api/signingrequeststatuses/list) — List Signing request statuses --- # Unified Emails API > Source: https://truto.one/docs/api-reference/unified-emails-api/ Base URL: `https://api.truto.one/unified/emails` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Emails](/api-reference/unified-emails-api/emails) - [GET /unified/emails/emails](/api-reference/unified-emails-api/emails/list) — List Emails - [POST /unified/emails/emails](/api-reference/unified-emails-api/emails/create) — Create Emails - [GET /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/get) — Get Emails - [PATCH /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/update) — Update Emails - [DELETE /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/delete) — Delete Emails - [POST /unified/emails/emails/send](/api-reference/unified-emails-api/emails/send) — Send Emails - [POST /unified/emails/emails/move](/api-reference/unified-emails-api/emails/move) — Move Emails - [POST /unified/emails/emails/reply](/api-reference/unified-emails-api/emails/reply) — Reply Emails - [POST /unified/emails/emails/reply-all](/api-reference/unified-emails-api/emails/reply-all) — Reply All Emails - [POST /unified/emails/emails/forward](/api-reference/unified-emails-api/emails/forward) — Forward Emails - [POST /unified/emails/emails/send-draft](/api-reference/unified-emails-api/emails/send-draft) — Send Draft Emails - [Folders](/api-reference/unified-emails-api/folders) - [GET /unified/emails/folders](/api-reference/unified-emails-api/folders/list) — List Folders - [POST /unified/emails/folders](/api-reference/unified-emails-api/folders/create) — Create Folders - [GET /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/get) — Get Folders - [PATCH /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/update) — Update Folders - [DELETE /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/delete) — Delete Folders - [Users](/api-reference/unified-emails-api/users) - [GET /unified/emails/users](/api-reference/unified-emails-api/users/list) — List Users - [GET /unified/emails/users/{id}](/api-reference/unified-emails-api/users/get) — Get Users - [DELETE /unified/emails/users/{id}](/api-reference/unified-emails-api/users/delete) — Delete Users - [Attachments](/api-reference/unified-emails-api/attachments) - [GET /unified/emails/attachments/{id}](/api-reference/unified-emails-api/attachments/get) — Get Attachments - [POST /unified/emails/attachments/download](/api-reference/unified-emails-api/attachments/download) — Download Attachments - [GET /unified/emails/attachments](/api-reference/unified-emails-api/attachments/list) — List Attachments - [Organizations](/api-reference/unified-emails-api/organizations) - [GET /unified/emails/organizations](/api-reference/unified-emails-api/organizations/list) — List Organizations - [GET /unified/emails/organizations/{id}](/api-reference/unified-emails-api/organizations/get) — Get Organizations - [Mailboxes](/api-reference/unified-emails-api/mailboxes) - [GET /unified/emails/mailboxes](/api-reference/unified-emails-api/mailboxes/list) — List Mailboxes - [GET /unified/emails/mailboxes/{id}](/api-reference/unified-emails-api/mailboxes/get) — Get Mailboxes --- # Emails Object > Source: https://truto.one/docs/api-reference/unified-emails-api/emails/ Schema for the `Emails` resource in **Unified Emails API**. ## Properties - **`id`** _(string)_ The unique identifier for the email - **`from`** _(string)_ Sender email address - **`to`** _(array)_ Recipient email addresses - **`cc`** _(array)_ CC email addresses - **`bcc`** _(array)_ BCC email addresses - **`subject`** _(string)_ Email subject - **`content`** _(object)_ - **`type`** _(string)_ Content type of the email Allowed: `plain_text`, `html` - **`value`** _(string)_ The body of the email in the selected format - **`headers`** _(object)_ Custom headers for the email - **`reply_to`** _(array)_ Reply-to email address - **`priority`** _(string)_ Priority of the email Allowed: `high`, `normal`, `low` - **`folder`** _(object)_ The folder where the email is stored - **`id`** _(string)_ The unique identifier for a folder - **`is_draft`** _(boolean)_ Indicates whether the email is saved as a draft (created but not sent yet). If true, the email is still edited or waiting to be sent Allowed: `true`, `false` - **`attachments`** _(array)_ The attachments of the email - **`id`** _(string)_ The unique identifier for the attachment - **`file_name`** _(string)_ The attachment's name - **`file_url`** _(string)_ The URL to download the attachment - **`content_type`** _(string)_ The content type of the attachment - **`created_at`** _(string)_ The time when the attachment was created - **`urls`** _(array)_ The email's urls - **`url`** _(string)_ The email's URL - **`type`** _(string)_ The email's URL type - **`created_at`** _(string)_ The date and time the email was created - **`updated_at`** _(string)_ The date and time the email was last updated - **`sent_at`** _(string)_ The date and time the email was sent - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/emails](/api-reference/unified-emails-api/emails/list) — List Emails - [POST /unified/emails/emails](/api-reference/unified-emails-api/emails/create) — Create Emails - [GET /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/get) — Get Emails - [PATCH /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/update) — Update Emails - [DELETE /unified/emails/emails/{id}](/api-reference/unified-emails-api/emails/delete) — Delete Emails - [POST /unified/emails/emails/send](/api-reference/unified-emails-api/emails/send) — Send Emails - [POST /unified/emails/emails/move](/api-reference/unified-emails-api/emails/move) — Move Emails - [POST /unified/emails/emails/reply](/api-reference/unified-emails-api/emails/reply) — Reply Emails - [POST /unified/emails/emails/reply-all](/api-reference/unified-emails-api/emails/reply-all) — Reply All Emails - [POST /unified/emails/emails/forward](/api-reference/unified-emails-api/emails/forward) — Forward Emails - [POST /unified/emails/emails/send-draft](/api-reference/unified-emails-api/emails/send-draft) — Send Draft Emails --- # Folders Object > Source: https://truto.one/docs/api-reference/unified-emails-api/folders/ Schema for the `Folders` resource in **Unified Emails API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a folder - **`name`** _(string)_ The name of the folder - **`folder_url`** _(string)_ The URL of the folder - **`size`** _(integer)_ The size of the folder - **`description`** _(string)_ The description of the folder - **`parent`** _(object)_ The folder where this folder belong - **`id`** _(string)_ The unique identifier for folder - **`created_at`** _(string)_ The date and time the folder was created - **`updated_at`** _(string)_ The date and time the folder was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/folders](/api-reference/unified-emails-api/folders/list) — List Folders - [POST /unified/emails/folders](/api-reference/unified-emails-api/folders/create) — Create Folders - [GET /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/get) — Get Folders - [PATCH /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/update) — Update Folders - [DELETE /unified/emails/folders/{id}](/api-reference/unified-emails-api/folders/delete) — Delete Folders --- # Users Object > Source: https://truto.one/docs/api-reference/unified-emails-api/users/ Schema for the `Users` resource in **Unified Emails API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/users](/api-reference/unified-emails-api/users/list) — List Users - [GET /unified/emails/users/{id}](/api-reference/unified-emails-api/users/get) — Get Users - [DELETE /unified/emails/users/{id}](/api-reference/unified-emails-api/users/delete) — Delete Users --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-emails-api/attachments/ Schema for the `Attachments` resource in **Unified Emails API**. ## Properties - **`id`** _(string)_ The unique identifier for the attachment - **`file_name`** _(string)_ The attachment's name. - **`email`** _(object)_ The email to which the attachment belongs - **`id`** _(string)_ The unique identifier for an email - **`size`** _(number)_ The file size in bytes - **`file_url`** _(string)_ The URL to download the attachment - **`content_type`** _(string)_ The content type of the attachment - **`uploaded_by`** _(string)_ The user who uploaded the attachment - **`created_at`** _(string)_ The time when the attachment was created - **`updated_at`** _(string)_ The time when the attachment was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/attachments/{id}](/api-reference/unified-emails-api/attachments/get) — Get Attachments - [POST /unified/emails/attachments/download](/api-reference/unified-emails-api/attachments/download) — Download Attachments - [GET /unified/emails/attachments](/api-reference/unified-emails-api/attachments/list) — List Attachments --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-emails-api/organizations/ Schema for the `Organizations` resource in **Unified Emails API**. ## Properties - **`id`** _(string, required)_ The ID of the organization - **`name`** _(string)_ The name of the organization - **`created_at`** _(string)_ The date and time the organization was created - **`updated_at`** _(string)_ The date and time the organization was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/organizations](/api-reference/unified-emails-api/organizations/list) — List Organizations - [GET /unified/emails/organizations/{id}](/api-reference/unified-emails-api/organizations/get) — Get Organizations --- # Mailboxes Object > Source: https://truto.one/docs/api-reference/unified-emails-api/mailboxes/ Schema for the `Mailboxes` resource in **Unified Emails API**. ## Properties - **`id`** _(string)_ The ID of the mailbox - **`name`** _(string)_ The name of the mailbox - **`status`** _(string)_ The status of the mailbox Allowed: `active`, `inactive` - **`description`** _(string)_ The description of the mailbox - **`created_at`** _(string)_ The date and time the mailbox was created - **`updated_at`** _(string)_ The date and time the mailbox was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/emails/mailboxes](/api-reference/unified-emails-api/mailboxes/list) — List Mailboxes - [GET /unified/emails/mailboxes/{id}](/api-reference/unified-emails-api/mailboxes/get) — Get Mailboxes --- # Unified Enrichment API > Source: https://truto.one/docs/api-reference/unified-enrichment-api/ Base URL: `https://api.truto.one/unified/enrichment` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Person](/api-reference/unified-enrichment-api/person) - [POST /unified/enrichment/person/enrich](/api-reference/unified-enrichment-api/person/enrich) — Enrich Person - [GET /unified/enrichment/person](/api-reference/unified-enrichment-api/person/list) — List Person - [Company](/api-reference/unified-enrichment-api/company) - [POST /unified/enrichment/company/enrich](/api-reference/unified-enrichment-api/company/enrich) — Enrich Company - [GET /unified/enrichment/company](/api-reference/unified-enrichment-api/company/list) — List Company --- # Person Object > Source: https://truto.one/docs/api-reference/unified-enrichment-api/person/ Schema for the `Person` resource in **Unified Enrichment API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the person in the provider. - **`name`** _(string)_ The full name of the person. - **`first_name`** _(string)_ The first name of the person. - **`last_name`** _(string)_ The last name of the person. - **`title`** _(string)_ The person's current job title. - **`headline`** _(string)_ The short professional summary line shown on the person's public profile. - **`seniority`** _(string)_ The seniority of the person's current role. `other` is a level with no equivalent in this list, such as an unpaid or training role. `unknown` is a level the provider returned that could not be classified. Allowed: `owner`, `founder`, `c_suite`, `partner`, `vp`, `head`, `director`, `manager`, `senior`, `entry`, `intern`, `other` (+1 more) - **`emails`** _(array)_ The email addresses of the person. - **`email`** _(string)_ The email address. - **`type`** _(string)_ Whether the address is a work or a personal address. Allowed: `work`, `personal`, `unknown` - **`status`** _(string)_ The provider's assessment of whether email sent to the address will be delivered. `verified` means the provider checked it and expects delivery. `risky` means delivery is uncertain, for example a catch-all domain or a likely but unconfirmed address. `invalid` means the provider expects the address to bounce. `suppressed` means the provider advises against contacting the address. `unknown` means the provider has not assessed it. Allowed: `verified`, `risky`, `invalid`, `suppressed`, `unknown` - **`phones`** _(array)_ The phone numbers of the person. Most providers return phone numbers only when requested, and charge extra for them. - **`number`** _(string)_ The phone number. - **`type`** _(string)_ The type of phone number. `direct` is a work line that reaches the person directly. `office` is a company main, headquarters or branch line. `personal` is a personal landline or a personal number of unknown device type. Allowed: `mobile`, `direct`, `office`, `fax`, `personal`, `other`, `unknown` - **`location`** _(object)_ Where the person is based. - **`city`** _(string)_ The city. - **`state`** _(string)_ The state or region. - **`country`** _(string)_ The country name. - **`linkedin_url`** _(string)_ The URL of the person's LinkedIn profile. - **`avatar`** _(string)_ The URL of the person's profile photo. - **`company`** _(object)_ The company the person currently works at. Its domain or LinkedIn URL can be passed to the company enrich method. - **`id`** _(string)_ The unique identifier of the company in the provider. - **`name`** _(string)_ The name of the company. - **`domain`** _(string)_ The company's primary website domain, without protocol or path. - **`linkedin_url`** _(string)_ The URL of the company's LinkedIn page. - **`updated_at`** _(string)_ The date and time the provider last updated its data for this person. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/enrichment/person/enrich](/api-reference/unified-enrichment-api/person/enrich) — Enrich Person - [GET /unified/enrichment/person](/api-reference/unified-enrichment-api/person/list) — List Person --- # Company Object > Source: https://truto.one/docs/api-reference/unified-enrichment-api/company/ Schema for the `Company` resource in **Unified Enrichment API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the company in the provider. - **`name`** _(string)_ The name of the company. - **`domain`** _(string)_ The company's primary website domain, without protocol or path, for example example.com. - **`website`** _(string)_ The URL of the company's website. - **`linkedin_url`** _(string)_ The URL of the company's LinkedIn page. - **`description`** _(string)_ A description of what the company does. - **`industry`** _(string)_ The company's industry, as the provider labels it. Labels are not normalised across providers; use industry_codes to compare companies across providers. - **`industry_codes`** _(array)_ Standard industry classification codes for the company. - **`type`** _(string)_ The classification system the code belongs to. Allowed: `naics`, `sic` - **`code`** _(string)_ The industry code. - **`description`** _(string)_ The name of the industry the code stands for. - **`number_of_employees`** _(integer)_ The company's number of employees. Most providers report an estimate. - **`founded_year`** _(integer)_ The year the company was founded. - **`addresses`** _(array)_ The addresses of the company. - **`street_1`** _(string)_ Line 1 of the street address. - **`street_2`** _(string)_ Line 2 of the street address. - **`city`** _(string)_ The city. - **`state`** _(string)_ The state or region. - **`postal_code`** _(string)_ The postal code. - **`country`** _(string)_ The country name. - **`type`** _(string)_ Whether the address is the company's headquarters. Allowed: `headquarters`, `other` - **`phones`** _(array)_ The phone numbers of the company. - **`number`** _(string)_ The phone number. - **`logo`** _(string)_ The URL of the company's logo image. - **`technologies`** _(array)_ Technologies the provider has detected in use at the company. - **`name`** _(string)_ The name of the technology. - **`category`** _(string)_ The category of the technology, as the provider labels it. - **`updated_at`** _(string)_ The date and time the provider last updated its data for this company. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/enrichment/company/enrich](/api-reference/unified-enrichment-api/company/enrich) — Enrich Company - [GET /unified/enrichment/company](/api-reference/unified-enrichment-api/company/list) — List Company --- # Unified File Storage API > Source: https://truto.one/docs/api-reference/unified-file-storage-api/ Base URL: `https://api.truto.one/unified/file-storage` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Drives](/api-reference/unified-file-storage-api/drives) - [POST /unified/file-storage/drives](/api-reference/unified-file-storage-api/drives/create) — Create Drives - [GET /unified/file-storage/drives](/api-reference/unified-file-storage-api/drives/list) — List Drives - [GET /unified/file-storage/drives/{id}](/api-reference/unified-file-storage-api/drives/get) — Get Drives - [Files](/api-reference/unified-file-storage-api/files) - [GET /unified/file-storage/files](/api-reference/unified-file-storage-api/files/list) — List Files - [GET /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/get) — Get Files - [PATCH /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/update) — Update Files - [DELETE /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/delete) — Delete Files - [Folders](/api-reference/unified-file-storage-api/folders) - [GET /unified/file-storage/folders](/api-reference/unified-file-storage-api/folders/list) — List Folders - [POST /unified/file-storage/folders](/api-reference/unified-file-storage-api/folders/create) — Create Folders - [GET /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/get) — Get Folders - [PATCH /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/update) — Update Folders - [DELETE /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/delete) — Delete Folders - [DriveItems](/api-reference/unified-file-storage-api/driveitems) - [GET /unified/file-storage/drive-items](/api-reference/unified-file-storage-api/driveitems/list) — List Drive items - [POST /unified/file-storage/drive-items](/api-reference/unified-file-storage-api/driveitems/create) — Create Drive items - [GET /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/get) — Get Drive items - [DELETE /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/delete) — Delete Drive items - [PATCH /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/update) — Update Drive items - [POST /unified/file-storage/drive-items/download](/api-reference/unified-file-storage-api/driveitems/download) — Download Drive items - [POST /unified/file-storage/drive-items/track](/api-reference/unified-file-storage-api/driveitems/track) — Track Drive items - [Groups](/api-reference/unified-file-storage-api/groups) - [GET /unified/file-storage/groups](/api-reference/unified-file-storage-api/groups/list) — List Groups - [GET /unified/file-storage/groups/{id}](/api-reference/unified-file-storage-api/groups/get) — Get Groups - [Users](/api-reference/unified-file-storage-api/users) - [GET /unified/file-storage/users](/api-reference/unified-file-storage-api/users/list) — List Users - [GET /unified/file-storage/users/{id}](/api-reference/unified-file-storage-api/users/get) — Get Users - [Workspaces](/api-reference/unified-file-storage-api/workspaces) - [GET /unified/file-storage/workspaces](/api-reference/unified-file-storage-api/workspaces/list) — List Workspaces - [Permissions](/api-reference/unified-file-storage-api/permissions) - [GET /unified/file-storage/permissions](/api-reference/unified-file-storage-api/permissions/list) — List Permissions - [POST /unified/file-storage/permissions](/api-reference/unified-file-storage-api/permissions/create) — Create Permissions - [GET /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/get) — Get Permissions - [PATCH /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/update) — Update Permissions - [DELETE /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/delete) — Delete Permissions - [Tags](/api-reference/unified-file-storage-api/tags) - [GET /unified/file-storage/tags](/api-reference/unified-file-storage-api/tags/list) — List Tags - [Comments](/api-reference/unified-file-storage-api/comments) - [GET /unified/file-storage/comments](/api-reference/unified-file-storage-api/comments/list) — List Comments - [POST /unified/file-storage/comments](/api-reference/unified-file-storage-api/comments/create) — Create Comments - [GET /unified/file-storage/comments/{id}](/api-reference/unified-file-storage-api/comments/get) — Get Comments - [VersionHistory](/api-reference/unified-file-storage-api/versionhistory) - [GET /unified/file-storage/version_history](/api-reference/unified-file-storage-api/versionhistory/list) — List Version history - [GET /unified/file-storage/version_history/{id}](/api-reference/unified-file-storage-api/versionhistory/get) — Get Version history - [WebhookSubscriptions](/api-reference/unified-file-storage-api/webhooksubscriptions) - [GET /unified/file-storage/webhook-subscriptions](/api-reference/unified-file-storage-api/webhooksubscriptions/list) — List Webhook subscriptions - [POST /unified/file-storage/webhook-subscriptions](/api-reference/unified-file-storage-api/webhooksubscriptions/create) — Create Webhook subscriptions - [PATCH /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/update) — Update Webhook subscriptions - [DELETE /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/delete) — Delete Webhook subscriptions - [GET /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/get) — Get Webhook subscriptions --- # Drives Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/drives/ Schema for the `Drives` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a drive - **`name`** _(string)_ The name of the drive - **`workspace`** _(object)_ - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`drive_url`** _(string)_ The URL of the drive - **`path`** _(string)_ The path that points to this drive within the storage provider - **`created_at`** _(string)_ The date and time the drive was created - **`updated_at`** _(string)_ The date and time the drive was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/file-storage/drives](/api-reference/unified-file-storage-api/drives/create) — Create Drives - [GET /unified/file-storage/drives](/api-reference/unified-file-storage-api/drives/list) — List Drives - [GET /unified/file-storage/drives/{id}](/api-reference/unified-file-storage-api/drives/get) — Get Drives --- # Files Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/files/ Schema for the `Files` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a file - **`name`** _(string)_ The name of the file - **`file_url`** _(string)_ The URL of the file - **`file_thumbnail_url`** _(string)_ The URL of the thumbnail preview of file - **`size`** _(integer)_ The size of the file - **`mime_type`** _(string)_ The mime type of the file - **`description`** _(string)_ The description of the file - **`folder`** _(string)_ The folder of the file where it belongs - **`drive`** _(string)_ The drive of the file where it belongs - **`created_at`** _(string)_ The date and time the file was created - **`updated_at`** _(string)_ The date and time the file was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/files](/api-reference/unified-file-storage-api/files/list) — List Files - [GET /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/get) — Get Files - [PATCH /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/update) — Update Files - [DELETE /unified/file-storage/files/{id}](/api-reference/unified-file-storage-api/files/delete) — Delete Files --- # Folders Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/folders/ Schema for the `Folders` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a folder - **`name`** _(string)_ The name of the folder - **`folder_url`** _(string)_ The URL of the folder - **`size`** _(integer)_ The size of the folder - **`description`** _(string)_ The description of the folder - **`parent_folder`** _(string)_ The folder where this folder belongs - **`drive`** _(string)_ The drive of the folder where it belongs - **`created_at`** _(string)_ The date and time the folder was created - **`updated_at`** _(string)_ The date and time the folder was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/folders](/api-reference/unified-file-storage-api/folders/list) — List Folders - [POST /unified/file-storage/folders](/api-reference/unified-file-storage-api/folders/create) — Create Folders - [GET /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/get) — Get Folders - [PATCH /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/update) — Update Folders - [DELETE /unified/file-storage/folders/{id}](/api-reference/unified-file-storage-api/folders/delete) — Delete Folders --- # DriveItems Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/driveitems/ Schema for the `DriveItems` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a drive item - **`name`** _(string)_ The name of the drive item - **`public_url`** _(string)_ The public URL of the drive item - **`path`** _(string)_ The path of the drive item - **`urls`** _(array)_ The URLs of the drive item - **`url`** _(string)_ The URL of the drive item - **`type`** _(string)_ The type of the drive item Allowed: `self`, `thumbnail` - **`type`** _(string)_ The type of the drive item Allowed: `file`, `folder` - **`has_children`** _(boolean)_ Whether the drive item has children - **`size`** _(integer)_ The size of the drive item - **`mime_type`** _(string)_ The mime type of the drive item - **`description`** _(string)_ The description of the drive item - **`parent`** _(object)_ The parent folder of the drive item - **`id`** _(string)_ The unique identifier for a folder - **`name`** _(string)_ The name of the folder - **`drive`** _(object)_ The drive of the drive item - **`id`** _(string)_ The unique identifier for a drive - **`creator`** _(object)_ The creator of the drive item - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`tags`** _(array)_ The tags associated with the drive item - **`created_at`** _(string)_ The date and time the drive item was created - **`updated_at`** _(string)_ The date and time the drive item was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/drive-items](/api-reference/unified-file-storage-api/driveitems/list) — List Drive items - [POST /unified/file-storage/drive-items](/api-reference/unified-file-storage-api/driveitems/create) — Create Drive items - [GET /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/get) — Get Drive items - [DELETE /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/delete) — Delete Drive items - [PATCH /unified/file-storage/drive-items/{id}](/api-reference/unified-file-storage-api/driveitems/update) — Update Drive items - [POST /unified/file-storage/drive-items/download](/api-reference/unified-file-storage-api/driveitems/download) — Download Drive items - [POST /unified/file-storage/drive-items/track](/api-reference/unified-file-storage-api/driveitems/track) — Track Drive items --- # Groups Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/groups/ Schema for the `Groups` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`created_at`** _(string)_ The date and time the group was created - **`updated_at`** _(string)_ The date and time the group was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/groups](/api-reference/unified-file-storage-api/groups/list) — List Groups - [GET /unified/file-storage/groups/{id}](/api-reference/unified-file-storage-api/groups/get) — Get Groups --- # Users Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/users/ Schema for the `Users` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/users](/api-reference/unified-file-storage-api/users/list) — List Users - [GET /unified/file-storage/users/{id}](/api-reference/unified-file-storage-api/users/get) — Get Users --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/workspaces/ Schema for the `Workspaces` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`created_at`** _(string)_ The date and time the workspace was created - **`updated_at`** _(string)_ The date and time the workspace was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/workspaces](/api-reference/unified-file-storage-api/workspaces/list) — List Workspaces --- # Permissions Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/permissions/ Schema for the `Permissions` resource in **Unified File Storage API**. ## Properties - **`id`** _(string)_ Unique identifier for the permission - **`resources`** _(array)_ The resources for which the permission is applicable for - **`id`** _(string)_ Unique identifier for the resource - **`type`** _(string)_ Type of the resource Allowed: `drive_item`, `drive` - **`user`** _(object)_ The user for whom the permission is applicable for - **`id`** _(string)_ Unique identifier for the user - **`permissions`** _(array)_ The list of permissions - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/permissions](/api-reference/unified-file-storage-api/permissions/list) — List Permissions - [POST /unified/file-storage/permissions](/api-reference/unified-file-storage-api/permissions/create) — Create Permissions - [GET /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/get) — Get Permissions - [PATCH /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/update) — Update Permissions - [DELETE /unified/file-storage/permissions/{id}](/api-reference/unified-file-storage-api/permissions/delete) — Delete Permissions --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/tags/ Schema for the `Tags` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the tag - **`name`** _(string)_ The name of the tag - **`description`** _(string)_ The description of the tag - **`options`** _(array)_ A list of selectable options under this tag - **`id`** _(string, required)_ The unique identifier for the tag option - **`name`** _(string)_ The display name of the tag option - **`is_active`** _(boolean)_ Indicates if the option is active - **`created_at`** _(string)_ The date and time the tag was created - **`updated_at`** _(string)_ The date and time the tag was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/tags](/api-reference/unified-file-storage-api/tags/list) — List Tags --- # Comments Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/comments/ Schema for the `Comments` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a comment - **`drive_item`** _(object)_ The drive item the comment is associated with - **`id`** _(string)_ The unique identifier for a drive item - **`name`** _(string)_ The name of the drive item - **`type`** _(string)_ The type of the drive item Allowed: `file`, `folder` - **`parent`** _(object)_ The parent comment this comment is replying to - **`id`** _(string)_ The unique identifier for a comment - **`body`** _(object)_ The body of the comment - **`content`** _(string)_ The content of the comment body - **`type`** _(string)_ The type of content in the comment body Allowed: `html`, `plaintext` - **`anchor`** _(object)_ The location or context within the drive item that the comment is associated with - **`description`** _(string)_ The description of the anchor - **`position`** _(string)_ The position or range in the drive item - **`version`** _(object)_ The drive item version the anchor applies to - **`id`** _(string)_ The unique identifier for a version - **`author`** _(object)_ The author of the comment - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`mentions`** _(array)_ The users mentioned in the comment - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`status`** _(string)_ The status of the comment - **`created_at`** _(string)_ The date and time the comment was created - **`updated_at`** _(string)_ The date and time the comment was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/comments](/api-reference/unified-file-storage-api/comments/list) — List Comments - [POST /unified/file-storage/comments](/api-reference/unified-file-storage-api/comments/create) — Create Comments - [GET /unified/file-storage/comments/{id}](/api-reference/unified-file-storage-api/comments/get) — Get Comments --- # VersionHistory Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/versionhistory/ Schema for the `VersionHistory` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a version - **`drive_item`** _(object)_ The drive item the version is associated with - **`id`** _(string)_ The unique identifier for a drive item - **`name`** _(string)_ The name of the drive item - **`type`** _(string)_ The type of the drive item Allowed: `file`, `folder` - **`name`** _(string)_ The name of the drive item for this version - **`description`** _(string)_ The description, note, or change comment associated with this version - **`mime_type`** _(string)_ The mime type of this version - **`size`** _(integer)_ The size of this version - **`checksum`** _(object)_ The checksum of this version - **`type`** _(string)_ The checksum type - **`value`** _(string)_ The checksum value - **`last_edited_by`** _(object)_ The user who last edited this version - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`status`** _(string)_ The status of the version - **`is_current`** _(boolean)_ Whether this version is the current version - **`is_retained`** _(boolean)_ Whether this version is retained from automatic deletion - **`urls`** _(array)_ The URLs associated with this version - **`url`** _(string)_ The URL associated with this version - **`type`** _(string)_ The type of URL Allowed: `truto_download` - **`created_at`** _(string)_ The date and time the version was created - **`updated_at`** _(string)_ The date and time the version was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/version_history](/api-reference/unified-file-storage-api/versionhistory/list) — List Version history - [GET /unified/file-storage/version_history/{id}](/api-reference/unified-file-storage-api/versionhistory/get) — Get Version history --- # WebhookSubscriptions Object > Source: https://truto.one/docs/api-reference/unified-file-storage-api/webhooksubscriptions/ Schema for the `WebhookSubscriptions` resource in **Unified File Storage API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the webhook subscription - **`type`** _(string)_ The type of subscription Allowed: `webhook`, `web_hook` - **`notification_url`** _(string, required)_ The URL where notifications will be sent - **`resource_id`** _(string)_ Provider-generated identifier for the watched resource - **`resource_uri`** _(string)_ The URI of the resource being watched - **`change_types`** _(array)_ Types of changes to monitor - **`expiration`** _(string)_ When the subscription expires (ISO 8601 datetime) - **`client_state`** _(string)_ Optional secret for verifying webhook authenticity - **`token`** _(string)_ Optional token sent with notifications - **`resource`** _(object)_ The resource being monitored - **`id`** _(string)_ ID of the resource (drive, folder, etc.) - **`type`** _(string)_ Type of resource Allowed: `drive`, `folder`, `file`, `root`, `changes` - **`drive`** _(object)_ The drive being monitored - **`id`** _(string)_ The unique identifier for a drive - **`page_token`** _(string)_ Starting page token for change notifications (Google Drive only) - **`created_at`** _(string)_ When the subscription was created - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/file-storage/webhook-subscriptions](/api-reference/unified-file-storage-api/webhooksubscriptions/list) — List Webhook subscriptions - [POST /unified/file-storage/webhook-subscriptions](/api-reference/unified-file-storage-api/webhooksubscriptions/create) — Create Webhook subscriptions - [PATCH /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/update) — Update Webhook subscriptions - [DELETE /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/delete) — Delete Webhook subscriptions - [GET /unified/file-storage/webhook-subscriptions/{id}](/api-reference/unified-file-storage-api/webhooksubscriptions/get) — Get Webhook subscriptions --- # Unified Finance API > Source: https://truto.one/docs/api-reference/unified-finance-api/ Base URL: `https://api.truto.one/unified/finance` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Accounts](/api-reference/unified-finance-api/accounts) - [GET /unified/finance/accounts](/api-reference/unified-finance-api/accounts/list) — List Accounts --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-finance-api/accounts/ Schema for the `Accounts` resource in **Unified Finance API**. ## Properties - **`id`** _(string)_ Unique identifier of the account - **`number`** _(string)_ The account number, usually masked to last 4 digits - **`type`** _(string)_ The primary account type Allowed: `investment`, `credit`, `despository`, `loan`, `brokerage` - **`sub_type`** _(string)_ Subclassification of the account within the primary account type - **`currency`** _(object)_ Currency used for the account - **`id`** _(string)_ Unique identifier of the currency - **`code`** _(string)_ Currency code - **`name`** _(string)_ Human readable currency name - **`name`** _(string)_ Name of the account - **`description`** _(string)_ Short description of the account - **`product`** _(object)_ The product that the account is an instance of - **`id`** _(string)_ Unique identifier of the product - **`name`** _(string)_ Human readable name of the product - **`status`** _(object)_ Status of the account - **`id`** _(string)_ Unique identifier of the status - **`name`** _(string)_ Name of the status - **`created_at`** _(string)_ The date and time when the account was created - **`updated_at`** _(string)_ The date and time when the account was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/finance/accounts](/api-reference/unified-finance-api/accounts/list) — List Accounts --- # Unified Forms API > Source: https://truto.one/docs/api-reference/unified-forms-api/ Base URL: `https://api.truto.one/unified/forms` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Workspaces](/api-reference/unified-forms-api/workspaces) - [GET /unified/forms/workspaces](/api-reference/unified-forms-api/workspaces/list) — List Workspaces - [GET /unified/forms/workspaces/{id}](/api-reference/unified-forms-api/workspaces/get) — Get Workspaces - [Forms](/api-reference/unified-forms-api/forms) - [GET /unified/forms/forms](/api-reference/unified-forms-api/forms/list) — List Forms - [GET /unified/forms/forms/{id}](/api-reference/unified-forms-api/forms/get) — Get Forms - [Responses](/api-reference/unified-forms-api/responses) - [GET /unified/forms/responses](/api-reference/unified-forms-api/responses/list) — List Responses - [GET /unified/forms/responses/{id}](/api-reference/unified-forms-api/responses/get) — Get Responses - [Organizations](/api-reference/unified-forms-api/organizations) - [GET /unified/forms/organizations](/api-reference/unified-forms-api/organizations/list) — List Organizations - [GET /unified/forms/organizations/{id}](/api-reference/unified-forms-api/organizations/get) — Get Organizations - [Users](/api-reference/unified-forms-api/users) - [GET /unified/forms/users](/api-reference/unified-forms-api/users/list) — List Users - [GET /unified/forms/users/{id}](/api-reference/unified-forms-api/users/get) — Get Users - [Collections](/api-reference/unified-forms-api/collections) - [GET /unified/forms/collections](/api-reference/unified-forms-api/collections/list) — List Collections - [GET /unified/forms/collections/{id}](/api-reference/unified-forms-api/collections/get) — Get Collections - [Contacts](/api-reference/unified-forms-api/contacts) - [GET /unified/forms/contacts](/api-reference/unified-forms-api/contacts/list) — List Contacts - [GET /unified/forms/contacts/{id}](/api-reference/unified-forms-api/contacts/get) — Get Contacts - [Groups](/api-reference/unified-forms-api/groups) - [GET /unified/forms/groups](/api-reference/unified-forms-api/groups/list) — List Groups - [GET /unified/forms/groups/{id}](/api-reference/unified-forms-api/groups/get) — Get Groups - [Fields](/api-reference/unified-forms-api/fields) - [GET /unified/forms/fields](/api-reference/unified-forms-api/fields/list) — List Fields --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-forms-api/workspaces/ Schema for the `Workspaces` resource in **Unified Forms API**. ## Properties - **`id`** _(string)_ The unique identifier of the workspace. - **`name`** _(string)_ The name of the workspace. - **`type`** _(string)_ The type of the workspace. - **`organization`** _(object)_ The organization to which the workspace belongs. - **`id`** _(string)_ The unique identifier of the organization. - **`name`** _(string)_ The name of the organization. - **`created_at`** _(string)_ The date and time when the workspace was created. - **`updated_at`** _(string)_ The date and time when the workspace was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/workspaces](/api-reference/unified-forms-api/workspaces/list) — List Workspaces - [GET /unified/forms/workspaces/{id}](/api-reference/unified-forms-api/workspaces/get) — Get Workspaces --- # Forms Object > Source: https://truto.one/docs/api-reference/unified-forms-api/forms/ Schema for the `Forms` resource in **Unified Forms API**. ## Properties - **`id`** _(string)_ The unique identifier of the form. - **`name`** _(string)_ The name of the form. - **`type`** _(string)_ The type of the form. - **`fields`** _(array)_ The form fields - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`placeholder`** _(string)_ The field's placeholder - **`description`** _(string)_ The field's description - **`position`** _(number)_ The index position of field in the form. - **`type`** _(string)_ The field's type. If no clear mapping exists, then raw value is returned. Allowed: `statement`, `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` (+5 more) - **`format`** _(string)_ The format of the field. Allowed: `url`, `email`, `password` - **`validation`** _(string)_ The validation string for the field. - **`range`** _(object)_ The range applicable for field types number, rating, scale. - **`min`** _(number)_ The minimum range for the field. - **`min_label`** _(number)_ The label for the minimum range of the field. - **`max`** _(number)_ The maximum range for the field. - **`max_label`** _(number)_ The label for the maximum range of the field. - **`is_required`** _(boolean)_ Whether the field is required - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`field_group`** _(object)_ The field's group identifier. If present, the field is part of a group. - **`id`** _(string)_ The field groups's identifier - **`name`** _(string)_ The field groups's name - **`label`** _(string)_ The field groups's label - **`rows`** _(array)_ The field's rows. If present, the field's type is matrix - **`label`** _(string)_ The row's label - **`value`** _(string)_ The row's value - **`description`** _(string)_ The row's description - **`columns`** _(array)_ The field's columns. If present, the field's type is matrix - **`label`** _(string)_ The column's label - **`value`** _(string)_ The column's value - **`description`** _(string)_ The column's description - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`workspace`** _(object)_ The workspace to which the form belongs. - **`id`** _(string)_ The unique identifier of the workspace. - **`name`** _(string)_ The name of the workspace. - **`organization`** _(object)_ The organization to which the workspace belongs. - **`id`** _(string)_ The unique identifier of the organization. - **`name`** _(string)_ The name of the organization. - **`last_submitted_at`** _(string)_ The date and time when the form was last submitted. - **`created_at`** _(string)_ The date and time when the form was created. - **`updated_at`** _(string)_ The date and time when the form was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/forms](/api-reference/unified-forms-api/forms/list) — List Forms - [GET /unified/forms/forms/{id}](/api-reference/unified-forms-api/forms/get) — Get Forms --- # Responses Object > Source: https://truto.one/docs/api-reference/unified-forms-api/responses/ Schema for the `Responses` resource in **Unified Forms API**. ## Properties - **`id`** _(string)_ The unique identifier of the response. - **`name`** _(string)_ The name of the response. - **`status`** _(string)_ The status of the form response. Allowed: `initiated`, `completed`, `submitted` - **`answers`** _(array)_ The answers submitted - **`field`** _(object)_ - **`id`** _(string)_ The field's unique identifier. - **`name`** _(string)_ The field's name. - **`label`** _(string)_ The field's label. - **`type`** _(string)_ The field's type. If no clear mapping exists, then raw value is returned. Allowed: `statement`, `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` (+5 more) - **`field_group`** _(object)_ The field's group identifier. If present, the field is part of a group. - **`id`** _(string)_ The field groups's identifier - **`name`** _(string)_ The field groups's name - **`value`** _(string)_ The value for the field submitted - **`created_by`** _(object)_ User who created the response. - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`form`** _(object)_ The form to which the response belongs. - **`id`** _(string)_ The unique identifier of the form. - **`name`** _(string)_ The name of the form. - **`workspace`** _(object)_ The workspace to which the response belongs. - **`id`** _(string)_ The unique identifier of the workspace. - **`name`** _(string)_ The name of the workspace. - **`organization`** _(object)_ The organization to which the response belongs. - **`id`** _(string)_ The unique identifier of the organization. - **`name`** _(string)_ The name of the organization. - **`opened_at`** _(string)_ The date and time when the form was opened. - **`created_at`** _(string)_ The date and time when the response was created. - **`updated_at`** _(string)_ The date and time when the response was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/responses](/api-reference/unified-forms-api/responses/list) — List Responses - [GET /unified/forms/responses/{id}](/api-reference/unified-forms-api/responses/get) — Get Responses --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-forms-api/organizations/ Schema for the `Organizations` resource in **Unified Forms API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`created_at`** _(string)_ Date and time when the organization was created. - **`updated_at`** _(string)_ Date and time when the organization was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/organizations](/api-reference/unified-forms-api/organizations/list) — List Organizations - [GET /unified/forms/organizations/{id}](/api-reference/unified-forms-api/organizations/get) — Get Organizations --- # Users Object > Source: https://truto.one/docs/api-reference/unified-forms-api/users/ Schema for the `Users` resource in **Unified Forms API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a member - **`first_name`** _(string)_ The first name of the member - **`last_name`** _(string)_ The last name of the member - **`title`** _(string)_ The title of the member - **`name`** _(string)_ The name of the member - **`username`** _(string)_ The username of the member - **`emails`** _(array)_ The emails of the member - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the member - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the member. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`is_email_verified`** _(boolean)_ Whether the member's email has been verified - **`organizations`** _(array)_ The organizations of the member - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`workspaces`** _(array)_ The workspaces of the member - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the worksapce - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`type`** _(string)_ The type of member - **`avatar`** _(string)_ The avatar of the member - **`timezone`** _(string)_ The timezone of the member - **`languages`** _(array)_ The languages preferred by the member - **`bio`** _(string)_ The bio of the member - **`created_at`** _(string)_ The date and time the member was created - **`updated_at`** _(string)_ The date and time the member was last updated - **`last_active_at`** _(string)_ The date and time the member was last active - **`last_login_at`** _(string)_ The date and time the member was last logged in - **`status_changed_at`** _(string)_ The date and time the member's status was last changed - **`activated_at`** _(string)_ The date and time the member was activated - **`urls`** _(array)_ The URLs of the member - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/users](/api-reference/unified-forms-api/users/list) — List Users - [GET /unified/forms/users/{id}](/api-reference/unified-forms-api/users/get) — Get Users --- # Collections Object > Source: https://truto.one/docs/api-reference/unified-forms-api/collections/ Schema for the `Collections` resource in **Unified Forms API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a collection - **`name`** _(string)_ The name of the collection - **`description`** _(string)_ The description of the collection - **`type`** _(string)_ The type of the collection - **`parent_collection_id`** _(string)_ The parent collection id - **`urls`** _(array)_ The URLs of the collection - **`url`** _(string)_ The URL of the collection - **`workspace`** _(object)_ - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`created_at`** _(string)_ The date and time when the collection was created - **`updated_at`** _(string)_ The date and time when the collection was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/collections](/api-reference/unified-forms-api/collections/list) — List Collections - [GET /unified/forms/collections/{id}](/api-reference/unified-forms-api/collections/get) — Get Collections --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-forms-api/contacts/ Schema for the `Contacts` resource in **Unified Forms API**. ## Properties - **`id`** _(string, required)_ The contact's unique identifier - **`first_name`** _(string)_ The contact's first name - **`last_name`** _(string)_ The contact's last name - **`name`** _(string)_ The contact's full name - **`title`** _(string)_ The contact's job title - **`account`** _(object)_ The contact's account - **`id`** _(string)_ The account's unique identifier - **`name`** _(string)_ The account's name - **`addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the address - **`street_1`** _(string)_ Line 1 of the street address - **`street_2`** _(string)_ Line 2 of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`type`** _(string)_ The address type - **`email_addresses`** _(array)_ - **`id`** _(string)_ The unique identifier of the email addresses - **`email`** _(string)_ The email address - **`type`** _(string)_ The email address type - **`phone_numbers`** _(array)_ - **`id`** _(string)_ The unique identifier of the phone number - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The phone number type - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`last_activity_at`** _(string)_ The date and time of the contact's last activity - **`created_at`** _(string)_ The date and time of the contact's creation - **`updated_at`** _(string)_ The date and time of the contact's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/contacts](/api-reference/unified-forms-api/contacts/list) — List Contacts - [GET /unified/forms/contacts/{id}](/api-reference/unified-forms-api/contacts/get) — Get Contacts --- # Groups Object > Source: https://truto.one/docs/api-reference/unified-forms-api/groups/ Schema for the `Groups` resource in **Unified Forms API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the group. - **`name`** _(string)_ Name of the group. - **`description`** _(string)_ Description of the group. - **`organization`** _(string)_ Unique identifier for the organization the group belongs to. - **`group_type`** _(string)_ Type of the group. Allowed: `team`, `department`, `group` - **`created_at`** _(string)_ Date and time when the group was created. - **`updated_at`** _(string)_ Date and time when the group was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/groups](/api-reference/unified-forms-api/groups/list) — List Groups - [GET /unified/forms/groups/{id}](/api-reference/unified-forms-api/groups/get) — Get Groups --- # Fields Object > Source: https://truto.one/docs/api-reference/unified-forms-api/fields/ Schema for the `Fields` resource in **Unified Forms API**. ## Properties - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`placeholder`** _(string)_ The field's placeholder - **`description`** _(string)_ The field's description - **`position`** _(number)_ The index position of field in the form. - **`type`** _(string)_ The field's type. If no clear mapping exists, then raw value is returned. Allowed: `statement`, `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` (+7 more) - **`format`** _(string)_ The format of the field. Allowed: `url`, `email`, `password` - **`validation`** _(string)_ The validation string for the field. - **`range`** _(object)_ The range applicable for field types number, rating, scale. - **`min`** _(number)_ The minimum range for the field. - **`min_label`** _(number)_ The label for the minimum range of the field. - **`max`** _(number)_ The maximum range for the field. - **`max_label`** _(number)_ The label for the maximum range of the field. - **`is_required`** _(boolean)_ Whether the field is required - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`field_group`** _(object)_ The field's group identifier. If present, the field is part of a group. - **`id`** _(string)_ The field groups's identifier - **`name`** _(string)_ The field groups's name - **`label`** _(string)_ The field group's label - **`description`** _(string)_ The field group's description - **`position`** _(number)_ The index position of field group in the form. - **`rows`** _(array)_ The field's rows. If present, the field's type is matrix - **`label`** _(string)_ The row's label - **`value`** _(string)_ The row's value - **`description`** _(string)_ The row's description - **`columns`** _(array)_ The field's columns. If present, the field's type is matrix - **`label`** _(string)_ The column's label - **`value`** _(string)_ The column's value - **`description`** _(string)_ The column's description - **`created_at`** _(string)_ The date and time of the field's creation - **`updated_at`** _(string)_ The date and time of the field's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/forms/fields](/api-reference/unified-forms-api/fields/list) — List Fields --- # Unified HRIS API > Source: https://truto.one/docs/api-reference/unified-hris-api/ Base URL: `https://api.truto.one/unified/hris` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [BankInfo](/api-reference/unified-hris-api/bankinfo) - [GET /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/get) — Get Bank info - [DELETE /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/delete) — Delete Bank info - [PATCH /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/update) — Update Bank info - [GET /unified/hris/bank_info](/api-reference/unified-hris-api/bankinfo/list) — List Bank info - [POST /unified/hris/bank_info](/api-reference/unified-hris-api/bankinfo/create) — Create Bank info - [Benefits](/api-reference/unified-hris-api/benefits) - [GET /unified/hris/benefits](/api-reference/unified-hris-api/benefits/list) — List Benefits - [POST /unified/hris/benefits](/api-reference/unified-hris-api/benefits/create) — Create Benefits - [GET /unified/hris/benefits/{id}](/api-reference/unified-hris-api/benefits/get) — Get Benefits - [PATCH /unified/hris/benefits/{id}](/api-reference/unified-hris-api/benefits/update) — Update Benefits - [Companies](/api-reference/unified-hris-api/companies) - [GET /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/get) — Get Companies - [PATCH /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/update) — Update Companies - [DELETE /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/delete) — Delete Companies - [GET /unified/hris/companies](/api-reference/unified-hris-api/companies/list) — List Companies - [POST /unified/hris/companies](/api-reference/unified-hris-api/companies/create) — Create Companies - [CompanyBenefits](/api-reference/unified-hris-api/companybenefits) - [GET /unified/hris/company_benefits](/api-reference/unified-hris-api/companybenefits/list) — List Company benefits - [EmployeePayrollRuns](/api-reference/unified-hris-api/employeepayrollruns) - [GET /unified/hris/employee_payroll_runs/{id}](/api-reference/unified-hris-api/employeepayrollruns/get) — Get Employee payroll runs - [GET /unified/hris/employee_payroll_runs](/api-reference/unified-hris-api/employeepayrollruns/list) — List Employee payroll runs - [Employees](/api-reference/unified-hris-api/employees) - [POST /unified/hris/employees](/api-reference/unified-hris-api/employees/create) — Create Employees - [GET /unified/hris/employees](/api-reference/unified-hris-api/employees/list) — List Employees - [DELETE /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/delete) — Delete Employees - [GET /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/get) — Get Employees - [PATCH /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/update) — Update Employees - [POST /unified/hris/employees/terminate](/api-reference/unified-hris-api/employees/terminate) — Terminate Employees - [EmployeeCompensations](/api-reference/unified-hris-api/employeecompensations) - [POST /unified/hris/employee_compensations](/api-reference/unified-hris-api/employeecompensations/create) — Create Employee compensations - [GET /unified/hris/employee_compensations](/api-reference/unified-hris-api/employeecompensations/list) — List Employee compensations - [GET /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/get) — Get Employee compensations - [PATCH /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/update) — Update Employee compensations - [DELETE /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/delete) — Delete Employee compensations - [Employments](/api-reference/unified-hris-api/employments) - [POST /unified/hris/employments](/api-reference/unified-hris-api/employments/create) — Create Employments - [GET /unified/hris/employments](/api-reference/unified-hris-api/employments/list) — List Employments - [DELETE /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/delete) — Delete Employments - [PATCH /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/update) — Update Employments - [GET /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/get) — Get Employments - [Groups](/api-reference/unified-hris-api/groups) - [POST /unified/hris/groups](/api-reference/unified-hris-api/groups/create) — Create Groups - [GET /unified/hris/groups](/api-reference/unified-hris-api/groups/list) — List Groups - [DELETE /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/delete) — Delete Groups - [GET /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/get) — Get Groups - [PATCH /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/update) — Update Groups - [Locations](/api-reference/unified-hris-api/locations) - [POST /unified/hris/locations](/api-reference/unified-hris-api/locations/create) — Create Locations - [GET /unified/hris/locations](/api-reference/unified-hris-api/locations/list) — List Locations - [DELETE /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/delete) — Delete Locations - [GET /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/get) — Get Locations - [PATCH /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/update) — Update Locations - [JobRoles](/api-reference/unified-hris-api/jobroles) - [POST /unified/hris/job_roles](/api-reference/unified-hris-api/jobroles/create) — Create Job roles - [GET /unified/hris/job_roles](/api-reference/unified-hris-api/jobroles/list) — List Job roles - [DELETE /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/delete) — Delete Job roles - [GET /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/get) — Get Job roles - [PATCH /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/update) — Update Job roles - [PayGroups](/api-reference/unified-hris-api/paygroups) - [GET /unified/hris/pay_groups](/api-reference/unified-hris-api/paygroups/list) — List Pay groups - [GET /unified/hris/pay_groups/{id}](/api-reference/unified-hris-api/paygroups/get) — Get Pay groups - [PayrollRuns](/api-reference/unified-hris-api/payrollruns) - [GET /unified/hris/payroll_runs/{id}](/api-reference/unified-hris-api/payrollruns/get) — Get Payroll runs - [GET /unified/hris/payroll_runs](/api-reference/unified-hris-api/payrollruns/list) — List Payroll runs - [TimeoffTypes](/api-reference/unified-hris-api/timeofftypes) - [GET /unified/hris/timeoff_types/{id}](/api-reference/unified-hris-api/timeofftypes/get) — Get Timeoff types - [GET /unified/hris/timeoff_types](/api-reference/unified-hris-api/timeofftypes/list) — List Timeoff types - [TimeoffPolicies](/api-reference/unified-hris-api/timeoffpolicies) - [GET /unified/hris/timeoff_policies](/api-reference/unified-hris-api/timeoffpolicies/list) — List Timeoff policies - [GET /unified/hris/timeoff_policies/{id}](/api-reference/unified-hris-api/timeoffpolicies/get) — Get Timeoff policies - [TimeoffRequests](/api-reference/unified-hris-api/timeoffrequests) - [POST /unified/hris/timeoff_requests](/api-reference/unified-hris-api/timeoffrequests/create) — Create Timeoff requests - [GET /unified/hris/timeoff_requests](/api-reference/unified-hris-api/timeoffrequests/list) — List Timeoff requests - [DELETE /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/delete) — Delete Timeoff requests - [GET /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/get) — Get Timeoff requests - [PATCH /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/update) — Update Timeoff requests - [TimeoffBalances](/api-reference/unified-hris-api/timeoffbalances) - [GET /unified/hris/timeoff_balances](/api-reference/unified-hris-api/timeoffbalances/list) — List Timeoff balances - [GET /unified/hris/timeoff_balances/{id}](/api-reference/unified-hris-api/timeoffbalances/get) — Get Timeoff balances - [Tags](/api-reference/unified-hris-api/tags) - [GET /unified/hris/tags](/api-reference/unified-hris-api/tags/list) — List Tags - [Fields](/api-reference/unified-hris-api/fields) - [GET /unified/hris/fields](/api-reference/unified-hris-api/fields/list) — List Fields - [GET /unified/hris/fields/{id}](/api-reference/unified-hris-api/fields/get) — Get Fields - [GroupTypes](/api-reference/unified-hris-api/grouptypes) - [GET /unified/hris/group_types/{id}](/api-reference/unified-hris-api/grouptypes/get) — Get Group types - [GET /unified/hris/group_types](/api-reference/unified-hris-api/grouptypes/list) — List Group types - [Bgv](/api-reference/unified-hris-api/bgv) - [GET /unified/hris/bgv](/api-reference/unified-hris-api/bgv/list) — List Bgv - [POST /unified/hris/bgv](/api-reference/unified-hris-api/bgv/create) — Create Bgv - [GET /unified/hris/bgv/{id}](/api-reference/unified-hris-api/bgv/get) — Get Bgv - [BgvPackages](/api-reference/unified-hris-api/bgvpackages) - [GET /unified/hris/bgv_packages](/api-reference/unified-hris-api/bgvpackages/list) — List Bgv packages - [Dependents](/api-reference/unified-hris-api/dependents) - [POST /unified/hris/dependents](/api-reference/unified-hris-api/dependents/create) — Create Dependents - [GET /unified/hris/dependents](/api-reference/unified-hris-api/dependents/list) — List Dependents - [GET /unified/hris/dependents/{id}](/api-reference/unified-hris-api/dependents/get) — Get Dependents - [TimesheetEntries](/api-reference/unified-hris-api/timesheetentries) - [POST /unified/hris/timesheet_entries](/api-reference/unified-hris-api/timesheetentries/create) — Create Timesheet entries - [GET /unified/hris/timesheet_entries](/api-reference/unified-hris-api/timesheetentries/list) — List Timesheet entries - [DELETE /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/delete) — Delete Timesheet entries - [GET /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/get) — Get Timesheet entries - [PATCH /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/update) — Update Timesheet entries --- # BankInfo Object > Source: https://truto.one/docs/api-reference/unified-hris-api/bankinfo/ Schema for the `BankInfo` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for bank info - **`employee`** _(string)_ This represents employee - **`account_number`** _(string)_ This represents the account number - **`bank_name`** _(string)_ This represents the bank name - **`account_type`** _(string)_ This represents the account type - **`created_at`** _(string)_ This represents the date when the bank info was created - **`updated_at`** _(string)_ This represents the date when the bank info was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/get) — Get Bank info - [DELETE /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/delete) — Delete Bank info - [PATCH /unified/hris/bank_info/{id}](/api-reference/unified-hris-api/bankinfo/update) — Update Bank info - [GET /unified/hris/bank_info](/api-reference/unified-hris-api/bankinfo/list) — List Bank info - [POST /unified/hris/bank_info](/api-reference/unified-hris-api/bankinfo/create) — Create Bank info --- # Benefits Object > Source: https://truto.one/docs/api-reference/unified-hris-api/benefits/ Schema for the `Benefits` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for benefits - **`name`** _(string)_ The name of the benefit - **`employee`** _(object)_ Employee associated with this benefit - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ This represents the name of the employee - **`provider_name`** _(string)_ This represents the provider name - **`company_benefit`** _(object)_ - **`id`** _(string)_ The unique identifier for company benefits - **`name`** _(string)_ This represents the name of the company benefit - **`description`** _(string)_ This represents the description of the company benefit - **`employee_contribution`** _(string)_ This represents the employee contribution - **`company_contribution`** _(string)_ This represents the company contribution - **`currency`** _(string)_ This represents the currency in which the contribution is made - **`start_date`** _(string)_ This represents the start date of the benefit - **`end_date`** _(string)_ This represents the end date of the benefit - **`status`** _(string)_ This represents the status of the benefit - **`created_at`** _(string)_ This represents the date when the benefits was created - **`updated_at`** _(string)_ This represents the date when the benefits was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/benefits](/api-reference/unified-hris-api/benefits/list) — List Benefits - [POST /unified/hris/benefits](/api-reference/unified-hris-api/benefits/create) — Create Benefits - [GET /unified/hris/benefits/{id}](/api-reference/unified-hris-api/benefits/get) — Get Benefits - [PATCH /unified/hris/benefits/{id}](/api-reference/unified-hris-api/benefits/update) — Update Benefits --- # Companies Object > Source: https://truto.one/docs/api-reference/unified-hris-api/companies/ Schema for the `Companies` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for companies - **`legal_name`** _(string)_ This represents the legal name - **`display_name`** _(string)_ This represents the display name - **`enis`** _(array)_ This represents the company's Employer Identification Numbers. - **`created_at`** _(string)_ This represents the date when the companies was created - **`updated_at`** _(string)_ This represents the date when the companies was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/get) — Get Companies - [PATCH /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/update) — Update Companies - [DELETE /unified/hris/companies/{id}](/api-reference/unified-hris-api/companies/delete) — Delete Companies - [GET /unified/hris/companies](/api-reference/unified-hris-api/companies/list) — List Companies - [POST /unified/hris/companies](/api-reference/unified-hris-api/companies/create) — Create Companies --- # CompanyBenefits Object > Source: https://truto.one/docs/api-reference/unified-hris-api/companybenefits/ Schema for the `CompanyBenefits` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for company benefits - **`name`** _(string)_ This represents the name of the company benefit - **`description`** _(string)_ This represents the description of the company benefit - **`status`** _(string)_ This represents the status of the company benefit Allowed: `active`, `inactive` - **`company`** _(object)_ This represents the company associated with the company benefit - **`id`** _(string)_ The unique identifier for companies - **`created_at`** _(string)_ This represents the date when the company benefits was created - **`updated_at`** _(string)_ This represents the date when the company benefits was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/company_benefits](/api-reference/unified-hris-api/companybenefits/list) — List Company benefits --- # EmployeePayrollRuns Object > Source: https://truto.one/docs/api-reference/unified-hris-api/employeepayrollruns/ Schema for the `EmployeePayrollRuns` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for Employee Payroll Runs - **`employee`** _(string)_ This represents employee - **`payroll_run`** _(string)_ This represents the payroll run - **`gross_pay`** _(number)_ This represents the gross pay - **`net_pay`** _(number)_ This represents the net pay - **`start_date`** _(string)_ This represents the start date - **`end_date`** _(string)_ This represents the end date - **`check_date`** _(string)_ This represents the check date - **`earnings`** _(array)_ This represents the earnings - **`deductions`** _(array)_ This represents the deductions - **`taxes`** _(array)_ This represents the taxes - **`created_at`** _(string)_ This represents the date when the Employee Payroll Runs was created - **`updated_at`** _(string)_ This represents the date when the Employee Payroll Runs was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/employee_payroll_runs/{id}](/api-reference/unified-hris-api/employeepayrollruns/get) — Get Employee payroll runs - [GET /unified/hris/employee_payroll_runs](/api-reference/unified-hris-api/employeepayrollruns/list) — List Employee payroll runs --- # Employees Object > Source: https://truto.one/docs/api-reference/unified-hris-api/employees/ Schema for the `Employees` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for employees - **`employee_number`** _(string)_ This represents the employee number - **`company`** _(object)_ This represents the company - **`id`** _(string)_ The unique identifier for companies - **`first_name`** _(string)_ This represents the first name of the employee - **`middle_name`** _(string)_ This represents the middle name of the employee - **`last_name`** _(string)_ This represents the last name of the employee - **`name`** _(string)_ This represents the name of the employee - **`username`** _(string)_ This represents the username - **`job_title`** _(string)_ Job title of the employee - **`groups`** _(array)_ This represents the groups - **`id`** _(string)_ The unique identifier for groups - **`name`** _(string)_ Group's name - **`type`** _(string)_ Type of the group. Some underlying providers use this to differentiate between in-built and user created groups. - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`employments`** _(array)_ Represents a role or employment of the employee in the company - **`id`** _(string, required)_ The unique identifier for employments - **`employee`** _(object)_ Employee associated with this employment - **`id`** _(string)_ The unique identifier for employees - **`job_title`** _(string)_ Job title of the employee - **`pay_rate`** _(number)_ This represents the pay rate - **`pay_period`** _(string)_ This represents the pay period - **`pay_frequency`** _(string)_ This represents the pay frequency - **`pay_currency`** _(string)_ This represents the pay currency - **`pay_group`** _(string)_ This represents the pay group - **`flsa_status`** _(string)_ This represents the flsa status - **`effective_date`** _(string)_ Represents the effective date of the employment - **`end_date`** _(string)_ Represents the end date of the employment - **`employment_type`** _(string)_ This represents the employment type Allowed: `full_time`, `part_time`, `contract`, `internship`, `temporary`, `trainee`, `volunteer`, `per_diem` - **`end_reason`** _(string)_ Represents why the employment ended - **`created_at`** _(string)_ This represents the date when the employments was created - **`updated_at`** _(string)_ This represents the date when the employments was updated - **`home_location`** _(array)_ This represents the home location - **`id`** _(string)_ The unique identifier for locations - **`name`** _(string)_ This represents the name of the location - **`street_1`** _(string)_ The first line of home address - **`street_2`** _(string)_ The second line of home address - **`city`** _(string)_ The city of the home address - **`state`** _(string)_ The state/province of the home address - **`postal_code`** _(string)_ The postal code of the home address - **`country`** _(string)_ The country of the home address - **`work_location`** _(object)_ This represents the work location - **`id`** _(string)_ The unique identifier for locations - **`name`** _(string)_ This represents the name of the location - **`street_1`** _(string)_ The first line of work address - **`street_2`** _(string)_ The second line of work address - **`city`** _(string)_ The city of the work address - **`state`** _(string)_ The state/province of the work address - **`postal_code`** _(string)_ The postal code of the work address - **`country`** _(string)_ The country of the work address - **`manager`** _(object)_ Represents the manager of the employee. Is also an employee. - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ This represents the name of the employee - **`pay_group`** _(object)_ This represents the pay group - **`id`** _(string)_ The unique identifier for pay groups - **`ssn`** _(string)_ This represents the ssn - **`gender`** _(string)_ This represents gender - **`ethnicity`** _(string)_ This represent ethnicity - **`marital_status`** _(string)_ This represents marital status - **`date_of_birth`** _(string)_ This represents date of birth - **`start_date`** _(string)_ This represents the start date - **`employment_status`** _(string)_ This represents the employment status. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `pending` - **`termination_date`** _(string)_ This represents the termination date - **`termination_type`** _(string)_ Represents the type of termination. If no clear mapping exists, then raw value is returned. Allowed: `voluntary`, `dismissed`, `redundancy`, `end_of_contract`, `retirement`, `mutual` - **`termination_reason`** _(string)_ Represents the reason for termination - **`avatar`** _(string)_ This represents the avatar - **`tags`** _(array)_ The employee's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`created_at`** _(string)_ This represents the date when the Employee was created - **`updated_at`** _(string)_ This represents the date when the Employee was updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/employees](/api-reference/unified-hris-api/employees/create) — Create Employees - [GET /unified/hris/employees](/api-reference/unified-hris-api/employees/list) — List Employees - [DELETE /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/delete) — Delete Employees - [GET /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/get) — Get Employees - [PATCH /unified/hris/employees/{id}](/api-reference/unified-hris-api/employees/update) — Update Employees - [POST /unified/hris/employees/terminate](/api-reference/unified-hris-api/employees/terminate) — Terminate Employees --- # EmployeeCompensations Object > Source: https://truto.one/docs/api-reference/unified-hris-api/employeecompensations/ Schema for the `EmployeeCompensations` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the compensation - **`type`** _(string)_ The type of compensation Allowed: `salary`, `hourly`, `commission`, `bonus`, `equity` - **`description`** _(string)_ The description of the compensation - **`employee`** _(object)_ Employee associated with this compensation - **`id`** _(string)_ The unique identifier for employees - **`amount`** _(number)_ Represents the amount of the compensation. Can be a number or percentage. - **`currency`** _(string)_ Represents the currency of the compensation - **`period`** _(string)_ Represents the period of the compensation Allowed: `hourly`, `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `annually`, `fixed`, `one_time` - **`payment_frequency`** _(string)_ Represents how often the compensation is paid Allowed: `hourly`, `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `annually`, `fixed`, `one_time` - **`status`** _(string)_ Represents the status of the compensation Allowed: `active`, `inactive` - **`start_date`** _(string)_ Represents the start date of the compensation - **`end_date`** _(string)_ Represents the end date of the compensation - **`end_reason`** _(string)_ Represents why the compensation ended - **`created_at`** _(string)_ This represents the date when the compensation was created - **`updated_at`** _(string)_ This represents the date when the compensation was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/employee_compensations](/api-reference/unified-hris-api/employeecompensations/create) — Create Employee compensations - [GET /unified/hris/employee_compensations](/api-reference/unified-hris-api/employeecompensations/list) — List Employee compensations - [GET /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/get) — Get Employee compensations - [PATCH /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/update) — Update Employee compensations - [DELETE /unified/hris/employee_compensations/{id}](/api-reference/unified-hris-api/employeecompensations/delete) — Delete Employee compensations --- # Employments Object > Source: https://truto.one/docs/api-reference/unified-hris-api/employments/ Schema for the `Employments` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for employments - **`employee`** _(object)_ Employee associated with this employment - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ The name of the employee - **`job_title`** _(string)_ Job title of the employee - **`pay_rate`** _(number)_ This represents the pay rate - **`pay_period`** _(string)_ This represents the pay period - **`pay_frequency`** _(string)_ This represents the pay frequency - **`pay_currency`** _(string)_ This represents the pay currency - **`pay_group`** _(string)_ This represents the pay group - **`flsa_status`** _(string)_ This represents the flsa status - **`effective_date`** _(string)_ Represents the effective date of the employment - **`end_date`** _(string)_ Represents the end date of the employment - **`employment_type`** _(string)_ This represents the employment type Allowed: `full_time`, `part_time`, `contract`, `internship`, `temporary`, `trainee`, `volunteer`, `per_diem` - **`end_reason`** _(string)_ Represents why the employment ended - **`created_at`** _(string)_ This represents the date when the employments was created - **`updated_at`** _(string)_ This represents the date when the employments was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/employments](/api-reference/unified-hris-api/employments/create) — Create Employments - [GET /unified/hris/employments](/api-reference/unified-hris-api/employments/list) — List Employments - [DELETE /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/delete) — Delete Employments - [PATCH /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/update) — Update Employments - [GET /unified/hris/employments/{id}](/api-reference/unified-hris-api/employments/get) — Get Employments --- # Groups Object > Source: https://truto.one/docs/api-reference/unified-hris-api/groups/ Schema for the `Groups` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for groups - **`parent_group`** _(string)_ Parent Group of this group - **`name`** _(string)_ Group's name - **`description`** _(string)_ Short description of the group - **`type`** _(string)_ Type of the group. Some underlying providers use this to differentiate between in-built and user created groups. Allowed: `team`, `department`, `group`, `cost_center`, `org_unit`, `office`, `division`, `business_unit`, `organization`, `org_location`, `pay_group`, `project_team` (+3 more) - **`created_at`** _(string)_ This represents the date when the groups was created - **`updated_at`** _(string)_ This represents the date when the groups was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/groups](/api-reference/unified-hris-api/groups/create) — Create Groups - [GET /unified/hris/groups](/api-reference/unified-hris-api/groups/list) — List Groups - [DELETE /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/delete) — Delete Groups - [GET /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/get) — Get Groups - [PATCH /unified/hris/groups/{id}](/api-reference/unified-hris-api/groups/update) — Update Groups --- # Locations Object > Source: https://truto.one/docs/api-reference/unified-hris-api/locations/ Schema for the `Locations` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for locations - **`name`** _(string)_ This represents the name of the location - **`phone_number`** _(object)_ This represents the phone number of the location - **`number`** _(string)_ This represents the phone number of the location - **`extension`** _(string)_ This represents the extension of the phone number of the location - **`street_1`** _(string)_ This represents the Line 1 of the location's street address. - **`street_2`** _(string)_ This represents the Line 2 of the location's street address. - **`city`** _(string)_ This represents the city - **`state`** _(string)_ This represents the state - **`postal_code`** _(string)_ This represents the zip - **`country`** _(string)_ This represents the country - **`location_type`** _(string)_ This represents the location type - **`created_at`** _(string)_ This represents the date when the locations was created - **`updated_at`** _(string)_ This represents the date when the locations was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/locations](/api-reference/unified-hris-api/locations/create) — Create Locations - [GET /unified/hris/locations](/api-reference/unified-hris-api/locations/list) — List Locations - [DELETE /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/delete) — Delete Locations - [GET /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/get) — Get Locations - [PATCH /unified/hris/locations/{id}](/api-reference/unified-hris-api/locations/update) — Update Locations --- # JobRoles Object > Source: https://truto.one/docs/api-reference/unified-hris-api/jobroles/ Schema for the `JobRoles` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for job roles - **`name`** _(string)_ This represents the name of the job role - **`description`** _(string)_ This represents the description of the job role - **`created_at`** _(string)_ This represents the date when the job roles was created - **`updated_at`** _(string)_ This represents the date when the job roles was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/job_roles](/api-reference/unified-hris-api/jobroles/create) — Create Job roles - [GET /unified/hris/job_roles](/api-reference/unified-hris-api/jobroles/list) — List Job roles - [DELETE /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/delete) — Delete Job roles - [GET /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/get) — Get Job roles - [PATCH /unified/hris/job_roles/{id}](/api-reference/unified-hris-api/jobroles/update) — Update Job roles --- # PayGroups Object > Source: https://truto.one/docs/api-reference/unified-hris-api/paygroups/ Schema for the `PayGroups` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for paygroups - **`name`** _(string)_ This represents the name of the paygroup - **`pay_group_name`** _(string)_ This represents the name of the paygroup - **`created_at`** _(string)_ This represents the date when the paygroups was created - **`updated_at`** _(string)_ This represents the date when the paygroups was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/pay_groups](/api-reference/unified-hris-api/paygroups/list) — List Pay groups - [GET /unified/hris/pay_groups/{id}](/api-reference/unified-hris-api/paygroups/get) — Get Pay groups --- # PayrollRuns Object > Source: https://truto.one/docs/api-reference/unified-hris-api/payrollruns/ Schema for the `PayrollRuns` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for payrollruns - **`run_state`** _(string)_ This represents the run state - **`run_type`** _(string)_ This represents the run type - **`start_date`** _(string)_ This represents the start date - **`end_date`** _(string)_ This represents the end date - **`check_date`** _(string)_ This represents the check date - **`created_at`** _(string)_ This represents the date when the payrollruns was created - **`updated_at`** _(string)_ This represents the date when the payrollruns was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/payroll_runs/{id}](/api-reference/unified-hris-api/payrollruns/get) — Get Payroll runs - [GET /unified/hris/payroll_runs](/api-reference/unified-hris-api/payrollruns/list) — List Payroll runs --- # TimeoffTypes Object > Source: https://truto.one/docs/api-reference/unified-hris-api/timeofftypes/ Schema for the `TimeoffTypes` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for TimeoffType - **`name`** _(string)_ This represents the name of the time off type - **`description`** _(string)_ This represents the description of the time off type - **`unit`** _(string)_ This represents the unit of the time off type Allowed: `hours`, `days`, `weeks`, `months` - **`created_at`** _(string)_ This represents the date when the timeofftype was created - **`updated_at`** _(string)_ This represents the date when the timeofftype was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/timeoff_types/{id}](/api-reference/unified-hris-api/timeofftypes/get) — Get Timeoff types - [GET /unified/hris/timeoff_types](/api-reference/unified-hris-api/timeofftypes/list) — List Timeoff types --- # TimeoffPolicies Object > Source: https://truto.one/docs/api-reference/unified-hris-api/timeoffpolicies/ Schema for the `TimeoffPolicies` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for TimeoffPolicy - **`name`** _(string)_ This represents the name of the time off policy - **`description`** _(string)_ This represents the description of the time off policy - **`unit`** _(string)_ This represents the unit of the time off policy Allowed: `hours`, `days`, `weeks`, `months` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/timeoff_policies](/api-reference/unified-hris-api/timeoffpolicies/list) — List Timeoff policies - [GET /unified/hris/timeoff_policies/{id}](/api-reference/unified-hris-api/timeoffpolicies/get) — Get Timeoff policies --- # TimeoffRequests Object > Source: https://truto.one/docs/api-reference/unified-hris-api/timeoffrequests/ Schema for the `TimeoffRequests` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for timeoffpolicies - **`description`** _(string)_ This represents the description of the time off request. - **`reason`** _(object)_ This represents the reason of the time off request. - **`id`** _(string, required)_ The unique identifier for timeoff_reason - **`name`** _(string)_ This represents the name of the timeoff_reason. - **`employee`** _(object)_ This represents the employee requesting time off. - **`id`** _(string, required)_ The unique identifier for employees - **`name`** _(string)_ This represents the name of the employee. - **`approver`** _(string)_ This represents the approver of the time off request. - **`status`** _(string)_ This represents the status of the time off request. - **`employee_note`** _(string)_ This represents the employee note for the time off request. - **`units`** _(string)_ This represents the units of the time off request. Allowed: `hours`, `days`, `weeks`, `months` - **`amount`** _(number)_ This represents the amount of the time off request. - **`timeoff_type`** _(string)_ This represents the time off type of the time off request. - **`request_policy_type`** _(string)_ This represents the request type of the time off request. - **`start_time`** _(string)_ This represents the start time of the time off request. - **`end_time`** _(string)_ This represents the end time of the time off request. - **`session`** _(string)_ This represents the session of the time off request. Allowed: `full`, `morning`, `afternoon` - **`created_at`** _(string)_ This represents the date when the timeoffpolicies was created - **`updated_at`** _(string)_ This represents the date when the timeoffpolicies was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/timeoff_requests](/api-reference/unified-hris-api/timeoffrequests/create) — Create Timeoff requests - [GET /unified/hris/timeoff_requests](/api-reference/unified-hris-api/timeoffrequests/list) — List Timeoff requests - [DELETE /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/delete) — Delete Timeoff requests - [GET /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/get) — Get Timeoff requests - [PATCH /unified/hris/timeoff_requests/{id}](/api-reference/unified-hris-api/timeoffrequests/update) — Update Timeoff requests --- # TimeoffBalances Object > Source: https://truto.one/docs/api-reference/unified-hris-api/timeoffbalances/ Schema for the `TimeoffBalances` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for time off balances - **`employee`** _(object)_ This represents the employee the balance belongs to.. - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ This represents the name of the employee. - **`timeoff_policy`** _(string)_ This represents the time off policy of the time off request. - **`balance`** _(number)_ This represents the balance of the time off request. - **`created_at`** _(string)_ This represents the date when the timeoffbalances was created - **`updated_at`** _(string)_ This represents the date when the timeoffbalances was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/timeoff_balances](/api-reference/unified-hris-api/timeoffbalances/list) — List Timeoff balances - [GET /unified/hris/timeoff_balances/{id}](/api-reference/unified-hris-api/timeoffbalances/get) — Get Timeoff balances --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-hris-api/tags/ Schema for the `Tags` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`created_at`** _(string)_ The date and time of the tag's creation - **`updated_at`** _(string)_ The date and time of the tag's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/tags](/api-reference/unified-hris-api/tags/list) — List Tags --- # Fields Object > Source: https://truto.one/docs/api-reference/unified-hris-api/fields/ Schema for the `Fields` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the field - **`name`** _(string)_ The name of the field - **`label`** _(string)_ The descriptive label of the field - **`entity_type`** _(string)_ The entity name the field belongs to - **`created_at`** _(string)_ This represents the date when the field was created - **`updated_at`** _(string)_ This represents the date when the field was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/fields](/api-reference/unified-hris-api/fields/list) — List Fields - [GET /unified/hris/fields/{id}](/api-reference/unified-hris-api/fields/get) — Get Fields --- # GroupTypes Object > Source: https://truto.one/docs/api-reference/unified-hris-api/grouptypes/ Schema for the `GroupTypes` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for group type - **`name`** _(string)_ Group type's name - **`description`** _(string)_ Short description of the group type - **`created_at`** _(string)_ This represents the date when the group types was created - **`updated_at`** _(string)_ This represents the date when the group types was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/group_types/{id}](/api-reference/unified-hris-api/grouptypes/get) — Get Group types - [GET /unified/hris/group_types](/api-reference/unified-hris-api/grouptypes/list) — List Group types --- # Bgv Object > Source: https://truto.one/docs/api-reference/unified-hris-api/bgv/ Schema for the `Bgv` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The BGV's unique identifier - **`candidate`** _(object)_ The BGV's candidate - **`id`** _(string)_ The candidate's unique identifier - **`first_name`** _(string)_ The candidate's first name - **`middle_name`** _(string)_ The candidate's middle name - **`last_name`** _(string)_ The candidate's last name - **`name`** _(string)_ The candidate's full name - **`emails`** _(array)_ The candidate's email addresses - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The candidate's phone numbers - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`gender`** _(string)_ The candidate's gender Allowed: `male`, `female`, `non_binary`, `not_specified`, `prefer_not_to_say`, `other` - **`date_of_birth`** _(string)_ The candidate's date of birth - **`address`** _(object)_ The candidate's address - **`street_1`** _(string)_ The first line of the street address - **`street_2`** _(string)_ The second line of the street address - **`city`** _(string)_ The city - **`state`** _(string)_ The state - **`postal_code`** _(string)_ The postal code - **`country`** _(string)_ The country - **`employee_number`** _(string)_ The candidate's employee number - **`employee`** _(object)_ The employee associated with the background verification - **`id`** _(string)_ The employee's unique identifier - **`name`** _(string)_ The employee's name - **`package`** _(object)_ The BGV's package - **`id`** _(string)_ The package's unique identifier - **`name`** _(string)_ The package's name - **`package_group`** _(object)_ The package's package group - **`id`** _(string)_ The package group's unique identifier - **`name`** _(string)_ The package group's name - **`status`** _(string)_ The BGV's status Allowed: `draft`, `invited`, `pending_candidate`, `in_progress`, `insufficient`, `completed`, `canceled`, `expired`, `failed`, `unknown` - **`result`** _(string)_ The BGV's result Allowed: `clear`, `consider`, `discrepant`, `verified`, `unable_to_verify`, `not_applicable`, `unknown` - **`checks`** _(array)_ The BGV's checks - **`id`** _(string)_ The check's unique identifier - **`name`** _(string)_ The check's name - **`type`** _(string)_ The check's type - **`status`** _(string)_ The check's status - **`result`** _(string)_ The check's result - **`details`** _(string)_ The check's details - **`documents`** _(array)_ The BGV's documents - **`id`** _(string)_ The document's unique identifier - **`type`** _(string)_ The document's type - **`name`** _(string)_ The document's name - **`url`** _(string)_ The document's URL - **`uploaded_at`** _(string)_ The date and time of the document's upload - **`report`** _(object)_ The BGV's report - **`expires_at`** _(string)_ The date and time of the report's expiry - **`mime_type`** _(string)_ The report's MIME type - **`urls`** _(array)_ The BGV's URLs - **`url`** _(string)_ The URL - **`type`** _(string)_ The URL type Allowed: `invitation`, `consent`, `candidate_portal`, `report` - **`requested_at`** _(string)_ The date and time of the BGV's request - **`submitted_at`** _(string)_ The date and time of the candidate's submission - **`completed_at`** _(string)_ The date and time of the BGV's completion - **`expires_at`** _(string)_ The date and time of the BGV's expiry - **`created_at`** _(string)_ The date and time of the BGV's creation - **`updated_at`** _(string)_ The date and time of the BGV's last update - **`etag`** _(string)_ The unique identifier for the specific version of the resource - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/bgv](/api-reference/unified-hris-api/bgv/list) — List Bgv - [POST /unified/hris/bgv](/api-reference/unified-hris-api/bgv/create) — Create Bgv - [GET /unified/hris/bgv/{id}](/api-reference/unified-hris-api/bgv/get) — Get Bgv --- # BgvPackages Object > Source: https://truto.one/docs/api-reference/unified-hris-api/bgvpackages/ Schema for the `BgvPackages` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The BGV package's unique identifier - **`name`** _(string)_ The BGV package's name - **`description`** _(string)_ The BGV package's description - **`checks`** _(array)_ The BGV package's checks - **`id`** _(string)_ The check's unique identifier - **`name`** _(string)_ The check's name - **`type`** _(string)_ The check's type - **`description`** _(string)_ The check's description - **`created_at`** _(string)_ The date and time of the BGV package's creation - **`updated_at`** _(string)_ The date and time of the BGV package's last update - **`package_group`** _(object)_ The BGV package's package group - **`id`** _(string)_ The package group's unique identifier - **`name`** _(string)_ The package group's name - **`etag`** _(string)_ The unique identifier for the specific version of the resource - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/hris/bgv_packages](/api-reference/unified-hris-api/bgvpackages/list) — List Bgv packages --- # Dependents Object > Source: https://truto.one/docs/api-reference/unified-hris-api/dependents/ Schema for the `Dependents` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the dependent - **`employee`** _(object)_ The employee the dependent belongs to - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ The name of the employee - **`first_name`** _(string)_ The first name of the dependent - **`middle_name`** _(string)_ The middle name of the dependent - **`last_name`** _(string)_ The last name of the dependent - **`name`** _(string)_ The full name of the dependent - **`relationship`** _(string)_ The dependent's relationship to the employee. Relationships that fit none of the other values, such as grandchild or legal guardian, are returned as other, and the provider's own label stays in remote_data. Registered or civil partnerships that the provider records separately from marriage are returned as domestic_partner. Allowed: `spouse`, `domestic_partner`, `child`, `stepchild`, `foster_child`, `ward`, `parent`, `other` - **`date_of_birth`** _(string)_ The date of birth of the dependent, in YYYY-MM-DD format. Empty when the provider masks it. - **`gender`** _(string)_ The gender of the dependent. Empty when the provider value fits none of these. Allowed: `male`, `female`, `non_binary`, `other`, `prefer_not_to_disclose` - **`ssn`** _(string)_ The social security number or national identifier of the dependent. Most providers return it masked. - **`is_student`** _(boolean)_ Whether the dependent is a full-time student - **`is_disabled`** _(boolean)_ Whether the dependent has a disability - **`is_tobacco_user`** _(boolean)_ Whether the dependent uses tobacco - **`home_location`** _(array)_ The home addresses of the dependent. Most providers record a single address. - **`id`** _(string)_ The unique identifier for locations - **`name`** _(string)_ This represents the name of the location - **`street_1`** _(string)_ The first line of home address - **`street_2`** _(string)_ The second line of home address - **`city`** _(string)_ The city of the home address - **`state`** _(string)_ The state/province of the home address - **`postal_code`** _(string)_ The postal code of the home address - **`country`** _(string)_ The country of the home address - **`phones`** _(array)_ The phone numbers of the dependent - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`emails`** _(array)_ The email addresses of the dependent - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`status`** _(string)_ Whether the person is currently a dependent of the employee. inactive means they no longer are, for example after being removed from coverage. Empty when the provider does not say. Allowed: `active`, `inactive` - **`start_date`** _(string)_ When the person became a dependent of the employee, such as the relationship or coverage eligibility start date - **`end_date`** _(string)_ When the person stopped being a dependent of the employee. Empty while they still are - **`created_at`** _(string)_ The date and time the dependent was created - **`updated_at`** _(string)_ The date and time the dependent was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/dependents](/api-reference/unified-hris-api/dependents/create) — Create Dependents - [GET /unified/hris/dependents](/api-reference/unified-hris-api/dependents/list) — List Dependents - [GET /unified/hris/dependents/{id}](/api-reference/unified-hris-api/dependents/get) — Get Dependents --- # TimesheetEntries Object > Source: https://truto.one/docs/api-reference/unified-hris-api/timesheetentries/ Schema for the `TimesheetEntries` resource in **Unified HRIS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the timesheet entry - **`employee`** _(object)_ The employee who worked the time, not the person who entered it - **`id`** _(string)_ The unique identifier for employees - **`name`** _(string)_ The name of the employee - **`work_date`** _(string)_ The local calendar date the time counts toward, in YYYY-MM-DD format: the provider's own work, business or payroll date when it has one, otherwise the date of start_time in timezone. It is never taken from the UTC date. A shift that crosses midnight counts toward the date the provider attributes it to. - **`start_time`** _(string)_ When the time block started, as an ISO 8601 date-time with an explicit offset (Z or +HH:MM). Provider local times without an offset are converted using timezone. Empty when the provider records only a duration, or when the time zone is unknown. - **`end_time`** _(string)_ When the time block ended, in the same format as start_time. Empty while the entry is still open, when the provider records only a duration, or when the time zone is unknown. - **`hours_worked`** _(number)_ The number of hours worked in this entry, excluding unpaid breaks. It is the provider's own worked or payable figure when it has one, otherwise end_time minus start_time minus unpaid breaks, and it is empty while the entry is still open. Summing it across entries gives the time worked: unpaid breaks, time off and holidays count as 0 and paid breaks count their length. - **`breaks`** _(array)_ The breaks taken during this entry - **`start_time`** _(string)_ When the break started - **`end_time`** _(string)_ When the break ended. Empty while the break is in progress. - **`is_paid`** _(boolean)_ Whether the break is paid - **`type`** _(string)_ The kind of time recorded: regular working time, overtime, on call, a break, time off or a holiday. Providers that store breaks as separate entries return them with type break. Allowed: `regular`, `overtime`, `on_call`, `break`, `time_off`, `holiday`, `other` - **`status`** _(string)_ The approval status of the entry. draft: not yet submitted. pending: awaiting approval. approved: approved. rejected: rejected or sent back for correction. processed: paid, exported or locked by payroll. Providers that only record an approved flag return approved when it is set, and otherwise pending for completed entries and draft for entries that are still open. Allowed: `draft`, `pending`, `approved`, `rejected`, `processed` - **`job_role`** _(object)_ The job role the time was worked in - **`id`** _(string)_ The unique identifier for job roles - **`name`** _(string)_ The name of the job role - **`location`** _(object)_ The location where the time was worked - **`id`** _(string)_ The unique identifier for locations - **`name`** _(string)_ The name of the location - **`groups`** _(array)_ The groups, such as departments or cost centers, the time is attributed to - **`id`** _(string)_ The unique identifier for groups - **`name`** _(string)_ The name of the group - **`type`** _(string)_ The type of the group - **`project`** _(object)_ The project the time was logged against - **`id`** _(string)_ The unique identifier for the project - **`name`** _(string)_ The name of the project - **`pay_rate`** _(number)_ The hourly pay rate applied to this entry, in major units of pay_currency (for example 15.5) - **`pay_currency`** _(string)_ The currency of the pay rate, as an ISO 4217 code - **`timezone`** _(string)_ The IANA time zone name the time was recorded in, for example America/New_York - **`notes`** _(string)_ The notes attached to the entry - **`created_at`** _(string)_ The date and time the timesheet entry was created - **`updated_at`** _(string)_ The date and time the timesheet entry was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/hris/timesheet_entries](/api-reference/unified-hris-api/timesheetentries/create) — Create Timesheet entries - [GET /unified/hris/timesheet_entries](/api-reference/unified-hris-api/timesheetentries/list) — List Timesheet entries - [DELETE /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/delete) — Delete Timesheet entries - [GET /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/get) — Get Timesheet entries - [PATCH /unified/hris/timesheet_entries/{id}](/api-reference/unified-hris-api/timesheetentries/update) — Update Timesheet entries --- # Unified Instant Messaging API > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/ Base URL: `https://api.truto.one/unified/instant-messaging` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Workspaces](/api-reference/unified-instant-messaging-api/workspaces) - [GET /unified/instant-messaging/workspaces](/api-reference/unified-instant-messaging-api/workspaces/list) — List Workspaces - [Members](/api-reference/unified-instant-messaging-api/members) - [GET /unified/instant-messaging/members](/api-reference/unified-instant-messaging-api/members/list) — List Members - [GET /unified/instant-messaging/members/{id}](/api-reference/unified-instant-messaging-api/members/get) — Get Members - [Channels](/api-reference/unified-instant-messaging-api/channels) - [GET /unified/instant-messaging/channels](/api-reference/unified-instant-messaging-api/channels/list) — List Channels - [POST /unified/instant-messaging/channels](/api-reference/unified-instant-messaging-api/channels/create) — Create Channels - [GET /unified/instant-messaging/channels/{id}](/api-reference/unified-instant-messaging-api/channels/get) — Get Channels - [PATCH /unified/instant-messaging/channels/{id}](/api-reference/unified-instant-messaging-api/channels/update) — Update Channels - [POST /unified/instant-messaging/channels/join](/api-reference/unified-instant-messaging-api/channels/join) — Join Channels - [Messages](/api-reference/unified-instant-messaging-api/messages) - [POST /unified/instant-messaging/messages](/api-reference/unified-instant-messaging-api/messages/create) — Create Messages - [GET /unified/instant-messaging/messages](/api-reference/unified-instant-messaging-api/messages/list) — List Messages - [GET /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/get) — Get Messages - [PATCH /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/update) — Update Messages - [DELETE /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/delete) — Delete Messages - [Attachments](/api-reference/unified-instant-messaging-api/attachments) - [GET /unified/instant-messaging/attachments](/api-reference/unified-instant-messaging-api/attachments/list) — List Attachments - [POST /unified/instant-messaging/attachments](/api-reference/unified-instant-messaging-api/attachments/create) — Create Attachments - [GET /unified/instant-messaging/attachments/{id}](/api-reference/unified-instant-messaging-api/attachments/get) — Get Attachments --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/workspaces/ Schema for the `Workspaces` resource in **Unified Instant Messaging API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the workspace. - **`name`** _(string)_ Name of the workspace. - **`description`** _(string)_ Description for the workspace. - **`status`** _(string)_ Status for the workspace Allowed: `active`, `inactive` - **`organization`** _(object)_ Organization to which the workspace belongs. - **`id`** _(string)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`created_at`** _(string)_ Date and time when the workspace was created. - **`updated_at`** _(string)_ Date and time when the workspace was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/instant-messaging/workspaces](/api-reference/unified-instant-messaging-api/workspaces/list) — List Workspaces --- # Members Object > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/members/ Schema for the `Members` resource in **Unified Instant Messaging API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a member - **`first_name`** _(string)_ The first name of the member - **`last_name`** _(string)_ The last name of the member - **`title`** _(string)_ The title of the member - **`name`** _(string)_ The name of the member - **`username`** _(string)_ The username of the member - **`emails`** _(array)_ The emails of the member - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the member - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the member. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`is_email_verified`** _(boolean)_ Whether the member's email has been verified - **`organizations`** _(array)_ The organizations of the member - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`workspaces`** _(array)_ The workspaces of the member - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the worksapce - **`type`** _(string)_ The type of member - **`groups`** _(array)_ The groups of the member - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`type`** _(string)_ The type of group - **`organization`** _(object)_ The organization of the group - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`workspace`** _(object)_ The workspace of the group - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`avatar`** _(string)_ The avatar of the member - **`timezone`** _(string)_ The timezone of the member - **`languages`** _(array)_ The languages preferred by the member - **`bio`** _(string)_ The bio of the member - **`created_at`** _(string)_ The date and time the member was created - **`updated_at`** _(string)_ The date and time the member was last updated - **`last_active_at`** _(string)_ The date and time the member was last active - **`last_login_at`** _(string)_ The date and time the member was last logged in - **`status_changed_at`** _(string)_ The date and time the member's status was last changed - **`activated_at`** _(string)_ The date and time the member was activated - **`urls`** _(array)_ The URLs of the member - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/instant-messaging/members](/api-reference/unified-instant-messaging-api/members/list) — List Members - [GET /unified/instant-messaging/members/{id}](/api-reference/unified-instant-messaging-api/members/get) — Get Members --- # Channels Object > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/channels/ Schema for the `Channels` resource in **Unified Instant Messaging API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the channel. - **`name`** _(string)_ Name of the channel. - **`description`** _(string)_ Description of the channel. - **`organization`** _(object)_ Organization to which the channel belongs. - **`id`** _(string)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`workspace`** _(object)_ Workspace to which the channel belongs. - **`id`** _(string)_ Unique identifier for the workspace. - **`name`** _(string)_ Name of the workspace. - **`group`** _(object)_ Group to which the channel belongs. - **`id`** _(string)_ Unique identifier for the group. - **`name`** _(string)_ Name of the group. - **`type`** _(string)_ Type of the channel. Allowed: `channel`, `private_channel`, `dm`, `group_dm`, `shared_channel` - **`status`** _(string)_ Status of the channel. Allowed: `active`, `archived` - **`is_member`** _(boolean)_ Is the current authed user or application is a member of the channel. This might not directly mean that the user or application can post messages on the channel. - **`created_by`** _(object)_ - **`id`** _(string)_ Unique identifier for the member. - **`created_at`** _(string)_ Date and time when the channel was created. - **`updated_at`** _(string)_ Date and time when the channel was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/instant-messaging/channels](/api-reference/unified-instant-messaging-api/channels/list) — List Channels - [POST /unified/instant-messaging/channels](/api-reference/unified-instant-messaging-api/channels/create) — Create Channels - [GET /unified/instant-messaging/channels/{id}](/api-reference/unified-instant-messaging-api/channels/get) — Get Channels - [PATCH /unified/instant-messaging/channels/{id}](/api-reference/unified-instant-messaging-api/channels/update) — Update Channels - [POST /unified/instant-messaging/channels/join](/api-reference/unified-instant-messaging-api/channels/join) — Join Channels --- # Messages Object > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/messages/ Schema for the `Messages` resource in **Unified Instant Messaging API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the message. - **`body`** _(object)_ Body of the message. - **`format`** _(string)_ Format of the message body. - **`content`** _(string)_ Content of the message body. - **`attachments`** _(array)_ Attachments of the message. - **`id`** _(string)_ Unique identifier for the attachment. - **`name`** _(string)_ Name of the attachment. - **`type`** _(string)_ Type of the attachment. - **`url`** _(string)_ URL of the attachment. - **`author`** _(object)_ Author of the message. Is a member object. - **`id`** _(string)_ Unique identifier for the author. - **`name`** _(string)_ Name of the author. - **`channel`** _(object)_ Channel to which the message belongs. - **`id`** _(string)_ Unique identifier for the channel. - **`name`** _(string)_ Name of the channel. - **`type`** _(string)_ Type of the channel. - **`parent`** _(object)_ Parent entity of the message. - **`id`** _(string)_ Unique identifier for the parent entity. - **`type`** _(string)_ Type of the parent entity. Allowed: `message` - **`has_children`** _(boolean)_ Whether the message has children. - **`created_at`** _(string)_ Date and time when the message was created. - **`updated_at`** _(string)_ Date and time when the message was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/instant-messaging/messages](/api-reference/unified-instant-messaging-api/messages/create) — Create Messages - [GET /unified/instant-messaging/messages](/api-reference/unified-instant-messaging-api/messages/list) — List Messages - [GET /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/get) — Get Messages - [PATCH /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/update) — Update Messages - [DELETE /unified/instant-messaging/messages/{id}](/api-reference/unified-instant-messaging-api/messages/delete) — Delete Messages --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-instant-messaging-api/attachments/ Schema for the `Attachments` resource in **Unified Instant Messaging API**. ## Properties - **`id`** _(string)_ The unique identifier for the attachment - **`file_name`** _(string)_ The attachment's name. - **`channel_id`** _(string)_ The channel id to which the attachment belongs - **`size`** _(number)_ The file size in bytes - **`file_url`** _(string)_ The URL to download the attachment - **`content_type`** _(string)_ The content type of the attachment - **`uploaded_by`** _(string)_ The user who uploaded the attachment - **`uploaded_by_type`** _(string)_ The type of the user who uploaded the attachment - **`created_at`** _(string)_ The time when the attachment was created - **`updated_at`** _(string)_ The time when the attachment was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/instant-messaging/attachments](/api-reference/unified-instant-messaging-api/attachments/list) — List Attachments - [POST /unified/instant-messaging/attachments](/api-reference/unified-instant-messaging-api/attachments/create) — Create Attachments - [GET /unified/instant-messaging/attachments/{id}](/api-reference/unified-instant-messaging-api/attachments/get) — Get Attachments --- # Unified Knowledge Base API > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/ Base URL: `https://api.truto.one/unified/knowledge-base` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Pages](/api-reference/unified-knowledge-base-api/pages) - [GET /unified/knowledge-base/pages/{id}](/api-reference/unified-knowledge-base-api/pages/get) — Get Pages - [PATCH /unified/knowledge-base/pages/{id}](/api-reference/unified-knowledge-base-api/pages/update) — Update Pages - [GET /unified/knowledge-base/pages](/api-reference/unified-knowledge-base-api/pages/list) — List Pages - [POST /unified/knowledge-base/pages](/api-reference/unified-knowledge-base-api/pages/create) — Create Pages - [PageContent](/api-reference/unified-knowledge-base-api/pagecontent) - [GET /unified/knowledge-base/page-content](/api-reference/unified-knowledge-base-api/pagecontent/list) — List Page content - [POST /unified/knowledge-base/page-content/append](/api-reference/unified-knowledge-base-api/pagecontent/append) — Append Page content - [POST /unified/knowledge-base/page-content/export](/api-reference/unified-knowledge-base-api/pagecontent/export) — Export Page content - [GET /unified/knowledge-base/page-content/{id}](/api-reference/unified-knowledge-base-api/pagecontent/get) — Get Page content - [Collections](/api-reference/unified-knowledge-base-api/collections) - [GET /unified/knowledge-base/collections](/api-reference/unified-knowledge-base-api/collections/list) — List Collections - [GET /unified/knowledge-base/collections/{id}](/api-reference/unified-knowledge-base-api/collections/get) — Get Collections - [Comments](/api-reference/unified-knowledge-base-api/comments) - [GET /unified/knowledge-base/comments](/api-reference/unified-knowledge-base-api/comments/list) — List Comments - [GET /unified/knowledge-base/comments/{id}](/api-reference/unified-knowledge-base-api/comments/get) — Get Comments - [Spaces](/api-reference/unified-knowledge-base-api/spaces) - [GET /unified/knowledge-base/spaces](/api-reference/unified-knowledge-base-api/spaces/list) — List Spaces - [GET /unified/knowledge-base/spaces/{id}](/api-reference/unified-knowledge-base-api/spaces/get) — Get Spaces - [Tags](/api-reference/unified-knowledge-base-api/tags) - [GET /unified/knowledge-base/tags](/api-reference/unified-knowledge-base-api/tags/list) — List Tags - [PageExports](/api-reference/unified-knowledge-base-api/pageexports) - [GET /unified/knowledge-base/page-exports/{id}](/api-reference/unified-knowledge-base-api/pageexports/get) — Get Page exports - [POST /unified/knowledge-base/page-exports](/api-reference/unified-knowledge-base-api/pageexports/create) — Create Page exports - [POST /unified/knowledge-base/page-exports/download](/api-reference/unified-knowledge-base-api/pageexports/download) — Download Page exports - [Files](/api-reference/unified-knowledge-base-api/files) - [GET /unified/knowledge-base/files](/api-reference/unified-knowledge-base-api/files/list) — List Files - [POST /unified/knowledge-base/files/download](/api-reference/unified-knowledge-base-api/files/download) — Download Files - [Permissions](/api-reference/unified-knowledge-base-api/permissions) - [GET /unified/knowledge-base/permissions](/api-reference/unified-knowledge-base-api/permissions/list) — List Permissions - [Users](/api-reference/unified-knowledge-base-api/users) - [GET /unified/knowledge-base/users/{id}](/api-reference/unified-knowledge-base-api/users/get) — Get Users - [GET /unified/knowledge-base/users](/api-reference/unified-knowledge-base-api/users/list) — List Users --- # Pages Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/pages/ Schema for the `Pages` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the page - **`title`** _(string)_ The title of the page - **`description`** _(string)_ The description of the page - **`page_type`** _(string)_ The type of the page Allowed: `landing-pages`, `site-pages`, `blog-posts`, `page`, `database` - **`status`** _(string)_ The status of the page Allowed: `draft`, `published`, `archived`, `deleted` - **`tags`** _(array)_ The tags associated with the page - **`parent`** _(object)_ The parent of the page - **`id`** _(string)_ The unique identifier for the parent page - **`type`** _(string)_ The type of the parent - **`space`** _(object)_ The space the page belongs to - **`id`** _(string)_ The unique identifier for the space - **`collection`** _(object)_ The collection the page belongs to - **`id`** _(string)_ The unique identifier for the collection - **`created_by`** _(object)_ The user who created the page - **`id`** _(string)_ The unique identifier for the user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email of the user - **`is_primary`** _(boolean)_ Whether the email is the primary email of the user - **`type`** _(string)_ The type of the email Allowed: `work`, `home`, `other` - **`last_edited_by`** _(object)_ The user who last edited the page - **`id`** _(string)_ The unique identifier for the user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email of the user - **`is_primary`** _(boolean)_ Whether the email is the primary email of the user - **`type`** _(string)_ The type of the email Allowed: `work`, `home`, `other` - **`published_at`** _(string)_ The date and time the page was published - **`urls`** _(array)_ The urls of the page - **`url`** _(string)_ The url of the page - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_at`** _(string)_ The date and time the page was created - **`updated_at`** _(string)_ The date and time the page was last updated - **`visibility`** _(string)_ The visibility of the page Allowed: `private`, `public` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/pages/{id}](/api-reference/unified-knowledge-base-api/pages/get) — Get Pages - [PATCH /unified/knowledge-base/pages/{id}](/api-reference/unified-knowledge-base-api/pages/update) — Update Pages - [GET /unified/knowledge-base/pages](/api-reference/unified-knowledge-base-api/pages/list) — List Pages - [POST /unified/knowledge-base/pages](/api-reference/unified-knowledge-base-api/pages/create) — Create Pages --- # PageContent Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/pagecontent/ Schema for the `PageContent` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the page content - **`sequence`** _(integer)_ The order of the page content in the context of a page. Will increase sequentially from 0. - **`page`** _(object)_ The page the content belongs to - **`id`** _(string)_ The unique identifier for the page - **`page_type`** _(string)_ The type of the page Allowed: `landing-pages`, `site-pages`, `blog-posts` - **`parent`** _(object)_ The parent of the page content - **`id`** _(string)_ The unique identifier for the parent page content - **`type`** _(string)_ The type of the parent - **`has_children`** _(boolean)_ Whether the page content has children - **`body`** _(object)_ The body of the page content - **`format`** _(string)_ The format of the body Allowed: `markdown`, `html`, `plaintext` - **`content`** _(string)_ The content of the body - **`urls`** _(array)_ The URLs of the files attached in the page content - **`url`** _(string)_ The URL of the file - **`type`** _(string)_ The URL type of the file Allowed: `original_url`, `truto_download` - **`created_at`** _(string)_ The date and time the page content was created - **`updated_at`** _(string)_ The date and time the page content was last updated - **`visibility`** _(string)_ The visibility of the page Allowed: `private`, `public` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/page-content](/api-reference/unified-knowledge-base-api/pagecontent/list) — List Page content - [POST /unified/knowledge-base/page-content/append](/api-reference/unified-knowledge-base-api/pagecontent/append) — Append Page content - [POST /unified/knowledge-base/page-content/export](/api-reference/unified-knowledge-base-api/pagecontent/export) — Export Page content - [GET /unified/knowledge-base/page-content/{id}](/api-reference/unified-knowledge-base-api/pagecontent/get) — Get Page content --- # Collections Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/collections/ Schema for the `Collections` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the collection - **`name`** _(string)_ The name of the collection - **`description`** _(string)_ The description of the collection - **`type`** _(string)_ The type of the collection - **`space`** _(object)_ The space the collection belongs to - **`id`** _(string)_ The unique identifier for the space - **`name`** _(string)_ The name of the space - **`parent`** _(object)_ The parent of the collection - **`id`** _(string)_ The unique identifier for the parent - **`type`** _(string)_ The type of the parent - **`urls`** _(array)_ The urls of the collection - **`url`** _(string)_ The url of the collection - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_at`** _(string)_ The date and time the collection was created - **`updated_at`** _(string)_ The date and time the collection was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/collections](/api-reference/unified-knowledge-base-api/collections/list) — List Collections - [GET /unified/knowledge-base/collections/{id}](/api-reference/unified-knowledge-base-api/collections/get) — Get Collections --- # Comments Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/comments/ Schema for the `Comments` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the comment - **`created_by`** _(object)_ The user who created the comment - **`id`** _(string)_ The unique identifier for the user - **`parent`** _(object)_ The parent of the comment - **`id`** _(string)_ The unique identifier for the parent - **`type`** _(string)_ The type of the parent - **`body`** _(string)_ The body of the comment - **`created_at`** _(string)_ The date and time the comment was created - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/comments](/api-reference/unified-knowledge-base-api/comments/list) — List Comments - [GET /unified/knowledge-base/comments/{id}](/api-reference/unified-knowledge-base-api/comments/get) — Get Comments --- # Spaces Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/spaces/ Schema for the `Spaces` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the space - **`identifier`** _(string)_ A human readable identifier for the space. Usually is a shortened version on the name. - **`name`** _(string)_ The name of the space - **`description`** _(string)_ The description of the space - **`status`** _(string)_ The status of the space Allowed: `active`, `archived` - **`urls`** _(array)_ The urls of the space - **`url`** _(string)_ The url of the space - **`type`** _(string)_ The type of the url Allowed: `view`, `edit`, `public_view` - **`created_at`** _(string)_ The date and time the space was created - **`updated_at`** _(string)_ The date and time the space was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/spaces](/api-reference/unified-knowledge-base-api/spaces/list) — List Spaces - [GET /unified/knowledge-base/spaces/{id}](/api-reference/unified-knowledge-base-api/spaces/get) — Get Spaces --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/tags/ Schema for the `Tags` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the tag - **`name`** _(string)_ The name of the tag - **`description`** _(string)_ The description of the tag - **`space`** _(object)_ The space the tag belongs to - **`id`** _(string)_ The unique identifier for the space - **`created_at`** _(string)_ The date and time the tag was created - **`updated_at`** _(string)_ The date and time the tag was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/tags](/api-reference/unified-knowledge-base-api/tags/list) — List Tags --- # PageExports Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/pageexports/ Schema for the `PageExports` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string)_ The unique identifier of the page export job - **`status`** _(string)_ The status of the page export job - **`page`** _(object)_ The page associated with the page export job - **`id`** _(string)_ The unique identifier of the page - **`urls`** _(array)_ The urls associated with the page export job - **`url`** _(string)_ The url associated with the page export - **`type`** _(string)_ The type of the url Allowed: `download`, `truto_download`, `view` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/page-exports/{id}](/api-reference/unified-knowledge-base-api/pageexports/get) — Get Page exports - [POST /unified/knowledge-base/page-exports](/api-reference/unified-knowledge-base-api/pageexports/create) — Create Page exports - [POST /unified/knowledge-base/page-exports/download](/api-reference/unified-knowledge-base-api/pageexports/download) — Download Page exports --- # Files Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/files/ Schema for the `Files` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string)_ The unique identifier for the file - **`file_name`** _(string)_ The file's name. - **`page_id`** _(string)_ The page id to which the file belongs - **`size`** _(number)_ The file size in bytes - **`file_url`** _(string)_ The URL to download the file - **`content_type`** _(string)_ The content type of the file - **`uploaded_by`** _(string)_ The user who uploaded the file - **`created_at`** _(string)_ The time when the file was created - **`updated_at`** _(string)_ The time when the file was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/files](/api-reference/unified-knowledge-base-api/files/list) — List Files - [POST /unified/knowledge-base/files/download](/api-reference/unified-knowledge-base-api/files/download) — Download Files --- # Permissions Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/permissions/ Schema for the `Permissions` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string)_ Unique identifier for the permission - **`resources`** _(array)_ The resources for which the permission is applicable for - **`id`** _(string)_ Unique identifier for the resource - **`type`** _(string)_ Type of the resource Allowed: `drive_item`, `drive` - **`user`** _(object)_ The user for whom the permission is applicable for - **`id`** _(string)_ Unique identifier for the user - **`permissions`** _(array)_ The list of permissions - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/permissions](/api-reference/unified-knowledge-base-api/permissions/list) — List Permissions --- # Users Object > Source: https://truto.one/docs/api-reference/unified-knowledge-base-api/users/ Schema for the `Users` resource in **Unified Knowledge Base API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`external_id`** _(string)_ The external identifier for a user. This is set when the SCIM API is being used. - **`identifiers`** _(object)_ The identifiers of the user. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`title`** _(string)_ The title of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`is_email_verified`** _(boolean)_ Whether the user's email has been verified - **`is_2fa_enabled`** _(boolean)_ Whether the user has 2FA enabled - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`group`** _(string)_ The role of the user in the group. This is available when the user can have different roles in different groups or teams in an application. - **`organization`** _(string)_ The role of the user in the organization. This is available when the user can have different roles in different organizations in an application. - **`workspace`** _(string)_ The role of the user in the workspace. This is available when the user can have different roles in different workspaces in an application. - **`organizations`** _(array)_ The organizations of the user - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`user_type`** _(string)_ The type of user - **`licenses`** _(array)_ The licenses of the user or the products the user has access to - **`id`** _(string)_ The unique identifier for a license - **`name`** _(string)_ The name of the license - **`organization`** _(string)_ The unique identifier of the organization to which the license belongs - **`last_active_at`** _(string)_ The date and time the user was last active for the license - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`workspaces`** _(array)_ The workspaces of the user - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspaces - **`avatar`** _(string)_ The avatar of the user - **`timezone`** _(string)_ The timezone of the user - **`languages`** _(array)_ The languages preferred by the user - **`bio`** _(string)_ The bio of the user. Usually a short description set by the user about them. - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`last_active_at`** _(string)_ The date and time the user was last active - **`last_login_at`** _(string)_ The date and time the user was last logged in - **`status_changed_at`** _(string)_ The date and time the user's status was last changed - **`activated_at`** _(string)_ The date and time the user was activated - **`urls`** _(array)_ The URLs of the user - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/knowledge-base/users/{id}](/api-reference/unified-knowledge-base-api/users/get) — Get Users - [GET /unified/knowledge-base/users](/api-reference/unified-knowledge-base-api/users/list) — List Users --- # Unified LMS API > Source: https://truto.one/docs/api-reference/unified-lms-api/ Base URL: `https://api.truto.one/unified/lms` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Users](/api-reference/unified-lms-api/users) - [GET /unified/lms/users](/api-reference/unified-lms-api/users/list) — List Users - [GET /unified/lms/users/{id}](/api-reference/unified-lms-api/users/get) — Get Users - [Courses](/api-reference/unified-lms-api/courses) - [GET /unified/lms/courses](/api-reference/unified-lms-api/courses/list) — List Courses - [GET /unified/lms/courses/{id}](/api-reference/unified-lms-api/courses/get) — Get Courses - [CourseEnrollments](/api-reference/unified-lms-api/courseenrollments) - [GET /unified/lms/course-enrollments](/api-reference/unified-lms-api/courseenrollments/list) — List Course enrollments --- # Users Object > Source: https://truto.one/docs/api-reference/unified-lms-api/users/ Schema for the `Users` resource in **Unified LMS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the user - **`first_name`** _(string)_ The user's first name - **`last_name`** _(string)_ The user's last name - **`name`** _(string)_ The user's name - **`username`** _(string)_ The user's username or login identifier, when different from email - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`status`** _(string)_ The lifecycle status of the user in the LMS Allowed: `active`, `inactive`, `invited`, `suspended`, `deleted`, `unknown` - **`role`** _(string)_ The primary role of the user in the LMS Allowed: `learner`, `instructor`, `admin`, `manager`, `other` - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`locale`** _(string)_ The locale of the user, when available. Example: en-US - **`timezone`** _(string)_ The timezone of the user, when available. Example: Asia/Kolkata - **`job_title`** _(string)_ The user's job title, when available - **`organization`** _(object)_ The organization or tenant the user belongs to, when available - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`manager`** _(object)_ The user's manager, when available - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`created_at`** _(string)_ The date and time the user record was created - **`updated_at`** _(string)_ The date and time the user record was last updated - **`custom_fields`** _(object)_ Provider or customer specific fields mapped into a flexible key-value object - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/lms/users](/api-reference/unified-lms-api/users/list) — List Users - [GET /unified/lms/users/{id}](/api-reference/unified-lms-api/users/get) — Get Users --- # Courses Object > Source: https://truto.one/docs/api-reference/unified-lms-api/courses/ Schema for the `Courses` resource in **Unified LMS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the course - **`title`** _(string)_ The title of the course - **`description`** _(string)_ The description of the course - **`code`** _(string)_ A course code or SKU, when available - **`type`** _(string)_ The type of learning item Allowed: `course`, `path`, `curriculum`, `program`, `microlearning`, `other` - **`status`** _(string)_ The publication or availability status of the course Allowed: `draft`, `published`, `archived`, `disabled`, `unknown` - **`language`** _(string)_ The primary language of the course, when available. Example: en - **`duration_seconds`** _(integer)_ The estimated duration of the course in seconds, when available - **`level`** _(string)_ The difficulty level of the course, when available Allowed: `beginner`, `intermediate`, `advanced`, `mixed`, `unknown` - **`urls`** _(array)_ The URLs related to the course. - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`tags`** _(array)_ Tags applied to the course - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`categories`** _(array)_ Categories the course belongs to, when available - **`id`** _(string)_ The category's unique identifier - **`name`** _(string)_ The category's name - **`organization`** _(object)_ The organization or tenant the course belongs to, when available - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`published_at`** _(string)_ The date and time the course was published, when available - **`created_at`** _(string)_ The date and time the course record was created - **`updated_at`** _(string)_ The date and time the course record was last updated - **`custom_fields`** _(object)_ Provider or customer specific fields mapped into a flexible key-value object - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/lms/courses](/api-reference/unified-lms-api/courses/list) — List Courses - [GET /unified/lms/courses/{id}](/api-reference/unified-lms-api/courses/get) — Get Courses --- # CourseEnrollments Object > Source: https://truto.one/docs/api-reference/unified-lms-api/courseenrollments/ Schema for the `CourseEnrollments` resource in **Unified LMS API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the course enrollment record - **`user`** _(object)_ The learner associated with this record - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`course`** _(object)_ The course associated with this record - **`id`** _(string)_ The unique identifier for the course - **`title`** _(string)_ The title of the course - **`status`** _(string)_ The lifecycle status for the user in this course Allowed: `assigned`, `enrolled`, `in_progress`, `completed`, `passed`, `failed`, `withdrawn`, `expired`, `overdue`, `unknown` - **`assigned_at`** _(string)_ The date and time the course was assigned to the user, when available - **`due_at`** _(string)_ The due date for course completion, when available - **`enrolled_at`** _(string)_ The date and time the user enrolled or registered, when available - **`started_at`** _(string)_ The date and time the user started the course, when available - **`last_activity_at`** _(string)_ The date and time of the last recorded activity for this enrollment, when available - **`completed_at`** _(string)_ The date and time the user completed the course, when available - **`progress_percent`** _(number)_ Progress percentage from 0 to 100, when available - **`time_spent_seconds`** _(integer)_ Total time spent in seconds, when available - **`score`** _(number)_ The latest or final score, when available - **`is_mandatory`** _(boolean)_ Whether this enrollment is part of a mandatory assignment, when available - **`assigned_by`** _(object)_ The assigner of this course to the user, when available - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`attempt_number`** _(integer)_ The latest attempt number, when the LMS supports retakes - **`attempts_count`** _(integer)_ Total attempts count, when available - **`urls`** _(array)_ The URLs of the course-enrollments - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`created_at`** _(string)_ The date and time the enrollment record was created - **`updated_at`** _(string)_ The date and time the enrollment record was last updated - **`custom_fields`** _(object)_ Provider or customer specific fields mapped into a flexible key-value object - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/lms/course-enrollments](/api-reference/unified-lms-api/courseenrollments/list) — List Course enrollments --- # Unified Marketing Automation API > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/ Base URL: `https://api.truto.one/unified/marketing-automation` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Automations](/api-reference/unified-marketing-automation-api/automations) - [GET /unified/marketing-automation/automations](/api-reference/unified-marketing-automation-api/automations/list) — List Automations - [Campaigns](/api-reference/unified-marketing-automation-api/campaigns) - [GET /unified/marketing-automation/campaigns](/api-reference/unified-marketing-automation-api/campaigns/list) — List Campaigns - [GET /unified/marketing-automation/campaigns/{id}](/api-reference/unified-marketing-automation-api/campaigns/get) — Get Campaigns - [Contacts](/api-reference/unified-marketing-automation-api/contacts) - [GET /unified/marketing-automation/contacts/{id}](/api-reference/unified-marketing-automation-api/contacts/get) — Get Contacts - [PATCH /unified/marketing-automation/contacts/{id}](/api-reference/unified-marketing-automation-api/contacts/update) — Update Contacts - [GET /unified/marketing-automation/contacts](/api-reference/unified-marketing-automation-api/contacts/list) — List Contacts - [POST /unified/marketing-automation/contacts](/api-reference/unified-marketing-automation-api/contacts/create) — Create Contacts - [Lists](/api-reference/unified-marketing-automation-api/lists) - [GET /unified/marketing-automation/lists](/api-reference/unified-marketing-automation-api/lists/list) — List Lists - [POST /unified/marketing-automation/lists](/api-reference/unified-marketing-automation-api/lists/create) — Create Lists - [GET /unified/marketing-automation/lists/{id}](/api-reference/unified-marketing-automation-api/lists/get) — Get Lists - [PATCH /unified/marketing-automation/lists/{id}](/api-reference/unified-marketing-automation-api/lists/update) — Update Lists - [Segments](/api-reference/unified-marketing-automation-api/segments) - [GET /unified/marketing-automation/segments](/api-reference/unified-marketing-automation-api/segments/list) — List Segments - [GET /unified/marketing-automation/segments/{id}](/api-reference/unified-marketing-automation-api/segments/get) — Get Segments - [Messages](/api-reference/unified-marketing-automation-api/messages) - [GET /unified/marketing-automation/messages](/api-reference/unified-marketing-automation-api/messages/list) — List Messages - [GET /unified/marketing-automation/messages/{id}](/api-reference/unified-marketing-automation-api/messages/get) — Get Messages - [Tags](/api-reference/unified-marketing-automation-api/tags) - [GET /unified/marketing-automation/tags](/api-reference/unified-marketing-automation-api/tags/list) — List Tags - [POST /unified/marketing-automation/tags](/api-reference/unified-marketing-automation-api/tags/create) — Create Tags - [GET /unified/marketing-automation/tags/{id}](/api-reference/unified-marketing-automation-api/tags/get) — Get Tags - [PATCH /unified/marketing-automation/tags/{id}](/api-reference/unified-marketing-automation-api/tags/update) — Update Tags - [Templates](/api-reference/unified-marketing-automation-api/templates) - [GET /unified/marketing-automation/templates](/api-reference/unified-marketing-automation-api/templates/list) — List Templates - [GET /unified/marketing-automation/templates/{id}](/api-reference/unified-marketing-automation-api/templates/get) — Get Templates - [Users](/api-reference/unified-marketing-automation-api/users) - [GET /unified/marketing-automation/users](/api-reference/unified-marketing-automation-api/users/list) — List Users - [GET /unified/marketing-automation/users/{id}](/api-reference/unified-marketing-automation-api/users/get) — Get Users - [Workspaces](/api-reference/unified-marketing-automation-api/workspaces) - [GET /unified/marketing-automation/workspaces](/api-reference/unified-marketing-automation-api/workspaces/list) — List Workspaces - [GET /unified/marketing-automation/workspaces/{id}](/api-reference/unified-marketing-automation-api/workspaces/get) — Get Workspaces --- # Automations Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/automations/ Schema for the `Automations` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The automation's unique identifier - **`name`** _(string)_ The automation's name - **`actions`** _(array)_ The actions that were executed as part of this automation - **`trigger_type`** _(string)_ The type of trigger that was used to execute this automation - **`start_date`** _(string)_ The date and time that the automation was started - **`end_date`** _(string)_ The date and time that the automation was ended - **`description`** _(string)_ The automation's description - **`status`** _(string)_ The automation's status - **`automation_trigger`** _(object)_ - **`updated_at`** _(string)_ The date and time of the automation's last update - **`created_at`** _(string)_ The date and time of the automation's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/automations](/api-reference/unified-marketing-automation-api/automations/list) — List Automations --- # Campaigns Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/campaigns/ Schema for the `Campaigns` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The campaign's unique identifier - **`name`** _(string)_ The campaign's name - **`unique_opens`** _(integer)_ The number of unique opens for this campaign - **`emails_sent`** _(integer)_ The number of emails sent for this campaign - **`updated_at`** _(string)_ The date and time of the campaign's last update - **`created_at`** _(string)_ The date and time of the campaign's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/campaigns](/api-reference/unified-marketing-automation-api/campaigns/list) — List Campaigns - [GET /unified/marketing-automation/campaigns/{id}](/api-reference/unified-marketing-automation-api/campaigns/get) — Get Campaigns --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/contacts/ Schema for the `Contacts` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The contact's unique identifier - **`first_name`** _(string)_ The contact's first name - **`last_name`** _(string)_ The contact's last name - **`name`** _(string)_ The contact's full name - **`email`** _(string)_ The contact's email - **`phones`** _(array)_ The contact's phone numbers - **`phone`** _(string)_ The phone number - **`type`** _(string)_ The phone number type - **`addresses`** _(array)_ The contact's addresses - **`street_1`** _(string)_ The contact's first line of street address - **`street_2`** _(string)_ The contact's second line of street address - **`city`** _(string)_ The contact's city - **`state`** _(string)_ The contact's state - **`country`** _(string)_ The contact's country - **`postal_code`** _(string)_ The contact's postal code - **`type`** _(string)_ The address type - **`lists`** _(array)_ The lists that the contact is subscribed to - **`id`** _(string)_ The list's unique identifier - **`tags`** _(array)_ The contact's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`status`** _(string)_ The contact's subscription status - **`updated_at`** _(string)_ The date and time of the contact's last update - **`created_at`** _(string)_ The date and time of the contact's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/contacts/{id}](/api-reference/unified-marketing-automation-api/contacts/get) — Get Contacts - [PATCH /unified/marketing-automation/contacts/{id}](/api-reference/unified-marketing-automation-api/contacts/update) — Update Contacts - [GET /unified/marketing-automation/contacts](/api-reference/unified-marketing-automation-api/contacts/list) — List Contacts - [POST /unified/marketing-automation/contacts](/api-reference/unified-marketing-automation-api/contacts/create) — Create Contacts --- # Lists Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/lists/ Schema for the `Lists` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The list's unique identifier - **`name`** _(string)_ The list's name - **`description`** _(string)_ The list's description - **`type`** _(string)_ The list's type - **`updated_at`** _(string)_ The date and time of the list's last update - **`created_at`** _(string)_ The date and time of the list's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/lists](/api-reference/unified-marketing-automation-api/lists/list) — List Lists - [POST /unified/marketing-automation/lists](/api-reference/unified-marketing-automation-api/lists/create) — Create Lists - [GET /unified/marketing-automation/lists/{id}](/api-reference/unified-marketing-automation-api/lists/get) — Get Lists - [PATCH /unified/marketing-automation/lists/{id}](/api-reference/unified-marketing-automation-api/lists/update) — Update Lists --- # Segments Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/segments/ Schema for the `Segments` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The segment's unique identifier - **`name`** _(string)_ The segment's name - **`description`** _(string)_ The segment's description - **`status`** _(string)_ The segment's computation status Allowed: `active`, `pending`, `processing`, `inactive`, `failed` - **`is_starred`** _(boolean)_ Whether the segment is starred - **`updated_at`** _(string)_ The date and time of the segment's last update - **`created_at`** _(string)_ The date and time of the segment's creation - **`last_calculated_at`** _(string)_ The date and time of the segment's last calculation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/segments](/api-reference/unified-marketing-automation-api/segments/list) — List Segments - [GET /unified/marketing-automation/segments/{id}](/api-reference/unified-marketing-automation-api/segments/get) — Get Segments --- # Messages Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/messages/ Schema for the `Messages` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The message's unique identifier - **`sender`** _(object)_ The sender of the message - **`id`** _(string)_ Unique identifier of the sender - **`name`** _(string)_ Name of the sender - **`type`** _(string)_ Type of the sender Allowed: `contact`, `user` - **`recipient`** _(object)_ The recipient of the message - **`id`** _(string)_ Unique identifier of the recipient - **`name`** _(string)_ Name of the recipient - **`type`** _(string)_ Type of the recipient Allowed: `contact`, `user` - **`send_date`** _(string)_ The date and time that the message was sent - **`subject`** _(string)_ The message's subject line - **`body`** _(string)_ The message's body - **`body_html`** _(string)_ The message's HTML body - **`status`** _(string)_ The sending status of the message - **`channel`** _(string)_ The medium through which the message was sent Allowed: `email`, `webhook`, `in_app`, `slack`, `push`, `twilio` - **`campaign`** _(object)_ The associated campaign for the message - **`id`** _(string)_ Unique identifier of the campaign - **`template`** _(object)_ The associated template for the message - **`id`** _(string)_ Unique identifier of the template - **`updated_at`** _(string)_ The date and time of the message's last update - **`created_at`** _(string)_ The date and time of the message's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/messages](/api-reference/unified-marketing-automation-api/messages/list) — List Messages - [GET /unified/marketing-automation/messages/{id}](/api-reference/unified-marketing-automation-api/messages/get) — Get Messages --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/tags/ Schema for the `Tags` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`created_at`** _(string)_ The date and time of the tag's creation - **`updated_at`** _(string)_ The date and time of the tag's last update - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/tags](/api-reference/unified-marketing-automation-api/tags/list) — List Tags - [POST /unified/marketing-automation/tags](/api-reference/unified-marketing-automation-api/tags/create) — Create Tags - [GET /unified/marketing-automation/tags/{id}](/api-reference/unified-marketing-automation-api/tags/get) — Get Tags - [PATCH /unified/marketing-automation/tags/{id}](/api-reference/unified-marketing-automation-api/tags/update) — Update Tags --- # Templates Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/templates/ Schema for the `Templates` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The template's unique identifier - **`name`** _(string)_ The template's name - **`type`** _(string)_ The template's type - **`contents`** _(string)_ The template's contents - **`owner`** _(object)_ The template's owner - **`id`** _(string)_ - **`updated_at`** _(string)_ The date and time of the template's last update - **`created_at`** _(string)_ The date and time of the template's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/templates](/api-reference/unified-marketing-automation-api/templates/list) — List Templates - [GET /unified/marketing-automation/templates/{id}](/api-reference/unified-marketing-automation-api/templates/get) — Get Templates --- # Users Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/users/ Schema for the `Users` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The user's unique identifier - **`name`** _(string)_ The user's name - **`username`** _(string)_ The user's username - **`email`** _(string)_ The user's email - **`role`** _(string)_ The user's role - **`timezone`** _(string)_ The user's timezone - **`updated_at`** _(string)_ The date and time of the user's last update - **`created_at`** _(string)_ The date and time of the user's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/users](/api-reference/unified-marketing-automation-api/users/list) — List Users - [GET /unified/marketing-automation/users/{id}](/api-reference/unified-marketing-automation-api/users/get) — Get Users --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-marketing-automation-api/workspaces/ Schema for the `Workspaces` resource in **Unified Marketing Automation API**. ## Properties - **`id`** _(string, required)_ The workspace's unique identifier - **`name`** _(string)_ The workspace's name - **`description`** _(string)_ The workspace's description - **`updated_at`** _(string)_ The date and time of the workspace's last update - **`created_at`** _(string)_ The date and time of the workspace's creation - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/marketing-automation/workspaces](/api-reference/unified-marketing-automation-api/workspaces/list) — List Workspaces - [GET /unified/marketing-automation/workspaces/{id}](/api-reference/unified-marketing-automation-api/workspaces/get) — Get Workspaces --- # Unified MDM API > Source: https://truto.one/docs/api-reference/unified-mdm-api/ Base URL: `https://api.truto.one/unified/mdm` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Devices](/api-reference/unified-mdm-api/devices) - [GET /unified/mdm/devices](/api-reference/unified-mdm-api/devices/list) — List Devices - [POST /unified/mdm/devices](/api-reference/unified-mdm-api/devices/create) — Create Devices - [GET /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/get) — Get Devices - [DELETE /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/delete) — Delete Devices - [PATCH /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/update) — Update Devices - [Apps](/api-reference/unified-mdm-api/apps) - [GET /unified/mdm/apps](/api-reference/unified-mdm-api/apps/list) — List Apps - [DELETE /unified/mdm/apps/{id}](/api-reference/unified-mdm-api/apps/delete) — Delete Apps - [GET /unified/mdm/apps/{id}](/api-reference/unified-mdm-api/apps/get) — Get Apps - [Users](/api-reference/unified-mdm-api/users) - [GET /unified/mdm/users](/api-reference/unified-mdm-api/users/list) — List Users - [POST /unified/mdm/users](/api-reference/unified-mdm-api/users/create) — Create Users - [GET /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/get) — Get Users - [DELETE /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/delete) — Delete Users - [PATCH /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/update) — Update Users - [Organizations](/api-reference/unified-mdm-api/organizations) - [GET /unified/mdm/organizations](/api-reference/unified-mdm-api/organizations/list) — List Organizations - [POST /unified/mdm/organizations](/api-reference/unified-mdm-api/organizations/create) — Create Organizations - [GET /unified/mdm/organizations/{id}](/api-reference/unified-mdm-api/organizations/get) — Get Organizations - [PATCH /unified/mdm/organizations/{id}](/api-reference/unified-mdm-api/organizations/update) — Update Organizations --- # Devices Object > Source: https://truto.one/docs/api-reference/unified-mdm-api/devices/ Schema for the `Devices` resource in **Unified MDM API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the device - **`name`** _(string)_ The display name of the device - **`hostname`** _(string)_ The host/system name of the device - **`dns_name`** _(string)_ The DNS name of the device - **`netbios_name`** _(string)_ The NetBIOS name of the device (Windows) - **`type`** _(string)_ The type/category of the device Allowed: `workstation`, `server`, `mobile`, `tablet`, `laptop`, `desktop`, `virtual_machine`, `other` - **`is_corporate_owned`** _(boolean)_ Whether the device is corporate-owned (as opposed to personally-owned/BYOD) - **`platform`** _(string)_ The platform family of the device Allowed: `windows`, `macos`, `linux`, `ios`, `ipados`, `android`, `chromeos`, `unknown` - **`model`** _(string)_ The hardware model of the device - **`manufacturer`** _(string)_ The hardware manufacturer of the device - **`serial_number`** _(string)_ The serial number of the device - **`asset_tag`** _(string)_ The asset tag / inventory tag of the device - **`os_name`** _(string)_ The operating system name - **`os_version`** _(string)_ The operating system version - **`os_build`** _(string)_ The operating system build identifier - **`os_version_extra`** _(string)_ Additional operating system version information - **`disk_encryption`** _(boolean)_ Whether the disk encryption is enabled on the device - **`firewall_enabled`** _(boolean)_ Whether the host firewall is enabled on the device - **`mdm_enabled`** _(boolean)_ Whether MDM management is enabled on the device - **`agent_installed`** _(boolean)_ Whether a management agent is installed - **`agent_version`** _(string)_ The management agent version - **`enrollment_status`** _(string)_ Enrollment state of the device in the provider Allowed: `enrolled`, `pending`, `removed`, `missing`, `unknown` - **`approval_status`** _(string)_ Approval state if the provider requires approval Allowed: `approved`, `pending`, `rejected`, `unknown` - **`is_offline`** _(boolean)_ Whether the device is currently offline - **`first_enrolled_at`** _(string)_ The date and time the device was first enrolled - **`last_enrolled_at`** _(string)_ The date and time the device was most recently enrolled - **`last_scan_at`** _(string)_ The date and time the device was last scanned for vulnerabilities or security posture signals, when supported by the underlying product - **`last_activity_at`** _(string)_ The date and time of the last recorded activity for the device - **`organization`** _(object)_ The organization/account the device belongs to - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`owner`** _(object)_ The assigned owner of the device - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`policy`** _(object)_ The applied policy / blueprint - **`id`** _(string)_ The unique identifier for a policy - **`name`** _(string)_ The name of the policy - **`edr_installed`** _(boolean)_ Whether an endpoint detection and response (EDR) agent is installed or detected on the device - **`edr_status`** _(string)_ The health/status of the EDR agent on the device, when available from the underlying product Allowed: `healthy`, `unhealthy`, `degraded`, `unknown` - **`critical_vuln_count`** _(integer)_ The number of critical severity vulnerabilities detected on the device - **`high_vuln_count`** _(integer)_ The number of high severity vulnerabilities detected on the device - **`patch_status`** _(string)_ The patch compliance status of the device, based on signals available in the underlying product Allowed: `up_to_date`, `updates_available`, `unknown` - **`maintenance_status`** _(string)_ The maintenance status Allowed: `none`, `pending`, `active`, `completed`, `unknown` - **`maintenance_start_at`** _(string)_ The date and time maintenance starts - **`maintenance_end_at`** _(string)_ The date and time maintenance ends - **`maintenance_reason`** _(string)_ The maintenance reason message - **`warranty_start_at`** _(string)_ The date and time warranty starts - **`warranty_end_at`** _(string)_ The date and time warranty ends - **`warranty_fulfillment_at`** _(string)_ The manufacturer fulfillment date - **`backup_last_success_at`** _(string)_ The date and time the last backup succeeded - **`backup_last_failure_at`** _(string)_ The date and time the last backup failed - **`backup_total_bytes`** _(number)_ Total backup usage in bytes - **`public_ip`** _(string)_ The public IP address of the device - **`ip_addresses`** _(array)_ The private IP addresses of the device - **`mac_addresses`** _(array)_ The MAC addresses of the device - **`tags`** _(array)_ The device's tags - **`id`** _(string)_ The tag's unique identifier - **`name`** _(string)_ The tag's name - **`notes`** _(array)_ Notes attached to the device - **`id`** _(string, required)_ The note's unique identifier - **`title`** _(string)_ The note's title - **`owner`** _(object)_ The note's owner - **`id`** _(string)_ The note's owner's unique identifier - **`content`** _(string)_ The note's content - **`custom_fields`** _(object)_ Provider or customer specific fields mapped into a flexible key-value object - **`created_at`** _(string)_ The date and time the device record was created - **`updated_at`** _(string)_ The date and time the device record was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/mdm/devices](/api-reference/unified-mdm-api/devices/list) — List Devices - [POST /unified/mdm/devices](/api-reference/unified-mdm-api/devices/create) — Create Devices - [GET /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/get) — Get Devices - [DELETE /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/delete) — Delete Devices - [PATCH /unified/mdm/devices/{id}](/api-reference/unified-mdm-api/devices/update) — Update Devices --- # Apps Object > Source: https://truto.one/docs/api-reference/unified-mdm-api/apps/ Schema for the `Apps` resource in **Unified MDM API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the installed software record - **`source_id`** _(string)_ The identifier of the installed software record in the underlying product - **`name`** _(string)_ The name of the software/application - **`version`** _(string)_ The installed version of the software/application - **`publisher`** _(string)_ The publisher or vendor of the software/application - **`app_id`** _(string)_ A platform-specific application identifier. Examples: bundle identifier (macOS/iOS), package name (Android/Linux), product code or app ID (Windows), depending on the underlying product. - **`app_id_type`** _(string)_ The type of application identifier provided in app_id Allowed: `bundle_id`, `package_name`, `product_code`, `app_id`, `unknown` - **`platform`** _(string)_ The platform family of the discovered/installed application Allowed: `windows`, `macos`, `linux`, `ios`, `ipados`, `android`, `chromeos`, `unknown` - **`install_state`** _(string)_ The installation state of the software on the device, when available from the underlying product Allowed: `installed`, `pending`, `failed`, `unknown` - **`is_managed`** _(boolean)_ Whether the software is managed/deployed by the MDM/RMM product (as opposed to discovered/unmanaged), when available - **`is_system_app`** _(boolean)_ Whether the software is a system/built-in application, when available - **`installed_at`** _(string)_ The date and time the software was installed, when available - **`last_seen_at`** _(string)_ The date and time the software was last observed on the device, when available - **`install_path`** _(string)_ The install path of the software, when available - **`size_bytes`** _(integer)_ The installed size of the software in bytes, when available - **`device`** _(object)_ The device this software record is associated with - **`id`** _(string, required)_ The unique identifier for a device - **`tags`** _(array)_ Tags/labels associated with the installed software record - **`created_at`** _(string)_ The date and time the installed software record was created - **`updated_at`** _(string)_ The date and time the installed software record was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/mdm/apps](/api-reference/unified-mdm-api/apps/list) — List Apps - [DELETE /unified/mdm/apps/{id}](/api-reference/unified-mdm-api/apps/delete) — Delete Apps - [GET /unified/mdm/apps/{id}](/api-reference/unified-mdm-api/apps/get) — Get Apps --- # Users Object > Source: https://truto.one/docs/api-reference/unified-mdm-api/users/ Schema for the `Users` resource in **Unified MDM API**. ## Properties - **`id`** _(string, required)_ The user's unique identifier - **`name`** _(string, required)_ The user's name - **`first_name`** _(string)_ The user's first name - **`last_name`** _(string)_ The user's last name - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`organization`** _(object)_ The organization/account the device belongs to - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`is_active`** _(boolean)_ Whether the user is active or not - **`avatar`** _(string)_ The URL of the user's avatar - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/mdm/users](/api-reference/unified-mdm-api/users/list) — List Users - [POST /unified/mdm/users](/api-reference/unified-mdm-api/users/create) — Create Users - [GET /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/get) — Get Users - [DELETE /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/delete) — Delete Users - [PATCH /unified/mdm/users/{id}](/api-reference/unified-mdm-api/users/update) — Update Users --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-mdm-api/organizations/ Schema for the `Organizations` resource in **Unified MDM API**. ## Properties - **`id`** _(string, required)_ The ID of the organization - **`name`** _(string)_ The name of the organization - **`created_at`** _(string)_ The date and time the organization was created - **`updated_at`** _(string)_ The date and time the organization was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/mdm/organizations](/api-reference/unified-mdm-api/organizations/list) — List Organizations - [POST /unified/mdm/organizations](/api-reference/unified-mdm-api/organizations/create) — Create Organizations - [GET /unified/mdm/organizations/{id}](/api-reference/unified-mdm-api/organizations/get) — Get Organizations - [PATCH /unified/mdm/organizations/{id}](/api-reference/unified-mdm-api/organizations/update) — Update Organizations --- # Unified Payment Gateway API > Source: https://truto.one/docs/api-reference/unified-payment-gateway-api/ Base URL: `https://api.truto.one/unified/payment-gateway` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Payments](/api-reference/unified-payment-gateway-api/payments) - [GET /unified/payment-gateway/payments/{id}](/api-reference/unified-payment-gateway-api/payments/get) — Get Payments - [GET /unified/payment-gateway/payments](/api-reference/unified-payment-gateway-api/payments/list) — List Payments - [Customers](/api-reference/unified-payment-gateway-api/customers) - [GET /unified/payment-gateway/customers/{id}](/api-reference/unified-payment-gateway-api/customers/get) — Get Customers - [GET /unified/payment-gateway/customers](/api-reference/unified-payment-gateway-api/customers/list) — List Customers --- # Payments Object > Source: https://truto.one/docs/api-reference/unified-payment-gateway-api/payments/ Schema for the `Payments` resource in **Unified Payment Gateway API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the payment - **`amount`** _(string)_ Amount of the payment - **`currency`** _(string)_ Currency of the payment - **`transaction_fee`** _(string)_ Transaction fee on a payment - **`refund_amount`** _(string)_ Refund amount of the payment - **`status`** _(string)_ Status of the payment. In case there is no clear mapping, the raw status is passed. Allowed: `pending`, `authorized`, `paid`, `partial`, `refunded`, `voided`, `cancelled`, `unknown` - **`customer`** _(object)_ - **`id`** _(string)_ Unique identifier for the customer - **`name`** _(string)_ Name of the customer - **`email`** _(string)_ Email of the customer - **`phone`** _(string)_ Phone number of the customer - **`description`** _(string)_ Description of the payment - **`payment_method`** _(object)_ - **`method`** _(string)_ Method of payment - **`id`** _(string)_ Unique identifier for the payment method - **`created_at`** _(string)_ Date and time when the payment was created - **`expires_on`** _(string)_ Date and time when the payment expires - **`reference_id`** _(string)_ Reference ID of the payment. This can be used to lookup payments in the system. - **`order_id`** _(string)_ Unique identifier for the order related to this payment. - **`metadata`** _(object)_ - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/payment-gateway/payments/{id}](/api-reference/unified-payment-gateway-api/payments/get) — Get Payments - [GET /unified/payment-gateway/payments](/api-reference/unified-payment-gateway-api/payments/list) — List Payments --- # Customers Object > Source: https://truto.one/docs/api-reference/unified-payment-gateway-api/customers/ Schema for the `Customers` resource in **Unified Payment Gateway API**. ## Properties - **`id`** _(string)_ Unique identifier for the customer - **`name`** _(string)_ Name of the customer - **`email`** _(string)_ Email of the customer - **`phone`** _(string)_ Phone number of the customer - **`created_at`** _(string)_ Date and time when the customer was created - **`updated_at`** _(string)_ Date and time when the customer was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/payment-gateway/customers/{id}](/api-reference/unified-payment-gateway-api/customers/get) — Get Customers - [GET /unified/payment-gateway/customers](/api-reference/unified-payment-gateway-api/customers/list) — List Customers --- # Unified Search API > Source: https://truto.one/docs/api-reference/unified-search-api/ Base URL: `https://api.truto.one/unified/search` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Search](/api-reference/unified-search-api/search) - [GET /unified/search/search](/api-reference/unified-search-api/search/list) — List Search --- # Search Object > Source: https://truto.one/docs/api-reference/unified-search-api/search/ Schema for the `Search` resource in **Unified Search API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the entity. - **`title`** _(string)_ The title of the entity. - **`description`** _(string)_ The description of the entity. - **`type`** _(string)_ The type of the entity. - **`urls`** _(array)_ The urls of the entity. - **`url`** _(string)_ The url of the entity. - **`type`** _(string)_ The type of the url. Allowed: `truto_api`, `truto_download` - **`unified_model`** _(string)_ Present when type is truto_api or truto_download. Specifies the unified model of the url. - **`resource`** _(string)_ Present when type is truto_api or truto_download. Specifies the resource of the url. - **`file_name`** _(string)_ The name of file. This is available only when the type is truto_download. - **`mime_type`** _(string)_ The mime type of file. This is available only when the type is truto_download. - **`meta`** _(object)_ The meta data of the entity. - **`created_at`** _(string)_ The date when the entity was created. - **`updated_at`** _(string)_ The date when the entity was updated. - **`children`** _(array)_ The children of the entity. Follows the same schema as the parent. - **`related_resources`** _(array)_ - **`url`** _(string)_ The url of the entity. - **`type`** _(string)_ The type of the url. Allowed: `truto_api`, `truto_download` - **`unified_model`** _(string)_ Present when type is truto_api or truto_download. Specifies the unified model of the url. - **`resource`** _(string)_ Present when type is truto_api or truto_download. Specifies the resource of the url. - **`method`** _(string)_ The Truto method to call Allowed: `list`, `get` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/search/search](/api-reference/unified-search-api/search/list) — List Search --- # Unified Single Sign-On API > Source: https://truto.one/docs/api-reference/unified-single-sign-on-api/ Base URL: `https://api.truto.one/unified/sso` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Apps](/api-reference/unified-single-sign-on-api/apps) - [GET /unified/sso/apps](/api-reference/unified-single-sign-on-api/apps/list) — List Apps - [GET /unified/sso/apps/{id}](/api-reference/unified-single-sign-on-api/apps/get) — Get Apps - [PATCH /unified/sso/apps/{id}](/api-reference/unified-single-sign-on-api/apps/update) — Update Apps - [AppUsers](/api-reference/unified-single-sign-on-api/appusers) - [GET /unified/sso/app_users](/api-reference/unified-single-sign-on-api/appusers/list) — List App users - [GET /unified/sso/app_users/{id}](/api-reference/unified-single-sign-on-api/appusers/get) — Get App users - [DELETE /unified/sso/app_users/{id}](/api-reference/unified-single-sign-on-api/appusers/delete) — Delete App users --- # Apps Object > Source: https://truto.one/docs/api-reference/unified-single-sign-on-api/apps/ Schema for the `Apps` resource in **Unified Single Sign-On API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the application. - **`name`** _(string, required)_ The name of the application. - **`display_name`** _(string)_ The display name of the application. - **`status`** _(string)_ The status of the application. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `archived`, `deleted` - **`sign_on_mode`** _(string)_ The sign on mode of the application. - **`created_at`** _(string)_ The date and time the application was created. - **`updated_at`** _(string)_ The date and time the application was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/sso/apps](/api-reference/unified-single-sign-on-api/apps/list) — List Apps - [GET /unified/sso/apps/{id}](/api-reference/unified-single-sign-on-api/apps/get) — Get Apps - [PATCH /unified/sso/apps/{id}](/api-reference/unified-single-sign-on-api/apps/update) — Update Apps --- # AppUsers Object > Source: https://truto.one/docs/api-reference/unified-single-sign-on-api/appusers/ Schema for the `AppUsers` resource in **Unified Single Sign-On API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the user. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. - **`apps`** _(array)_ The applications the user is assigned to. - **`id`** _(string)_ The unique identifier of the application. - **`name`** _(string)_ The name of the application. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/sso/app_users](/api-reference/unified-single-sign-on-api/appusers/list) — List App users - [GET /unified/sso/app_users/{id}](/api-reference/unified-single-sign-on-api/appusers/get) — Get App users - [DELETE /unified/sso/app_users/{id}](/api-reference/unified-single-sign-on-api/appusers/delete) — Delete App users --- # Unified Subscription Management API > Source: https://truto.one/docs/api-reference/unified-subscription-management-api/ Base URL: `https://api.truto.one/unified/subscription-management` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Customers](/api-reference/unified-subscription-management-api/customers) - [GET /unified/subscription-management/customers](/api-reference/unified-subscription-management-api/customers/list) — List Customers - [GET /unified/subscription-management/customers/{id}](/api-reference/unified-subscription-management-api/customers/get) — Get Customers - [Invoices](/api-reference/unified-subscription-management-api/invoices) - [GET /unified/subscription-management/invoices](/api-reference/unified-subscription-management-api/invoices/list) — List Invoices - [GET /unified/subscription-management/invoices/{id}](/api-reference/unified-subscription-management-api/invoices/get) — Get Invoices - [Payments](/api-reference/unified-subscription-management-api/payments) - [GET /unified/subscription-management/payments](/api-reference/unified-subscription-management-api/payments/list) — List Payments - [GET /unified/subscription-management/payments/{id}](/api-reference/unified-subscription-management-api/payments/get) — Get Payments --- # Customers Object > Source: https://truto.one/docs/api-reference/unified-subscription-management-api/customers/ Schema for the `Customers` resource in **Unified Subscription Management API**. ## Properties - **`id`** _(string)_ Unique identifier for the customer - **`first_name`** _(string)_ The first name of the customer - **`last_name`** _(string)_ The last name of the customer - **`name`** _(string)_ Name of the customer - **`email`** _(string)_ Email of the customer - **`phone`** _(string)_ Phone number of the customer - **`created_at`** _(string)_ Date and time when the customer was created - **`updated_at`** _(string)_ Date and time when the customer was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/subscription-management/customers](/api-reference/unified-subscription-management-api/customers/list) — List Customers - [GET /unified/subscription-management/customers/{id}](/api-reference/unified-subscription-management-api/customers/get) — Get Customers --- # Invoices Object > Source: https://truto.one/docs/api-reference/unified-subscription-management-api/invoices/ Schema for the `Invoices` resource in **Unified Subscription Management API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the invoice - **`customer`** _(object)_ - **`id`** _(string)_ Unique identifier for the customer - **`name`** _(string)_ Name of the customer - **`email`** _(string)_ Email of the customer - **`phone`** _(string)_ Phone number of the customer - **`created_at`** _(string)_ Date and time when the customer was created - **`updated_at`** _(string)_ Date and time when the customer was last updated - **`subscription_id`** _(string)_ Unique identifier for the subscription associated with the invoice - **`is_recurring`** _(boolean)_ Whether the invoice is recurring or not - **`status`** _(string)_ Status of the invoice. In case there is no clear mapping, the raw status is passed. Allowed: `pending`, `paid`, `failed`, `cancelled`, `refunded`, `draft` - **`issue_date`** _(string)_ Date of the invoice - **`due_date`** _(string)_ Due date of the invoice - **`paid_on_date`** _(string)_ Date when the invoice was paid or marked as paid - **`transaction_fee`** _(string)_ Transaction fee on a payment - **`number`** _(string)_ Invoice number - **`currency`** _(string)_ Currency of the invoice - **`exchange_rate`** _(number)_ Exchange rate of the currency of the invoice - **`total_discount`** _(string)_ Total discount applied to the invoice - **`sub_total`** _(string)_ Sub total of the invoice - **`total_tax_amount`** _(string)_ Total tax amount of the invoice - **`balance`** _(string)_ Balance amount to be paid - **`payments`** _(array)_ List of payments associated with the invoice - **`id`** _(string)_ Unique identifier for the payment - **`method`** _(string)_ Payment method used for the payment. In case there is no clear mapping, the raw payment method is passed. Allowed: `card`, `bank_transfer`, `cash`, `check`, `paypal`, `wallet`, `wire_transfer` - **`status`** _(string)_ Status of the payment. In case there is no clear mapping, the raw status is passed. Allowed: `pending`, `authorized`, `paid`, `partial`, `refunded`, `voided`, `cancelled`, `unknown` - **`amount`** _(string)_ Amount of the payment - **`currency`** _(string)_ Currency of the payment - **`exchange_rate`** _(number)_ Exchange rate of the currency of the payment - **`created_at`** _(string)_ Date and time when the payment was created - **`updated_at`** _(string)_ Date and time when the payment was last updated - **`line_items`** _(array)_ List of line items associated with the invoice - **`id`** _(string)_ The unique identifier for line item - **`name`** _(string)_ The name of the line item - **`description`** _(string)_ The description of the line item - **`item`** _(string)_ The ID of the item - **`quantity`** _(number)_ The quantity of the line item - **`unit_price`** _(string)_ The unit price of the line item - **`tax_rate`** _(string)_ The ID of the tax rate - **`tax_amount`** _(string)_ The tax amount of the line item - **`total_line_amount`** _(string)_ The total line amount of the line item. - **`type`** _(string)_ The type of the line item - **`currency`** _(string)_ The currency of the line item - **`exchange_rate`** _(number)_ The exchange rate of the currency for the line item - **`memo`** _(string)_ Memo of the invoice - **`created_at`** _(string)_ Date and time when the invoice was created - **`updated_at`** _(string)_ Date and time when the invoice was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/subscription-management/invoices](/api-reference/unified-subscription-management-api/invoices/list) — List Invoices - [GET /unified/subscription-management/invoices/{id}](/api-reference/unified-subscription-management-api/invoices/get) — Get Invoices --- # Payments Object > Source: https://truto.one/docs/api-reference/unified-subscription-management-api/payments/ Schema for the `Payments` resource in **Unified Subscription Management API**. ## Properties - **`id`** _(string)_ Unique identifier for the payment - **`method`** _(string)_ Payment method used for the payment. In case there is no clear mapping, the raw payment method is passed. Allowed: `card`, `bank_transfer`, `cash`, `check`, `paypal`, `wallet`, `wire_transfer` - **`status`** _(string)_ Status of the payment. In case there is no clear mapping, the raw status is passed. Allowed: `pending`, `authorized`, `paid`, `partial`, `refunded`, `voided`, `cancelled`, `unknown` - **`amount`** _(string)_ Amount of the payment - **`transaction_fee`** _(string)_ Transaction fee on a payment - **`refund_amount`** _(string)_ Refund amount of the payment - **`currency`** _(string)_ Currency of the payment - **`exchange_rate`** _(number)_ Exchange rate of the currency of the payment - **`invoice_id`** _(string)_ ID of the invoice the payment is for - **`created_at`** _(string)_ Date and time when the payment was created - **`updated_at`** _(string)_ Date and time when the payment was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/subscription-management/payments](/api-reference/unified-subscription-management-api/payments/list) — List Payments - [GET /unified/subscription-management/payments/{id}](/api-reference/unified-subscription-management-api/payments/get) — Get Payments --- # Unified Ticketing API > Source: https://truto.one/docs/api-reference/unified-ticketing-api/ Base URL: `https://api.truto.one/unified/ticketing` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Accounts](/api-reference/unified-ticketing-api/accounts) - [GET /unified/ticketing/accounts](/api-reference/unified-ticketing-api/accounts/list) — List Accounts - [POST /unified/ticketing/accounts](/api-reference/unified-ticketing-api/accounts/create) — Create Accounts - [GET /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/get) — Get Accounts - [DELETE /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/delete) — Delete Accounts - [PATCH /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/update) — Update Accounts - [Attachments](/api-reference/unified-ticketing-api/attachments) - [GET /unified/ticketing/attachments](/api-reference/unified-ticketing-api/attachments/list) — List Attachments - [POST /unified/ticketing/attachments](/api-reference/unified-ticketing-api/attachments/create) — Create Attachments - [GET /unified/ticketing/attachments/{id}](/api-reference/unified-ticketing-api/attachments/get) — Get Attachments - [PATCH /unified/ticketing/attachments/{id}](/api-reference/unified-ticketing-api/attachments/update) — Update Attachments - [POST /unified/ticketing/attachments/download](/api-reference/unified-ticketing-api/attachments/download) — Download Attachments - [POST /unified/ticketing/attachments/stage](/api-reference/unified-ticketing-api/attachments/stage) — Stage Attachments - [Collections](/api-reference/unified-ticketing-api/collections) - [GET /unified/ticketing/collections](/api-reference/unified-ticketing-api/collections/list) — List Collections - [POST /unified/ticketing/collections](/api-reference/unified-ticketing-api/collections/create) — Create Collections - [GET /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/get) — Get Collections - [DELETE /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/delete) — Delete Collections - [PATCH /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/update) — Update Collections - [Comments](/api-reference/unified-ticketing-api/comments) - [GET /unified/ticketing/comments](/api-reference/unified-ticketing-api/comments/list) — List Comments - [POST /unified/ticketing/comments](/api-reference/unified-ticketing-api/comments/create) — Create Comments - [GET /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/get) — Get Comments - [PATCH /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/update) — Update Comments - [DELETE /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/delete) — Delete Comments - [Contacts](/api-reference/unified-ticketing-api/contacts) - [GET /unified/ticketing/contacts](/api-reference/unified-ticketing-api/contacts/list) — List Contacts - [POST /unified/ticketing/contacts](/api-reference/unified-ticketing-api/contacts/create) — Create Contacts - [GET /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/get) — Get Contacts - [PATCH /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/update) — Update Contacts - [DELETE /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/delete) — Delete Contacts - [Tags](/api-reference/unified-ticketing-api/tags) - [GET /unified/ticketing/tags](/api-reference/unified-ticketing-api/tags/list) — List Tags - [POST /unified/ticketing/tags](/api-reference/unified-ticketing-api/tags/create) — Create Tags - [GET /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/get) — Get Tags - [PATCH /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/update) — Update Tags - [DELETE /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/delete) — Delete Tags - [Teams](/api-reference/unified-ticketing-api/teams) - [GET /unified/ticketing/teams](/api-reference/unified-ticketing-api/teams/list) — List Teams - [POST /unified/ticketing/teams](/api-reference/unified-ticketing-api/teams/create) — Create Teams - [GET /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/get) — Get Teams - [DELETE /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/delete) — Delete Teams - [PATCH /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/update) — Update Teams - [Tickets](/api-reference/unified-ticketing-api/tickets) - [GET /unified/ticketing/tickets](/api-reference/unified-ticketing-api/tickets/list) — List Tickets - [POST /unified/ticketing/tickets](/api-reference/unified-ticketing-api/tickets/create) — Create Tickets - [GET /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/get) — Get Tickets - [PATCH /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/update) — Update Tickets - [DELETE /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/delete) — Delete Tickets - [POST /unified/ticketing/tickets/import](/api-reference/unified-ticketing-api/tickets/import) — Import Tickets - [TicketTypes](/api-reference/unified-ticketing-api/tickettypes) - [GET /unified/ticketing/ticket_types](/api-reference/unified-ticketing-api/tickettypes/list) — List Ticket types - [Fields](/api-reference/unified-ticketing-api/fields) - [GET /unified/ticketing/fields](/api-reference/unified-ticketing-api/fields/list) — List Fields - [POST /unified/ticketing/fields](/api-reference/unified-ticketing-api/fields/create) — Create Fields - [GET /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/get) — Get Fields - [PATCH /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/update) — Update Fields - [DELETE /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/delete) — Delete Fields - [TicketStatus](/api-reference/unified-ticketing-api/ticketstatus) - [GET /unified/ticketing/ticket_status](/api-reference/unified-ticketing-api/ticketstatus/list) — List Ticket status - [TicketPriorities](/api-reference/unified-ticketing-api/ticketpriorities) - [GET /unified/ticketing/ticket_priorities](/api-reference/unified-ticketing-api/ticketpriorities/list) — List Ticket priorities - [Users](/api-reference/unified-ticketing-api/users) - [GET /unified/ticketing/users](/api-reference/unified-ticketing-api/users/list) — List Users - [POST /unified/ticketing/users](/api-reference/unified-ticketing-api/users/create) — Create Users - [GET /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/get) — Get Users - [DELETE /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/delete) — Delete Users - [PATCH /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/update) — Update Users - [Workspaces](/api-reference/unified-ticketing-api/workspaces) - [GET /unified/ticketing/workspaces](/api-reference/unified-ticketing-api/workspaces/list) — List Workspaces - [POST /unified/ticketing/workspaces](/api-reference/unified-ticketing-api/workspaces/create) — Create Workspaces - [GET /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/get) — Get Workspaces - [PATCH /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/update) — Update Workspaces - [DELETE /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/delete) — Delete Workspaces - [TaskLists](/api-reference/unified-ticketing-api/tasklists) - [GET /unified/ticketing/task_lists](/api-reference/unified-ticketing-api/tasklists/list) — List Task lists - [POST /unified/ticketing/task_lists](/api-reference/unified-ticketing-api/tasklists/create) — Create Task lists - [GET /unified/ticketing/task_lists/{id}](/api-reference/unified-ticketing-api/tasklists/get) — Get Task lists - [Tasks](/api-reference/unified-ticketing-api/tasks) - [GET /unified/ticketing/tasks](/api-reference/unified-ticketing-api/tasks/list) — List Tasks - [POST /unified/ticketing/tasks](/api-reference/unified-ticketing-api/tasks/create) — Create Tasks - [GET /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/get) — Get Tasks - [PATCH /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/update) — Update Tasks - [DELETE /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/delete) — Delete Tasks - [Organizations](/api-reference/unified-ticketing-api/organizations) - [GET /unified/ticketing/organizations](/api-reference/unified-ticketing-api/organizations/list) — List Organizations - [GET /unified/ticketing/organizations/{id}](/api-reference/unified-ticketing-api/organizations/get) — Get Organizations --- # Accounts Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/accounts/ Schema for the `Accounts` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for an account - **`name`** _(string)_ The name of the account - **`domains`** _(array)_ Domains associated with the account - **`updated_at`** _(string)_ The date and time of the account's last update - **`created_at`** _(string)_ The date and time of the account's creation - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/accounts](/api-reference/unified-ticketing-api/accounts/list) — List Accounts - [POST /unified/ticketing/accounts](/api-reference/unified-ticketing-api/accounts/create) — Create Accounts - [GET /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/get) — Get Accounts - [DELETE /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/delete) — Delete Accounts - [PATCH /unified/ticketing/accounts/{id}](/api-reference/unified-ticketing-api/accounts/update) — Update Accounts --- # Attachments Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/attachments/ Schema for the `Attachments` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string)_ The unique identifier for the attachment - **`file_name`** _(string)_ The attachment's name. - **`ticket_id`** _(string)_ The ticket id to which the attachment belongs - **`size`** _(number)_ The file size in bytes - **`file_url`** _(string)_ The URL to download the attachment - **`content_type`** _(string)_ The content type of the attachment - **`uploaded_by`** _(string)_ The user who uploaded the attachment - **`uploaded_by_type`** _(string)_ The type of the user who uploaded the attachment - **`created_at`** _(string)_ The time when the attachment was created - **`updated_at`** _(string)_ The time when the attachment was updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/attachments](/api-reference/unified-ticketing-api/attachments/list) — List Attachments - [POST /unified/ticketing/attachments](/api-reference/unified-ticketing-api/attachments/create) — Create Attachments - [GET /unified/ticketing/attachments/{id}](/api-reference/unified-ticketing-api/attachments/get) — Get Attachments - [PATCH /unified/ticketing/attachments/{id}](/api-reference/unified-ticketing-api/attachments/update) — Update Attachments - [POST /unified/ticketing/attachments/download](/api-reference/unified-ticketing-api/attachments/download) — Download Attachments - [POST /unified/ticketing/attachments/stage](/api-reference/unified-ticketing-api/attachments/stage) — Stage Attachments --- # Collections Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/collections/ Schema for the `Collections` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a collection - **`name`** _(string)_ The name of the collection - **`description`** _(string)_ The description of the collection - **`type`** _(string)_ The type of the collection - **`parent_collection_id`** _(string)_ The parent collection id - **`urls`** _(array)_ The URLs of the collection - **`url`** _(string)_ The URL of the collection - **`workspace`** _(object)_ - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`created_at`** _(string)_ The date and time when the collection was created - **`updated_at`** _(string)_ The date and time when the collection was updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`entity_type`** _(string)_ The type of entity that belongs to this collection Allowed: `contact`, `ticket` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/collections](/api-reference/unified-ticketing-api/collections/list) — List Collections - [POST /unified/ticketing/collections](/api-reference/unified-ticketing-api/collections/create) — Create Collections - [GET /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/get) — Get Collections - [DELETE /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/delete) — Delete Collections - [PATCH /unified/ticketing/collections/{id}](/api-reference/unified-ticketing-api/collections/update) — Update Collections --- # Comments Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/comments/ Schema for the `Comments` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a comment - **`author`** _(object)_ The id of the user or contact who created the comment - **`id`** _(string, required)_ The id of the user or contact who created the comment - **`name`** _(string)_ The name of the user or contact who created the comment - **`username`** _(string)_ The username of the user or contact who created the comment - **`type`** _(string, required)_ Type of the author Allowed: `user`, `contact`, `system` - **`receiver`** _(object)_ The id of the user or contact who is receiving the comment - **`id`** _(string, required)_ The id of the user or contact who receiving the comment - **`name`** _(string)_ The name of the user or contact who receiving the comment - **`type`** _(string, required)_ Type of the receiver Allowed: `user`, `contact`, `system` - **`body`** _(string)_ The body of the comment - **`html_body`** _(string)_ The body of the comment in HTML format - **`ticket`** _(object)_ The ticket to which the comment belongs - **`id`** _(string, required)_ The unique identifier for a ticket - **`attachments`** _(array)_ The attachments of the comment - **`id`** _(string)_ The unique identifier for the attachment - **`file_name`** _(string)_ The attachment's name. - **`file_url`** _(string)_ The URL to download the attachment - **`content_type`** _(string)_ The content type of the attachment - **`uploaded_by`** _(object)_ The user who uploaded the attachment - **`id`** _(string)_ The user who uploaded the attachment - **`name`** _(string)_ The user who uploaded the attachment - **`uploaded_by_type`** _(string)_ The type of the user who uploaded the attachment - **`created_at`** _(string)_ The time when the attachment was created - **`is_internal`** _(boolean)_ Whether the comment is internal. True for internal notes left by users. - **`is_private`** _(boolean)_ Whether the comment is private or not - **`channel`** _(object)_ The medium through which the comment was sent. - **`id`** _(string)_ The unique identifier for the channel - **`name`** _(string)_ The name of the channel - **`type`** _(string)_ The type of the channel - **`created_at`** _(string)_ The date and time when the comment was created - **`updated_at`** _(string)_ The date and time when the comment was updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/comments](/api-reference/unified-ticketing-api/comments/list) — List Comments - [POST /unified/ticketing/comments](/api-reference/unified-ticketing-api/comments/create) — Create Comments - [GET /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/get) — Get Comments - [PATCH /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/update) — Update Comments - [DELETE /unified/ticketing/comments/{id}](/api-reference/unified-ticketing-api/comments/delete) — Delete Comments --- # Contacts Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/contacts/ Schema for the `Contacts` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a contact - **`first_name`** _(string)_ The first name of the contact - **`last_name`** _(string)_ The last name of the contact - **`name`** _(string)_ The name of the contact - **`emails`** _(array)_ The emails of the contact - **`email`** _(string, required)_ The email of the contact - **`type`** _(string)_ The type of the email - **`phones`** _(array)_ The phone numbers of the contact - **`number`** _(string)_ The phone of the contact - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of the phone - **`details`** _(string)_ The details of the contact - **`account_id`** _(string)_ The account id of the contact - **`created_at`** _(string)_ The date the contact was created - **`updated_at`** _(string)_ The date the contact was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`custom_fields`** _(object)_ All the custom fields present on the contact - **`is_active`** _(boolean)_ Whether the contact is active or not - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/contacts](/api-reference/unified-ticketing-api/contacts/list) — List Contacts - [POST /unified/ticketing/contacts](/api-reference/unified-ticketing-api/contacts/create) — Create Contacts - [GET /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/get) — Get Contacts - [PATCH /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/update) — Update Contacts - [DELETE /unified/ticketing/contacts/{id}](/api-reference/unified-ticketing-api/contacts/delete) — Delete Contacts --- # Tags Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/tags/ Schema for the `Tags` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string)_ The unique identifier for a tag - **`name`** _(string)_ The name of the tag - **`color`** _(string)_ Color of the tag. In hex format. - **`workspace`** _(object)_ The workspace the tag belongs to - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`created_at`** _(string)_ The date the tag was created - **`updated_at`** _(string)_ The date the tag was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`status`** _(string)_ The status of the tag. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive` - **`parent`** _(object)_ The parent tag of this tag - **`id`** _(string)_ The unique identifier for the tag - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/tags](/api-reference/unified-ticketing-api/tags/list) — List Tags - [POST /unified/ticketing/tags](/api-reference/unified-ticketing-api/tags/create) — Create Tags - [GET /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/get) — Get Tags - [PATCH /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/update) — Update Tags - [DELETE /unified/ticketing/tags/{id}](/api-reference/unified-ticketing-api/tags/delete) — Delete Tags --- # Teams Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/teams/ Schema for the `Teams` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a team - **`name`** _(string)_ The name of the team - **`description`** _(string)_ The description of the team - **`created_at`** _(string)_ The date the team was created - **`updated_at`** _(string)_ The date the team was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/teams](/api-reference/unified-ticketing-api/teams/list) — List Teams - [POST /unified/ticketing/teams](/api-reference/unified-ticketing-api/teams/create) — Create Teams - [GET /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/get) — Get Teams - [DELETE /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/delete) — Delete Teams - [PATCH /unified/ticketing/teams/{id}](/api-reference/unified-ticketing-api/teams/update) — Update Teams --- # Tickets Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/tickets/ Schema for the `Tickets` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a ticket - **`name`** _(string)_ The name of the ticket - **`number`** _(string)_ An optional ticket number maintained by the system. - **`assignees`** _(array)_ Users assigned to the ticket - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`emails`** _(array)_ The user's email addresses - **`email`** _(string, required)_ The user's email address - **`type`** _(string)_ The type of email address - **`phones`** _(array)_ The user's phone number - **`number`** _(string, required)_ The user's phone number - **`type`** _(string)_ The type of phone number - **`status`** _(object)_ The status of the ticket - **`id`** _(string)_ The unique identifier for a status - **`name`** _(string)_ The name of the status Allowed: `active`, `closed`, `open`, `pending`, `spam`, `resolved`, `archived`, `deleted`, `completed` - **`created_by`** _(object)_ User or contact who created the ticket - **`id`** _(string)_ The unique identifier for a user - **`name`** _(string)_ The name of the user - **`type`** _(string)_ The type of the user Allowed: `user`, `contact` - **`due_date`** _(string)_ Due date of the ticket - **`description`** _(string)_ Description of the ticket - **`workspace`** _(object)_ Workspace associated with the ticket - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspace - **`team`** _(object)_ Team associated with the ticket - **`id`** _(string)_ The unique identifier for a team - **`name`** _(string)_ The name of the team - **`collections`** _(array)_ Collections associated with the ticket - **`id`** _(string)_ The unique identifier for a collection - **`name`** _(string)_ The name of the collection - **`type`** _(string)_ The type of the collection - **`conversations`** _(array)_ Conversations associated with the ticket - **`id`** _(string)_ The unique identifier for a conversation - **`name`** _(string)_ The name of the conversation - **`type`** _(string)_ The type of the conversation - **`ticket_type`** _(object)_ Type of the ticket - **`id`** _(string)_ The unique identifier for a ticket type - **`name`** _(string)_ The name of the ticket type - **`contact`** _(object)_ Contact associated with the ticket - **`id`** _(string)_ The unique identifier for a contact - **`first_name`** _(string)_ The first name of the contact - **`last_name`** _(string)_ The last name of the contact - **`name`** _(string)_ The name of the contact - **`emails`** _(array)_ The emails of the contact - **`email`** _(string, required)_ The email of the contact - **`type`** _(string)_ The type of the email - **`phones`** _(array)_ The contact's phone number - **`number`** _(string, required)_ The contact's phone number - **`type`** _(string)_ The type of phone number - **`additional_contacts`** _(array)_ Additional Contacts associated with the ticket - **`id`** _(string)_ The unique identifier for a contact - **`first_name`** _(string)_ The first name of the contact - **`last_name`** _(string)_ The last name of the contact - **`name`** _(string)_ The name of the contact - **`emails`** _(array)_ The emails of the contact - **`email`** _(string, required)_ The email of the contact - **`type`** _(string)_ The type of the email - **`phones`** _(array)_ The contact's phone number - **`number`** _(string, required)_ The contact's phone number - **`type`** _(string)_ The type of phone number - **`account`** _(object)_ Account associated with the ticket - **`id`** _(string)_ The unique identifier for a contact - **`parent_ticket`** _(object)_ Parent ticket associated with the ticket - **`id`** _(string)_ The unique identifier for a ticket - **`name`** _(string)_ The name of the ticket - **`attachments`** _(array)_ Attachments associated with the ticket - **`id`** _(string)_ The unique identifier for an attachment - **`file_name`** _(string)_ The name of the attachment - **`file_url`** _(string)_ The url of the attachment - **`tags`** _(array)_ Tags associated with the ticket - **`id`** _(string)_ The unique identifier for a tag - **`name`** _(string)_ The name of the tag - **`created_at`** _(string)_ Time at which the ticket was created - **`updated_at`** _(string)_ Time at which the ticket was last updated - **`completed_at`** _(string)_ Time at which the ticket was completed - **`ticket_url`** _(string)_ URL of the ticket - **`priority`** _(object)_ Priority of the ticket - **`id`** _(string)_ The unique identifier for a priority - **`name`** _(string)_ The name of the priority - **`languages`** _(array)_ Languages of the ticket - **`is_unread`** _(boolean)_ Whether the ticket is unread - **`source`** _(object)_ The source of the ticket - **`id`** _(string)_ The unique identifier for a source - **`name`** _(string)_ The name of the source - **`custom_fields`** _(object)_ All the custom fields present on the ticket - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/tickets](/api-reference/unified-ticketing-api/tickets/list) — List Tickets - [POST /unified/ticketing/tickets](/api-reference/unified-ticketing-api/tickets/create) — Create Tickets - [GET /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/get) — Get Tickets - [PATCH /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/update) — Update Tickets - [DELETE /unified/ticketing/tickets/{id}](/api-reference/unified-ticketing-api/tickets/delete) — Delete Tickets - [POST /unified/ticketing/tickets/import](/api-reference/unified-ticketing-api/tickets/import) — Import Tickets --- # TicketTypes Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/tickettypes/ Schema for the `TicketTypes` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string)_ The ticket type's unique identifier - **`name`** _(string)_ The ticket type's name - **`description`** _(string)_ The ticket type's description - **`project`** _(string)_ The ticket type's project - **`created_at`** _(string)_ The date and time the ticket type was created - **`updated_at`** _(string)_ The date and time the ticket type was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/ticket_types](/api-reference/unified-ticketing-api/tickettypes/list) — List Ticket types --- # Fields Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/fields/ Schema for the `Fields` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string)_ The field's unique identifier - **`name`** _(string)_ The field's name. This is the name of the property in the entity. - **`label`** _(string)_ The field's label - **`description`** _(string)_ The field's description - **`type`** _(string)_ The field's type. If no clear mapping exists, then raw value is returned. Allowed: `string`, `text`, `rich_text`, `number`, `boolean`, `date`, `datetime`, `time`, `enum`, `array`, `file` - **`format`** _(string)_ The field's format. - **`is_hidden`** _(boolean)_ Whether the field is hidden - **`is_unique`** _(boolean)_ Whether the field is unique - **`is_required`** _(boolean)_ Whether the field is required - **`options`** _(array)_ The field's options - **`label`** _(string)_ The option's label - **`value`** _(string)_ The option's value - **`description`** _(string)_ The option's description - **`is_hidden`** _(boolean)_ Whether the option is hidden - **`is_user_defined`** _(boolean)_ Whether the field is user defined - **`entity_type`** _(string)_ The entity type the field belongs to Allowed: `ticket_type`, `ticket`, `collection`, `user` - **`entity_id`** _(string)_ The unique identifier for the entity the field belongs to - **`created_at`** _(string)_ The date and time of the field's creation - **`updated_at`** _(string)_ The date and time of the field's last update - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`applicable_in`** _(string)_ The context in which the field is applicable Allowed: `collection`, `workspace`, `ticket` - **`applicable_for`** _(string)_ The unique identifier of the applicable - **`ticket_type`** _(string)_ The ticket_type's unique identifier - **`status`** _(string)_ The status of the field Allowed: `active`, `archived` - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/fields](/api-reference/unified-ticketing-api/fields/list) — List Fields - [POST /unified/ticketing/fields](/api-reference/unified-ticketing-api/fields/create) — Create Fields - [GET /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/get) — Get Fields - [PATCH /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/update) — Update Fields - [DELETE /unified/ticketing/fields/{id}](/api-reference/unified-ticketing-api/fields/delete) — Delete Fields --- # TicketStatus Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/ticketstatus/ Schema for the `TicketStatus` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The status's unique identifier - **`name`** _(string)_ The status's name - **`description`** _(string)_ The status's description - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/ticket_status](/api-reference/unified-ticketing-api/ticketstatus/list) — List Ticket status --- # TicketPriorities Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/ticketpriorities/ Schema for the `TicketPriorities` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The priority's unique identifier - **`name`** _(string)_ The priority's name - **`description`** _(string)_ The priority's description - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/ticket_priorities](/api-reference/unified-ticketing-api/ticketpriorities/list) — List Ticket priorities --- # Users Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/users/ Schema for the `Users` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The user's unique identifier - **`name`** _(string, required)_ The user's name - **`first_name`** _(string)_ The user's first name - **`last_name`** _(string)_ The user's last name - **`username`** _(string)_ The user's username - **`emails`** _(array)_ The user's email addresses - **`email`** _(string, required)_ The user's email address - **`type`** _(string)_ The type of email address - **`is_active`** _(boolean)_ Whether the user is active or not - **`team_ids`** _(array)_ The IDs of the teams the user is a member of - **`avatar`** _(string)_ The URL of the user's avatar - **`roles`** _(array)_ The roles the user has - **`id`** _(string)_ The role's unique identifier - **`name`** _(string)_ The role's name - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/users](/api-reference/unified-ticketing-api/users/list) — List Users - [POST /unified/ticketing/users](/api-reference/unified-ticketing-api/users/create) — Create Users - [GET /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/get) — Get Users - [DELETE /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/delete) — Delete Users - [PATCH /unified/ticketing/users/{id}](/api-reference/unified-ticketing-api/users/update) — Update Users --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/workspaces/ Schema for the `Workspaces` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string)_ The ID of the workspace - **`name`** _(string)_ The name of the workspace - **`status`** _(string)_ The status of the workspace Allowed: `active`, `inactive` - **`description`** _(string)_ The description of the workspace - **`created_at`** _(string)_ The date and time the workspace was created - **`updated_at`** _(string)_ The date and time the workspace was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/workspaces](/api-reference/unified-ticketing-api/workspaces/list) — List Workspaces - [POST /unified/ticketing/workspaces](/api-reference/unified-ticketing-api/workspaces/create) — Create Workspaces - [GET /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/get) — Get Workspaces - [PATCH /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/update) — Update Workspaces - [DELETE /unified/ticketing/workspaces/{id}](/api-reference/unified-ticketing-api/workspaces/delete) — Delete Workspaces --- # TaskLists Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/tasklists/ Schema for the `TaskLists` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the task list - **`name`** _(string)_ The name of the task list - **`ticket`** _(object)_ The ticket the task list is associated with - **`id`** _(string)_ The unique identifier for the ticket - **`tasks`** _(array)_ The tasks in the task list - **`id`** _(string)_ The unique identifier for the task - **`name`** _(string)_ The name of the task - **`created_at`** _(string)_ The date and time the task list was created - **`updated_at`** _(string)_ The date and time the task list was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/task_lists](/api-reference/unified-ticketing-api/tasklists/list) — List Task lists - [POST /unified/ticketing/task_lists](/api-reference/unified-ticketing-api/tasklists/create) — Create Task lists - [GET /unified/ticketing/task_lists/{id}](/api-reference/unified-ticketing-api/tasklists/get) — Get Task lists --- # Tasks Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/tasks/ Schema for the `Tasks` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The unique identifier for the task - **`name`** _(string)_ The name of the task - **`assignees`** _(array)_ The users assigned to the task - **`id`** _(string)_ The unique identifier for the user - **`name`** _(string)_ The name of the user - **`description`** _(string)_ The description of the task - **`due_date`** _(string)_ The due date of the task - **`ticket`** _(object)_ The ticket the task is associated with - **`id`** _(string)_ The unique identifier for the ticket - **`task_list`** _(object)_ The task list the task is associated with - **`id`** _(string)_ The unique identifier for the task list - **`status`** _(object)_ The status of the task - **`id`** _(string)_ The unique identifier for the status - **`name`** _(string)_ The name of the status - **`created_at`** _(string)_ The date and time the task was created - **`updated_at`** _(string)_ The date and time the task was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/tasks](/api-reference/unified-ticketing-api/tasks/list) — List Tasks - [POST /unified/ticketing/tasks](/api-reference/unified-ticketing-api/tasks/create) — Create Tasks - [GET /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/get) — Get Tasks - [PATCH /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/update) — Update Tasks - [DELETE /unified/ticketing/tasks/{id}](/api-reference/unified-ticketing-api/tasks/delete) — Delete Tasks --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-ticketing-api/organizations/ Schema for the `Organizations` resource in **Unified Ticketing API**. ## Properties - **`id`** _(string, required)_ The ID of the organization - **`name`** _(string)_ The name of the organization - **`created_at`** _(string)_ The date and time the organization was created - **`updated_at`** _(string)_ The date and time the organization was last updated - **`etag`** _(string)_ The unique identifier for the specific version of the resource. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/ticketing/organizations](/api-reference/unified-ticketing-api/organizations/list) — List Organizations - [GET /unified/ticketing/organizations/{id}](/api-reference/unified-ticketing-api/organizations/get) — Get Organizations --- # Unified Usage Metering API > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/ Base URL: `https://api.truto.one/unified/usage-metering` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Products](/api-reference/unified-usage-metering-api/products) - [GET /unified/usage-metering/products](/api-reference/unified-usage-metering-api/products/list) — List Products - [Usage](/api-reference/unified-usage-metering-api/usage) - [GET /unified/usage-metering/usage](/api-reference/unified-usage-metering-api/usage/list) — List Usage - [Organizations](/api-reference/unified-usage-metering-api/organizations) - [GET /unified/usage-metering/organizations/{id}](/api-reference/unified-usage-metering-api/organizations/get) — Get Organizations - [GET /unified/usage-metering/organizations](/api-reference/unified-usage-metering-api/organizations/list) — List Organizations - [Workspaces](/api-reference/unified-usage-metering-api/workspaces) - [GET /unified/usage-metering/workspaces](/api-reference/unified-usage-metering-api/workspaces/list) — List Workspaces - [GET /unified/usage-metering/workspaces/{id}](/api-reference/unified-usage-metering-api/workspaces/get) — Get Workspaces - [DELETE /unified/usage-metering/workspaces/{id}](/api-reference/unified-usage-metering-api/workspaces/delete) — Delete Workspaces - [Users](/api-reference/unified-usage-metering-api/users) - [GET /unified/usage-metering/users](/api-reference/unified-usage-metering-api/users/list) — List Users - [GET /unified/usage-metering/users/{id}](/api-reference/unified-usage-metering-api/users/get) — Get Users - [DELETE /unified/usage-metering/users/{id}](/api-reference/unified-usage-metering-api/users/delete) — Delete Users --- # Products Object > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/products/ Schema for the `Products` resource in **Unified Usage Metering API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the product. - **`name`** _(string)_ Name of the product. - **`description`** _(string)_ Description for the product. - **`created_at`** _(string)_ Date and time when the product was created. - **`updated_at`** _(string)_ Date and time when the product was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/usage-metering/products](/api-reference/unified-usage-metering-api/products/list) — List Products --- # Usage Object > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/usage/ Schema for the `Usage` resource in **Unified Usage Metering API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the usage. - **`product`** _(object)_ The product associated with the usage. - **`id`** _(string, required)_ Unique identifier for the product. - **`name`** _(string)_ Name of the product. - **`metric_name`** _(string)_ Name of the metric being charged for - **`resources`** _(array)_ - **`id`** _(string)_ Unique identifier for the resource. - **`name`** _(string)_ Name of the resource. - **`workspace`** _(object)_ The resource is present in this workspace. - **`id`** _(string)_ Unique identifier for the workspace. - **`name`** _(string)_ Name of the workspace. - **`organization`** _(object)_ The organization associated with the usage. - **`id`** _(string, required)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`user`** _(object)_ User attributed to the usage row when the vendor exposes a user pivot. Omit for org-level or aggregated rows. - **`id`** _(string)_ Unique identifier for the user in the source application. - **`email`** _(string)_ Primary email of the user. - **`name`** _(string)_ Display name of the user. - **`model`** _(object)_ AI model for the row when applicable. Omit for non-AI vendors. - **`id`** _(string)_ Model identifier (e.g. claude-sonnet-4-6, gpt-5). - **`provider`** _(string)_ Provider hosting the model (e.g. anthropic, openai, cursor). - **`charges`** _(array)_ The amounts charged for the usage. - **`amount`** _(number)_ The amount charged for the usage. - **`currency`** _(string)_ The currency in which the charge is made. - **`type`** _(string)_ The type of charge. Allowed: `total`, `net`, `on_demand`, `committed`, `included`, `usage_based`, `discount`, `tax`, `credit`, `platform_fee` - **`usage`** _(object)_ The usage data for the product. - **`quantity`** _(number)_ Generic quantity (e.g. Confluent). - **`unit`** _(string)_ Unit for quantity (e.g. GB, request, hour). - **`requests`** _(object)_ - **`total`** _(number)_ - **`chat`** _(number)_ - **`agent`** _(number)_ - **`composer`** _(number)_ - **`cmdk`** _(number)_ Inline edit (e.g. Cursor Cmd+K). - **`tab_shown`** _(number)_ - **`tab_accepted`** _(number)_ - **`api_key`** _(number)_ - **`included`** _(number)_ - **`usage_based`** _(number)_ - **`bugbot`** _(number)_ - **`sessions`** _(object)_ - **`distinct`** _(number)_ - **`dispatch_turns`** _(number)_ Cowork / background dispatch turns. - **`conversations`** _(object)_ - **`distinct`** _(number)_ - **`message_count`** _(number)_ - **`thinking_message_count`** _(number)_ - **`shared_viewed_count`** _(number)_ - **`turn_count`** _(number)_ - **`thread_count`** _(number)_ - **`code`** _(object)_ - **`lines_added`** _(number)_ - **`lines_removed`** _(number)_ - **`lines_accepted_added`** _(number)_ - **`lines_accepted_removed`** _(number)_ - **`applies`** _(number)_ - **`accepts`** _(number)_ - **`rejects`** _(number)_ - **`commits`** _(number)_ - **`pull_requests`** _(number)_ - **`tool_actions`** _(object)_ Per-tool accept/reject counts (e.g. Claude Code). - **`file_extensions`** _(object)_ - **`apply_most_used`** _(string)_ - **`tab_most_used`** _(string)_ - **`tokens`** _(object)_ - **`input`** _(number)_ - **`output`** _(number)_ - **`cache_read`** _(number)_ - **`cache_write`** _(number)_ - **`cache_write_ephemeral_5m`** _(number)_ - **`cache_write_ephemeral_1h`** _(number)_ - **`total`** _(number)_ - **`tools`** _(object)_ - **`web_search_count`** _(number)_ - **`connectors_used_count`** _(number)_ - **`distinct_connectors_used_count`** _(number)_ - **`skills_used_count`** _(number)_ - **`distinct_skills_used_count`** _(number)_ - **`action_count`** _(number)_ - **`activity`** _(object)_ - **`is_active`** _(boolean)_ - **`max_mode`** _(boolean)_ - **`client_version`** _(string)_ - **`start_date`** _(string)_ The start date for the usage data. - **`end_date`** _(string)_ The end date for the usage data. - **`created_at`** _(string)_ Date and time when the usage data metric was created. - **`updated_at`** _(string)_ Date and time when the usage data metric was last updated. - **`surface`** _(string)_ Specific product surface for this row when the source exposes a single surface, such as chat, claude_code, cowork, office_agent, composer, or api. Omit when the row is aggregate and no per-surface split exists. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/usage-metering/usage](/api-reference/unified-usage-metering-api/usage/list) — List Usage --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/organizations/ Schema for the `Organizations` resource in **Unified Usage Metering API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`created_at`** _(string)_ Date and time when the organization was created. - **`updated_at`** _(string)_ Date and time when the organization was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/usage-metering/organizations/{id}](/api-reference/unified-usage-metering-api/organizations/get) — Get Organizations - [GET /unified/usage-metering/organizations](/api-reference/unified-usage-metering-api/organizations/list) — List Organizations --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/workspaces/ Schema for the `Workspaces` resource in **Unified Usage Metering API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the workspace. - **`name`** _(string)_ Name of the workspace. - **`organization`** _(object)_ Workspace belongs to this organization - **`id`** _(string)_ Unique identifier for the organization. - **`created_at`** _(string)_ Date and time when the workspace was created. - **`updated_at`** _(string)_ Date and time when the workspace was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/usage-metering/workspaces](/api-reference/unified-usage-metering-api/workspaces/list) — List Workspaces - [GET /unified/usage-metering/workspaces/{id}](/api-reference/unified-usage-metering-api/workspaces/get) — Get Workspaces - [DELETE /unified/usage-metering/workspaces/{id}](/api-reference/unified-usage-metering-api/workspaces/delete) — Delete Workspaces --- # Users Object > Source: https://truto.one/docs/api-reference/unified-usage-metering-api/users/ Schema for the `Users` resource in **Unified Usage Metering API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the user inside the source application. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`name`** _(string, required)_ Display name of the user. - **`emails`** _(array)_ Email addresses of the user. - **`email`** _(string)_ Email address. - **`is_primary`** _(boolean)_ Whether this is the primary email. - **`roles`** _(array)_ The roles the user has. - **`id`** _(string)_ The role's unique identifier. - **`name`** _(string)_ The role's name. - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`organization`** _(object)_ The organization / team / workspace the user belongs to. - **`id`** _(string)_ - **`name`** _(string)_ - **`spend_limit`** _(object)_ Per-user spending limit configured in the source application. - **`amount`** _(number)_ Spending limit amount (smallest currency unit). - **`currency`** _(string)_ ISO 4217 currency code. - **`last_active_at`** _(string)_ - **`created_at`** _(string)_ - **`updated_at`** _(string)_ - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/usage-metering/users](/api-reference/unified-usage-metering-api/users/list) — List Users - [GET /unified/usage-metering/users/{id}](/api-reference/unified-usage-metering-api/users/get) — Get Users - [DELETE /unified/usage-metering/users/{id}](/api-reference/unified-usage-metering-api/users/delete) — Delete Users --- # Unified User Directory API > Source: https://truto.one/docs/api-reference/unified-user-directory-api/ Base URL: `https://api.truto.one/unified/user-directory` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Roles](/api-reference/unified-user-directory-api/roles) - [GET /unified/user-directory/roles](/api-reference/unified-user-directory-api/roles/list) — List Roles - [POST /unified/user-directory/roles](/api-reference/unified-user-directory-api/roles/create) — Create Roles - [GET /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/get) — Get Roles - [PATCH /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/update) — Update Roles - [DELETE /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/delete) — Delete Roles - [Users](/api-reference/unified-user-directory-api/users) - [GET /unified/user-directory/users](/api-reference/unified-user-directory-api/users/list) — List Users - [POST /unified/user-directory/users](/api-reference/unified-user-directory-api/users/create) — Create Users - [GET /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/get) — Get Users - [PATCH /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/update) — Update Users - [DELETE /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/delete) — Delete Users - [POST /unified/user-directory/users/downgrade](/api-reference/unified-user-directory-api/users/downgrade) — Downgrade Users - [POST /unified/user-directory/users/deactivate](/api-reference/unified-user-directory-api/users/deactivate) — Deactivate Users - [POST /unified/user-directory/users/assign-role](/api-reference/unified-user-directory-api/users/assign-role) — Assign Role Users - [POST /unified/user-directory/users/unassign-role](/api-reference/unified-user-directory-api/users/unassign-role) — Unassign Role Users - [POST /unified/user-directory/users/assign_role](/api-reference/unified-user-directory-api/users/assign_role) — Assign Role Users - [POST /unified/user-directory/users/unassign_role](/api-reference/unified-user-directory-api/users/unassign_role) — Unassign Role Users - [POST /unified/user-directory/users/suspend](/api-reference/unified-user-directory-api/users/suspend) — Suspend Users - [Organizations](/api-reference/unified-user-directory-api/organizations) - [GET /unified/user-directory/organizations](/api-reference/unified-user-directory-api/organizations/list) — List Organizations - [GET /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/get) — Get Organizations - [DELETE /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/delete) — Delete Organizations - [PATCH /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/update) — Update Organizations - [Groups](/api-reference/unified-user-directory-api/groups) - [GET /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/get) — Get Groups - [PATCH /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/update) — Update Groups - [DELETE /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/delete) — Delete Groups - [GET /unified/user-directory/groups](/api-reference/unified-user-directory-api/groups/list) — List Groups - [POST /unified/user-directory/groups](/api-reference/unified-user-directory-api/groups/create) — Create Groups - [POST /unified/user-directory/groups/remove-user](/api-reference/unified-user-directory-api/groups/remove-user) — Remove User Groups - [POST /unified/user-directory/groups/add-user](/api-reference/unified-user-directory-api/groups/add-user) — Add User Groups - [POST /unified/user-directory/groups/add](/api-reference/unified-user-directory-api/groups/add) — Add Groups - [POST /unified/user-directory/groups/remove](/api-reference/unified-user-directory-api/groups/remove) — Remove Groups - [Activities](/api-reference/unified-user-directory-api/activities) - [GET /unified/user-directory/activities](/api-reference/unified-user-directory-api/activities/list) — List Activities - [GET /unified/user-directory/activities/{id}](/api-reference/unified-user-directory-api/activities/get) — Get Activities - [Billing](/api-reference/unified-user-directory-api/billing) - [GET /unified/user-directory/billing](/api-reference/unified-user-directory-api/billing/list) — List Billing - [Utilization](/api-reference/unified-user-directory-api/utilization) - [GET /unified/user-directory/utilization](/api-reference/unified-user-directory-api/utilization/list) — List Utilization - [Licenses](/api-reference/unified-user-directory-api/licenses) - [GET /unified/user-directory/licenses](/api-reference/unified-user-directory-api/licenses/list) — List Licenses - [GET /unified/user-directory/licenses/{id}](/api-reference/unified-user-directory-api/licenses/get) — Get Licenses - [Workspaces](/api-reference/unified-user-directory-api/workspaces) - [GET /unified/user-directory/workspaces](/api-reference/unified-user-directory-api/workspaces/list) — List Workspaces - [GET /unified/user-directory/workspaces/{id}](/api-reference/unified-user-directory-api/workspaces/get) — Get Workspaces - [Me](/api-reference/unified-user-directory-api/me) - [GET /unified/user-directory/me](/api-reference/unified-user-directory-api/me/list) — List Me - [RoleAssignments](/api-reference/unified-user-directory-api/roleassignments) - [GET /unified/user-directory/role_assignments](/api-reference/unified-user-directory-api/roleassignments/list) — List Role assignments - [GET /unified/user-directory/role_assignments/{id}](/api-reference/unified-user-directory-api/roleassignments/get) — Get Role assignments - [DELETE /unified/user-directory/role_assignments/{id}](/api-reference/unified-user-directory-api/roleassignments/delete) — Delete Role assignments --- # Roles Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/roles/ Schema for the `Roles` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`label`** _(string)_ The display label of the role - **`description`** _(string)_ The description of the role - **`type`** _(string)_ The type of the role - **`applicable_in`** _(string)_ The context in which the role is applicable Allowed: `group`, `workspace` - **`created_at`** _(string)_ The date and time the role was created - **`updated_at`** _(string)_ The date and time the role was last updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/roles](/api-reference/unified-user-directory-api/roles/list) — List Roles - [POST /unified/user-directory/roles](/api-reference/unified-user-directory-api/roles/create) — Create Roles - [GET /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/get) — Get Roles - [PATCH /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/update) — Update Roles - [DELETE /unified/user-directory/roles/{id}](/api-reference/unified-user-directory-api/roles/delete) — Delete Roles --- # Users Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/users/ Schema for the `Users` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`external_id`** _(string)_ The external identifier for a user. This is set when the SCIM API is being used. - **`identifiers`** _(object)_ The identifiers of the user. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`title`** _(string)_ The title of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`is_email_verified`** _(boolean)_ Whether the user's email has been verified - **`is_2fa_enabled`** _(boolean)_ Whether the user has 2FA enabled - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`group`** _(string)_ The role of the user in the group. This is available when the user can have different roles in different groups or teams in an application. - **`organization`** _(string)_ The role of the user in the organization. This is available when the user can have different roles in different organizations in an application. - **`workspace`** _(string)_ The role of the user in the workspace. This is available when the user can have different roles in different workspaces in an application. - **`organizations`** _(array)_ The organizations of the user - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`user_type`** _(string)_ The type of user - **`licenses`** _(array)_ The licenses of the user or the products the user has access to - **`id`** _(string)_ The unique identifier for a license - **`name`** _(string)_ The name of the license - **`organization`** _(string)_ The unique identifier of the organization to which the license belongs - **`last_active_at`** _(string)_ The date and time the user was last active for the license - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`workspaces`** _(array)_ The workspaces of the user - **`id`** _(string)_ The unique identifier for a workspace - **`name`** _(string)_ The name of the workspaces - **`avatar`** _(string)_ The avatar of the user - **`timezone`** _(string)_ The timezone of the user - **`languages`** _(array)_ The languages preferred by the user - **`bio`** _(string)_ The bio of the user. Usually a short description set by the user about them. - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`last_active_at`** _(string)_ The date and time the user was last active - **`last_login_at`** _(string)_ The date and time the user was last logged in - **`status_changed_at`** _(string)_ The date and time the user's status was last changed - **`activated_at`** _(string)_ The date and time the user was activated - **`urls`** _(array)_ The URLs of the user - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`manager`** _(object)_ The user's manager - **`id`** _(string)_ The unique identifier for a user - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/users](/api-reference/unified-user-directory-api/users/list) — List Users - [POST /unified/user-directory/users](/api-reference/unified-user-directory-api/users/create) — Create Users - [GET /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/get) — Get Users - [PATCH /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/update) — Update Users - [DELETE /unified/user-directory/users/{id}](/api-reference/unified-user-directory-api/users/delete) — Delete Users - [POST /unified/user-directory/users/downgrade](/api-reference/unified-user-directory-api/users/downgrade) — Downgrade Users - [POST /unified/user-directory/users/deactivate](/api-reference/unified-user-directory-api/users/deactivate) — Deactivate Users - [POST /unified/user-directory/users/assign-role](/api-reference/unified-user-directory-api/users/assign-role) — Assign Role Users - [POST /unified/user-directory/users/unassign-role](/api-reference/unified-user-directory-api/users/unassign-role) — Unassign Role Users - [POST /unified/user-directory/users/assign_role](/api-reference/unified-user-directory-api/users/assign_role) — Assign Role Users - [POST /unified/user-directory/users/unassign_role](/api-reference/unified-user-directory-api/users/unassign_role) — Unassign Role Users - [POST /unified/user-directory/users/suspend](/api-reference/unified-user-directory-api/users/suspend) — Suspend Users --- # Organizations Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/organizations/ Schema for the `Organizations` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the organization. - **`name`** _(string)_ Name of the organization. - **`pricing_plan`** _(string)_ Pricing plan associated with the organization. - **`licenses`** _(array)_ Licenses associated with the organization. - **`id`** _(string)_ Unique identifier for the license. - **`name`** _(string)_ Name of the license. - **`created_at`** _(string)_ Date and time when the organization was created. - **`updated_at`** _(string)_ Date and time when the organization was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/organizations](/api-reference/unified-user-directory-api/organizations/list) — List Organizations - [GET /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/get) — Get Organizations - [DELETE /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/delete) — Delete Organizations - [PATCH /unified/user-directory/organizations/{id}](/api-reference/unified-user-directory-api/organizations/update) — Update Organizations --- # Groups Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/groups/ Schema for the `Groups` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the group. - **`name`** _(string)_ Name of the group. - **`description`** _(string)_ Description of the group. - **`organization`** _(string)_ Unique identifier for the organization the group belongs to. - **`group_type`** _(string)_ Type of the group. Allowed: `team`, `department`, `group` - **`created_at`** _(string)_ Date and time when the group was created. - **`updated_at`** _(string)_ Date and time when the group was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/get) — Get Groups - [PATCH /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/update) — Update Groups - [DELETE /unified/user-directory/groups/{id}](/api-reference/unified-user-directory-api/groups/delete) — Delete Groups - [GET /unified/user-directory/groups](/api-reference/unified-user-directory-api/groups/list) — List Groups - [POST /unified/user-directory/groups](/api-reference/unified-user-directory-api/groups/create) — Create Groups - [POST /unified/user-directory/groups/remove-user](/api-reference/unified-user-directory-api/groups/remove-user) — Remove User Groups - [POST /unified/user-directory/groups/add-user](/api-reference/unified-user-directory-api/groups/add-user) — Add User Groups - [POST /unified/user-directory/groups/add](/api-reference/unified-user-directory-api/groups/add) — Add Groups - [POST /unified/user-directory/groups/remove](/api-reference/unified-user-directory-api/groups/remove) — Remove Groups --- # Activities Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/activities/ Schema for the `Activities` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the activity. - **`actor`** _(object)_ Actor who performed the activity. - **`type`** _(string)_ Type of the actor. Allowed: `user`, `system`, `anonymous` - **`user`** _(object)_ User who performed the activity. - **`id`** _(string)_ Unique identifier for the user. - **`organization`** _(string)_ Unique identifier for the organization the activity belongs to. - **`group`** _(string)_ Unique identifier for the group the activity belongs to. - **`description`** _(string)_ Description for the activity. - **`action`** _(string)_ Action performed by the user. If no clear mapping is available, then the raw value is returned. Allowed: `login`, `login_failed`, `logout`, `user_invited`, `user_created`, `user_joined`, `user_deactivated`, `user_deleted`, `user_updated`, `create`, `destroy`, `exported` (+1 more) - **`entity`** _(string)_ Unique identifier for the entity on which the action was performed. - **`entity_type`** _(string)_ Type of the entity on which the action was performed. - **`context`** _(object)_ Context of the activity. - **`ip_address`** _(string)_ IP address of the user who performed the activity. - **`user_agent`** _(string)_ User agent of the user who performed the activity. - **`authentication_method`** _(string)_ Authentication method used by the user. - **`created_at`** _(string)_ Date and time when the activity was created. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/activities](/api-reference/unified-user-directory-api/activities/list) — List Activities - [GET /unified/user-directory/activities/{id}](/api-reference/unified-user-directory-api/activities/get) — Get Activities --- # Billing Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/billing/ Schema for the `Billing` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the bill. - **`description`** _(string)_ Description for the bill. - **`billing_frequency`** _(string)_ Billing frequency for the license Allowed: `monthly`, `yearly` - **`currency`** _(string)_ Currency for the bill. - **`total_amount`** _(string)_ Total amount for the bill. - **`tax_amount`** _(string)_ Tax amount for the bill. - **`start_date`** _(string)_ Start date for the billing period. - **`end_date`** _(string)_ End date for the billing period - **`created_at`** _(string)_ Date and time when the bill was created. - **`updated_at`** _(string)_ Date and time when the bill was updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/billing](/api-reference/unified-user-directory-api/billing/list) — List Billing --- # Utilization Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/utilization/ Schema for the `Utilization` resource in **Unified User Directory API**. ## Properties - **`name`** _(string, required)_ Name of the utilization report - **`metadata`** _(object)_ Metadata of the utilization report - **`columns`** _(array, required)_ Columns of the utilization report - **`label`** _(string)_ Label of the column data - **`description`** _(string)_ Description of the column data - **`format`** _(string)_ Format of the column data - **`rows`** _(array>)_ Rows of the utilization report - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/utilization](/api-reference/unified-user-directory-api/utilization/list) — List Utilization --- # Licenses Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/licenses/ Schema for the `Licenses` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the license. - **`name`** _(string)_ Name of the license. - **`description`** _(string)_ Description for the license. - **`available_quantity`** _(number)_ Total number of licenses that can be assigned to users. - **`assigned_quantity`** _(number)_ Number of licenses that have been assigned to users. - **`unit_amount`** _(number)_ Unit amount for the license. - **`roles`** _(array)_ Valid Roles for the license. - **`id`** _(string)_ Unique identifier for the role. - **`name`** _(string)_ Name of the role. - **`is_paid`** _(boolean)_ Whether the license is paid or not. - **`currency`** _(string)_ Currency for the license. - **`status`** _(string)_ Status for the license Allowed: `active`, `inactive` - **`products`** _(array)_ The products that are part of the license. - **`id`** _(string)_ Unique identifier for the product - **`name`** _(string)_ The name of product - **`status`** _(string)_ Status for the product within the license. Usually denotes the provisioning status. Allowed: `active`, `inactive`, `errored`, `needs_input`, `needs_confirmation`, `pending` - **`created_at`** _(string)_ Date and time when the license was created. - **`updated_at`** _(string)_ Date and time when the license was last updated. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/licenses](/api-reference/unified-user-directory-api/licenses/list) — List Licenses - [GET /unified/user-directory/licenses/{id}](/api-reference/unified-user-directory-api/licenses/get) — Get Licenses --- # Workspaces Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/workspaces/ Schema for the `Workspaces` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ Unique identifier for the workspace. - **`name`** _(string)_ Name of the workspace. - **`description`** _(string)_ Description for the workspace. - **`status`** _(string)_ Status for the workspace Allowed: `active`, `inactive` - **`created_at`** _(string)_ Date and time when the workspace was created. - **`updated_at`** _(string)_ Date and time when the workspace was last updated. - **`organization`** _(object)_ organization associated with the workspace - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/workspaces](/api-reference/unified-user-directory-api/workspaces/list) — List Workspaces - [GET /unified/user-directory/workspaces/{id}](/api-reference/unified-user-directory-api/workspaces/get) — Get Workspaces --- # Me Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/me/ Schema for the `Me` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a user - **`external_id`** _(string)_ The external identifier for a user. This is set when the SCIM API is being used. - **`identifiers`** _(object)_ The identifiers of the user. - **`first_name`** _(string)_ The first name of the user - **`last_name`** _(string)_ The last name of the user - **`title`** _(string)_ The title of the user - **`name`** _(string)_ The name of the user - **`username`** _(string)_ The username of the user - **`emails`** _(array)_ The emails of the user - **`email`** _(string)_ The email address - **`type`** _(string)_ The type of email address - **`is_primary`** _(boolean)_ Whether the email address is primary - **`phones`** _(array)_ The phones of the user - **`number`** _(string)_ The phone number - **`extension`** _(string)_ The extension of the phone number - **`type`** _(string)_ The type of phone number - **`status`** _(string)_ The status of the user. If no clear mapping is available, then the raw value is returned. Allowed: `active`, `inactive`, `deleted`, `invited` - **`is_email_verified`** _(boolean)_ Whether the user's email has been verified - **`is_2fa_enabled`** _(boolean)_ Whether the user has 2FA enabled - **`roles`** _(array)_ The roles of the user - **`id`** _(string)_ The unique identifier for a role - **`name`** _(string)_ The name of the role - **`group`** _(string)_ The role of the user in the group. This is available when the user can have different roles in different groups or teams in an application. - **`organization`** _(string)_ The role of the user in the organization. This is available when the user can have different roles in different organizations in an application. - **`workspace`** _(string)_ The role of the user in the workspace. This is available when the user can have different roles in different workspaces in an application. - **`organizations`** _(array)_ The organizations of the user - **`id`** _(string)_ The unique identifier for an organization - **`name`** _(string)_ The name of the organization - **`user_type`** _(string)_ The type of user - **`licenses`** _(array)_ The licenses of the user or the products the user has access to - **`id`** _(string)_ The unique identifier for a license - **`name`** _(string)_ The name of the license - **`organization`** _(string)_ The unique identifier of the organization to which the license belongs - **`last_active_at`** _(string)_ The date and time the user was last active for the license - **`groups`** _(array)_ The groups of the user - **`id`** _(string)_ The unique identifier for a group - **`name`** _(string)_ The name of the group - **`organization`** _(string)_ The unique identifier of the organization to which the group belongs - **`avatar`** _(string)_ The avatar of the user - **`timezone`** _(string)_ The timezone of the user - **`languages`** _(array)_ The languages preferred by the user - **`bio`** _(string)_ The bio of the user - **`created_at`** _(string)_ The date and time the user was created - **`updated_at`** _(string)_ The date and time the user was last updated - **`last_active_at`** _(string)_ The date and time the user was last active - **`last_login_at`** _(string)_ The date and time the user was last logged in - **`status_changed_at`** _(string)_ The date and time the user's status was last changed - **`activated_at`** _(string)_ The date and time the user was activated - **`urls`** _(array)_ The URLs of the user - **`url`** _(string)_ The URL - **`type`** _(string)_ The type of URL - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/me](/api-reference/unified-user-directory-api/me/list) — List Me --- # RoleAssignments Object > Source: https://truto.one/docs/api-reference/unified-user-directory-api/roleassignments/ Schema for the `RoleAssignments` resource in **Unified User Directory API**. ## Properties - **`id`** _(string, required)_ The unique identifier for a role assignment - **`user_id`** _(string)_ The unique identifier for a user who the role is assigned to - **`group_id`** _(string)_ The unique identifier for a group the role is assigned to - **`group_type`** _(string)_ The type of the group the role is assigned to Allowed: `product`, `group`, `team` - **`role_id`** _(string)_ The unique identifier for a role - **`workspace`** _(array)_ The unique identifier for a workspace the assignment is applicable in - **`created_at`** _(string)_ The date and time of the role assignment was created - **`updated_at`** _(string)_ The date and time of the role assignment was updated - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/user-directory/role_assignments](/api-reference/unified-user-directory-api/roleassignments/list) — List Role assignments - [GET /unified/user-directory/role_assignments/{id}](/api-reference/unified-user-directory-api/roleassignments/get) — Get Role assignments - [DELETE /unified/user-directory/role_assignments/{id}](/api-reference/unified-user-directory-api/roleassignments/delete) — Delete Role assignments --- # Unified Voice API > Source: https://truto.one/docs/api-reference/unified-voice-api/ Base URL: `https://api.truto.one/unified/voice` Set the `integrated_account_id` query parameter on every request to scope it to a specific connection. ## Resources - [Calls](/api-reference/unified-voice-api/calls) - [GET /unified/voice/calls](/api-reference/unified-voice-api/calls/list) — List Calls - [Recordings](/api-reference/unified-voice-api/recordings) - [POST /unified/voice/recordings/download](/api-reference/unified-voice-api/recordings/download) — Download Recordings - [GET /unified/voice/recordings](/api-reference/unified-voice-api/recordings/list) — List Recordings --- # Calls Object > Source: https://truto.one/docs/api-reference/unified-voice-api/calls/ Schema for the `Calls` resource in **Unified Voice API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the call. - **`from`** _(string)_ The phone number or name of the caller. - **`to`** _(string)_ The phone number or name of the callee. - **`status`** _(string)_ The status of the call. - **`direction`** _(string)_ The direction of the call. - **`created_at`** _(string)_ The date and time the call was created. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [GET /unified/voice/calls](/api-reference/unified-voice-api/calls/list) — List Calls --- # Recordings Object > Source: https://truto.one/docs/api-reference/unified-voice-api/recordings/ Schema for the `Recordings` resource in **Unified Voice API**. ## Properties - **`id`** _(string, required)_ The unique identifier of the recording. - **`url`** _(string)_ The URL of the recording. - **`call_id`** _(string)_ The unique identifier of the call. - **`start_time`** _(string)_ The date and time the recording started. - **`end_time`** _(string)_ The date and time the recording ended. - **`created_at`** _(string)_ The date and time the recording was created. - **`remote_data`** _(object)_ Raw data returned from the remote API call. ## Methods - [POST /unified/voice/recordings/download](/api-reference/unified-voice-api/recordings/download) — Download Recordings - [GET /unified/voice/recordings](/api-reference/unified-voice-api/recordings/list) — List Recordings ---