1 of 12

Docs

Getting Started

Welcome

Integry helps software builders add user-facing integrations inside their apps and AI. Integry is a full-stack integration platform and we provide everything you need to build, delivery, scale, manage and support integrations.

Jump right in

Functions

Overview

Integry Functions enables you to integrate a vast array of apps into your AI applications seamlessly.

What are Integry Functions?

Integry Functions lets you use Integry's extensive library of app functions as tools within your AI applications. By leveraging Integry's function-calling compatible JSON structures, you can invoke third-party app functions directly from your AI calls. You can:

Access hundreds of third-party app functions.
Use function-calling compatible JSON structures in your AI calls.
Show a populated form of the action for user editing and confirmation
Invoke functions directly (headlessly i.e. without a UI)
Predict and populate functions based on user input.

Integry supports many functions for 200+ apps. Click the Marketplace button in the app to browse the full list of Functions or use the API.

Using Functions with Your AI

Generally, when using AI with function calling, you take the following steps:

Collect User Input: You collect a user message, which requires talking to an external API. For example: "send hello to my team on slack on #general"
Call AI Model: You take the user message, their data context, and a prompt and pass a list of function specs with to the AI's API call
AI Populates Function: The AI selects the function, fills in its parameters, and returns the result
Call Function: You then call the function with the arguments and take next steps based on the response
Validate Arguments (optional): before calling the function in step 3, you might need to validate the user input. In our example, the user wrote #general whereas the actual channel was #general. To resolve this, you may need to first fetch all channels and find the closest match
Show UI (optional): you could also show the user the final function call in a UI before executing it.

To achieve this, we have two methods. The first method is faster and easier to start with. The second method requires more effort but provides greater control. Here they are:

Function Prediction: Pass the user message to/functions/?predict_function=true&prompt=<user_message> to get the most relevant function. You can also get populated arguments.
Function List Retrieval: Retrieve a list of available functions using the /functions endpoint and pass them to your AI model. Your model will predict the function to use and will populate the arguments. You may need to validate your inputs with additional supporting function calls.

Both approaches converge after obtaining the function parameters, where you can choose to call the function directly or show the UI.

Additional Resources

Quickstart for AI

In this guide, we will use the and to enable users to connect apps and invoke functions in those apps from your AI application.

