Phone.inc

Integrations

See which integrations are configured for your account and whether each connection is connected, disconnected, or in an error state. These read-only endpoints use saved connection metadata and do not contact the provider.

To connect or reconnect, obtain a setup link through the API or MCP, then let the user complete authorization in the browser. Credentials never belong in a tool call. Edit settings or disconnect in the dashboard. For customer data from connected systems, use caller context.

The integration model

Only connections belonging to the authenticated company are returned. Credentials, endpoint URLs, provider settings, and raw error messages are never included.

Properties

  • Name
    id
    Type
    string
    Description
    Public integration identifier, used by the detail endpoint.
  • Name
    name
    Type
    string
    Description
    The connection's saved display name.
  • Name
    provider
    Type
    string
    Description
    One of shopify, custom_endpoint, dinero, or attio.
  • Name
    status
    Type
    string
    Description
    One of connected, disconnected, or error.
  • Name
    connected_at
    Type
    timestamp | null
    Description
    ISO 8601 timestamp when the connection was last marked connected, or null.
  • Name
    last_error_at
    Type
    timestamp | null
    Description
    ISO 8601 timestamp of the most recent recorded error, or null. A transient error can be recorded while status remains connected.
GET/v1/integrations

List integrations

Returns all saved connections, including disconnected connections and connections in an error state, ordered by name. An account with no configured connections returns []. There are no query parameters.

MCP equivalent: list_integrations.

Request

GET
/v1/integrations
curl https://app.phone.inc/api/v1/integrations \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

[
  {
    "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc",
    "name": "Acme Workspace",
    "provider": "attio",
    "status": "connected",
    "connected_at": "2026-10-12T12:00:00Z",
    "last_error_at": null
  }
]
GET/v1/integration_setups

List integration providers

Returns available installation options: Shopify, Custom Endpoint, Dinero, and Attio. These are providers you can set up, not connections already installed. Use GET /v1/integrations for current connections. No query parameters. MCP equivalent: list_integration_providers.

Each entry contains provider, name, description, authorization_required, setup_path, and setup_url. authorization_required is false for Custom Endpoint, which uses a configuration form rather than OAuth. Shopify requires store and app credentials in its browser form before OAuth. Dinero and Attio require server-side OAuth app configuration.

Request

GET
/v1/integration_setups
curl https://app.phone.inc/api/v1/integration_setups \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response (excerpt)

[
  {
    "provider": "shopify",
    "name": "Shopify",
    "description": "Match callers to their Shopify customer record and recent orders.",
    "authorization_required": true,
    "setup_path": "/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc",
    "setup_url": "https://app.phone.inc/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc"
  }
]
GET/v1/integration_setups/:provider

Prepare installation for one provider: shopify, custom_endpoint, dinero, or attio. Unknown providers return 404. MCP equivalent: get_integration_setup, with required provider.

Present setup_url as a button or link for the user to click. The dashboard assistant renders an authorization card automatically. Opening the link requires a signed-in browser session for the same company as the API credentials; an account mismatch sends the user back to integrations with an error. The relative setup_path is for clients already running on the app host.

Obtaining a link does not create a connection, contact the provider, or grant access. The browser flow handles OAuth state, permissions, callback verification, and secrets. The dashboard assistant automatically updates its card after the server verifies and saves the connection; closing the setup tab does not count as success. Credentials and provider errors never enter the assistant's completion status. External API clients should query the integrations list after setup to verify the saved connection. Never claim installation succeeded just because the link was returned.

Request

GET
/v1/integration_setups/shopify
curl https://app.phone.inc/api/v1/integration_setups/shopify \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "provider": "shopify",
  "name": "Shopify",
  "description": "Match callers to their Shopify customer record and recent orders.",
  "authorization_required": true,
  "setup_path": "/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc",
  "setup_url": "https://app.phone.inc/integration_authorizations/shopify?company_id=019daef1-085e-73f0-85f6-a71e2d8dd2cc"
}
GET/v1/integrations/:id

Get an integration

Returns one connection by its public id from the list endpoint. An unknown ID or an ID belonging to another company returns 404 Not Found.

MCP equivalent: get_integration, with required id.

Request

GET
/v1/integrations/:id
curl https://app.phone.inc/api/v1/integrations/019daef1-085e-73f0-85f6-a71e2d8dd2cc \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "id": "019daef1-085e-73f0-85f6-a71e2d8dd2cc",
  "name": "Acme Workspace",
  "provider": "attio",
  "status": "connected",
  "connected_at": "2026-10-12T12:00:00Z",
  "last_error_at": null
}