Create Integration

Create a new integration. Typically used to add new custom integrations or to register a new API integration in your Truto account.

Endpoint

http

POST /integration

Request Body

name

string

REQUIRED ·

The name of your integration.

Example: my_custom_crm

Response Body

string · uuid

The ID of the integration.

Example: 4a4de828-f4db-4c9e-adfd-434e0864c3c7

name

string

The name of the integration.

Example: zendesk

category

string

The category of the integration.

Example: helpdesk

is_beta

boolean

Whether the integration is in beta or not. Beta integrations might not have been tested completely and are not recommended for production environments.

config

object

The configuration object defining the underlying API of the integration.

Example:

{
  "base_url": "https://api.example.com",
  "label": "Example API Integration",
  "logo": "https://example.com/logo.png",
  "icon": "https://example.com/icon.png",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "User-Agent": "truto"
  },
  "query": {
    "search": "{{search_query}}",
    "filter": "{{filter_criteria}}"
  },
  "query_array_format": "comma",
  "actions": {
    "sync_users": {
      "type": "request",
      "config": {
        "method": "post",
        "path": "/sync/users",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "body": {
          "users": "{{context.users}}"
        }
      }
    }
  },
  "credentials": {
    "oauth2": {
      "format": "oauth2",
      "config": {
        "client": {
          "id": "your-client-id",
          "secret": "your-client-secret"
        },
        "auth": {
          "tokenHost": "https://auth.example.com",
          "tokenPath": "/oauth/token",
          "refreshPath": "/oauth/refresh"
        },
        "options": {
          "scopeSeparator": " ",
          "authorizationMethod": "header",
          "bodyFormat": "form"
        },
        "fields": [
          {
            "name": "client_id",
            "label": "Client ID",
            "type": "text",
            "required": true
          },
          {
            "name": "client_secret",
            "label": "Client Secret",
            "type": "password",
            "required": true
          }
        ],
        "tokenParams": {
          "grant_type": "client_credentials"
        },
        "refreshParams": {
          "grant_type": "refresh_token"
        },
        "tokenExpiryDuration": "3600"
      }
    }
  },
  "authorization": {
    "format": "bearer",
    "config": {
      "token": "{{oauth.token.access_token}}"
    }
  },
  "pagination": {
    "format": "page",
    "config": {
      "page_key": "page",
      "limit_key": "per_page"
    }
  },
  "rate_limit": {
    "is_rate_limited": true,
    "retry_after_header_expression": "Retry-After",
    "rate_limit_header_expression": "X-RateLimit-Remaining"
  },
  "resources": {
    "users": {
      "list": {
        "method": "get",
        "path": "/users",
        "response_path": "data.users",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "query": {
          "page": "{{pagination.page}}",
          "per_page": "{{pagination.per_page}}"
        },
        "pagination": {
          "format": "page",
          "config": {
            "page_key": "page",
            "limit_key": "per_page"
          }
        },
        "authorization": {
          "format": "bearer",
          "config": {
            "token": "{{oauth.token.access_token}}"
          }
        },
        "rate_limit": {
          "is_rate_limited": true,
          "retry_after_header_expression": "Retry-After",
          "rate_limit_header_expression": "X-RateLimit-Remaining"
        },
        "examples": {
          "response": "{\n  \"data\": {\n    \"users\": [\n      {\n        \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n        \"name\": \"John Doe\",\n        \"email\": \"john.doe@example.com\"\n      }\n    ]\n  }\n}\n"
        }
      }
    },
    "orders": {
      "create": {
        "method": "post",
        "path": "/orders",
        "body": {
          "user_id": "{{context.user_id}}",
          "items": "{{context.items}}"
        },
        "response_path": "data.order",
        "headers": {
          "Authorization": "Bearer {{oauth.token.access_token}}"
        },
        "authorization": {
          "format": "bearer",
          "config": {
            "token": "{{oauth.token.access_token}}"
          }
        }
      }
    }
  },
  "webhook": {
    "signature_verification": {
      "format": "HMAC-SHA256",
      "config": {
        "secret": "your-webhook-secret",
        "algorithm": "sha256",
        "parts": [
          "header",
          "body"
        ]
      }
    },
    "handle_verification": "verify_webhook_signature"
  },
  "error_expression": "{{response.error}}"
}

team_id

string · uuid

The ID of the team that owns this integration.

Example: 05daecaf-4365-42e8-8370-8127de5dd717

sharing

string

The sharing policy of the integration.

All possible enum values:

allow
ask
deny

Example: allow

created_at

string · date-time

The date and time when the integration was created.

Example: 2021-08-10T10:00:00.000Z

updated_at

string · date-time

The date and time when the integration was last updated.

Example: 2021-08-10T10:00:00.000Z

installed_environment

string[]

A list of environment IDs where this integration is installed.

team

object

The team that owns this integration.

string · uuid

The ID of the team.

Example: 05daecaf-4365-42e8-8370-8127de5dd717

name

string

The name of the team.

Example: My Awesome Team

domain

string

The domain of the team.

Example: example.com

logo

string

The URL of the team's logo.

Example: https://example.com/logo.png

is_verified

boolean

Whether the team is verified or not.

Example: true

is_white_label

boolean

Whether the team is white-labeled or not.

tos_link

string

A link to the team's Terms of Service, if available.

Example: https://example.com/tos

allow_impersonation

boolean

Whether the team allows impersonation.

created_at

string · date-time

The date and time when the team was created.

Example: 2021-08-10T10:00:00.000Z

updated_at

string · date-time

The date and time when the team was last updated.

Example: 2021-08-10T10:00:00.000Z