Before you proceed, please for a free trial (if you haven't).

Set up the SDK

Follow the steps .

Enable your users to connect apps

Your users have to first connect an app before you can invoke functions in that app. You could use or more of the following options.

Shows apps in the Integry marketplace

Call the method to easily show all (or some) available apps as a marketplace. Users will simply click an app to connect.

Show apps in your own marketplace

Connect apps when needed

Predict the function to invoke

Let's say your user says they want to "send a message saying hello! to the random channel on slack".

In order to execute the slack-post-message function, you have to first predict that its the most relevant function.

Predict the function with Integry AI

Sample Response:

The response will be empty if Integry is unable to predict the function. You can ask the user to improve the prompt and try again.

Predict the function yourself

Prepare the arguments

In order to invoke a function, you have to first prepare the arguments based on the parameters that the function requires.

Parameter vs Argument: A function parameter is the placeholder name of the type of input the function expects. The actual value passed is called the argument.

Predict the arguments with Integry AI

Sample Response for Prediction with Populated Arguments:

The response is the same as above.

Predict the arguments yourself

If you use predict the arguments with Integry AI, we handle this for you.

Show the Function UI to the user

This will open the Function UI (with the pre-filled arguments) in a modal.

This method returns a result object with the filled-in arguments that you can use to invoke the function.

Functions that mutate data can potentially do irreversible damage. Even if you have predicted the arguments, consider always showing the Function UI to the user (with the predicted arguments) so they can confirm before you execute.

Execute the function

Call invokeFunction()

Process the result

The result object will have the response from the app if the function was executed (or error details if it wasn't).

In this case, you should see the following success response from Slack in the console:

That's it! You have enabled your users to connect apps and execute functions in those apps from your AI application using Integry Functions.

Next steps

Try fetching data using a function like pipedrive-get-all-persons . It supports paginated calls so the the result will include a next_page cursor that you will include in the arguments in the next invocation.

Source functions

Source functions return object arrays that can be used to dynamically populate dropdown options, or fetch custom fields.

Functions like slack-post-message require the user to provide an ID value for the channel parameter. Source functions help populate such arguments.

For example, when you show the Function UI to the user so they can select a channel, we call the source function slack-list-conversations (using the user's auth credentials) to populate the channel dynamic dropdown.

In fact, when you predict the arguments with Integry AI, we call the same source function to get the list of channels so we can predict the most relevant option.

When you get a function, the description of a field will mention if there is a source function available to list the options for that field.

Sample response for GET /functions/slack-post-message:

{
    "name": "slack-post-message",
    "description": "Post a message in a channel",
    "parameters": {
        "type": "object",
        "properties": {
            "channel": {
                "type": "string",
                "description": "The channel to send the message in. Call `slack-list-conversations` to get the available values."
            },
            "attachments": {
                "type": "string",
                "description": "A JSON-based array of structured attachments, presented as a URL-encoded string."
            },
            "blocks": {
                "type": "array",
                "description": "A JSON-based array of structured blocks, presented as a URL-encoded string.",
                "items": {
                    "type": "string"
                }
            },
            "text": {
                "type": "string",
                "description": "The content of the message."
            },
            "as_user": {
                "type": "boolean",
                "description": "(Legacy) Pass true to post the message as the authed user instead of as a bot. Defaults to false. Can only be used by classic apps."
            },
            "icon_emoji": {
                "type": "string",
                "description": "Emoji to use as the icon for this message. Overrides icon_url."
            },
            "icon_url": {
                "type": "string",
                "description": "URL to an image to use as the icon for this message."
            },
            "link_names": {
                "type": "boolean",
                "description": "Find and link user groups. No longer supports linking individual users; use syntax shown in Mentioning Users instead."
            },
            "metadata": {
                "type": "string",
                "description": "JSON object with event_type and event_payload fields, presented as a URL-encoded string. Metadata you post to Slack is accessible to any app or user who is a member of that workspace."
            },
            "mrkdwn": {
                "type": "boolean",
                "description": "Disable Slack markup parsing by setting to false. Enabled by default."
            },
            "parse": {
                "type": "string",
                "description": "Change how messages are treated."
            },
            "reply_broadcast": {
                "type": "boolean",
                "description": "Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation. Defaults to false."
            },
            "thread_ts": {
                "type": "string",
                "description": "Provide another message's ts value to make this message a reply. Avoid using a reply's ts value; use its parent instead."
            },
            "unfurl_links": {
                "type": "boolean",
                "description": "Pass true to enable unfurling of primarily text-based content."
            },
            "unfurl_media": {
                "type": "boolean",
                "description": "Pass false to disable unfurling of media content."
            },
            "username": {
                "type": "string",
                "description": "Set your bot's user name."
            }
        },
        "required": [
            "channel",
            "text"
        ]
    }
}

Fetch custom fields

Apps like Hubspot let the user completely customize objects to represent their business. Hence, functions like hubspot-create-contact don't have any typical standard parameters like email, name, etc. Instead, it requires an object parameter called properties in which all the fields of the contact to be created have to be passed. Source functions help populate such arguments.

When you show the Function UI to the user so they can fill the Contact object fields, we call the source function hubspot-list-properties (with objectType: Contact) to fetch all the custom fields for the Contact object.

Similarly, when you predict the arguments with Integry AI, we call the same source function to get the list of fields so we can predict the most relevant values for the fields.

When you get a function, the description of an object field will mention if there is a source function available to list the fields for that object.

Sample response for GET /functions/hubspot-create-contact:

{
    "name": "hubspot-create-contact",
    "description": "Create a contact with the given properties. Call hubspot-list-properties to get the properties.",
    "parameters": {
        "type": "object",
        "properties": {
            "properties": {
                "type": "object",
                "description": "Provide the properties as key, value pairs.. Call `hubspot-list-properties` to get the available values.",
                "properties": {}
            }
        },
        "required": []
    }
}

Call a source function

You can call a source function like any other function via the API or SDK.

In fact, they can typically be called headlessly because they usually don't have any required parameters. You should cache the data to avoid repeated calls.

Good candidates to cache are channel list, user list, issue types, project names, etc. Ultimately, it depends on your use-case, but you can also implement a generic solution for supporting function data.

List all source functions

You cannot list all source functions, per se, because they are context-dependent. Instead, you can list all query type functions with GET /functions?type=query.

See /functions for more options.

Passthrough requests

We have Functions for the most commonly used endpoints of 200+ apps.

If you want to do anything else, you can call the Passthrough Request function of any app we support via API endpoint or SDK method. Integry will automatically add the user's auth credentials to the request.

Make a passthrough request via API

POST /<app_name>-passthrough-request

Integry will execute the function if the user has already connected their account for the function app, and the method and URL parameters are provided in the body. These function calls will show in the Function Calls log in the Integry app.

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

Body

Name

Type

Description

Required

Response

If Integry executes the function, it will respond with a 200 OK with following keys in the response body:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.

If Integry does not execute the function, it will respond with a 400 Bad Request with following keys in the response body:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

// Function name: slack-passthrough-request
// GET https://slack.com/api/conversations.list?limit=2

{
    "network_code": "200",
    "output": {
        "ok": true,
        "channels": [
            {
                "id": "C6F3LQ03A",
                "name": "random",
                "is_channel": true,
                "is_group": false,
                "is_im": false,
                "is_mpim": false,
                "is_private": false,
                "created": 1501486653,
                "is_archived": false,
                "is_general": false,
                "unlinked": 0,
                "name_normalized": "random",
                "is_shared": false,
                "is_org_shared": false,
                "is_pending_ext_shared": false,
                "pending_shared": [],
                "context_team_id": "T6F74R6TB",
                "updated": 1724807678577,
                "parent_conversation": null,
                "creator": "U6GKMKPE2",
                "is_ext_shared": false,
                "shared_team_ids": [
                    "T6F74R6TB"
                ],
                "pending_connected_team_ids": [],
                "is_member": true,
                "topic": {
                    "value": "Non-work banter and water cooler conversation",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "purpose": {
                    "value": "A place for non-work-related flimflam, faffing, hodge-podge or jibber-jabber you'd prefer to keep out of more focused work-related channels.",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "properties": {
                    "tabs": [
                        {
                            "id": "files",
                            "label": "",
                            "type": "files"
                        }
                    ]
                },
                "previous_names": [],
                "num_members": 7
            },
            {
                "id": "C6GKMKRUN",
                "name": "general",
                "is_channel": true,
                "is_group": false,
                "is_im": false,
                "is_mpim": false,
                "is_private": false,
                "created": 1501486653,
                "is_archived": false,
                "is_general": true,
                "unlinked": 0,
                "name_normalized": "general",
                "is_shared": false,
                "is_org_shared": false,
                "is_pending_ext_shared": false,
                "pending_shared": [],
                "context_team_id": "T6F74R6TB",
                "updated": 1731095674264,
                "parent_conversation": null,
                "creator": "U6GKMKPE2",
                "is_ext_shared": false,
                "shared_team_ids": [
                    "T6F74R6TB"
                ],
                "pending_connected_team_ids": [],
                "is_member": true,
                "topic": {
                    "value": "Channel for high priority, company-wide announcements and work-related matters. If you want to banter please head over to <#C02D3JZA45T|> if you want to discuss low priority items head over to <#G01L3PW2A01|integry-internal>",
                    "creator": "U6FQESQ02",
                    "last_set": 1632860908
                },
                "purpose": {
                    "value": "This channel is for team-wide communication and announcements. All team members are in this channel.",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "properties": {
                    "tabs": [
                        {
                            "id": "files",
                            "label": "",
                            "type": "files"
                        }
                    ]
                },
                "previous_names": [],
                "num_members": 14
            }
        ],
        "response_metadata": {
            "next_cursor": "dGVhbTpDOFBLNUhOOTU="
        }
    }
}

// Function name: slack-passthrough-request
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Slack account. To connect an account, please call following SDK method: `connectApp('slack')`"
    ]
}

Make a passthrough request via SDK

invokeFunction(<app_name>-passthrough-request, params, connectedAccountId)

Integry will execute the function if the user has already connected their account for the function app, and the method and URL parameters are provided in the params object. These function calls will show in the Function Calls log in the Integry app.

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

const params = {
  method: "GET",
  url: "https://slack.com/api/conversations.list?limit=2"
};
integry.invokeFunction("slack-passthrough-request", params).then((result) => {
  console.log("Received response from Slack:", result);
}).catch((error) => {
  console.error("Failed to invoke function:", error);
});

Method parameters

Returns

If Integry executes the function, this method returns a result object with following keys:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.

If Integry does not execute the function, this method returns a result object with following keys:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

// Function name: pipedrive-passthrough-request
// POST https://api.pipedrive.com/api/v2/persons
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

// Function name: pipedrive-passthrough-request
// POST https://api.pipedrive.com/api/v2/persons
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

List all passthrough request functions

GET /functions?type=passthrough

List all passthrough request functions supported by Integry. See /functions for more options.

Flows

Overview

What is Integry Flows?

Integry is an Integration Platform as a Service (iPaaS) that allows you to add an integration marketplace to your product in minutes.

You build flows between your app and up to 250+ other apps. Your users get a fully native integration experience within your product. Their data moves seamlessly between their apps.

What's included?

Integry Flows comes with:

Ready-to-use authentication, triggers, queries and actions of 270+ apps
An intuitive, powerful, low-code flow builder that you will use to build one-way, or two-way, flows between your app and other apps
A customizable marketplace UI that you will embed in your app (using an SDK) where your users will discover, setup and manage their integrations
Detailed logs of integration runs with customizable error notifications enabling you to proactively support your users
User-level reporting and adoption notifications to effectively drive usage and ROI
A robust, scalable, secure backend with SOC 2, GDPR and CCPA compliance

We are in the process of migrating Flows help docs. For now, please go here.

APIs and SDKs

API Reference

The Integry API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded and form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Setting Up

Base URL

https://api.integry.io

Authentication

The Integry API requires an App-Key , User-ID and a hash of App-Secret and User-ID in the request headers to authenticate requests.

You can view and copy your App-Key and App-Secret from the Integry app.

User-ID is a unique string identifier for a user in your app. Function Calls and Integrations are associated to a user ID.

If your app has workspaces/accounts and you want integrations to be shared across all users in a workspace/account, use the workspace/account ID as the user ID.

Calculating the hash

Calculate the hash server-side using HMAC SHA256.

const crypto = require("crypto");

const userId = "";
const appSecret = "";

const hash = crypto
.createHmac("sha256", appSecret)
.update(userId)
.digest("hex");

import hmac
import hashlib

app_secret = b"<app_secret>"
user_id = b"<user_id>"

hash = hmac.new(app_secret, user_id, hashlib.sha256).hexdigest()

<?php

$appSecret = '<APP_SECRET>';
$userId = '<USER_ID>';
$hash = hash_hmac('sha256', $userId, $appSecret);

Headers

Pass the App-Key, computed hash and User-ID in the headers of the API call.

Apps

List all apps

GET /apps

List all apps available in Integry. If you need more, please reach out!

Query parameters

Response

{
    "apps": [
        {
            "id": 410,
            "name": "pipedrive",
            "title": "Pipedrive",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
            "docs_url": "",
            "connected_accounts": [
                {
                    "id": 247714,
                    "display_name": "663----------8b1",
                    "modified_at": "2024-11-10T23:28:58Z"
                }
            ]
        },
        {
            "id": 24514,
            "name": "4me",
            "title": "4me",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/0d80bd3a-8207-426d-80e8-8aa75f5db662.png",
            "docs_url": "",
            "connected_accounts": []
        },
        {
            "id": 118,
            "name": "accelo",
            "title": "Accelo",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/e36d9d8c-8188-40e9-9fbf-9f4b5433e4ee.png",
            "docs_url": "",
            "connected_accounts": []
        }
    ],
    "cursor": "E5JTNBMzklM0EzOS43NzA4MzclMkIwMCUzQTAw"
}

{
    "detail": "Authentication credentials were not provided."
}

Get an app

GET /apps/<app_name>

Get the details of an individual app by passing <app_name> as a path variable.

Response

{
    "id": 491,
    "name": "slack",
    "title": "Slack",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c53aa5ce-1ced-48cb-98cc-8859eb8bf85d.png",
    "docs_url": "",
    "connected_accounts": []
}

{
    "detail": "Authentication credentials were not provided."
}

Functions

List all functions

GET /functions

List all functions available in Integry. If you need more, make a passthrough request or reach out!

Query Parameters

Response

{
    "functions": [
        {
            "name": "kit-tag-a-subscriber",
            "description": "Tag a subscriber by providing tag_id. Call kit-list-tags to get the tags.",
            "parameters": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": ""
                    },
                    "tag_id": {
                        "type": "string",
                        "description": ""
                    }
                },
                "required": [
                    "id",
                    "tag_id"
                ]
            }
        }
    ],
    "cursor": "cD0yMDI0LTExLTExKzEwJTNBNDAlM0EwMC42NjI3MjMlMkIwMCUzQTAw"
}

{
    "detail": "Authentication credentials were not provided."
}

Get a function

GET /functions/<function_name>

Get the JSON schema of an individual function by passing function name as a path variable.

Query Parameters

Response

All supported function parameters are returned as keys, along with their type and description as key, value pairs. Required parameters are listed in the required array.

Sample response for pipedrive-add-a-person get function call:

{
    "name": "pipedrive-add-a-person",
    "description": "Adds a new person.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The name of the person"
            },
            "owner_id": {
                "type": "number",
                "description": "The ID of the user who owns the person. Call `pipedrive-get-all-users` to get the available values."
            },
            "org_id": {
                "type": "number",
                "description": "The ID of the organization linked to the person. Call `pipedrive-get-all-organizations` to get the available values."
            },
            "add_time": {
                "type": "string",
                "description": "The creation date and time of the person"
            },
            "emails": {
                "type": "array",
                "description": "The emails of the person",
                "items": {
                    "type": "string"
                }
            },
            "phones": {
                "type": "array",
                "description": "The phones of the person",
                "items": {
                    "type": "string"
                }
            },
            "visible_to": {
                "type": "number",
                "description": "The visibility of the person"
            },
            "label_ids": {
                "type": "array",
                "description": "The IDs of labels assigned to the person. Call `pipedrive-get-person-labels` to get the available values.",
                "items": {
                    "type": "number"
                }
            }
        },
        "required": []
    }
}

