1 of 1

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.

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