API Introduction | iPaaS.com

Overview

iPaaS.com is API-first — everything you can do in our platform can be accomplished through API calls. Our database is accessed exclusively through the API, and our UI is entirely API-driven.

Important:

If you aren't familiar with working with an API and Swagger, you may experience the following issues:

Incorrect API Calls: Leading to errors, unexpected responses, or failure to retrieve and submit data.
Data Corruption or Loss: Improperly structured requests or misunderstanding of API operations could unintentionally modify or delete critical data or configuration.
System Instability: Malformed requests or excessive or improper API usage could impact system performance or availability.
Security Vulnerabilities: Misconfiguration or misunderstanding of authentication and authorization mechanisms could expose sensitive information.
Wasted Time and Resources: Significant time may be lost troubleshooting issues that stem from a lack of understanding of API principles and Swagger documentation.

Proceed with caution and ensure you have the necessary skills and understanding before interacting with this system.

The iPaaS.com API enables you to:

Subscribers: Manage subscriptions and mapping configurations, plus perform CRUD (Create, Read, Update, and Delete) operations.
Integrators: Manage private and certified integrations.
Managed integration Service Providers (MiSPs): Automate subscriber account relationships.

Key Points:

Role-based permissions are managed via API.

Authenticate using username/password or API tokens.
Tokens must be regenerated when roles or users are updated.

Authentication

Choose between two authentication methods:

Method 1: User Credentials

Since users operate across multiple companies, authorizations are maintained at the company level, not the user level.

Authentication Flow:

User Login → /v2/Auth/Login
- Provide username and password.
- Receive initial access_token.
Get Company IDs → /v2/User/{id}/Companies (Optional if you know the company_id)
- Use the access token from step 1.
- Returns a list of affiliated companies.
Get Company Authorization → /v2/User/ChangeCompany/{id}
- Provide company_id and user access_token.
- Receive an updated token with company authorizations.

Method 2: API Key

If your company has issued an API Key, it comes preconfigured with all approved company authorizations. If you need to create an API key, see API Keys in User & Role Management for details.

Making Authorized Requests

Once you have a valid access token, include it in your request headers:

curl -X 'GET' \
  'https://api.ipaas.com/subscriptions/v2/Events?pageNumber=1&pageSize=100' \
  -H 'accept: text/plain' \
  -H 'Authorization: {your_access_token}'

Error Handling

Error Response Format: Error messages are returned as plaintext in the response body.

HTTP Status Codes

Code	Status	Description
200	OK	Successful request
201	Created	A new resource has been successfully created
400	Bad Request	Invalid JSON, missing required fields, or validation errors encountered
401	Unauthorized	Missing, invalid, or insufficient API token permissions
404	Not Found	The requested resource does not exist at the specified API
429	Too Many Requests	The rate limit was exceeded. See Working with API Rate Limits.
5XX	Server error	There is an internal iPaaS.com server error

Rate Limits

You may encounter 429 Too Many Requests errors in two scenarios:

Monthly API Limits: Based on your billing plan.
- Plans with overage allowance: Additional charges apply beyond limits.
- Plans without overage: API calls blocked after limit reached.
Volume Restrictions: Temporary limits when resources are overwhelmed.

The error message will specify whether the limit is monthly or volume-based.

Pagination

Pagination metadata is returned in the X-Pagination header as JSON. For example:

{
   "total_Count":165,
   "page_Size":100,
   "current_Page":1,
   "total_Pages":2,
   "previous_Page":"No",
   "next_Page":"Yes"
{

Metadata Fields:

total_Count: Total records available
page_Size: Records per page
current_Page: Current page number
total_Pages: Total number of pages
previous_Page/next_Page: Navigation flags ("Yes"/"No")

Response Format

Successful requests: Return the requested, modified, or created data.
PUT/POST requests: Include the complete updated resource.
Error responses: Return error messages as plaintext.

API Versioning

Current Version: V2
Upcoming: V3 (backwards compatible with V2)
Compatibility: Currently, we do not expect to launch any API versions or endpoints that are not backwards compatible.

BigCommerce Connections and Settings

Accessing the API

Orderful Connections and Settings

Philips Hue Connections and Settings

Syncing a Large Dataset using iPaaS.com and Postman Runner