Pre-built integrations cover common tools. But business systems are diverse. Your organisation might use industry-specific software, custom-built applications, or services too niche for pre-built connectors.
SwiftCase's configurable API system solves this. Connect to any system with a REST API. No custom development required. Configure endpoints, authentication, and data mapping through the user interface. Webhooks handle the reverse: receiving data from external systems when events occur.
This guide explains how to use these capabilities to connect SwiftCase to virtually any external system.
Understanding the Integration Architecture
Outbound: Calling External APIs
SwiftCase can send requests to external systems:
Trigger: a workflow action, user button click, or scheduled task initiates the API call.
Request: SwiftCase constructs an HTTP request with the configured endpoint, method, headers, and body.
Response: the external system returns data that SwiftCase captures and processes.
Action: captured data updates case fields, triggers further workflow steps, or displays to users.
This pattern handles any scenario where SwiftCase needs to push data out or pull data in from external systems.
Inbound: Receiving Webhooks
External systems can send data to SwiftCase:
Event: something happens in the external system. A payment is received. A document is signed. A status changes.
Request: the external system sends an HTTP request to a SwiftCase webhook endpoint.
Processing: SwiftCase receives the data, validates it, and processes according to configuration.
Action: incoming data creates cases, updates existing records, triggers workflows, or logs information.
Webhooks enable real-time integration without polling. Events flow immediately when they occur.
Configuring API Connections
Defining the Connection
Each API connection requires basic configuration:
Name and description: identify the connection for reference. Clear names like "Address Lookup Service" or "Payment Gateway" help staff understand what connects where.
Base URL: the root address of the API. All endpoints build from this base. For example, https://api.example.com/v2.
Authentication method: how the API verifies requests. SwiftCase supports seven methods to cover virtually any API.
Default headers: headers that apply to all requests. Content type, API version, and other standard headers configure here.
Timeout settings: how long to wait for responses before considering requests failed.
Authentication Methods
SwiftCase supports extensive authentication options:
OAuth 2.0: the modern standard for API authentication. SwiftCase handles the token exchange, refresh, and management automatically. Common for major platforms like Microsoft, Google, and Salesforce.
OAuth 1.0: older OAuth version still used by some APIs. More complex signing requirements handled automatically.
Bearer token: simple token-based authentication. Provide the token; SwiftCase includes it in request headers.
Basic authentication: username and password authentication. Credentials encode automatically in request headers.
API key: key-based authentication through headers or query parameters. Configure where the key appears in requests.
AWS Signature: signing method required for AWS services. SwiftCase handles the complex signing algorithm.
Digest authentication: challenge-response authentication for legacy systems.
Defining Endpoints
Within a connection, define specific endpoints:
Path: the specific API path, appending to the base URL. Use placeholders for dynamic values: /customers/{customer_id}/invoices.
Method: HTTP method (GET, POST, PUT, PATCH, DELETE) appropriate for the operation.
Headers: endpoint-specific headers beyond connection defaults.
Query parameters: URL parameters for the request. Static values or mapped from case data.
Request body: for POST, PUT, and PATCH requests, define the body structure. JSON templates with placeholders for case data.
Response Mapping
Configure how API responses update SwiftCase:
Response parsing: define expected response structure. SwiftCase extracts data from JSON responses automatically.
Field mapping: map response fields to case fields. The API returns {"customer_id": "12345"}; that value maps to your Customer Reference field.
Array handling: for responses containing multiple items, configure how to handle each element.
Error handling: define how to recognise and respond to error conditions in responses.
Practical API Integration Examples
Address Lookup
Verify and complete addresses using a postcode lookup service:
Trigger: user enters a postcode in a case form.
API call: GET request to address service with postcode as parameter.
Response: list of matching addresses returns.
Action: user selects correct address; fields populate automatically.
Configuration involves:
- Create connection to address service with API key authentication
- Define GET endpoint with postcode parameter
- Map response fields to address fields
- Configure workflow trigger on postcode entry
Company Information Retrieval
Pull company data from Companies House or similar registries:
Trigger: user enters company registration number.
API call: GET request with registration number.
Response: company details including registered address, directors, and filing history.
Action: case fields populate with verified company information.
This ensures accurate data without manual research.
Credit Check Integration
Check customer creditworthiness through external services:
Trigger: new customer case reaches verification stage.
API call: POST request with customer details.
Response: credit score, risk rating, and recommendations.
Action: case updates with credit information; workflow routes based on risk level.
Automated checks replace manual credit assessment processes.
SMS Notifications
Send SMS messages through providers like Twilio:
Trigger: workflow reaches notification stage.
API call: POST request with phone number and message content.
Response: confirmation of message submission.
Action: case logs the notification; delivery status updates via webhook.
Messages send automatically as part of case processing.
Document Generation Services
Generate documents through external services:
Trigger: case requires a document.
API call: POST request with template ID and merge data.
Response: generated document URL or content.
Action: document attaches to case; workflow continues.
External generation services complement SwiftCase's built-in document capabilities.
Configuring Webhooks
Creating Webhook Endpoints
Define endpoints where external systems send data:
Endpoint URL: SwiftCase generates a unique URL for each webhook. This URL goes into the external system's configuration.
Authentication: options include shared secrets, signature verification, or IP whitelisting depending on security requirements.
Payload expectations: define expected data structure so SwiftCase knows how to parse incoming requests.
Processing Incoming Data
Configure what happens when webhooks arrive:
Validation: verify the request is legitimate before processing. Check signatures, tokens, or other authentication.
Parsing: extract relevant data from the incoming payload.
Matching: for updates to existing records, define how to find the correct case. Reference numbers, external IDs, or other identifiers.
Action: create new cases, update existing ones, trigger workflows, or log events.
Common Webhook Scenarios
Payment notifications: payment processors send webhooks when payments succeed, fail, or are refunded. Cases update automatically to reflect payment status.
Document signing: DocuSign, HelloSign, and similar services send webhooks when documents are signed. Cases advance automatically upon completion.
Form submissions: external forms can submit to SwiftCase webhooks. New cases create from form data without manual entry.
Status updates: external systems tracking deliveries, applications, or processes can push status changes to SwiftCase.
Scheduled events: calendar systems can send webhooks for appointment reminders or deadline notifications.
Building Complex Integrations
Multi-Step API Sequences
Some integrations require multiple API calls:
Sequential calls: one call's response provides data for the next. Look up customer ID, then retrieve their invoices, then check payment status.
Conditional calls: based on initial response, different subsequent calls might be needed.
Aggregation: combine data from multiple sources into unified case information.
SwiftCase workflows can orchestrate complex sequences, calling APIs in order and passing data between steps.
Bidirectional Synchronisation
Keep data consistent across systems:
Outbound on change: when case data changes in SwiftCase, push updates to external systems via API.
Inbound via webhook: when external systems change, receive updates via webhook.
Conflict handling: define how to handle situations where both systems change simultaneously.
True synchronisation requires careful design to avoid loops and conflicts.
Error Handling and Retry
Integrations fail sometimes. Handle failures gracefully:
Automatic retry: configure retry attempts for failed requests. Exponential backoff prevents overwhelming struggling services.
Error notification: alert staff when integrations fail so issues can be investigated.
Manual retry: provide options to retry failed integrations manually after problems are resolved.
Fallback processing: when automated integration isn't possible, route to manual handling.
Security Considerations
Credential Management
Protect API credentials appropriately:
Secure storage: SwiftCase stores credentials securely, encrypted at rest.
Access control: limit who can view or modify integration credentials.
Credential rotation: plan for periodic credential updates as a security practice.
Data in Transit
Protect data moving between systems:
HTTPS required: all API connections use encrypted HTTPS connections.
Certificate validation: SwiftCase verifies external system certificates to prevent man-in-the-middle attacks.
Sensitive data handling: consider what data flows through integrations and whether it's appropriate.
Webhook Security
Protect incoming webhooks:
Authentication: require some form of authentication on webhook endpoints.
Signature validation: for systems that sign payloads, verify signatures before processing.
IP restrictions: where external system IPs are known, restrict webhook access to those addresses.
Rate limiting: protect against abuse by limiting incoming request rates.
Testing Integrations
Development Testing
Test before production deployment:
Sandbox environments: many services offer sandbox or test environments. Connect to these first.
Test data: use test cases with known data to verify expected results.
Response simulation: some services provide tools to simulate various responses for testing.
Request Logging
Understand what's happening:
Full request logging: SwiftCase logs complete request and response details for debugging.
Log review: check logs when integrations don't behave as expected.
Sensitive data: configure logging to exclude sensitive data where appropriate.
Production Monitoring
Watch integrations after deployment:
Success rates: track what percentage of integration calls succeed.
Response times: monitor how long integrations take. Slow integrations might indicate problems.
Error patterns: look for patterns in failures that might indicate systemic issues.
Best Practices
Start Simple
Begin with straightforward integrations:
Single purpose: each integration should do one thing well before expanding scope.
Minimal data: transfer only necessary data. Extra fields complicate debugging.
Clear triggers: ensure integration triggers are obvious and predictable.
Document Everything
Create reference documentation:
Integration inventory: list all active integrations with their purposes.
Configuration details: document authentication, endpoints, and mappings.
Data flows: diagram what data moves where and when.
Troubleshooting guides: capture common issues and resolutions.
Plan for Failure
Integrations will fail eventually:
Graceful degradation: systems should work, if imperfectly, when integrations fail.
User feedback: when integrations fail, inform users appropriately.
Recovery procedures: document how to recover from various failure scenarios.
Monitor and Maintain
Integrations require ongoing attention:
Regular review: periodically review integration performance and relevance.
API changes: external APIs change. Monitor for deprecations and updates.
Security updates: keep authentication credentials current.
Advanced Patterns
API Orchestration
Combine multiple APIs into unified processes:
Customer verification: check identity service, credit bureau, and sanctions list in sequence.
Order processing: verify inventory, process payment, arrange shipping through different providers.
Data enrichment: gather information from multiple sources to build complete pictures.
Event-Driven Architecture
Build systems that respond to events:
Event sources: webhooks, status changes, and scheduled triggers all generate events.
Event processing: consistent handling regardless of event source.
Event chains: events can trigger further events, creating sophisticated automated processes.
Custom API Development
For unique requirements:
SwiftCase API: SwiftCase exposes its own API, enabling external systems to interact with your operational data.
Middleware: for complex transformations, middleware services can sit between SwiftCase and external systems.
Custom development: when configuration doesn't suffice, custom integrations remain an option.
Moving Forward
SwiftCase's API and webhook capabilities extend integration possibilities beyond pre-built connectors. Any system with a REST API becomes accessible. Any system that sends webhooks can push data in.
The configurable approach means operations teams can build integrations without waiting for development resources. The same people who understand the business processes can connect the systems that support them.
Start with your highest-value integration opportunity. A single successful connection proves the approach and builds confidence for expansion. The goal is an operational platform that connects seamlessly to whatever systems your organisation uses, now and in the future.
Ready to connect SwiftCase to your systems?
Tell us what systems you need to integrate. We'll show you how SwiftCase's configurable API system connects to your specific tools and help you design effective integration workflows.