{
    "detail": "Function not found"
}

Call a function

POST /functions/<function_name>/

Call a function by passing <function_name> as a path variable and the function parameters in the request body. Integry will automatically add the user's authentication credentials (eg. access token, API key) to the call.

Query Parameters

Integry will execute the function if the user has already connected their account for the function app, and all required parameters (if any) are provided in the body. These function calls will show in the Function Calls log in the Integry app.

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

Body

Pass the function parameters in the request body.

Sample body for pipedrive-add-a-person function call:

{
    "name": "Sample contact"
}

Sample body for pipedrive-get-all-persons function call with next_page:

{
    "limit": 5,
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

Response

If Integry executes the function, it will respond with a 200 OK with following keys in the response body:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.
next_page: The cursor for the next page. It will only be present in responses of functions that support paginated calls. If there are no more pages, it will be empty.

If Integry does not execute the function, it will respond with a 400 Bad Request with following keys in the response body:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

Sample responses for pipedrive-add-a-person and pipedrive-get-all-persons:

// Function name: pipedrive-add-a-person
// Outcome: Person was created
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

// Function name: pipedrive-add-a-person
// Outcome: Validation error
{
    "network_code": "400",
    "output": {
        "success": false,
        "error": "Validation failed: owner_id: User not found or not accessible.",
        "code": "ERR_SCHEMA_VALIDATION_FAILED"
    }
}

// Function name: pipedrive-get-all-persons
// Outcome: Data was fetched with a next_page cursor.
{
    "network_code": "200",
    "output": [
        {
            "id": 1,
            "name": "[Sample] Phyllis Yang",
            "first_name": "[Sample] Phyllis",
            "last_name": "Yang",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-11T00:52:38Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [
                14
            ],
            "org_id": 5,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "240-707-3884",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "phyllis.yang@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 2,
            "name": "[Sample] Tony Turner",
            "first_name": "[Sample] Tony",
            "last_name": "Turner",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 1,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "218-348-8528",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "tony.turner@moveer.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 3,
            "name": "[Sample] Gloria Quinn",
            "first_name": "[Sample] Gloria",
            "last_name": "Quinn",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 2,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "862-252-9773",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "gloria.quinn@empowermmove.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 4,
            "name": "[Sample] Benjamin Leon",
            "first_name": "[Sample] Benjamin",
            "last_name": "Leon",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "785-202-7824",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "benjamin.leon@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 5,
            "name": "[Sample] Otto Miller",
            "first_name": "[Sample] Otto",
            "last_name": "Miller",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 3,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "601-906-7534",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "otto.miller@itablee.eu",
                    "primary": true
                }
            ]
        }
    ],
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- required parameter was missing
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": {
        "name": "This parameter is required and must not be null or empty"
    }
}

In rare cases where Integry is unable to determine if there are more pages, it will respond with a next_page cursor. Your subsequent call will return an empty output[] and next_page cursor since there are no more pages.

Quickstart for AI

In this guide, we will use the and to enable users to connect apps and invoke functions in those apps from your AI application.

Before you proceed, please for a free trial (if you haven't).

Set up the SDK

Follow the steps .

Enable your users to connect apps

Your users have to first connect an app before you can invoke functions in that app. You could use or more of the following options.

Shows apps in the Integry marketplace

Call the method to easily show all (or some) available apps as a marketplace. Users will simply click an app to connect.

Show apps in your own marketplace

Build your own apps marketplace and call the method when they click on an app.

integry.connectApp("slack").then((connectedAccountId) => {
  console.log("Connected to Slack with account ID:", connectedAccountId);
}).catch((error) => {
  console.error("Failed to connect to Slack:", error);
});

Connect apps when needed

Call method (when they try to use a function of an app) to check if the app is connected. If not, ask them to .

integry.isAppConnected("slack").then((result) => {
  if(result) {
    renderFunctionUI("slack-post-message");
  } else {
    integry.connectApp("slack").then((response) => {
      renderFunctionUI("slack-post-message")
    });
  }
}).catch((error) => {
  console.error("Failed to determine auth status:", error);
});

Predict the function to invoke

Let's say your user says they want to "send a message saying hello! to the random channel on slack".

In order to execute the slack-post-message function, you have to first predict that its the most relevant function.

You can simply pass the prompt to Integry and , or (by listing all available functions).

Predict the function with Integry AI

Call the API endpoint with predict_function=true&prompt=<user_message> to get the most relevant function. You can also have Integry .

import requests

# Example 2: Basic Prediction
message = "send a message saying hello! to the random channel on slack"
response = requests.get(
    "https://api.integry.io/functions/",
    params={"predict_function": "true", "prompt": message},
    headers={
        "User-ID": "<string>",
        "App-Key": "<string>",
        "Hash": "<string>"
    },
)
function = response

Sample Response:

{
    "name": "slack-post-message",
    "description": "Sends a message to a channel",
    "parameters": {
        "type": "object",
        "properties": {
            "channel": {
                "type": "string",
                "description": "Select channel you want to post the message to. Call `slack-list-conversations` to get available channels"
            },
            "text": {
                "type": "string",
                "description": "The message text to be posted to Slack"
            }
        },
        "required": [
            "channel",
            "text"
        ]
    }
}

The response will be empty if Integry is unable to predict the function. You can ask the user to improve the prompt and try again.

Predict the function yourself

Retrieve a list of available functions using the endpoint and pass them to your AI model. Your model will predict the function to use.

If you need to call an endpoint that is not supported by Integry, you can make a .

Prepare the arguments

In order to invoke a function, you have to first prepare the arguments based on the parameters that the function requires.

Similar to predicting the function, you can simply pass the prompt to Integry and , or (using the function spec).

Parameter vs Argument: A function parameter is the placeholder name of the type of input the function expects. The actual value passed is called the argument.

Predict the arguments with Integry AI

Call the API endpoint with predict_function=true&predict_arguments=true&prompt=<user_message> to get the most relevant function with populated arguments.

# Example 1: Prediction with Populated Arguments
message = "send a message saying hello! to the random channel on slack"
response = requests.get(
    "https://api.integry.io/functions/",
    params={"predict_function": "true", "prompt": message, "predict_arguments": "true"},
    headers={
        "User-ID": "<string>",
        "App-Key": "<string>",
        "Hash": "<string>",
    },
)
function = response

Sample Response for Prediction with Populated Arguments:

{
  "name": "slack-post-message",
  "description": "Sends a message to a channel",
  "parameters": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "description": "Select channel you want to post the message to. Call `slack-list-conversations` to get available channels"
          },
          "text": {
            "type": "string",
            "description": "The message text to be posted to Slack"
          }
        },
        "required": [
          "channel", "text"
        ]
      },
  "arguments": {
    "channel": "random",
    "text": "hello!"
  }
}

Alternatively, if you predicted the function yourself and want Integry to predict the arguments, call the API endpoint with predict_arguments=true&prompt=<user_message> to get the function with populated arguments.

message = "send a message saying hello! to the random channel on slack"
response = requests.get(
    "https://api.integry.io/functions/slack-post-message",
    params={"prompt": message, "predict_arguments": "true"},
    headers={
        "User-ID": "<string>",
        "App-Key": "<string>",
        "Hash": "<string>",
    },
)
function = response

The response is the same as above.

Predict the arguments yourself

Call the endpoint to get the function spec and pass it to your AI model. Your model will predict and populate the arguments.

You may need to make additional calls to to fetch options. Once you have the related data from the source function, use your model to pick the most relevant value from the set.

If you use predict the arguments with Integry AI, we handle this for you.

Show the Function UI to the user

Before you invoke the function, if you want the user to confirm the predicted arguments, or provide one (or more) required arguments that could not be predicted, you can call method to show the Function UI to the user (with pre-filled arguments, if any).

