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

In the workspace sidebar, open Integrations, then select Create custom integration.

2

Configure Basics

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

3

Configure Authentication

Select None, API Key, Basic, or OAuth (2.0). Add any required custom header keys and values in the header table.

4

Define Tools and Actions

Choose Add tool for manual tool setup or Import from URL to start from a specification URL. The builder also provides a Bypass SSL verification option.

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

Select Save to create the integration. Select Discard to leave the builder without saving.

​

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