Applications

Connect your SaaS to your customers' Phone.inc accounts. Customers choose which data to share, and your application gets access through OAuth—not their passwords or API keys.

If you only need an internal script for your own company, use an API key. This guide is for products that other Phone.inc companies install.

What you can build

Use the existing API, provide customer information when the phone rings, or do both:

Log calls in a CRM. Read call history, recordings, transcripts, and summaries to attach a conversation to the right customer record.
Create follow-up workflows. React to call or voicemail webhooks, create a task in your SaaS, or send a text with the customer's permission through the texting API.
Show customer context during a call. Return open support tickets, recent orders, or account details from your SaaS so the employee knows who's calling.
Build a shared activity view. Read inbox activity for the resource types the customer grants, without requesting unrelated company data.

Permissions are resource-specific. You do not need API access to provide caller context, and API-only applications do not need a caller-context endpoint.

Application management is rolling out per company and is off by default. Phone.inc must enable the Applications feature flag for your publishing company. Disabling it hides application management and blocks creation, edits, deletion, and secret rotation; existing customer installations, OAuth, API access, and disconnect remain available. Customer companies do not need this flag to install an application.

Once enabled, sign in under your ordinary Phone.inc company account. Open Applications, alongside API keys, and choose New application. No separate partner account or marketplace listing is required.

Give your app a name and description, register its exact OAuth callback URLs, and enable only the permissions it needs. No scopes are selected by default. For example, calls:read is labeled Read calls, recordings, and transcripts and includes summaries and search. voicemails:read is labeled Read voicemails, recordings, and transcripts. See the 23-scope catalog and dependencies before choosing permissions.

Save the client ID, client secret, and separate context signing secret securely when shown. Secrets are shown only once on creation or rotation. Keep them on your server, never in browser code or logs. Manage an existing application at /applications/:id/edit, including its client ID, secret rotation, and deletion. The OAuth reference covers callback restrictions and credential management.

Let customers connect

Add a Connect to Phone.inc action in your SaaS. The installation flow is:

Your server creates a fresh OAuth state and S256 PKCE challenge, tied to the signed-in SaaS user.
Redirect the customer to Phone.inc's /oauth/authorize with your client ID, registered callback, and a nonempty subset of your enabled scopes.
Any authenticated employee in the customer company can approve consent. They see the publisher, application, and requested permissions. Caller-context permission explicitly discloses that caller phone numbers will be sent to your app.
Validate state at your callback. Exchange the authorization code on your server at /oauth/token, authenticating with your client secret and supplying the PKCE verifier.
Store the returned tokens and map installation_id and company_id to the correct tenant in your SaaS.

An installation is the connection between one customer company and your application. Repeated authorization updates that installation rather than creating duplicates. Customers see it on their Integrations page. Tokens cannot be redirected to another company by changing an ID in a request.

Follow the confidential-client OAuth flow for exact parameters, token exchange, refresh, and revocation. Public MCP dynamic registration is a different flow; do not use it to register your SaaS application.

Call the API

Send the installation's access token as Authorization: Bearer <access_token> to https://app.phone.inc/api/v1. Use the existing API reference, including calls, voicemails, contacts, and integrations. Resource-page examples use API keys; your SaaS uses its customer's OAuth bearer token instead.

Read scopes include the resource's content: calls include recordings, transcripts, summaries, and search; voicemails include recordings and transcripts; messages include texts. Embedded contact, employee, department, and business-number details still need their own read permissions. Combined inbox reads need at least one supported resource read and show only granted types. See inbox permissions for filtering, search, and seen updates.

You can also use existing MCP tools with partner tokens. They delegate to the same API permissions; they do not bypass consent or add credential-management tools.

Provide caller context

To show information from your SaaS when a customer receives a call, configure your application's HTTPS context endpoint and request caller_context:provide. A context-only installation can request just that scope.

Phone.inc sends a signed lookup containing the caller's phone number and installation identity to your endpoint. Verify the signature with the context signing secret before looking up data. Resolve the installation to your SaaS tenant, then return structured fields or tables, such as recent orders or open tickets. Never use the caller's phone number alone to choose a tenant.

The signing secret is separate from your OAuth client secret. Implement the exact request, signature verification, and response format in signed partner lookups. To fetch context from Phone.inc instead, use the caller-context API with caller_context:read; that scope does not permit outbound caller-number delivery.

Operate the connection

Access tokens last one hour. Refresh them server-side and store the latest returned tokens. Keep each customer's credentials and data isolated by installation.

Any authenticated employee in the customer company can approve installation through OAuth consent or disconnect an application from Integrations. Disconnect revokes installation tokens and pending codes, stops caller lookups, deletes its webhook subscriptions, and blocks queued deliveries and retries. Reconnecting cannot revive old deliveries; create new subscriptions. Each subscription belongs to its creating installation and keeps a scope ceiling that can shrink but never expand. See webhook permissions.

Adding enabled permissions keeps installations, existing tokens, caller context, and webhooks working. Existing tokens and refresh cannot gain scopes. Your SaaS must start fresh S256 PKCE authorization for the full desired scope set, not just the additions. Consent distinguishes additional, already approved, and omitted (removed) permissions. Approval updates the same installation; cancelling changes nothing.

Optionally register an HTTPS connect_url, labeled Connection URL, pointing to your SaaS's OAuth start page, not its callback. That page uses your own user session, state, and fresh PKCE. When additional scopes are enabled, Integrations shows Additional permissions available and links Update permissions to this URL, or instructs customers to open your SaaS if none is configured. Disconnected apps can reconnect through the same URL. The dashboard does not grant permissions or automatically expand tokens.

Reducing installation or application permissions revokes only credentials containing removed scopes; unaffected narrower tokens and installations continue. Removing every installed permission disconnects that installation. Webhook scope ceilings and event lists shrink permanently: readding scopes cannot revive removed access on old subscriptions. Expanded webhook access needs a new subscription.

Secret rotation, application deletion, installation revocation, and changes to callback URLs or the context endpoint still disconnect access. Changing the name, description, or Connection URL alone does not. Historical call context remains available. Follow the installation lifecycle reference.