What is Unipile?

Unipile is an innovative API designed to provide seamless integrations of various messaging, mailing and social services into your application.

We call platforms like LinkedIn, Google, WhatsApp... a Provider, as it provides the data.

Each Provider API is different in term of design, data modelling, authentication and have their own specificities. They are not always public or well documented, so it can become a hassle to implement and maintain your own connector to each of them.

This is where Unipile comes in:

• Hassle free authentication. Let your users authenticate their Provider Accounts easily with Passwords, QR Code scanning, 2FA, OTP, Oauth... with few lines of code only.
• Unified API design for all providers. For exemple, a Message object from LinkedIn and Instagram have the same schema. The request to get a list of chats is the same for LinkedIn and Instagram. Learn once, integrate everything!
• Simple yet powerful Realtime. Use webhooks to receive new data (Messages, Emails, Posts...) in realtime, without the need to setup servers that maintain opened connections through various protocols.
• Connector maintenance handled by Unipile. When a provider changes its API or behavior, we investigate and update the connector so you do not have to maintain a separate integration for every provider.
• Developer first experience. Unipile provide a fully documented API along tools to easily debug your integrations, including mock accounts and webhook logs.

---

Building on third-party providers

Unipile is an integration layer between your application and third-party providers. Your application calls Unipile, and Unipile in turn authenticates with and interacts with those providers on behalf of connected accounts.

This removes the need to build and continuously maintain a separate connector for every provider. However, it also means that the end-to-end integration depends on systems and interfaces that Unipile does not control.

API availability and provider connectivity are different

There are two distinct layers of availability:

• Unipile API availability: whether your application can reach and use the Unipile platform.
• Provider connectivity: whether Unipile can currently authenticate with and use a provider for a connected account or product.

An API request can reach Unipile successfully while the provider connection required to complete the operation is unavailable. Likewise, linking an account confirms that it is operational at that moment; it does not guarantee that provider connectivity will remain continuously available for any duration.

Unipile can operate and monitor its own API infrastructure, but it cannot guarantee the availability or behavior of third-party provider systems.

Why provider connectivity can change

Provider integrations do not all rely on stable, public APIs. Some interfaces are private, undocumented, partially documented, or subject to change without notice. In those cases, Unipile may receive no advance notice of a change and may not have a dedicated provider support channel for the integration.

Connectivity can also be affected when:

• A provider changes an authentication flow, endpoint, data model, restriction, or internal behavior.
• A session expires or is revoked, credentials change, or the provider requires the user to authenticate again.
• The provider experiences an outage, slowdown, or degraded service.
• A proxy or another network dependency becomes unavailable.
• The provider applies a rate limit, anti-abuse measure, account restriction, or feature-specific limitation.

As a result, temporary disconnections, service interruptions, failed API Methods, and pauses in provider-derived realtime events are expected failure modes. Their cause can be Unipile, the provider, a proxy, the network, or the account's authentication state.

What Unipile handles

When a provider changes or an integration fails, Unipile takes responsibility for:

• Monitoring connectors and detecting connectivity problems.
• Investigating failures and identifying their origin when possible.
• Retrying recoverable interruptions.
• Updating and deploying connectors in response to provider changes.
• Exposing normalized Connection Status, error responses, and webhooks so your application can react consistently across providers.

Unipile aims to expose as many useful and consistent signals as possible so that error handling remains straightforward to implement. Instead of requiring provider-specific recovery logic for every integration, your application can rely on normalized statuses, error types, lifecycle events, retries, and reconnection flows.

This transfers connector maintenance to Unipile; it does not make the underlying third-party dependency infallible or eliminate temporary interruptions from the system.

What your application must handle

Error handling must be more defensive than for an API that fully controls the system behind every operation. A provider-dependent operation crosses two service boundaries—your application to Unipile, then Unipile to the provider—and the second boundary can change or become unavailable independently of the first.

Build your application with provider connectivity as a dynamic state rather than a permanent property of an account. Temporary failures are not exceptional cases that can be ignored: comprehensive error handling is a core requirement of a production Unipile integration.

Your application must:

• Listen for account.status.* webhooks and reflect status changes in your application and user interface.
• Handle API errors without causing unrelated parts of your application to fail.
• Pause workflows that depend on an unavailable account or product and resume them when connectivity returns.
• Prompt the account owner to reconnect when authentication is required.
• Avoid asking users to reconnect during a service interruption that does not require their action.
• Reconcile provider data after recovery when missing an event would affect data consistency.

When an existing account, API Method, or realtime workflow stops working, follow Troubleshoot Connection Issues to identify the affected layer and the appropriate recovery action.

Responsibility boundary

Unipile is responsible for operating its platform, maintaining its connectors, investigating provider changes, and exposing the tools your application needs to detect and handle connectivity changes. Unipile cannot control or prevent provider outages, unannounced provider changes, session revocations, account restrictions, user actions, proxy failures, or other provider-controlled behavior.

Your application is responsible for using the available connection statuses, account.status.* webhooks, API errors, retries, and reconnection flows. Providing these mechanisms is Unipile's responsibility; implementing and acting on them is the responsibility of the application operator.

If your application assumes that a connected account will remain permanently available, ignores these signals, or allows a provider interruption to break unrelated functionality, the resulting application failure is the responsibility of your application—not a failure of the status and recovery mechanisms provided by Unipile. Unipile cannot be held responsible for downstream application failures caused by the application's failure to implement these documented mechanisms.

In particular, continuous provider connectivity is not guaranteed, and a provider-side interruption is not equivalent to downtime of the Unipile API. Integrating Unipile without implementing the documented error and lifecycle handling does not transfer responsibility for the resulting downstream failures to Unipile.

---

Core Concepts

1. Platform Management

Organizations are collaborative workspaces where teams manage applications and billing together.

Applications are containers that group related resources (accounts, API keys, webhooks) within an organization. You can create multiple applications to separate different environments or products.

2. Provider Accounts

A Provider is an external platform (LinkedIn, Gmail, WhatsApp, etc.) that provides data through Unipile.

A Provider Account is a user account from one of these providers that has been linked to Unipile. Once linked, you can interact with that account through Unipile's unified API.

3. Methods

Methods are API endpoints that provide access to read, write, and update resources from providers. They are organized into API groups: Messaging, Emails, Calendar, Users, Posts, and provider-specific APIs.

Unipile adds a layer of security with built-in cache and rate limiters to prevent bot detection.

4. Realtime

Webhooks allow your application to receive instant notifications about events occurring on connected accounts (new messages, emails, account status changes, etc.) instead of polling the API repeatedly.

Configure a webhook endpoint URL, select which events you want to receive, and Unipile will send HTTPS POST requests to your endpoint when events occur.

---

The Unipile Workflow

To start using Unipile, follow these essential steps:

1. Create a Unipile account → Sign up and create your organization on the Dashboard V2
2. Create an Application → Set up your application within your organization
3. Link Provider Accounts → Connect accounts from providers (LinkedIn, Gmail, WhatsApp, etc.)
4. Create API Keys → Generate authentication keys for your application
5. Call Methods → Use the unified API with the API Key to interact with provider data
6. Setup Webhooks → Configure real-time event notifications

---

Next Steps

Explore each concept in depth: