---
title: "POST /create-app"
method: POST
path: "/create-app"
---

# POST /create-app

`POST /create-app`

## Request

- Base URL: `https://api.retellai.com`
- URL: `https://api.retellai.com/create-app`
- Auth: HTTP bearer

Create an App: the connection to one external system (a CRM, calendar, support desk, and so on), holding its credentials and settings. Providers with caller-managed credentials accept auth_config. Providers using OAuth must omit auth_config and be authorized through connect-app. Providers supporting both methods, such as Cal.com, also accept caller-managed API keys. Credentials are stored encrypted and never returned. Up to 20 apps per provider by default, unless a custom limit is configured for the organization.

## Request body

- object
  - `type` 'crm' | 'calendar' | 'knowledge_base' | 'support' | 'communication', required: App integration category.
  - `provider` string, required: Provider name. Must be valid for the App's type; the supported providers per type are listed by list-app-templates.
  - `name` string: Display name.
  - `tenant_url` string: Per-tenant API base URL.
  - `tenant_id` string: Sub-account id, for providers that scope requests by a sub-account id on a shared host.
  - `auth_config` union: Caller-managed credentials. Providers using the OAuth callback reject auth_config and must be authorized through connect-app.
    - OAuthConfigRequest
      - `type` 'oauth2', required
      - `client_id` string, required
      - `client_secret` string, required: Secret credential; stored encrypted at rest.
    - ApiKeyAuthConfigRequest
      - `type` 'api_key', required
      - `api_key` string, required: API key credential; stored encrypted at rest.
    - BasicAuthConfigRequest
      - `type` 'basic', required
      - `username` string, required
      - `password` string, required: Password credential; stored encrypted at rest.
  - `crm_config` AppCRMConfig
    - `inbound_sync_mappings` CRMSyncMapping[]: Field mappings applied when syncing CRM records into Retell contacts. Must include phone_number, which is the field the two systems are matched on. A do_not_call mapping can mark contacts as do-not-call but never clears the flag.
      - `field_name` string, required: Retell contact field, built-in or custom, to map. Types must be compatible with the CRM field on both sides of the sync.
      - `external_field_name` string, required: Field on the CRM's contact object to map to. A name that does not exist there surfaces as an error on the sync job rather than at configuration time.
    - `outbound_sync_mappings` CRMSyncMapping[]: Field mappings applied when writing Retell contact changes back to the CRM.
      - `field_name` string, required: Retell contact field, built-in or custom, to map. Types must be compatible with the CRM field on both sides of the sync.
      - `external_field_name` string, required: Field on the CRM's contact object to map to. A name that does not exist there surfaces as an error on the sync job rather than at configuration time.
    - `sync_conversation_activity` boolean: Whether to push call/chat activity to the external CRM. Opt-in — defaults to false when unset.
    - `sync_new_contacts` boolean: Whether to create a CRM record after a conversation when the contact is not yet linked to one.

## Response `201`

App created.

- AppResponse
  - `app_id` string, required
  - `org_id` string, required
  - `type` 'crm' | 'calendar' | 'knowledge_base' | 'support' | 'communication', required: App integration category.
  - `provider` string, required: Provider name. Must be valid for the App's type; the supported providers per type are listed by list-app-templates.
  - `connection_status` 'not_connected' | 'connected' | 'error': Connection health of the App, server-managed. `not_connected` after create or a credential / tenant URL change; `connected` once verified via OAuth connect, an auth test, or a successful live tool call; `error` when the provider rejects the credentials (on connect, an auth test, or a live tool call).
  - `name` string
  - `tenant_url` string: Per-tenant API base URL. Set by providers with per-org hosts; omitted by providers on a single global host. For OneDrive for Business, this is the tenant's -my.sharepoint.com origin used by File Picker v8; personal OneDrive omits it.
  - `tenant_type` 'business' | 'personal': Microsoft OneDrive account type discovered during OAuth.
  - `tenant_id` string: Sub-account id, for providers that scope requests by a sub-account id on a shared host. Omitted by every other provider.
  - `auth_config` union: Non-secret auth metadata. Encrypted secret fields are never returned by the API.
    - OAuthConfigResponse
      - `type` 'oauth2', required
      - `client_id` string, required
    - ApiKeyAuthConfigResponse
      - `type` 'api_key', required
    - AccessTokenAuthConfigResponse
      - `type` 'access_token', required
    - BasicAuthConfigResponse
      - `type` 'basic', required
      - `username` string, required
    - RefreshTokenAuthConfigResponse
      - `type` 'refresh_token', required
  - `crm_config` AppCRMConfig
    - `inbound_sync_mappings` CRMSyncMapping[]: Field mappings applied when syncing CRM records into Retell contacts. Must include phone_number, which is the field the two systems are matched on. A do_not_call mapping can mark contacts as do-not-call but never clears the flag.
      - `field_name` string, required: Retell contact field, built-in or custom, to map. Types must be compatible with the CRM field on both sides of the sync.
      - `external_field_name` string, required: Field on the CRM's contact object to map to. A name that does not exist there surfaces as an error on the sync job rather than at configuration time.
    - `outbound_sync_mappings` CRMSyncMapping[]: Field mappings applied when writing Retell contact changes back to the CRM.
      - `field_name` string, required: Retell contact field, built-in or custom, to map. Types must be compatible with the CRM field on both sides of the sync.
      - `external_field_name` string, required: Field on the CRM's contact object to map to. A name that does not exist there surfaces as an error on the sync job rather than at configuration time.
    - `sync_conversation_activity` boolean: Whether to push call/chat activity to the external CRM. Opt-in — defaults to false when unset.
    - `sync_new_contacts` boolean: Whether to create a CRM record after a conversation when the contact is not yet linked to one.
  - `created_timestamp` number, required
  - `user_modified_timestamp` number, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-10-16** `ca41f0dbb297`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/retellai/apis/retell-sdk/changes/create-app/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) - [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/retellai/apis/retell-sdk/revisions/e482acaa292c?raw)