Setting Up API Connections

API connections allow you to send and receive EDI files via HTTP/HTTPS endpoints. This is useful for integrating with custom systems, webhooks, or partners with API-based interfaces.

When to Use API Connections

API connections are best for:

• Partners with REST API endpoints for file delivery
• Custom integrations with business applications
• Webhook-based workflows
• Real-time file delivery needs

Information You Need

Get the following from your partner:

Authentication Methods

Modalius supports several authentication methods for API connections. If the API does not require authentication, you can leave the credential unset.

Basic Authentication

Username and password sent in the Authorization header. Credentials are base64-encoded.

API Key / Header Value

A token or key sent in a custom header. You specify:

• Header name - e.g., "X-API-Key" or "Authorization"
• Prefix - Optional, e.g., "Bearer" or "Token"
• Value - The API key or token

OAuth 2.0

Token-based authentication using OAuth 2.0 flow. Modalius will:

1. Request an access token from the OAuth endpoint
2. Include the token in subsequent requests
3. Refresh tokens as needed

To enable OAuth, click Add OAuth during connection setup and provide the Token URL, request method, OAuth credential, and optional header prefix.

File Delivery Options

Files can be delivered in two formats:

Multipart Form (Default)

File is sent as a multipart form attachment. This is the standard approach for file uploads.

Custom Payload

For partners requiring a specific JSON or XML format, you can define a custom payload template. Use placeholders:

• [[filename]] - Replaced with the file name
• [[filecontent]] - Replaced with base64-encoded file content

Setting Up an API Connection

1. Navigate to Connections & Routing in the sidebar
2. Click Add Connection
3. Select API as the connection type
4. Enter a Connection Name and the Endpoint URL
5. Select the HTTP Method (POST, GET, PUT, or PATCH) and set the Expected Response Code
6. Optionally select or create a credential for authentication (select "None" if the API does not require it)
7. Optionally define a Payload Specification for custom request formats
8. Optionally click Add Health Check to configure a health check endpoint and method
9. Optionally click Add OAuth to configure OAuth 2.0 token-based authentication
10. Click Save
11. Test the connection to verify it works

Adding Routing Rules

After creating the connection, add routing rules to control how files are delivered:

1. Open the connection detail page
2. Go to the Routing Rules tab
3. Click Add a Routing Rule
4. Configure the direction, business unit, and any file filters
5. Click Save

Connection Health

If you configure a health check URL, Modalius will:

• Monitor the endpoint availability
• Update the connection health indicator
• Queue files if the endpoint becomes unreachable
• Automatically retry when connectivity is restored