const arguments = {
  "channel": "random",
  "text": "hello!"
}

integry.showFunctionUI("slack-post-message", arguments).then((result) => {
  console.log("Function parameters filled-in by the user:", result);
}).catch((error) => {
  console.error("Failed to load function UI:", error);
});

This will open the Function UI (with the pre-filled arguments) in a modal.

This method returns a result object with the filled-in arguments that you can use to invoke the function.

Execute the function

Call invokeFunction()

Call with the <function_name> and arguments object to execute the function.

const arguments = {
  "channel": "random",
  "text": "hello!"
}

integry.invokeFunction("slack-post-message", arguments).then((result) => {
  console.log("Received response from Slack:", result);
}).catch((error) => {
  console.error("Failed to invoke function:", error);
});

Process the result

The result object will have the response from the app if the function was executed (or error details if it wasn't).

In this case, you should see the following success response from Slack in the console:

That's it! You have enabled your users to connect apps and execute functions in those apps from your AI application using Integry Functions.

Next steps

API Reference

Setting Up

Base URL

https://api.integry.io

Authentication

The Integry API requires an App-Key , User-ID and a hash of App-Secret and User-ID in the request headers to authenticate requests.

You can view and copy your App-Key and App-Secret from the Integry app.

User-ID is a unique string identifier for a user in your app. Function Calls and Integrations are associated to a user ID.

If your app has workspaces/accounts and you want integrations to be shared across all users in a workspace/account, use the workspace/account ID as the user ID.

Calculating the hash

Calculate the hash server-side using HMAC SHA256.

const crypto = require("crypto");

const userId = "";
const appSecret = "";

const hash = crypto
.createHmac("sha256", appSecret)
.update(userId)
.digest("hex");

import hmac
import hashlib

app_secret = b"<app_secret>"
user_id = b"<user_id>"

hash = hmac.new(app_secret, user_id, hashlib.sha256).hexdigest()

<?php

$appSecret = '<APP_SECRET>';
$userId = '<USER_ID>';
$hash = hash_hmac('sha256', $userId, $appSecret);

Headers

Pass the App-Key, computed hash and User-ID in the headers of the API call.

Name

Value

Apps

List all apps

GET /apps

List all apps available in Integry. If you need more, please reach out!

Query parameters

Name

Type

Description

Example

Required

Response

{
    "apps": [
        {
            "id": 410,
            "name": "pipedrive",
            "title": "Pipedrive",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
            "docs_url": "",
            "connected_accounts": [
                {
                    "id": 247714,
                    "display_name": "663----------8b1",
                    "modified_at": "2024-11-10T23:28:58Z"
                }
            ]
        },
        {
            "id": 24514,
            "name": "4me",
            "title": "4me",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/0d80bd3a-8207-426d-80e8-8aa75f5db662.png",
            "docs_url": "",
            "connected_accounts": []
        },
        {
            "id": 118,
            "name": "accelo",
            "title": "Accelo",
            "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/e36d9d8c-8188-40e9-9fbf-9f4b5433e4ee.png",
            "docs_url": "",
            "connected_accounts": []
        }
    ],
    "cursor": "E5JTNBMzklM0EzOS43NzA4MzclMkIwMCUzQTAw"
}

{
    "detail": "Authentication credentials were not provided."
}

Get an app

GET /apps/<app_name>

Get the details of an individual app by passing <app_name> as a path variable.

Response

{
    "id": 491,
    "name": "slack",
    "title": "Slack",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c53aa5ce-1ced-48cb-98cc-8859eb8bf85d.png",
    "docs_url": "",
    "connected_accounts": []
}

{
    "detail": "Authentication credentials were not provided."
}

Functions

List all functions

GET /functions

List all functions available in Integry. If you need more, make a passthrough request or reach out!

Query Parameters

Name

Type

Description

Example

Required

Response

{
    "functions": [
        {
            "name": "kit-tag-a-subscriber",
            "description": "Tag a subscriber by providing tag_id. Call kit-list-tags to get the tags.",
            "parameters": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": ""
                    },
                    "tag_id": {
                        "type": "string",
                        "description": ""
                    }
                },
                "required": [
                    "id",
                    "tag_id"
                ]
            }
        }
    ],
    "cursor": "cD0yMDI0LTExLTExKzEwJTNBNDAlM0EwMC42NjI3MjMlMkIwMCUzQTAw"
}

{
    "detail": "Authentication credentials were not provided."
}

Get a function

GET /functions/<function_name>

Get the JSON schema of an individual function by passing function name as a path variable.

Query Parameters

Name

Type

Description

Example

Required

Response

All supported function parameters are returned as keys, along with their type and description as key, value pairs. Required parameters are listed in the required array.

Sample response for pipedrive-add-a-person get function call:

{
    "name": "pipedrive-add-a-person",
    "description": "Adds a new person.",
    "parameters": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string",
                "description": "The name of the person"
            },
            "owner_id": {
                "type": "number",
                "description": "The ID of the user who owns the person. Call `pipedrive-get-all-users` to get the available values."
            },
            "org_id": {
                "type": "number",
                "description": "The ID of the organization linked to the person. Call `pipedrive-get-all-organizations` to get the available values."
            },
            "add_time": {
                "type": "string",
                "description": "The creation date and time of the person"
            },
            "emails": {
                "type": "array",
                "description": "The emails of the person",
                "items": {
                    "type": "string"
                }
            },
            "phones": {
                "type": "array",
                "description": "The phones of the person",
                "items": {
                    "type": "string"
                }
            },
            "visible_to": {
                "type": "number",
                "description": "The visibility of the person"
            },
            "label_ids": {
                "type": "array",
                "description": "The IDs of labels assigned to the person. Call `pipedrive-get-person-labels` to get the available values.",
                "items": {
                    "type": "number"
                }
            }
        },
        "required": []
    }
}

{
    "detail": "Function not found"
}

Call a function

POST /functions/<function_name>/

Query Parameters

Name

Type

Description

Example

Required

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

Body

Pass the function parameters in the request body.

Sample body for pipedrive-add-a-person function call:

{
    "name": "Sample contact"
}

Sample body for pipedrive-get-all-persons function call with next_page:

