Custom Integrations

​

When to Build Custom Integrations

• Check if the service exists in Beam’s 1500+ integration catalog
• Have API documentation ready (OpenAPI spec preferred)
• Confirm authentication credentials and permissions

​

Building a Custom Integration

1

Access Integration Builder

Navigate to Integrations → “Create custom integration”

2

Configure Basics

Name: Clear, descriptive (e.g., “Acme CRM API”)Icon: Optional, for visual identificationCategory: Select appropriate category for filtering

3

Configure Authentication

Choose authentication method:API Key (Most common):

• Send via: Default, Bearer, Query, or Header
• Supports custom header names

Basic: Username and password (legacy systems)OAuth 2.0: Modern standard requiring Authorization URL, Access Token URL, Client ID/Secret, and Scopes

None: Public APIs without authentication

4

Define Tools and Actions

Manual Creation:

• Click “Add tool”
• Define name, description, endpoint, parameters

OpenAPI Import:

• Click “Import from URL”
• Provide OpenAPI spec URL
• System auto-generates tools

5

Configure Tool Details

API Endpoint:

• HTTP Method: GET, POST, PUT, PATCH, DELETE
• Endpoint URL with parameter placeholders
• Example: https://api.vendor.com/orders/{order_id}

Parameters:

• URL: Path variables ({order_id})
• Query: URL parameters (?status=completed)
• Body: JSON for POST/PUT/PATCH

Each parameter needs:

• Key (name)
• Type (String, Number, Boolean, Object, Array)
• Parameter hint (AI context)
• Required toggle

Test Tool: Validate with sample values before saving

6

Save and Add Connection

Click “Save” to create the integration

Your integration appears in the catalog:

Add Connection:

1. Find your custom integration
2. Click “Add a connection”
3. Provide credentials
4. Test and save

​

Using in Workflows

​

Adding Custom Integration to Nodes

1. Select Tool: Browse to your custom integration in node configuration
2. Choose Action: Pick specific API operation
3. Map Inputs: Use variable fill methods to pass data
4. Select Connection: Choose which credentials to use

​

Accessing Outputs

${node_name.field_name}

Order ID: ${get_order.order_id}
Status: ${get_order.status}
Total: ${get_order.total}

​

Authentication Methods

​

API Key

• Bearer: Authorization: Bearer {api_key}
• Header: Custom header name
• Query: URL parameter

​

OAuth 2.0

​

Basic

​

Schema Definition

​

OpenAPI Import

1. Provide OpenAPI spec URL
2. System generates tools automatically
3. Review and activate endpoints

​

Manual Schema

{
  "tool_name": "Get Order Details",
  "description": "Retrieve order information",
  "required_extracted_args": [
    "order_id: string // Order identifier"
  ],
  "integration_provider_details": {
    "request": {
      "method": "GET",
      "endpoint": "https://api.vendor.com/orders/{order_id}"
    },
    "response": {
      "order_id": "{{result.data.id}}",
      "status": "{{result.data.status}}"
    }
  }
}

​

Testing

1. Open tool configuration
2. Click “Test tool” tab
3. Provide sample values
4. Verify response structure

• Build minimal flow with static data
• Run task manually
• Review execution results
• Verify data flows to next nodes

​

Common Errors

​

Advanced Patterns

https://api.vendor.com/tenants/{tenant_id}/orders/{order_id}

​

Best Practices

• Never expose API keys in logs
• Separate credentials for dev/staging/prod
• Rotate credentials regularly

• Minimize unnecessary requests
• Cache frequently accessed data
• Respect rate limits

• Document API version in integration name
• Test after API updates
• Monitor provider changelogs

​

Examples

​

Internal CRM

• Auth: API Key (Header)
• Tools: Get Customer, Create Customer, Update Status
• Use: Workflow creates CRM record on signup

​

Legacy ERP

• Auth: Basic Authentication
• Tools: Query Inventory, Create PO, Update Status
• Use: Check inventory before order, create PO if low

​

Microservices

• Auth: OAuth 2.0 (Client Credentials)
• Tools: Process Order, Calculate Shipping, Validate Payment
• Use: E-commerce workflow orchestrates multiple services

​

Next Steps