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.

JS

const crypto = require("crypto");

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

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

Python

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

<?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
Content-Type	application/json
App-Key	<App key>
Hash	<App secret + User-ID hash>
User-ID	<User ID>

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
connected_only	boolean	Only return apps that the user has connected	true	false
cursor	string	Use the cursor to get the next page.	cD0yMDI0LTExLTEwKzE5JTNBMzklM0EzOS43NzA4MzclMkIwMCUzQTAw	false

Response

200

{
    "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"
}

400

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

200

{
    "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": []
}

400

{
    "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
app	string	Only return functions of an app	slack	false
type	string	Allowed values: query, mutation, passthrough	query	false
connected_only	boolean	Only return functions of apps that the user has connected	true	false
predict_function	boolean	Uses the prompt to predict one function. See Predict Function with Integry AI.	true	false
predict_arguments	boolean	Only allowed if predict_function=true. Uses the prompt to predict the arguments of the predicted function. See Predict Arguments with Integry AI.	true	false
prompt	string	Prompt to use to predict function (and arguments).	Send a message saying hello on slack	true if predict_function=true
cursor	string	Page size is 50. Use the cursor to get the next page.	cD0yMDI0LTExLTEwKzE5JTNBMzklM0EzOS43NzA4MzclMkIwMCUzQTAw	false
include	string	Include info for rendering the function UI. Allowed values: meta	meta	false

Response

200

{
    "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"
}

403

{
    "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
predict_arguments	boolean	Uses the prompt to predict the arguments of the function. See Predict Arguments with Integry AI.	true	false
prompt	string	Prompt to use to predict function (and arguments).	Send a message saying hello on slack	true if predict_arguments=true
include	string	Include info for rendering the function UI. Allowed values: meta	meta	false

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:

200

{
    "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": []
    }
}

404

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

Name	Type	Description	Example	Required
connected_account_id	Number	The ID of the connected account to use for calling the function. Only use if the user has connected multiple accounts.	32543	false

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:

200

// 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": []
        }
    }
}

200

// 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"
    }
}

200 (with next_page)

// 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": "[e-mail]",
                    "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": "[e-mail]",
                    "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": "[e-mail]",
                    "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": "[e-mail]",
                    "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": "[e-mail]",
                    "primary": true
                }
            ]
        }
    ],
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

400

// 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')`"
    ]
}

400

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