{
    "limit": 5,
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

Response

If Integry executes the function, it will respond with a 200 OK with following keys in the response body:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.
next_page: The cursor for the next page. It will only be present in responses of functions that support paginated calls. If there are no more pages, it will be empty.

If Integry does not execute the function, it will respond with a 400 Bad Request with following keys in the response body:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

Sample responses for pipedrive-add-a-person and pipedrive-get-all-persons:

// Function name: pipedrive-add-a-person
// Outcome: Person was created
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

// Function name: pipedrive-add-a-person
// Outcome: Validation error
{
    "network_code": "400",
    "output": {
        "success": false,
        "error": "Validation failed: owner_id: User not found or not accessible.",
        "code": "ERR_SCHEMA_VALIDATION_FAILED"
    }
}

// Function name: pipedrive-get-all-persons
// Outcome: Data was fetched with a next_page cursor.
{
    "network_code": "200",
    "output": [
        {
            "id": 1,
            "name": "[Sample] Phyllis Yang",
            "first_name": "[Sample] Phyllis",
            "last_name": "Yang",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-11T00:52:38Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [
                14
            ],
            "org_id": 5,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "240-707-3884",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "phyllis.yang@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 2,
            "name": "[Sample] Tony Turner",
            "first_name": "[Sample] Tony",
            "last_name": "Turner",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 1,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "218-348-8528",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "tony.turner@moveer.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 3,
            "name": "[Sample] Gloria Quinn",
            "first_name": "[Sample] Gloria",
            "last_name": "Quinn",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 2,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "862-252-9773",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "gloria.quinn@empowermmove.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 4,
            "name": "[Sample] Benjamin Leon",
            "first_name": "[Sample] Benjamin",
            "last_name": "Leon",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "785-202-7824",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "benjamin.leon@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 5,
            "name": "[Sample] Otto Miller",
            "first_name": "[Sample] Otto",
            "last_name": "Miller",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 3,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "601-906-7534",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "otto.miller@itablee.eu",
                    "primary": true
                }
            ]
        }
    ],
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- required parameter was missing
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": {
        "name": "This parameter is required and must not be null or empty"
    }
}

JS SDK Reference

This reference documents every object and method available in Integry’s browser-side JavaScript library, Integry.js.

Setting Up

Including Integry.js

To use the Integry JS SDK, you need to include it in your project. You can install it via npm:

npm install @integry/sdk

Or include it via a script tag:

<script src="https://unpkg.com/@integry/sdk/dist/umd/index.umd.js"></script>

Authentication

The Integry JS SDK requires an App-Key and a hash of App-Secret and User-ID to authenticate calls.

You can view and copy your App-Key and App-Secret from the Integry app.

User-ID is a unique string identifier for a user in your app. Function Calls and Integrations are associated to a user ID.

If your app has workspaces/accounts and you want integrations to be shared across all users in a workspace/account, use the workspace/account ID as the user ID.

Calculating the hash

Calculate the hash server-side using HMAC SHA256.

const crypto = require("crypto");

const userId = "";
const appSecret = "";

const hash = crypto
.createHmac("sha256", appSecret)
.update(userId)
.digest("hex");

import hmac
import hashlib

app_secret = b"<app_secret>"
user_id = b"<user_id>"

hash = hmac.new(app_secret, user_id, hashlib.sha256).hexdigest()

<?php

$appSecret = '<APP_SECRET>';
$userId = '<USER_ID>';
$hash = hash_hmac('sha256', $userId, $appSecret);

Initializing IntegryJS()

Call IntegryJS(authentication) with theApp-Key, computed hash and User-ID to create an instance of the Integry object.

const userId = "USER_ID"; // Your user's ID
const appKey = "YOUR_INTEGRY_APP_KEY";
const hash = "YOUR_GENERATED_HASH";

const integry = new IntegryJS({
    appKey,
    hash,
    user: {
        userId: userId,
    },
});

Emits event

This method emits a ready event if the access credentials are valid.

Listening to Events

Some SDK methods emit events (eg. ready, app-connected) that you can leverage to manipulate the user journey.

Call eventEmitter.on('<event_name>') method.

integry.eventEmitter.on('app-connected', (data) => {
    //do something here
});

Events emitted by the SDK are scoped to the instance on which the eventEmitter object is configured. There is no possibility of naming collision with global events, or even with the same event subscribed on multiple SDK instances.

Unsubscribe from an event

Call eventEmitter.unsub('<event_name>') method.

integry.eventEmitter.on('app-disconnected', (data) => {
    //do something here
});

Error Handling

All methods in the Integry JS SDK return Promises. It is recommended to always include .catch() to handle errors gracefully. Here is an example:

integry.connectApp("slack").then((connectedAccountId) => {
  console.log("Connected to Slack with account ID:", connectedAccountId);
}).catch((error) => {
  console.error("An error occurred:", error);
});

Apps

Integry supports many apps like Slack, Hubspot, or Jira.

Show apps

showApps(apps, renderMode, containerID)

Renders a marketplace-style listing of apps. You can show all apps or specific apps.

If you want to directly connect an app from your own marketplace, use connect(appName).

integry.showApps(
  ["slack", "mailchimp"],
  IntegryJS.MarketplaceRenderModes.INLINE,
  "marketplace-container"
).then(() => {
  console.log("Marketplace rendered in-line with specific apps.");
}).catch((error) => {
  console.error("Error rendering filtered marketplace:", error);
});

Method parameters

Name

Type

Description

Required

Emits events

app-connected

Fired when the user successfully connects an app. It includes the app details along with an array of connected_accounts sorted by modified_at in descending order.

{
    "id": 410,
    "name": "pipedrive",
    "title": "Pipedrive",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
    "docs_url": "",
    "connected_accounts": [
        {
            "id": 247714,
            "display_name": "663----------8b1",
            "modified_at": "2024-11-10T23:28:58Z"
        }
    ]
}

app-disconnected

Fired when the user disconnects an app. It includes the app details along with an array of remaining connected_accounts(if any) sorted by modified_at in descending order.

{
    "id": 410,
    "name": "pipedrive",
    "title": "Pipedrive",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
    "docs_url": "",
    "connected_accounts": []
}

Connect an app

connectApp(appName)

Invokes a UI flow to prompt the user to authenticate with the specified app. After the user connects, Integry verifies that it can access their account. It also refreshes the token, if needed.

Use this to connect apps if you are not using showApps() .

integry.connectApp("slack").then((connectedAccountId) => {
  console.log("Connected to Slack with account ID:", connectedAccountId);
}).catch((error) => {
  console.error("Failed to connect to Slack:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns a connectedAccountId (string).

If you use connectApp()to enable your users to connect multiple accounts for an app, you will need to use this ID when you disconnectApp(), showFunctionUI() and invokeFunction().

Disconnect an app

disconnectApp(appName, connectedAccountId)

Disconnects the user's connected account for an app.

integry.disconnectApp("slack").then(() => {
  console.log("Successfully disconnected from Slack");
}).catch((error) => {
  console.error("Failed to disconnect from Slack:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns a Promise which resolves if the account is disconnected.

Check if app is connected

isAppConnected(appName)

Checks if the user has connected the specified app.

integry.isAppConnected("slack").then((result) => {
  if(result) {
    console.log("User has connected Slack.");
  } else {
    console.log("User has not connected Slack.");
  }
  
}).catch((error) => {
  console.error("Failed to determine auth status:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns a boolean result. It will be true if the user has one (or more) connected account(s) with this app.

If your users have connected multiple accounts, use getConnectedAccounts() to get their IDs.

Get connected accounts of an app

getConnectedAccounts(appName)

Returns a user's connected accounts for an app.

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns an array of connected_accounts.

{
    "connected_accounts": [
        {
            "id": 247714,
            "display_name": "663----------8b1",
            "modified_at": "2024-11-10T23:28:58Z"
        }
    ]
}

Functions

Show the function UI

showFunctionUI(functionName, params, connectedAccountId)

Renders the UI for a specific function. This method shows the user a pre-filled form based on the provided action ID and parameters, allowing them to review and confirm the action before executing it.

const params = {
  channel: "general",
  message: "Hello, team!"
};

integry.showFunctionUI("slack-post-message", params, "abc123").then((result) => {
  console.log("Function parameters filled-in by the user:", result);
}).catch((error) => {
  console.error("Failed to load function UI:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns a result object with the filled-in arguments.

{
        "channel":"random",
        "text":"hello world from the other side"
}

Use it as params to invokeFunction().

Call a function

invokeFunction(functionName, params, connectedAccountId)

Invokes the specified function of an app with the provided parameters. Integry will automatically include your user's authentication credentials when making the onwards API call.

Integry will execute the function if the user has already connected their account for the function app, and all required parameters (if any) are provided in params. These function calls will show in the Function Calls log in the Integry app.

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

const params = {
  channel: "random",
  message: "hello world from the other side"
};
integry.invokeFunction("slack-post-message", params).then((result) => {
  console.log("Received response from Slack:", result);
}).catch((error) => {
  console.error("Failed to invoke function:", error);
});

Method parameters

Name

Type

Description

Example

Required

Sample params object for pipedrive-add-a-person function call:

{
    "name": "Sample contact"
}

The functions which fetch data from an app will often return pages of data and allow you to fetch further data by making subsequent calls. These functions use cursor-based pagination via the next_page parameter that is returned in the result (if there are more pages).

Sample params object for pipedrive-get-all-persons function call with next_page:

{
    "limit": 5,
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

Returns

If Integry executes the function, this method returns a result object with following keys:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.
next_page: The cursor for the next page. It will only be present in responses of functions that support paginated calls. If there are no more pages, it will be empty.

If Integry does not execute the function, this method returns a result object with following keys:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

Sample responses for pipedrive-add-a-person and pipedrive-get-all-persons:

// Function name: pipedrive-add-a-person
// Outcome: Person was created
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

// Function name: pipedrive-add-a-person
// Outcome: Validation error
{
    "network_code": "400",
    "output": {
        "success": false,
        "error": "Validation failed: owner_id: User not found or not accessible.",
        "code": "ERR_SCHEMA_VALIDATION_FAILED"
    }
}

// Function name: pipedrive-get-all-persons
// Outcome: Data was fetched with a next_page cursor.
{
    "network_code": "200",
    "output": [
        {
            "id": 1,
            "name": "[Sample] Phyllis Yang",
            "first_name": "[Sample] Phyllis",
            "last_name": "Yang",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-11T00:52:38Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [
                14
            ],
            "org_id": 5,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "240-707-3884",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "phyllis.yang@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 2,
            "name": "[Sample] Tony Turner",
            "first_name": "[Sample] Tony",
            "last_name": "Turner",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 1,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "218-348-8528",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "tony.turner@moveer.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 3,
            "name": "[Sample] Gloria Quinn",
            "first_name": "[Sample] Gloria",
            "last_name": "Quinn",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 2,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "862-252-9773",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "gloria.quinn@empowermmove.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 4,
            "name": "[Sample] Benjamin Leon",
            "first_name": "[Sample] Benjamin",
            "last_name": "Leon",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "785-202-7824",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "benjamin.leon@gmial.com",
                    "primary": true
                }
            ]
        },
        {
            "id": 5,
            "name": "[Sample] Otto Miller",
            "first_name": "[Sample] Otto",
            "last_name": "Miller",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 3,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "601-906-7534",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "otto.miller@itablee.eu",
                    "primary": true
                }
            ]
        }
    ],
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

// Function name: pipedrive-add-a-person
// Outcome: Error -- required parameter was missing
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": {
        "name": "This parameter is required and must not be null or empty"
    }
}

Get a function

getFunction(functionName)

Gets the signature for a specific function to understand the parameters.

integry.getFunction("slack-post-message").then((result) => {
  console.log("Function signature:", result);
}).catch((error) => {
  console.error("Failed to get function signature:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

This method returns a result object with the function's signature.

{
    "name": "slack-post-message",
    "description": "Post a message in a channel",
    "parameters": {
        "type": "object",
        "properties": {
            "text": {
                "type": "string",
                "description": "The content of the message."
            },
            "channel": {
                "type": "string",
                "description": "The channel to send the message in. Call `slack-list-conversations` to get the available values."
            },
            "as_user": {
                "type": "boolean",
                "description": "(Legacy) Pass true to post the message as the authed user instead of as a bot. Defaults to false. Can only be used by classic apps."
            },
            "attachments": {
                "type": "string",
                "description": "A JSON-based array of structured attachments, presented as a URL-encoded string."
            },
            "blocks": {
                "type": "array",
                "description": "A JSON-based array of structured blocks, presented as a URL-encoded string.",
                "items": {
                    "type": "string"
                }
            },
            "icon_emoji": {
                "type": "string",
                "description": "Emoji to use as the icon for this message. Overrides icon_url."
            },
            "icon_url": {
                "type": "string",
                "description": "URL to an image to use as the icon for this message."
            },
            "link_names": {
                "type": "boolean",
                "description": "Find and link user groups. No longer supports linking individual users; use syntax shown in Mentioning Users instead."
            },
            "metadata": {
                "type": "string",
                "description": "JSON object with event_type and event_payload fields, presented as a URL-encoded string. Metadata you post to Slack is accessible to any app or user who is a member of that workspace."
            },
            "mrkdwn": {
                "type": "boolean",
                "description": "Disable Slack markup parsing by setting to false. Enabled by default."
            },
            "parse": {
                "type": "string",
                "description": "Change how messages are treated."
            },
            "reply_broadcast": {
                "type": "boolean",
                "description": "Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation. Defaults to false."
            },
            "thread_ts": {
                "type": "string",
                "description": "Provide another message's ts value to make this message a reply. Avoid using a reply's ts value; use its parent instead."
            },
            "unfurl_links": {
                "type": "boolean",
                "description": "Pass true to enable unfurling of primarily text-based content."
            },
            "unfurl_media": {
                "type": "boolean",
                "description": "Pass false to disable unfurling of media content."
            },
            "username": {
                "type": "string",
                "description": "Set your bot's user name."
            }
        },
        "required": [
            "text",
            "channel"
        ]
    }
}

Passthrough requests

We have Functions for the most commonly used endpoints of 200+ apps.

Make a passthrough request via API

POST /<app_name>-passthrough-request

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

Body

Name

Type

Description

Required

Response

If Integry executes the function, it will respond with a 200 OK with following keys in the response body:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.

If Integry does not execute the function, it will respond with a 400 Bad Request with following keys in the response body:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

// Function name: slack-passthrough-request
// GET https://slack.com/api/conversations.list?limit=2

{
    "network_code": "200",
    "output": {
        "ok": true,
        "channels": [
            {
                "id": "C6F3LQ03A",
                "name": "random",
                "is_channel": true,
                "is_group": false,
                "is_im": false,
                "is_mpim": false,
                "is_private": false,
                "created": 1501486653,
                "is_archived": false,
                "is_general": false,
                "unlinked": 0,
                "name_normalized": "random",
                "is_shared": false,
                "is_org_shared": false,
                "is_pending_ext_shared": false,
                "pending_shared": [],
                "context_team_id": "T6F74R6TB",
                "updated": 1724807678577,
                "parent_conversation": null,
                "creator": "U6GKMKPE2",
                "is_ext_shared": false,
                "shared_team_ids": [
                    "T6F74R6TB"
                ],
                "pending_connected_team_ids": [],
                "is_member": true,
                "topic": {
                    "value": "Non-work banter and water cooler conversation",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "purpose": {
                    "value": "A place for non-work-related flimflam, faffing, hodge-podge or jibber-jabber you'd prefer to keep out of more focused work-related channels.",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "properties": {
                    "tabs": [
                        {
                            "id": "files",
                            "label": "",
                            "type": "files"
                        }
                    ]
                },
                "previous_names": [],
                "num_members": 7
            },
            {
                "id": "C6GKMKRUN",
                "name": "general",
                "is_channel": true,
                "is_group": false,
                "is_im": false,
                "is_mpim": false,
                "is_private": false,
                "created": 1501486653,
                "is_archived": false,
                "is_general": true,
                "unlinked": 0,
                "name_normalized": "general",
                "is_shared": false,
                "is_org_shared": false,
                "is_pending_ext_shared": false,
                "pending_shared": [],
                "context_team_id": "T6F74R6TB",
                "updated": 1731095674264,
                "parent_conversation": null,
                "creator": "U6GKMKPE2",
                "is_ext_shared": false,
                "shared_team_ids": [
                    "T6F74R6TB"
                ],
                "pending_connected_team_ids": [],
                "is_member": true,
                "topic": {
                    "value": "Channel for high priority, company-wide announcements and work-related matters. If you want to banter please head over to <#C02D3JZA45T|> if you want to discuss low priority items head over to <#G01L3PW2A01|integry-internal>",
                    "creator": "U6FQESQ02",
                    "last_set": 1632860908
                },
                "purpose": {
                    "value": "This channel is for team-wide communication and announcements. All team members are in this channel.",
                    "creator": "U6GKMKPE2",
                    "last_set": 1501486653
                },
                "properties": {
                    "tabs": [
                        {
                            "id": "files",
                            "label": "",
                            "type": "files"
                        }
                    ]
                },
                "previous_names": [],
                "num_members": 14
            }
        ],
        "response_metadata": {
            "next_cursor": "dGVhbTpDOFBLNUhOOTU="
        }
    }
}

// Function name: slack-passthrough-request
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Slack account. To connect an account, please call following SDK method: `connectApp('slack')`"
    ]
}

Make a passthrough request via SDK

invokeFunction(<app_name>-passthrough-request, params, connectedAccountId)

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

const params = {
  method: "GET",
  url: "https://slack.com/api/conversations.list?limit=2"
};
integry.invokeFunction("slack-passthrough-request", params).then((result) => {
  console.log("Received response from Slack:", result);
}).catch((error) => {
  console.error("Failed to invoke function:", error);
});

Method parameters

Name

Type

Description

Example

Required

Returns

If Integry executes the function, this method returns a result object with following keys:

network_code: HTTP response status code of the onwards API call made by Integry.
output: HTTP response body of the onwards API call made by Integry.

If Integry does not execute the function, this method returns a result object with following keys:

error: Summary of the error.
error_details[]: Detailed errors for individual fields (if applicable).

// Function name: pipedrive-passthrough-request
// POST https://api.pipedrive.com/api/v2/persons
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

// Function name: pipedrive-passthrough-request
// POST https://api.pipedrive.com/api/v2/persons
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

List all passthrough request functions

GET /functions?type=passthrough

List all passthrough request functions supported by Integry. See /functions for more options.

Docs

Getting Started

Welcome

Jump right in

Functions

Overview

What are Integry Functions?

Using Functions with Your AI

Additional Resources

Quickstart for AI

Set up the SDK

Enable your users to connect apps

Shows apps in the Integry marketplace

Show apps in your own marketplace

Connect apps when needed

Predict the function to invoke

Predict the function with Integry AI

Predict the function yourself

Prepare the arguments

Predict the arguments with Integry AI

Predict the arguments yourself

Show the Function UI to the user

Execute the function

Call invokeFunction()

Process the result

Next steps

Source functions

Populate dropdown options

Fetch custom fields

Call a source function

List all source functions

Passthrough requests

Make a passthrough request via API

Body

Response

Make a passthrough request via SDK

Method parameters

Returns

List all passthrough request functions

Flows

Overview

What is Integry Flows?

What's included?

APIs and SDKs

API Reference

Setting Up

Base URL

Authentication

Calculating the hash

Headers

Apps

List all apps

Query parameters

Get an app

Functions

List all functions

Query Parameters

Response

Get a function

Query Parameters

Response

Call a function

Query Parameters

Body

Response

Welcome

Jump right in

Overview

What is Integry Flows?

What's included?

Quickstart for AI

Set up the SDK

Enable your users to connect apps

Shows apps in the Integry marketplace

Show apps in your own marketplace

Connect apps when needed

Predict the function to invoke

Predict the function with Integry AI

Predict the function yourself

Prepare the arguments