{ "openapi": "3.0.3", "info": { "title": "App Connect Connector Server API", "version": "1.7.41", "description": "HTTP API exposed by an App Connect connector server (called the CRM or adapter server in older code). The configured manifest serverUrl is the HTTPS base URL, without a trailing slash, to which App Connect appends these paths. The contract combines shared @app-connect/core routes with connector-specific routes implemented by this server; fields and supported capabilities can vary by connector where an operation delegates to a connector interface.\n\nAuthorization: userJwt is an App Connect CRM-session JWT issued by /apiKeyLogin or /oauth-callback; it is not a RingCentral OAuth token. X-RC-Access-Token carries a RingCentral OAuth credential for RingCentral user or administrator validation. Legacy jwtToken and rcAccessToken query parameters remain active for older clients, but credentials in URLs can leak through logs and browser history and should be avoided.\n\nLegacy response convention: some connector operations return HTTP 200 with successful: false and returnMessage when the request was processed but the CRM operation failed. Callers must inspect the response body rather than treating every 2xx response as business success. Payloads can contain CRM records, communications content, recording URLs, and access tokens; do not log credentials or retain personal data beyond the workflow that requires it.\n\nThis public reference omits internal and application-specific endpoints.", "contact": { "name": "RingCentral Labs", "url": "https://github.com/ringcentral/rc-unified-crm-extension" }, "license": { "name": "MIT", "url": "https://opensource.org/license/mit" } }, "externalDocs": { "description": "App Connect developer guide", "url": "https://appconnect.labs.ringcentral.com/developers/" }, "servers": [ { "url": "https://unified-crm-extension.labs.ringcentral.com", "description": "RingCentral Labs hosted server" }, { "url": "http://localhost:6066", "description": "Local development server" }, { "url": "https://{host}", "description": "Self-managed connector server", "variables": { "host": { "default": "unified-crm-extension.labs.ringcentral.com", "description": "Hostname of the deployed App Connect server." } } } ], "tags": [ { "name": "Health", "description": "Process liveness and legacy version metadata. Liveness does not imply database, connector, or upstream readiness." }, { "name": "Manifest", "description": "Connector manifests, capability discovery, release notes, and version metadata used by App Connect clients." }, { "name": "Auth", "description": "CRM authorization, managed-auth discovery, and App Connect user-session lifecycle." }, { "name": "Admin", "description": "RingCentral account settings, managed credentials, server-side logging configuration, and CRM user mapping." }, { "name": "Account data", "description": "Account-level CRM metadata (e.g. Pipedrive activity types) cached per RingCentral account and shared across its users." }, { "name": "User", "description": "Effective per-user settings and connector-owned CRM user information." }, { "name": "Contacts", "description": "Connector-backed CRM contact lookup and creation, including synthetic create-new choices." }, { "name": "Appointments", "description": "Connector-backed appointment listing, creation, partial update, refresh, confirmation, cancellation, and status changes." }, { "name": "Call Logs", "description": "CRM call-activity lookup and mutation, temporary note caching, and connector-defined dispositions." }, { "name": "Message Logs", "description": "CRM logging for RingCentral SMS, MMS, fax, voicemail, and grouped conversations." }, { "name": "Call Down", "description": "Server-owned scheduled call-back entries scoped to the current App Connect user." }, { "name": "Plugins", "description": "Account-level plugin installation, advisory licensing, legacy built-ins, and asynchronous completion callbacks." }, { "name": "RingCentral Reports", "description": "RingCentral account and extension reports generated with stored account OAuth credentials." } ], "security": [], "paths": { "/isAlive": { "get": { "tags": [ "Health" ], "summary": "Check HTTP process liveness", "operationId": "getIsAlive", "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Plain-text liveness response.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "examples": { "healthy": { "summary": "Healthy server", "value": "OK" } } } } } }, "description": "Returns the literal text OK when the HTTP process can answer. The App Connect client treats any HTTP 200 as reachable and ignores the body. This route does not check the database, connector module, or upstream CRM dependencies." } }, "/implementedInterfaces": { "get": { "tags": [ "Manifest" ], "summary": "List implemented connector methods for a platform", "operationId": "getImplementedInterfaces", "parameters": [ { "$ref": "#/components/parameters/platform" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Connector-interface availability for the requested platform.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImplementedInterfacesResponse" }, "examples": { "oauthConnector": { "summary": "OAuth connector capabilities", "value": { "getAuthType": true, "getOauthInfo": true, "getUserInfo": true, "createCallLog": true, "updateCallLog": true, "getCallLog": true, "createMessageLog": true, "updateMessageLog": true, "createContact": true, "findContact": true, "listAppointments": false, "createAppointment": false, "updateAppointment": false, "refreshAppointment": false, "confirmAppointment": false, "cancelAppointment": false, "unAuthorize": true, "upsertCallDisposition": true, "findContactWithName": true, "getUserList": false, "getLicenseStatus": true, "getLogFormatType": true, "refreshUserInfo": true, "cacheCallNote": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Returns a boolean capability map for the selected connector. A true value means the connector exports the corresponding handler, not that its upstream service is healthy. App Connect uses these flags to enable features such as name search, call-note caching, dispositions, and user mapping; cacheCallNote also reflects server deployment configuration." } }, "/crmManifest": { "get": { "tags": [ "Manifest" ], "summary": "Return a platform manifest", "description": "Returns the selected connector manifest used by legacy App Connect clients. If platformName is omitted, the server uses its default connector. Development deployments can override manifest URLs with local server configuration.", "operationId": "getCrmManifest", "parameters": [ { "name": "platformName", "in": "query", "schema": { "type": "string" }, "description": "Connector platform key. When omitted, the server returns its default connector manifest." } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "deprecated": true } }, "/releaseNotes": { "get": { "tags": [ "Manifest" ], "summary": "Get release notes for connector versions", "operationId": "getReleaseNotes", "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Release notes grouped by server version and connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseNotesResponse" }, "examples": { "release": { "summary": "Global and connector release notes", "value": { "1.7.14": { "global": [], "exampleCRM": [ { "type": "New", "description": "Added SMS time tracking." } ] } } } } } } } }, "description": "Returns global and connector release-note sections for versions registered by the selected connector. Global notes are merged only into connector version keys, so global-only versions are not included; the client performs the final presentation merge." } }, "/serverVersionInfo": { "get": { "tags": [ "Health" ], "summary": "Return server version metadata", "operationId": "getServerVersionInfo", "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Version metadata from the default CRM manifest.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerVersionInfoResponse" }, "examples": { "version": { "summary": "Server version", "value": { "version": "1.7.41" } } } } } } }, "deprecated": true, "description": "Returns legacy server-version metadata from the default connector manifest. This is a compatibility endpoint and is not a health or update-availability check." } }, "/oauth-callback": { "get": { "tags": [ "Auth" ], "summary": "CRM OAuth callback", "operationId": "getOauthCallback", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Opaque connector OAuth state. The server and connector use it to restore platform, user, redirect, and anti-forgery context." }, { "name": "code", "in": "query", "schema": { "type": "string" }, "description": "One-time authorization code returned by the CRM OAuth provider." }, { "name": "callbackUri", "in": "query", "schema": { "type": "string" }, "description": "Full browser callback URI containing the CRM provider result. Legacy clients can send provider fields separately when this value is not encoded." }, { "name": "hostname", "in": "query", "schema": { "type": "string" }, "description": "Optional tenant-specific CRM hostname retained through the OAuth flow." }, { "name": "tokenUrl", "in": "query", "schema": { "type": "string" }, "description": "Optional connector-specific OAuth token endpoint retained through the authorization flow." }, { "name": "apiUrl", "in": "query", "schema": { "type": "string" }, "description": "Optional connector-specific CRM API base URL retained through the authorization flow." }, { "name": "proxyId", "in": "query", "required": false, "description": "Proxy connector identifier retained through the OAuth exchange.", "schema": { "type": "string" } }, { "name": "rcAccountId", "in": "query", "required": false, "description": "Optional RingCentral account context forwarded to connectors that bind CRM OAuth to an account.", "schema": { "type": "string" } }, { "name": "rcExtensionId", "in": "query", "required": false, "description": "Optional RingCentral extension context forwarded to connectors that bind CRM OAuth to a user.", "schema": { "type": "string" } }, { "name": "userEmail", "in": "query", "required": false, "description": "Optional RingCentral user email forwarded to connectors that need it during OAuth completion.", "schema": { "type": "string", "format": "email" } }, { "name": "username", "in": "query", "required": false, "description": "Optional connector login name used by connectors such as Bullhorn during OAuth completion.", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Completes connector OAuth by passing the provider result and connector context to the selected connector, storing the resulting CRM credentials, and issuing an App Connect CRM-session JWT. Browser flows restore context from state or callbackUri. Connector-specific query fields such as account, extension, email, or username can also be forwarded. MCP authorization stores the completed session server-side and returns plain text instead of a browser token." } }, "/apiKeyLogin": { "post": { "tags": [ "Auth" ], "summary": "API-key login", "description": "Authenticates an API-key connector and creates an App Connect CRM session. When a RingCentral access token is supplied, the server derives the RingCentral account and extension identities and can combine submitted values with administrator-managed credentials. A successful response returns userJwt as jwtToken; connector rejection is returned as HTTP 400 with an error or returnMessage.", "operationId": "postApiKeyLogin", "parameters": [ { "name": "state", "in": "query", "required": false, "deprecated": true, "description": "Ignored browser-client compatibility parameter. The server selects the connector from body.platform.", "schema": { "type": "string" } } ], "requestBody": { "$ref": "#/components/requestBodies/ApiKeyLogin" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The connector credentials were accepted and an App Connect user token was issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyLoginResponse" }, "examples": { "connected": { "summary": "Connected user session", "value": { "jwtToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "name": "Ada Lovelace", "returnMessage": { "message": "Connected successfully.", "messageType": "success", "ttl": 3000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ {}, { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ] } }, "/unAuthorize": { "post": { "tags": [ "Auth" ], "summary": "Disconnect a CRM user", "operationId": "postUnAuthorize", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Invokes the connector disconnect or revocation hook for the CRM user identified by the current App Connect session. It does not delete the App Connect user record or independently invalidate the supplied App Connect JWT." } }, "/licenseStatus": { "get": { "tags": [ "Auth" ], "summary": "Get connector license status", "operationId": "getLicenseStatus", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Returns the connector-reported license state for the current CRM user. The exact fields are connector-defined. Missing authorization or connector lookup failure can be represented by HTTP 200 with an invalid license state, so callers must inspect the body." } }, "/authValidation": { "get": { "tags": [ "Auth" ], "summary": "Validate the current CRM authentication", "operationId": "getAuthValidation", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "CRM authentication validation result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthValidationResponse" }, "examples": { "valid": { "summary": "Authentication is valid", "value": { "successful": true, "returnMessage": { "message": "Authentication is valid.", "messageType": "success", "ttl": 1000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Validates the current user's stored CRM authorization through the connector. HTTP 200 with successful: false means validation ran and the connector rejected or expired the credentials; HTTP 400 represents missing session context, an invalid request, or an execution failure." } }, "/apiKeyManagedAuthState": { "get": { "tags": [ "Auth" ], "summary": "Get admin-managed API-key auth state", "operationId": "getApiKeyManagedAuthState", "parameters": [ { "$ref": "#/components/parameters/platform" }, { "name": "connectorId", "in": "query", "required": false, "description": "Private or proxy connector identifier.", "schema": { "type": "string" } }, { "name": "isPrivate", "in": "query", "required": false, "description": "Whether connector-scoped managed credentials should be used.", "schema": { "type": "boolean", "default": false } }, { "x-app-connect-generated-contract": true, "name": "devRcAccountId", "in": "query", "required": false, "description": "RingCentral account that owns the private or shared Developer Portal connector.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Connector-defined entity identifier, represented as a string or number." }, "example": "400012345678" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Managed API-key field state for the RingCentral user and account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAuthStateResponse" }, "examples": { "manualAuth": { "summary": "No managed credentials are configured", "value": { "hasManagedAuth": false, "allRequiredFieldsSatisfied": false, "visibleFieldConsts": null, "missingRequiredFieldConsts": [ "apiKey" ], "fallbackToManualAuth": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Derives RingCentral account and extension identity from the supplied RingCentral token and reports whether administrator-managed API-key fields can satisfy the selected connector login. Missing required manual fields and a previous managed-login fallback are returned explicitly. Client-supplied account or extension identifiers are not trusted for this decision." } }, "/oauthManagedAuthState": { "get": { "tags": [ "Auth" ], "summary": "Get admin-managed OAuth state", "operationId": "getOauthManagedAuthState", "parameters": [ { "$ref": "#/components/parameters/platform" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Managed OAuth configuration state for the RingCentral account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOAuthStateResponse" }, "examples": { "unconfigured": { "summary": "No managed OAuth configuration", "value": { "isAdmin": false, "hasAccountOAuth": false, "hasPendingOAuth": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Derives the RingCentral account from the supplied token and returns completed or pending administrator-managed OAuth state for the selected connector. Pending values are returned only to an authorized administrator and can contain sensitive client credentials." } }, "/hostname": { "get": { "tags": [ "Auth" ], "summary": "Resolve hostname metadata for a platform", "operationId": "getHostname", "parameters": [], "responses": { "200": { "description": "Stored CRM hostname.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "description": "The hostname could not be loaded." } }, "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "description": "Returns the CRM hostname stored for the user identified by the App Connect session. The value can be empty for connectors that do not use tenant-specific hosts." } }, "/userInfoHash": { "get": { "tags": [ "User" ], "summary": "Return a hash for the current user info", "operationId": "getUserInfoHash", "security": [], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Deterministic account and extension hashes.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoHashResponse" }, "examples": { "hashes": { "summary": "Hashed user identifiers", "value": { "extensionId": "74c4089f5df0e6f37a78371fc535c2335327999ffb55ddf2c17ab6feeb9378c7", "accountId": "318b43a184b5607066f97c570af26b73fc787778d221cd06002308ef50755d90" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "parameters": [ { "name": "extensionId", "in": "query", "required": false, "description": "RingCentral extension identifier to hash.", "schema": { "type": "string" } }, { "name": "accountId", "in": "query", "required": false, "description": "RingCentral account identifier to hash.", "schema": { "type": "string" } } ], "description": "Produces deterministic server-keyed hashes for supplied RingCentral account or extension identifiers. Either input may be omitted. These opaque correlation values are not authentication proofs and this route does not validate ownership of the identifiers." } }, "/admin/settings": { "get": { "tags": [ "Admin" ], "summary": "Read admin settings", "operationId": "getAdminSettings", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "userJwt": [], "ringCentralAccessToken": [] }, { "userJwt": [], "legacyRingCentralAccessToken": [] }, { "legacyUserJwt": [], "ringCentralAccessToken": [] }, { "legacyUserJwt": [], "legacyRingCentralAccessToken": [] } ], "description": "Returns account-level connector settings after validating both the App Connect CRM session and the supplied RingCentral administrator token. If the account has no saved settings, the route returns the connector's default empty configuration." }, "post": { "tags": [ "Admin" ], "summary": "Save admin settings", "operationId": "postAdminSettings", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/AdminSettingsUpdate" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The account settings were updated.", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/AdminSuccessMessage" }, "examples": { "updated": { "summary": "Settings updated", "value": "Admin settings updated" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Validates the supplied RingCentral administrator token and replaces account-level App Connect settings for that RingCentral account. The nested settings and optional custom-connector data come from the request body; this write path does not require a userJwt." } }, "/admin/managedAuth": { "get": { "tags": [ "Admin" ], "summary": "Read admin-managed API-key credentials", "operationId": "getAdminManagedAuth", "parameters": [ { "name": "connectorId", "in": "query", "required": false, "description": "Private or proxy connector identifier.", "schema": { "type": "string" } }, { "name": "isPrivate", "in": "query", "required": false, "description": "Whether connector-scoped managed credentials should be used.", "schema": { "type": "boolean", "default": false } }, { "x-app-connect-generated-contract": true, "name": "devRcAccountId", "in": "query", "required": false, "description": "RingCentral account that owns the private or shared Developer Portal connector.", "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Connector-defined entity identifier, represented as a string or number." }, "example": "400012345678" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Managed authentication field definitions and configured account/user values.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAuthAdminResponse" }, "examples": { "configured": { "summary": "Managed authentication configuration", "value": { "hasManagedAuth": true, "fields": [ { "const": "tenantId", "required": true, "managed": true, "managedScope": "account" }, { "const": "userToken", "required": true, "managed": true, "managedScope": "user" } ], "orgFields": [ { "const": "tenantId", "required": true, "managed": true, "managedScope": "account" } ], "userFields": [ { "const": "userToken", "required": true, "managed": true, "managedScope": "user" } ], "orgValues": { "tenantId": { "hasValue": true, "value": "tenant.example" } }, "userValues": [ { "rcExtensionId": "101", "rcUserName": "Ada Lovelace", "fields": { "userToken": { "hasValue": true, "value": "configured" } } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "userJwt": [], "ringCentralAccessToken": [] }, { "userJwt": [], "legacyRingCentralAccessToken": [] }, { "legacyUserJwt": [], "ringCentralAccessToken": [] }, { "legacyUserJwt": [], "legacyRingCentralAccessToken": [] } ], "description": "Returns managed-auth field definitions and decrypted account or extension values for the connector selected by userJwt, after RingCentral administrator validation. Returned credential values are sensitive and must not be logged or exposed outside the administration flow." }, "post": { "tags": [ "Admin" ], "summary": "Save admin-managed API-key credentials", "operationId": "postAdminManagedAuth", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/ManagedAuthUpdate" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The managed authentication values were updated.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "text/html": { "schema": { "$ref": "#/components/schemas/AdminSuccessMessage" }, "examples": { "updated": { "summary": "Managed authentication updated", "value": "Shared authentication updated" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "userJwt": [], "ringCentralAccessToken": [] }, { "userJwt": [], "legacyRingCentralAccessToken": [] }, { "legacyUserJwt": [], "ringCentralAccessToken": [] }, { "legacyUserJwt": [], "legacyRingCentralAccessToken": [] } ], "description": "Stores or removes account-scoped or extension-scoped managed API-key values for the connector selected by userJwt. RingCentral administrator validation is required, and submitted credential values must be treated as secrets." } }, "/admin/managedOAuth/cache": { "post": { "tags": [ "Admin" ], "summary": "Cache admin-managed OAuth credentials", "operationId": "postAdminManagedOauthCache", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/AdminManagedOAuthCache" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The pending managed OAuth values were cached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" }, "examples": { "cached": { "summary": "Pending values cached", "value": { "successful": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Validates the RingCentral administrator and caches sensitive managed OAuth client values for the account until the connector OAuth flow activates them. Existing pending values can be replaced." }, "delete": { "tags": [ "Admin" ], "summary": "Delete cached admin-managed OAuth credentials", "operationId": "deleteAdminManagedOauthCache", "parameters": [], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The pending managed OAuth values were removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" }, "examples": { "removed": { "summary": "Pending values removed", "value": { "successful": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Validates the RingCentral administrator and removes the account's pending, not-yet-activated managed OAuth values. Completed account OAuth configuration is not removed by this route." } }, "/admin/managedOAuth/account": { "delete": { "tags": [ "Admin" ], "summary": "Delete account-scoped admin-managed OAuth credentials", "operationId": "deleteAdminManagedOauthAccount", "parameters": [ { "$ref": "#/components/parameters/platform" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The account managed OAuth values were reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" }, "examples": { "reset": { "summary": "Account OAuth reset", "value": { "successful": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Validates the RingCentral administrator and removes completed account-scoped managed OAuth configuration for the selected connector. Users may need to authorize again afterward." } }, "/admin/userMapping": { "post": { "tags": [ "Admin" ], "summary": "Resolve CRM user mappings", "operationId": "postAdminUserMapping", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/GenericJson" }, "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "userJwt": [], "ringCentralAccessToken": [] }, { "userJwt": [], "legacyRingCentralAccessToken": [] }, { "legacyUserJwt": [], "ringCentralAccessToken": [] }, { "legacyUserJwt": [], "legacyRingCentralAccessToken": [] } ], "description": "Resolves CRM users for the supplied RingCentral extension list and returns the resulting account mapping. The connector can initialize missing mapping records or indicate that a user session should be revoked. This operation does not save the submitted extension list as configuration." } }, "/admin/reinitializeUserMapping": { "post": { "tags": [ "Admin" ], "summary": "Reinitialize admin user mapping", "operationId": "postAdminReinitializeUserMapping", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/GenericJson" }, "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "userJwt": [], "ringCentralAccessToken": [] }, { "userJwt": [], "legacyRingCentralAccessToken": [] }, { "legacyUserJwt": [], "ringCentralAccessToken": [] }, { "legacyUserJwt": [], "legacyRingCentralAccessToken": [] } ], "description": "Clears and rebuilds the account's CRM-to-RingCentral user mapping from the supplied extension list after App Connect session and RingCentral administrator validation. Existing mapping state can be replaced." } }, "/admin/serverLoggingSettings": { "get": { "tags": [ "Admin" ], "summary": "Read server-side logging settings", "operationId": "getAdminServerLoggingSettings", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Returns connector-specific additional-field definitions and values used by server-side call logging for the current App Connect CRM user. Despite the admin path prefix, this route does not independently validate RingCentral administrator status." }, "post": { "tags": [ "Admin" ], "summary": "Update server-side logging settings", "operationId": "postAdminServerLoggingSettings", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/GenericJson" }, "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Replaces connector-specific additionalFieldValues used by server-side call logging for the current App Connect CRM user. The body must include additionalFieldValues. Despite the admin path prefix, this route does not independently validate RingCentral administrator status." } }, "/user/preloadSettings": { "get": { "tags": [ "User" ], "summary": "Preload user settings for a platform", "operationId": "getUserPreloadSettings", "parameters": [ { "name": "rcAccountId", "in": "query", "required": false, "description": "RingCentral account identifier used when no access token is available.", "schema": { "type": "string" } } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Account-level user settings to preload before CRM login.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsEnvelope" }, "examples": { "configured": { "summary": "Preconfigured account settings", "value": { "userSettings": { "theme": { "value": "dark", "customizable": true, "defaultValue": "system", "options": [ "system", "light", "dark" ] } } } }, "empty": { "summary": "No account settings configured", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ {}, { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Returns account-managed user settings before CRM login. The RingCentral account is derived from a supplied RingCentral token when present, or from rcAccountId for legacy pre-login clients." } }, "/user/refreshInfo": { "post": { "tags": [ "User" ], "summary": "Refresh connector-owned CRM user information", "description": "Refreshes connector-owned CRM identity and authorization information for the current App Connect user. A completed refresh that the connector cannot satisfy can return HTTP 200 with successful: false and a returnMessage.", "operationId": "postUserRefreshInfo", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "CRM user-information refresh result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" }, "examples": { "refreshed": { "summary": "User information refreshed", "value": { "successful": true, "returnMessage": { "message": "User information refreshed.", "messageType": "success" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/user/settings": { "get": { "tags": [ "User" ], "summary": "Read user settings", "operationId": "getUserSettings", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "rcAccountId", "in": "query", "required": false, "description": "RingCentral account id used to resolve account-managed defaults when an access token is unavailable.", "schema": { "type": "string" } } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Effective user settings after account-level overrides are applied.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettings" }, "examples": { "settings": { "summary": "Effective user settings", "value": { "theme": { "value": "dark", "customizable": true, "defaultValue": "system", "options": [ "system", "light", "dark" ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Returns effective user settings after merging the user's values with account-managed defaults and customization restrictions. rcAccountId is a legacy fallback for resolving account settings when RingCentral token context is unavailable." }, "post": { "tags": [ "User" ], "summary": "Update user settings", "operationId": "postUserSettings", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/UserSettingsUpdate" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Updated user settings. Legacy connector-hook failures can return an empty object.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsEnvelope" }, "examples": { "updated": { "summary": "User settings updated", "value": { "userSettings": { "theme": { "value": "dark", "customizable": true, "defaultValue": "system", "options": [ "system", "light", "dark" ] } } } }, "empty": { "summary": "Legacy connector hook returned no settings", "value": {} } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Upserts supplied user settings and removes named setting keys for the current CRM user, then invokes the connector update hook when implemented. Connectors using the legacy update hook currently return an empty JSON object after the hook path; other connectors return the effective settings envelope." } }, "/contact": { "get": { "tags": [ "Contacts" ], "summary": "Find contacts by phone number", "operationId": "getContact", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/phoneNumber" }, { "name": "overridingFormat", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated phone-number formats used by CRM-specific matching." }, { "$ref": "#/components/parameters/isExtension" }, { "name": "isForceRefreshAccountData", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Bypass and refresh cached contact search data." } ], "responses": { "200": { "description": "Matching CRM contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Searches CRM contacts by phone number using connector-specific number formats and optional extension semantics. The server can use cached account data unless forceContactRefresh is requested. Results can include a synthetic create-new option marked isNewContact rather than an existing CRM record; clients must not treat that option as a match." }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "operationId": "postContact", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CreateContact" }, "responses": { "200": { "description": "Created CRM contact information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMutationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Creates a CRM contact using the supplied name, phone number, optional CRM entity type, and connector-defined additional submission fields. Connector validation failures can return HTTP 200 with successful: false and returnMessage." } }, "/custom/contact/search": { "get": { "tags": [ "Contacts" ], "summary": "Find contacts by name", "operationId": "getCustomContactSearch", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "CRM contact name search text." } ], "responses": { "200": { "description": "Matching CRM contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Searches CRM contacts by display name through the connector's optional findContactWithName capability. The returned contact array can include connector-specific fields, and connector-level failure can be represented by successful: false." } }, "/appointments": { "get": { "tags": [ "Appointments" ], "summary": "List appointments", "operationId": "getAppointments", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointments returned by the active connector.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentListResponse" }, "examples": { "appointments": { "summary": "Scheduled appointments", "value": { "successful": true, "appointments": [ { "id": "101", "thirdPartyAppointmentId": "101", "title": "Candidate Screen", "description": "Talk through resume", "participantName": "", "startTimeUtc": "2026-07-20T15:00:00.000Z", "durationMinutes": 45, "status": "scheduled", "contactId": "501", "contactType": "Candidate", "attendees": [ { "id": "601", "name": "Alice Able", "type": "CorporateUser", "status": "ACCEPTED" } ] } ] } }, "unavailable": { "summary": "Appointments unavailable", "value": { "successful": false, "returnMessage": { "message": "Error listing appointments", "messageType": "warning", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "parameters": [ { "name": "range", "in": "query", "required": false, "deprecated": true, "description": "Ignored browser-client compatibility object. Use startDate and endDate; the current server does not read range.", "style": "deepObject", "explode": true, "schema": { "type": "object", "additionalProperties": true } }, { "name": "mineOnly", "in": "query", "required": false, "deprecated": true, "description": "Ignored browser-client compatibility flag. The current HTTP route does not filter appointments by owner.", "schema": { "type": "boolean" } }, { "name": "forceSync", "in": "query", "required": false, "deprecated": true, "description": "Ignored browser-client compatibility flag. The current HTTP route does not expose a force-synchronization option.", "schema": { "type": "boolean" } }, { "x-app-connect-generated-contract": true, "name": "startDate", "in": "query", "required": false, "description": "Inclusive appointment start date. Supply together with endDate.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "ISO-8601 calendar date." }, "example": "2026-07-01" }, { "x-app-connect-generated-contract": true, "name": "endDate", "in": "query", "required": false, "description": "Inclusive appointment end date. Supply together with startDate.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "ISO-8601 calendar date." }, "example": "2026-07-31" } ], "description": "Lists CRM appointments through the active connector. Supply both startDate and endDate in YYYY-MM-DD form or neither; when omitted, the connector chooses its default range. The range, mineOnly, and forceSync parameters sent by older browser clients are ignored. Connector-level failures can return HTTP 200 with successful: false." }, "post": { "tags": [ "Appointments" ], "summary": "Create an appointment", "operationId": "postAppointments", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/AppointmentCreate" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointment creation result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCreateResponse" }, "examples": { "created": { "summary": "Appointment created", "value": { "successful": true, "appointmentId": "777" } }, "rejected": { "summary": "Connector rejected the create request", "value": { "successful": false, "returnMessage": { "message": "Could not create appointment in Bullhorn.", "messageType": "warning", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Creates a CRM appointment. The wrapped payload form is canonical; direct top-level appointment fields remain accepted for compatibility. Times use ISO 8601 with an explicit offset, and connector-level rejection can return HTTP 200 with successful: false." } }, "/appointments/{appointmentId}": { "patch": { "tags": [ "Appointments" ], "summary": "Update an appointment", "operationId": "patchAppointment", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/appointmentId" } ], "requestBody": { "$ref": "#/components/requestBodies/AppointmentPatch" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointment update result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentRecordResponse" }, "examples": { "updated": { "summary": "Appointment updated", "value": { "successful": true, "appointmentId": "333", "appointment": { "id": "333", "title": "Updated Strategy Call", "description": "Updated description", "startTimeUtc": "2026-07-20T20:00:00.000Z", "durationMinutes": 60, "status": "scheduled" } } }, "missing": { "summary": "Appointment not found", "value": { "successful": false, "returnMessage": { "message": "Appointment not found in Clio.", "messageType": "warning", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Partially updates a CRM appointment and preserves omitted fields. The wrapped patch form is canonical. Legacy replacement start-time fields remain supported but must be supplied with their paired duration fields." } }, "/appointments/{appointmentId}/status": { "post": { "tags": [ "Appointments" ], "summary": "Update an appointment status", "description": "Requests a connector-specific appointment status change. The server normalizes the supplied status to lowercase. Supported status values depend on the connector, and an unsupported change can return successful: false.", "operationId": "postAppointmentStatus", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/appointmentId" } ], "requestBody": { "$ref": "#/components/requestBodies/AppointmentStatusUpdate" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointment status update result; connector support varies.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentRecordResponse" }, "examples": { "updated": { "summary": "Appointment status updated", "value": { "successful": true, "appointmentId": "3003", "appointment": { "id": "3003", "title": "Strategy Call", "status": "TENTATIVE" } } }, "unsupported": { "summary": "Connector does not support status changes", "value": { "successful": false, "returnMessage": { "message": "This connector does not support appointment status changes.", "messageType": "warning", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } } } }, "/appointments/{appointmentId}/refresh": { "get": { "tags": [ "Appointments" ], "summary": "Refresh an appointment", "operationId": "getAppointmentRefresh", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/appointmentId" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Refreshed appointment result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentRecordResponse" }, "examples": { "refreshed": { "summary": "Appointment refreshed", "value": { "successful": true, "appointmentId": "888", "appointment": { "id": "888", "title": "Candidate Screen", "description": "Talk through resume", "startTimeUtc": "2026-07-20T15:00:00.000Z", "durationMinutes": 45, "status": "scheduled" } } }, "missing": { "summary": "Appointment not found", "value": { "successful": false, "returnMessage": { "message": "Appointment not found in Bullhorn.", "messageType": "warning", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Fetches the current CRM representation of an appointment after it may have changed outside App Connect. The response identifies the requested appointment and can report connector-level failure in the body." } }, "/appointments/{appointmentId}/confirm": { "post": { "tags": [ "Appointments" ], "summary": "Confirm an appointment", "operationId": "postAppointmentConfirm", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/appointmentId" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointment confirmation result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentActionResponse" }, "examples": { "confirmed": { "summary": "Appointment confirmed", "value": { "successful": true, "appointmentId": "3003", "returnMessage": { "message": "Appointment confirmed successfully", "messageType": "success", "ttl": 60000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Confirms an appointment through the active connector. Depending on connector support, a successful response can include the current appointment record or only an appointment identifier and status message." } }, "/appointments/{appointmentId}/cancel": { "post": { "tags": [ "Appointments" ], "summary": "Cancel an appointment", "operationId": "postAppointmentCancel", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/appointmentId" } ], "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Appointment cancellation result.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentActionResponse" }, "examples": { "cancelled": { "summary": "Appointment cancelled", "value": { "successful": true, "appointmentId": "888", "returnMessage": { "message": "Appointment cancelled successfully.", "messageType": "success", "ttl": 5000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Cancels an appointment through the active connector. Depending on connector support, a successful response can include the affected appointment or only an appointment identifier and status message." } }, "/callLog": { "get": { "tags": [ "Call Logs" ], "summary": "Fetch existing call logs", "operationId": "getCallLog", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "description": "Call-log lookup result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogLookupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "parameters": [ { "$ref": "#/components/parameters/sessionIds" }, { "$ref": "#/components/parameters/extensionNumber" }, { "$ref": "#/components/parameters/hashedExtensionId" }, { "$ref": "#/components/parameters/requireDetails" } ], "description": "Checks up to five RingCentral call session IDs for existing local CRM call mappings, scoped by extension identity. When requireDetails is true, matched entries can include connector-provided CRM activity details. A revoked connector session can return HTTP 401." }, "post": { "tags": [ "Call Logs" ], "summary": "Create a call log", "operationId": "postCallLog", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CreateCallLog" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Call-log creation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogMutationResponse" }, "examples": { "created": { "summary": "Call log created with a numeric connector id", "value": { "successful": true, "logId": 42, "returnMessage": { "message": "Call logged.", "messageType": "success", "ttl": 3000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Creates a CRM activity for a RingCentral call and records the session-plus-extension mapping used for de-duplication and later updates. Both the browser client and server-side logging service use this route; the latter can create a pending call and later patch it. Synchronous plugins can transform the payload before CRM creation, and asynchronous call plugins are dispatched after the activity is saved." }, "patch": { "tags": [ "Call Logs" ], "summary": "Update a call log", "operationId": "patchCallLog", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/UpdateCallLog" }, "responses": { "200": { "description": "Updated call-log result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Updates the CRM activity associated with a RingCentral session and the same extension identity used at creation. Only supplied activity fields are changed. Recording download URLs can contain RingCentral access tokens and must not be logged or retained unnecessarily. Registered plugins can augment the update." } }, "/callLog/cacheNote": { "post": { "tags": [ "Call Logs" ], "summary": "Cache a call note before full logging", "operationId": "postCallLogCacheNote", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CallNoteCache" }, "responses": { "200": { "description": "Call note cache result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Caches a call note by RingCentral session ID before full server-side call logging when the connector advertises cacheCallNote. The cache entry expires after one hour. The legacy success response uses a plain-string returnMessage." } }, "/callDisposition": { "put": { "tags": [ "Call Logs" ], "summary": "Upsert call dispositions", "operationId": "putCallDisposition", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CallDisposition" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Disposition upsert result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" }, "examples": { "saved": { "summary": "Disposition saved", "value": { "successful": true, "returnMessage": { "message": "Disposition saved.", "messageType": "success", "ttl": 3000 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Creates or updates connector-defined disposition values on the CRM activity identified by RingCentral session and extension identity. dispositions is an object keyed by connector-defined field identifier; additionalSubmission is retained only for backward compatibility and is not processed." } }, "/messageLog": { "post": { "tags": [ "Message Logs" ], "summary": "Create or update an SMS/fax/message log", "operationId": "postMessageLog", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/MessageLog" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "Message-log creation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageLogResponse" }, "examples": { "created": { "summary": "Message logs created with numeric connector ids", "value": { "successful": true, "logIds": [ 101, 102 ], "returnMessage": { "message": "Messages logged.", "messageType": "success", "ttl": 3000 } } }, "alreadyLogged": { "summary": "All messages were already logged", "value": { "successful": true, "logIds": [], "returnMessage": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Logs RingCentral SMS, MMS, fax, voicemail, or text records to the CRM. Messages can be written individually or grouped into a shared conversation activity, and previously processed RingCentral message IDs are de-duplicated. Fax and MMS payloads can include a RingCentral access token for attachment downloads; treat it as secret and do not persist it." } }, "/calldown": { "get": { "tags": [ "Call Down" ], "summary": "List scheduled call-back entries", "operationId": "getCallDown", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "responses": { "200": { "description": "The current user's call-back entries ordered by scheduledAt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownListResponse" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Optional status filter: called; not called, not_called, or notcalled; or any other value for all entries.", "schema": { "type": "string" } } ], "description": "Lists server-owned scheduled call-back entries for the current App Connect user in ascending scheduledAt order. status=called returns completed entries; not called, not_called, and notcalled return entries whose status is not called; other values return all entries." }, "post": { "tags": [ "Call Down" ], "summary": "Schedule a call-back entry", "operationId": "postCallDown", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CallDownCreate" }, "responses": { "200": { "description": "The call-back entry was scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownCreateResponse" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Creates a server-owned call-back entry for the current App Connect user with status scheduled and a generated identifier. contactId, contactType, and scheduledAt are persisted. Current browser clients also send contactName, phoneNumber, and note, but the current data model does not retain those fields." } }, "/calldown/{id}": { "patch": { "tags": [ "Call Down" ], "summary": "Update a call-back entry", "operationId": "patchCallDown", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "$ref": "#/components/requestBodies/CallDownPatch" }, "responses": { "200": { "description": "The owned call-back entry was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownMutationResponse" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Updates allowed fields on a call-back entry owned by the current App Connect user. status, scheduledAt, lastCallAt, contactId, and contactType are persisted. Current browser clients also send contactName, phoneNumber, and note, but the current data model does not retain those fields." }, "delete": { "tags": [ "Call Down" ], "summary": "Delete a call-back entry", "operationId": "deleteCallDown", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "The owned call-back entry was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownMutationResponse" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Deletes the identified call-back entry only when it belongs to the current App Connect user. A missing or foreign identifier is returned as a bad request with a not-found error." } }, "/plugin/register": { "post": { "tags": [ "Plugins" ], "summary": "Register a plugin for an account", "operationId": "postPluginRegister", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/PluginRegister" }, "responses": { "200": { "x-app-connect-generated-contract": true, "description": "The plugin was registered for the account.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginMutationResponse" }, "examples": { "registered": { "summary": "Plugin registered", "value": { "successful": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Installs a plugin for a RingCentral account. The route validates administrator access and account identity, resolves the selected platform entry from the Developer Console plugin manifest, calls its registration URL with the short-lived RingCentral administrator token, and stores the returned opaque plugin credential and manifest metadata." } }, "/plugin/unregister": { "delete": { "tags": [ "Plugins" ], "summary": "Remove a local plugin registration", "operationId": "deletePluginUnregister", "parameters": [ { "name": "pluginId", "in": "query", "required": true, "description": "Developer Console plugin identifier whose local account registration will be removed.", "schema": { "type": "string", "minLength": 1 } }, { "name": "rcAccountId", "in": "query", "required": true, "description": "RingCentral account that owns the local plugin registration. It must match the administrator token.", "schema": { "type": "string", "minLength": 1 } }, { "name": "pluginName", "in": "query", "required": false, "deprecated": true, "description": "Legacy plugin platform key accepted by the route but ignored by the current unregister handler.", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ringCentralAccessToken": [] }, { "legacyRingCentralAccessToken": [] } ], "description": "Removes the account's local App Connect plugin registration after RingCentral administrator validation. The current protocol does not notify the remote plugin server or revoke its credential, so providers need their own stale-account cleanup and retention policy." } }, "/plugin/licenseStatus": { "get": { "tags": [ "Plugins" ], "summary": "Get plugin license status for a user", "operationId": "getPluginLicenseStatus", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "rcAccountId", "in": "query", "required": true, "description": "RingCentral account id whose plugin license is being checked.", "schema": { "type": "string", "minLength": 1 } }, { "name": "pluginId", "in": "query", "required": true, "description": "Plugin identifier from the connector manifest.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "description": "Calls the installed plugin server's optional licenseStatusUrl with the stored account-scoped plugin credential and forwards its advisory status to the browser client. A missing installation returns null; provider lookup failures can be normalized to HTTP 200 with licenseStatus false. Current logging code does not use this result to gate invocation." } }, "/plugin/async-callback/{taskId}": { "post": { "tags": [ "Plugins" ], "summary": "Receive an async plugin callback", "description": "Completes a callback-enabled asynchronous call-plugin task identified by its random task UUID. The UUID is a bearer capability and expires after seven days. A successful report appends note to the existing CRM activity and deletes the task; a plugin-reported failure marks the task failed and is acknowledged with HTTP 200.", "operationId": "postPluginAsyncCallback", "parameters": [ { "$ref": "#/components/parameters/taskId" } ], "requestBody": { "$ref": "#/components/requestBodies/AsyncPluginCallback" }, "responses": { "200": { "description": "Async plugin callback result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncPluginCallbackResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Async plugin task was not found or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncPluginCallbackResponse" } } } }, "500": { "description": "Callback was valid, but App Connect failed to update the CRM log.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncPluginCallbackResponse" } } } } } } }, "/ringcentral/admin/report": { "get": { "tags": [ "RingCentral Reports" ], "summary": "Generate an admin report", "operationId": "getRingCentralAdminReport", "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone used to group report data.", "schema": { "type": "string" } }, { "name": "timeFrom", "in": "query", "required": false, "description": "Inclusive report start time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "timeTo", "in": "query", "required": false, "description": "Exclusive report end time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "groupBy", "in": "query", "required": false, "description": "Report aggregation interval.", "schema": { "type": "string" } } ], "description": "Generates an account-level RingCentral calls and messages report using OAuth credentials previously stored for the RingCentral account associated with userJwt. The route authenticates an App Connect CRM user but does not independently verify that the caller is currently a RingCentral administrator." } }, "/ringcentral/admin/userReport": { "get": { "tags": [ "RingCentral Reports" ], "summary": "Generate an admin user report", "operationId": "getRingCentralAdminUserReport", "responses": { "200": { "$ref": "#/components/responses/OkJson" }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "rcExtensionId", "in": "query", "required": true, "description": "RingCentral extension identifier.", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone used for report data.", "schema": { "type": "string" } }, { "name": "timeFrom", "in": "query", "required": false, "description": "Inclusive report start time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "timeTo", "in": "query", "required": false, "description": "Exclusive report end time.", "schema": { "type": "string", "format": "date-time" } } ], "description": "Generates RingCentral calls and messages report data for the requested extension using OAuth credentials stored for the App Connect user's RingCentral account. The route does not independently verify current RingCentral administrator status." } }, "/ringcentral/oauth/callback": { "get": { "tags": [ "RingCentral Reports" ], "summary": "RingCentral admin OAuth callback", "description": "Exchanges a RingCentral OAuth authorization code and stores the resulting account-level credentials for report access. The target RingCentral account is taken from the App Connect CRM user session, not from a caller-supplied account identifier.", "operationId": "getRingCentralOauthCallback", "parameters": [ { "name": "code", "in": "query", "required": true, "description": "One-time authorization code returned by RingCentral OAuth.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The RingCentral OAuth authorization was completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicMutationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ] } }, "/debug/report/url": { "get": { "tags": [ "RingCentral Reports" ], "summary": "Generate a debug report URL", "operationId": "getDebugReportUrl", "responses": { "200": { "x-app-connect-generated-contract": true, "description": "A short-lived debug-report upload URL.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebugReportUrlResponse" }, "examples": { "uploadUrl": { "summary": "Presigned report upload URL", "value": { "presignedUrl": "https://uploads.example.com/debug-report.json?signature=example" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "description": "Creates a presigned URL for uploading a JSON debug report to error-log storage. The URL accepts an HTTP PUT with JSON content and expires after five minutes; it should be treated as a short-lived bearer capability." } }, "/accountData": { "get": { "tags": [ "Account data" ], "summary": "Get account-level CRM data cached for the current CRM account", "operationId": "getAccountData", "security": [ { "userJwt": [] }, { "legacyUserJwt": [] } ], "parameters": [ { "name": "keys", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated connector-registered account data keys to fetch (e.g. activityTypes)." }, { "name": "forceRefresh", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Bypass the cached value and refetch from the CRM before returning." } ], "responses": { "200": { "description": "Requested account data keyed by data key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "successful": { "type": "boolean" }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" }, "data": { "type": "object", "additionalProperties": true, "description": "Map of requested data key to its cached value." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedSession" } }, "description": "Returns account-level CRM metadata (e.g. Pipedrive activity types) registered by the connector's accountData descriptor table. Values are cached per (rcAccountId, platform, dataKey) with a lazy TTL refresh; pass forceRefresh=true to bypass the cache. Unknown keys return 400." } } }, "x-app-connect-generated-contracts": { "version": 1, "schemas": [ "AdminSuccessMessage", "AdminSettingsUpdateRequest", "ManagedAuthFieldDefinition", "StoredFieldValue", "ManagedAuthAdminUserValue", "ManagedAuthAdminResponse", "ManagedAuthUpdateRequest", "ManagedOAuthValues", "AdminManagedOAuthCacheRequest", "AppointmentAttendee", "IdentifiedAppointment", "AppointmentContactReference", "AppointmentCreateInput", "AppointmentPatchInput", "AppointmentCreateRequest", "AppointmentPatchRequest", "AppointmentStatusUpdateRequest", "AppointmentFailureResponse", "AppointmentListResponse", "AppointmentCreateResponse", "AppointmentRecordResponse", "AppointmentActionResponse", "ReturnMessage", "BasicMutationResponse", "ApiKeyLoginRequest", "ApiKeyLoginResponse", "AuthValidationResponse", "ManagedAuthStateResponse", "ManagedOAuthStateResponse", "HealthResponse", "ReleaseNoteItem", "ReleaseNoteSections", "ReleaseNotesResponse", "ServerVersionInfoResponse", "ImplementedInterfacesResponse", "UserInfoHashResponse", "DebugReportUrlResponse", "PluginRegisterRequest", "PluginMutationResponse", "AdditionalSubmission", "ContactInfo", "CallLogMutationResponse", "MessageLogResponse", "CallDispositionRequest", "UserSetting", "UserSettings", "UserSettingsEnvelope", "UserSettingsUpdateRequest" ], "requestBodies": [ "ApiKeyLogin", "PluginRegister", "CallDisposition", "UserSettingsUpdate", "AdminSettingsUpdate", "ManagedAuthUpdate", "AdminManagedOAuthCache", "AppointmentCreate", "AppointmentPatch", "AppointmentStatusUpdate" ], "operations": [ { "method": "get", "path": "/isAlive", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/releaseNotes", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/apiKeyLogin", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "get", "path": "/serverVersionInfo", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/implementedInterfaces", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/userInfoHash", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/debug/report/url", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/plugin/register", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "post", "path": "/callLog", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/messageLog", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "put", "path": "/callDisposition", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "get", "path": "/authValidation", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/apiKeyManagedAuthState", "parameters": [ "query:devRcAccountId" ], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/oauthManagedAuthState", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/user/preloadSettings", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/user/refreshInfo", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/user/settings", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/user/settings", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "post", "path": "/admin/settings", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "get", "path": "/admin/managedAuth", "parameters": [ "query:devRcAccountId" ], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/admin/managedAuth", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "post", "path": "/admin/managedOAuth/cache", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "delete", "path": "/admin/managedOAuth/cache", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "delete", "path": "/admin/managedOAuth/account", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "get", "path": "/appointments", "parameters": [ "query:startDate", "query:endDate" ], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/appointments", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "patch", "path": "/appointments/{appointmentId}", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "post", "path": "/appointments/{appointmentId}/status", "parameters": [], "requestBody": true, "responses": [ "200" ] }, { "method": "get", "path": "/appointments/{appointmentId}/refresh", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/appointments/{appointmentId}/confirm", "parameters": [], "requestBody": false, "responses": [ "200" ] }, { "method": "post", "path": "/appointments/{appointmentId}/cancel", "parameters": [], "requestBody": false, "responses": [ "200" ] } ] }, "components": { "securitySchemes": { "userJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "App Connect CRM-session JWT issued by /apiKeyLogin or /oauth-callback. It is not a RingCentral OAuth token. A response can rotate it in X-Refreshed-JWT-Token." }, "legacyUserJwt": { "type": "apiKey", "in": "query", "name": "jwtToken", "description": "Legacy query location for the App Connect CRM-session JWT. Prefer Authorization: Bearer. Query credentials can leak through URLs, logs, analytics, and browser history and must never be recorded." }, "ringCentralAccessToken": { "type": "apiKey", "in": "header", "name": "X-RC-Access-Token", "description": "RingCentral OAuth access token used to validate a RingCentral user or administrator. This credential is separate from userJwt and must not be logged." }, "legacyRingCentralAccessToken": { "type": "apiKey", "in": "query", "name": "rcAccessToken", "description": "Legacy query location for a RingCentral OAuth access token. Prefer X-RC-Access-Token. Query credentials can leak through URLs and logs; some legacy request bodies also carry rcAccessToken." } }, "parameters": { "platform": { "name": "platform", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Connector platform key from the App Connect manifest." }, "phoneNumber": { "name": "phoneNumber", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Phone number to search, normally E.164." }, "appointmentId": { "name": "appointmentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connector-assigned CRM appointment identifier." }, "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-generated call-back entry identifier." }, "taskId": { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Random asynchronous plugin task UUID embedded in the callback URL. Treat it as a bearer capability; tasks expire after seven days." }, "sessionIds": { "name": "sessionIds", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated RingCentral call session ids. The server processes at most five ids." }, "extensionNumber": { "name": "extensionNumber", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Legacy RingCentral extension number used to disambiguate duplicated call session ids when hashedExtensionId is unavailable." }, "hashedExtensionId": { "name": "hashedExtensionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Hashed RingCentral extension id used to disambiguate duplicated call session ids. Preferred over extensionNumber when available." }, "requireDetails": { "name": "requireDetails", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, the server calls the connector getCallLog interface and includes CRM log details." }, "isExtension": { "name": "isExtension", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Marks the lookup as an internal extension-number lookup." } }, "requestBodies": { "GenericJson": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "description": "Connector-defined JSON payload. The exact fields depend on the selected connector interface." }, "ApiKeyLogin": { "x-app-connect-generated-contract": true, "required": true, "description": "Connector and credential data used to create an App Connect user session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyLoginRequest" }, "examples": { "apiKey": { "summary": "API-key login", "value": { "platform": "exampleCRM", "apiKey": "example-api-key", "hostname": "crm.example.com" } } } } } }, "CreateContact": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } }, "description": "CRM contact identity and optional connector-defined creation fields." }, "CreateCallLog": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallLogRequest" } } }, "description": "RingCentral call, CRM contact association, note, and optional enrichment data. Recording download URLs and nested tokens are sensitive." }, "UpdateCallLog": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCallLogRequest" } } }, "description": "RingCentral session identity and the CRM call-activity fields to update." }, "CallNoteCache": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallNoteCacheRequest" } } }, "description": "RingCentral session ID and note to cache for up to one hour before server-side logging." }, "CallDisposition": { "x-app-connect-generated-contract": true, "required": true, "description": "Call-log identity and the dispositions selected by the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDispositionRequest" }, "examples": { "qualifiedLead": { "summary": "Set a call disposition", "value": { "sessionId": "s-a1b2c3d4", "extensionNumber": "101", "hashedExtensionId": "c16b7b40d7a9d5b5f6d8f633f0e362af", "dispositions": { "outcome": "Qualified lead" } } } } } } }, "MessageLog": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageLogRequest" } } }, "description": "RingCentral message conversation, CRM contact association, and optional connector-specific logging fields." }, "AsyncPluginCallback": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncPluginCallbackRequest" } } }, "description": "Completion report for the task identified by the callback URL. successful describes plugin work, not HTTP transport success." }, "AppointmentStatusUpdate": { "x-app-connect-generated-contract": true, "required": true, "description": "New appointment status. Status support depends on connector capability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentStatusUpdateRequest" }, "examples": { "tentative": { "summary": "Mark an appointment tentative", "value": { "status": "tentative" } } } } } }, "PluginRegister": { "x-app-connect-generated-contract": true, "required": true, "description": "Plugin and RingCentral account identifiers to register.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginRegisterRequest" }, "examples": { "sharedPlugin": { "summary": "Register a shared plugin", "value": { "pluginId": "plugin.example", "rcAccountId": "123456789", "pluginAccess": "shared", "pluginName": "examplePlugin" } } } } } }, "UserSettingsUpdate": { "x-app-connect-generated-contract": true, "required": true, "description": "User settings to upsert and setting keys to remove.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsUpdateRequest" }, "examples": { "update": { "summary": "Update user settings", "value": { "userSettings": { "theme": { "value": "dark", "customizable": true, "defaultValue": "system", "options": [ "system", "light", "dark" ] } }, "settingKeysToRemove": [ "legacySetting" ] } } } } } }, "AdminSettingsUpdate": { "x-app-connect-generated-contract": true, "required": true, "description": "Account-level App Connect settings. Nested setting definitions are extensible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSettingsUpdateRequest" }, "examples": { "settings": { "summary": "Update account settings", "value": { "adminSettings": { "userSettings": { "autoLogCalls": true, "autoLogMessages": false } } } } } } } }, "ManagedAuthUpdate": { "x-app-connect-generated-contract": true, "required": true, "description": "Account-scoped or user-scoped managed authentication values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAuthUpdateRequest" }, "examples": { "account": { "summary": "Update account-scoped values", "value": { "scope": "org", "values": { "tenantId": "tenant.example" }, "fieldsToRemove": [ "legacyTenantId" ] } }, "user": { "summary": "Update user-scoped values", "value": { "scope": "user", "rcExtensionId": "101", "rcUserName": "Ada Lovelace", "values": { "userToken": "example-user-token" }, "fieldsToRemove": [ "oldUserToken" ] } } } } } }, "AdminManagedOAuthCache": { "x-app-connect-generated-contract": true, "required": true, "description": "Managed OAuth values cached until the account OAuth flow completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminManagedOAuthCacheRequest" }, "examples": { "oauth": { "summary": "Cache managed OAuth client settings", "value": { "values": { "clientId": "managed-oauth-client", "clientSecret": "example-client-secret", "authorizationUri": "https://crm.example.com/oauth/authorize", "accessTokenUri": "https://crm.example.com/oauth/token", "scopes": [ "contacts.read", "activities.write" ] } } } } } } }, "AppointmentCreate": { "x-app-connect-generated-contract": true, "required": true, "description": "Appointment payload. The wrapper is canonical; the direct form remains for compatibility.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCreateRequest" }, "examples": { "appointment": { "summary": "Create an appointment", "value": { "payload": { "title": "Strategy Call", "summary": "Discuss case plan", "startTimeUtc": "2026-07-20T19:00:00.000Z", "durationMinutes": 30, "contacts": [ { "id": "501", "type": "Contact" } ] } } } } } } }, "AppointmentPatch": { "x-app-connect-generated-contract": true, "required": true, "description": "Partial appointment update. Omitted fields are preserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentPatchRequest" }, "examples": { "appointment": { "summary": "Patch an appointment", "value": { "patch": { "title": "Updated Strategy Call" } } } } } } }, "CallDownCreate": { "required": true, "description": "Callback scheduling fields. Current clients send display fields that the server accepts but does not currently persist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownCreateRequest" } } } }, "CallDownPatch": { "required": true, "description": "Persisted callback fields to update. At least one handler-supported field is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDownPatchRequest" } } } } }, "responses": { "OkJson": { "description": "Successful route-specific JSON response. Consult the operation description for ownership and semantics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "BadRequest": { "description": "Bad request, missing authentication, or connector error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } }, "Forbidden": { "description": "The caller is authenticated but is not permitted to perform the operation.", "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "UnauthorizedSession": { "description": "The user session is expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Refreshed-JWT-Token": { "$ref": "#/components/headers/RefreshedUserJwt" } } } }, "schemas": { "ReturnMessage": { "type": "object", "properties": { "message": { "type": "string", "description": "User-facing status or error message." }, "messageType": { "type": "string", "description": "Presentation severity. Common values are success, info, warning, danger, and error." }, "ttl": { "type": "integer", "minimum": 0, "maximum": 2147483647, "format": "int32", "description": "Suggested notification display time in milliseconds." }, "details": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Extensible JSON object whose fields are defined by the selected connector or workflow." }, "description": "Optional structured details for clients that can present more than the main message." } }, "additionalProperties": true, "description": "Optional user-facing notification returned by connector and App Connect workflows.", "x-app-connect-generated-contract": true }, "ApiKeyLoginRequest": { "type": "object", "properties": { "platform": { "type": "string", "minLength": 1, "description": "Connector platform identifier from the App Connect manifest.", "example": "exampleCRM" }, "apiKey": { "type": "string", "format": "password", "writeOnly": true, "description": "Primary connector credential. It can be omitted when managed authentication supplies the value." }, "rcAccessToken": { "type": "string", "format": "password", "writeOnly": true, "deprecated": true, "description": "Legacy body location for a RingCentral access token. Use the X-RC-Access-Token header instead." }, "rcAccountId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Ignored browser-client compatibility field. The server derives the RingCentral account from rcAccessToken.", "deprecated": true }, "rcExtensionId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Ignored browser-client compatibility field. The server derives the RingCentral extension from rcAccessToken.", "deprecated": true }, "userEmail": { "type": "string", "deprecated": true, "description": "Ignored browser-client compatibility field. Connector credential fields belong in additionalInfo." }, "hostname": { "type": "string", "description": "Optional connector host name for CRM deployments with tenant-specific endpoints." }, "proxyId": { "type": "string", "description": "Optional proxy connector identifier." }, "connectorId": { "type": "string", "description": "Developer Portal connector identifier used to resolve managed authentication fields." }, "devRcAccountId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "RingCentral account that owns the private or shared Developer Portal connector." }, "isPrivate": { "type": "boolean", "default": false, "description": "Whether connectorId identifies a private connector." }, "additionalInfo": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Connector-defined credential fields, such as tenant or user identifiers." } }, "required": [ "platform" ], "additionalProperties": false, "description": "Credentials and connector context used to establish an App Connect session for an API-key connector.", "x-app-connect-generated-contract": true }, "ApiKeyLoginResponse": { "type": "object", "properties": { "jwtToken": { "type": "string", "description": "App Connect JWT used to authenticate subsequent user operations." }, "name": { "type": "string", "description": "Display name returned by the CRM connector." }, "returnMessage": { "description": "Optional connector message about the completed login.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "jwtToken" ], "additionalProperties": true, "description": "Successful API-key login result and the new App Connect session token.", "x-app-connect-generated-contract": true }, "ErrorResponse": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "error": { "description": "Route-specific error value. It can be text, an Error-like object, or an upstream payload." }, "successful": { "type": "boolean", "description": "False when the legacy error envelope reports business failure." }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" } }, "additionalProperties": true } ], "description": "Error payload. Legacy routes may return a plain string instead." }, "GenericSuccessResponse": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Route-specific JSON response. Consult the operation description; this generic shape is retained for legacy endpoints that do not have a stable shared schema." }, "BasicMutationResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "description": "Whether the requested operation completed successfully." }, "returnMessage": { "anyOf": [ { "$ref": "#/components/schemas/ReturnMessage" }, { "type": "string" } ], "description": "Optional status message. Most routes return a structured notification; a few legacy routes return plain text." } }, "required": [ "successful" ], "additionalProperties": true, "description": "Standard result envelope for an App Connect mutation.", "x-app-connect-generated-contract": true }, "ContactInfo": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "CRM record identifier. The synthetic create-new-contact choice uses the exact sentinel createNewContact." }, "name": { "type": "string", "description": "CRM contact display name." }, "phone": { "type": "string", "description": "Phone number associated with the matched contact." }, "phoneNumber": { "type": "string", "description": "Compatibility alias for the matched contact phone number." }, "type": { "type": "string", "description": "CRM entity type, such as Contact, Lead, or Candidate." }, "title": { "type": "string", "description": "Contact job title when supplied by the connector." }, "company": { "type": "string", "description": "Contact company or organization name." }, "email": { "type": "string", "description": "Contact email address." }, "createdDate": { "type": "string", "description": "Connector-formatted CRM record creation date or timestamp." }, "mostRecentActivityDate": { "type": "string", "description": "Connector-formatted date or timestamp of the contact's most recent CRM activity." }, "additionalInfo": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Connector-defined association, ownership, or display metadata for this contact." }, "isNewContact": { "type": "boolean", "description": "Whether this is a synthetic create-new-contact option rather than an existing CRM record." } }, "additionalProperties": true, "description": "Connector-normalized CRM contact returned by lookup and create operations.", "x-app-connect-generated-contract": true }, "ContactSearchResponse": { "type": "object", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "description": "Whether the connector completed the lookup successfully." }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" }, "contact": { "type": "array", "items": { "$ref": "#/components/schemas/ContactInfo" }, "description": "Matched contacts. The legacy property name is singular even though its value is an array and can include a synthetic create-new choice." } }, "description": "Result of a connector-backed CRM contact search." }, "CreateContactRequest": { "type": "object", "required": [ "phoneNumber", "newContactName" ], "properties": { "phoneNumber": { "type": "string", "description": "Phone number for the new CRM record, normally in E.164 form." }, "newContactName": { "type": "string", "description": "Display name for the new CRM record." }, "newContactType": { "type": "string", "description": "Connector-defined CRM entity type, such as Contact, Lead, or Candidate." }, "additionalSubmission": { "type": "object", "additionalProperties": true, "description": "Connector-defined creation or association fields collected by App Connect." } }, "description": "Standard CRM contact creation fields plus connector-specific submission data." }, "ContactMutationResponse": { "type": "object", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "description": "Whether the CRM contact was created." }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" }, "contact": { "$ref": "#/components/schemas/ContactInfo" } }, "description": "Result of creating a CRM contact through the active connector." }, "RcParty": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "External or direct phone number when available." }, "extensionNumber": { "type": "string", "description": "RingCentral extension number when available." }, "extensionId": { "type": "string", "description": "RingCentral extension identifier when available." }, "name": { "type": "string", "description": "Caller or callee display name." }, "location": { "type": "string", "description": "RingCentral-provided geographic location text." } }, "additionalProperties": true, "description": "RingCentral caller or callee identity embedded in a call record." }, "RcCallRecording": { "type": "object", "properties": { "id": { "type": "string", "description": "RingCentral recording identifier." }, "uri": { "type": "string", "format": "uri", "description": "RingCentral recording resource URI." }, "type": { "type": "string", "enum": [ "Automatic", "OnDemand" ], "description": "Whether recording was automatic or started on demand." }, "contentUri": { "type": "string", "format": "uri", "description": "RingCentral media endpoint. Access normally requires a RingCentral OAuth token." }, "link": { "type": "string", "format": "uri", "description": "Browser-accessible recording link when RingCentral provides one." } }, "additionalProperties": true, "description": "RingCentral call-recording metadata. Recording and download URLs can be sensitive." }, "RcCallLogLeg": { "type": "object", "properties": { "legType": { "type": "string", "description": "RingCentral leg classification." }, "master": { "type": "boolean", "description": "Whether this is the master leg for the call." }, "direction": { "type": "string", "enum": [ "Inbound", "Outbound" ], "description": "Inbound or outbound leg direction." }, "action": { "type": "string", "description": "RingCentral action such as Phone Call or VoIP Call." }, "result": { "type": "string", "description": "RingCentral leg result such as Accepted, Missed, or Voicemail." }, "startTime": { "type": "string", "format": "date-time", "description": "Leg start time in ISO 8601 date-time form." }, "duration": { "type": "integer", "format": "int64", "description": "Leg duration in seconds." }, "from": { "$ref": "#/components/schemas/RcParty" }, "to": { "$ref": "#/components/schemas/RcParty" } }, "additionalProperties": true, "description": "One RingCentral call leg included in a detailed call record." }, "RcCallLogRecord": { "type": "object", "required": [ "sessionId" ], "properties": { "id": { "type": "string", "description": "RingCentral call-log record identifier." }, "uri": { "type": "string", "format": "uri", "description": "RingCentral call-log resource URI." }, "accountId": { "type": "string", "description": "RingCentral account identifier associated with the call." }, "sessionId": { "type": "string", "description": "RingCentral call session identifier used for App Connect de-duplication and CRM mapping." }, "telephonySessionId": { "type": "string", "description": "RingCentral telephony session identifier when available." }, "direction": { "type": "string", "enum": [ "Inbound", "Outbound" ], "description": "Inbound or outbound call direction." }, "type": { "type": "string", "enum": [ "Voice", "Fax" ], "description": "RingCentral communication type." }, "action": { "type": "string", "description": "RingCentral call action." }, "result": { "type": "string", "description": "RingCentral call result." }, "reason": { "type": "string", "description": "Optional RingCentral result reason." }, "startTime": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64", "minimum": 0 } ], "description": "Call start as ISO 8601 date-time or epoch milliseconds. Server-side logging uses epoch milliseconds." }, "duration": { "oneOf": [ { "type": "integer", "format": "int64", "minimum": 0 }, { "type": "string", "enum": [ "pending" ] } ], "description": "Call duration in seconds, or the literal pending for a server-side logging record created before call completion." }, "durationMs": { "type": "integer", "format": "int64", "description": "Call duration in milliseconds when supplied by a realtime event." }, "from": { "$ref": "#/components/schemas/RcParty" }, "to": { "$ref": "#/components/schemas/RcParty" }, "recording": { "$ref": "#/components/schemas/RcCallRecording" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/RcCallLogLeg" }, "description": "Detailed RingCentral call legs when available." }, "customSubject": { "type": "string", "description": "Client- or server-generated CRM activity subject." }, "lastModifiedTime": { "type": "string", "format": "date-time", "description": "RingCentral call-log last-modified timestamp." } }, "additionalProperties": true, "description": "RingCentral call record accepted from the browser client or server-side logging service. Unknown RingCentral fields are preserved for connector use." }, "AdditionalSubmission": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Connector-defined logging fields assembled by the browser client or server-side logging service, including Bullhorn note actions, Clio billing state, and administrator-assignment metadata when configured.", "x-app-connect-generated-contract": true }, "CreateCallLogRequest": { "type": "object", "required": [ "logInfo", "contactId" ], "properties": { "logInfo": { "$ref": "#/components/schemas/RcCallLogRecord" }, "extensionNumber": { "type": "string", "description": "Legacy RingCentral extension-number identity fallback used with sessionId." }, "hashedExtensionId": { "type": "string", "description": "Deployment-scoped hashed RingCentral extension identifier used by browser logging." }, "rcExtensionId": { "type": "string", "description": "Raw RingCentral extension identifier sent by server-side logging and hashed by the connector server before persistence." }, "contactId": { "type": "string", "description": "CRM contact identifier associated with the activity." }, "contactType": { "type": "string", "description": "Connector-defined CRM entity type for contactId." }, "contactName": { "type": "string", "description": "Display name of the associated CRM contact." }, "note": { "type": "string", "description": "User or server-generated note for the CRM activity." }, "additionalSubmission": { "$ref": "#/components/schemas/AdditionalSubmission" }, "aiNote": { "type": "string", "description": "Optional AI-generated note text." }, "transcript": { "type": "string", "description": "Optional call transcript text." }, "ringSenseTranscript": { "type": "string", "description": "Optional RingSense transcript supplied by server-side logging." }, "ringSenseSummary": { "type": "string", "description": "Optional RingSense summary supplied by server-side logging." }, "ringSenseAIScore": { "type": "object", "additionalProperties": true, "description": "Connector-defined RingSense scoring data." }, "ringSenseBulletedSummary": { "type": "string", "description": "Optional RingSense bulleted summary." }, "ringSenseLink": { "type": "string", "format": "uri", "description": "Link to the RingSense conversation record." }, "overridingFormat": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "One or more connector-specific phone-number formats to try. A blank legacy string is also accepted from server-side logging." } }, "example": { "logInfo": { "id": "123456789", "sessionId": "987654321", "telephonySessionId": "s-a1b2c3", "direction": "Inbound", "from": { "phoneNumber": "+14155550100", "name": "Jane Smith" }, "to": { "phoneNumber": "+16505550199", "extensionNumber": "101" }, "startTime": "2026-06-24T02:30:00.000Z", "duration": 125, "result": "Accepted", "recording": { "link": "https://example.com/recording/123" } }, "extensionNumber": "101", "hashedExtensionId": "hashed-extension-101", "contactId": "crm-contact-123", "contactName": "Jane Smith", "contactType": "Contact", "note": "Discussed renewal options." }, "description": "Call, contact, note, identity, and optional RingSense data used to create a CRM call activity." }, "UpdateCallLogRequest": { "type": "object", "required": [ "sessionId" ], "properties": { "sessionId": { "type": "string", "description": "RingCentral call session identifier used to find the local CRM activity mapping." }, "extensionNumber": { "type": "string", "description": "Legacy extension-number identity fallback used with sessionId." }, "hashedExtensionId": { "type": "string", "description": "Deployment-scoped hashed extension identifier used to find the mapping." }, "rcExtensionId": { "type": "string", "description": "Raw RingCentral extension identifier sent by server-side logging and hashed locally before lookup." }, "accountId": { "type": "string", "description": "RingCentral account identifier used for analytics context by server-side logging." }, "recordingLink": { "type": "string", "format": "uri", "description": "Browser-accessible RingCentral recording link." }, "recordingDownloadLink": { "type": "string", "format": "uri", "description": "Recording download URL that can embed a RingCentral access token. Treat as secret; do not log or retain unnecessarily." }, "subject": { "type": "string", "description": "Replacement CRM activity subject." }, "note": { "type": "string", "description": "Replacement or appended activity note, depending on connector behavior." }, "startTime": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "integer", "format": "int64", "minimum": 0 } ], "description": "Call start as ISO 8601 date-time or epoch milliseconds. Server-side logging uses epoch milliseconds." }, "duration": { "type": "integer", "format": "int64", "description": "Completed call duration in seconds." }, "result": { "type": "string", "description": "RingCentral call result." }, "direction": { "type": "string", "enum": [ "Inbound", "Outbound" ], "description": "Inbound or outbound call direction." }, "from": { "$ref": "#/components/schemas/RcParty" }, "to": { "$ref": "#/components/schemas/RcParty" }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/RcCallLogLeg" }, "description": "Replacement detailed RingCentral call legs." }, "aiNote": { "type": "string", "description": "Optional AI-generated note text." }, "transcript": { "type": "string", "description": "Optional call transcript text." }, "additionalSubmission": { "$ref": "#/components/schemas/AdditionalSubmission" }, "ringSenseTranscript": { "type": "string", "description": "Optional RingSense transcript." }, "ringSenseSummary": { "type": "string", "description": "Optional RingSense summary." }, "ringSenseAIScore": { "type": "object", "additionalProperties": true, "description": "Connector-defined RingSense scoring data." }, "ringSenseBulletedSummary": { "type": "string", "description": "Optional RingSense bulleted summary." }, "ringSenseLink": { "type": "string", "format": "uri", "description": "Link to the RingSense conversation record." }, "telephonySessionId": { "type": "string", "description": "RingCentral telephony session identifier supplied by current browser call updates when available." } }, "description": "Fields used to find and partially update an existing CRM call activity." }, "CallLogInfo": { "type": "object", "properties": { "subject": { "type": "string", "description": "CRM activity subject." }, "note": { "type": "string", "description": "CRM activity note." }, "fullBody": { "type": "string", "description": "Connector-formatted complete activity body." }, "fullLogResponse": { "type": "object", "additionalProperties": true, "description": "Raw connector activity response when details were requested." }, "contactName": { "type": "string", "description": "Associated CRM contact display name." }, "dispositions": { "type": "object", "additionalProperties": true, "description": "Connector-defined disposition values." } }, "additionalProperties": true, "description": "Connector-normalized details for an existing CRM call activity." }, "CallLogLookupItem": { "type": "object", "required": [ "sessionId", "matched" ], "properties": { "sessionId": { "type": "string", "description": "Requested RingCentral call session identifier." }, "matched": { "type": "boolean", "description": "Whether a local CRM activity mapping exists for the session and extension identity." }, "logId": { "type": "string", "description": "Connector-assigned CRM activity identifier when matched." }, "logData": { "$ref": "#/components/schemas/CallLogInfo" } }, "description": "Lookup result for one requested RingCentral call session." }, "CallLogLookupResponse": { "type": "object", "required": [ "successful", "logs" ], "properties": { "successful": { "type": "boolean", "description": "Whether lookup completed without connector-session failure." }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/CallLogLookupItem" }, "description": "One result per processed RingCentral session identifier." }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" } }, "description": "Existing-activity lookup results for up to five RingCentral call sessions." }, "CallLogMutationResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "description": "Whether the CRM call activity was created or accepted." }, "logId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Connector-assigned CRM activity identifier." }, "returnMessage": { "description": "Optional connector status message.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful" ], "additionalProperties": true, "description": "Result of creating a CRM call activity.", "x-app-connect-generated-contract": true }, "CallLogUpdateResponse": { "type": "object", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "description": "Whether the connector updated the CRM activity." }, "logId": { "type": "string", "description": "Connector-assigned CRM activity identifier." }, "updatedNote": { "type": "string", "description": "Final note returned by the connector after update processing." }, "returnMessage": { "$ref": "#/components/schemas/ReturnMessage" } }, "description": "Result of updating an existing CRM call activity." }, "CallNoteCacheRequest": { "type": "object", "required": [ "sessionId", "note" ], "properties": { "sessionId": { "type": "string", "description": "RingCentral call session identifier used as the cache key." }, "note": { "type": "string", "description": "Call note to retain for up to one hour." } }, "description": "Temporary call note stored before full server-side call logging." }, "CallDispositionRequest": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "description": "RingCentral call session identifier." }, "extensionNumber": { "anyOf": [ { "nullable": true, "type": "string" }, { "nullable": true, "type": "number" } ], "description": "Legacy RingCentral extension-number identity fallback." }, "hashedExtensionId": { "anyOf": [ { "nullable": true, "type": "string" }, { "nullable": true, "type": "number" } ], "description": "Hashed RingCentral extension id used to find the local call-log mapping." }, "dispositions": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Disposition values keyed by connector-defined field identifier." }, "additionalSubmission": { "description": "Accepted for client compatibility; the current call-disposition handler does not persist or forward these values.", "allOf": [ { "$ref": "#/components/schemas/AdditionalSubmission" } ] } }, "required": [ "sessionId" ], "additionalProperties": true, "description": "Call identity and connector-defined dispositions to apply to an existing CRM activity.", "x-app-connect-generated-contract": true }, "MessageAttachment": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ], "description": "RingCentral attachment identifier." }, "uri": { "type": "string", "format": "uri", "description": "RingCentral attachment resource URI." }, "link": { "type": "string", "format": "uri", "description": "Attachment link when supplied by RingCentral." }, "type": { "type": "string", "enum": [ "AudioRecording", "AudioTranscription", "Text", "SourceDocument", "RenderedDocument", "MmsAttachment" ], "description": "RingCentral attachment type." }, "contentType": { "type": "string", "description": "Attachment MIME type." }, "vmDuration": { "type": "integer", "format": "int32", "description": "Voicemail audio duration in seconds." }, "fileName": { "type": "string", "description": "Attachment file name." }, "size": { "type": "integer", "format": "int32", "description": "Attachment size in bytes." }, "height": { "type": "integer", "format": "int32", "description": "Image height in pixels." }, "width": { "type": "integer", "format": "int32", "description": "Image width in pixels." } }, "additionalProperties": true, "description": "RingCentral message attachment metadata." }, "MessageParty": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Sender or recipient phone number." }, "extensionNumber": { "type": "string", "description": "RingCentral extension number when available." }, "extensionId": { "type": "string", "description": "RingCentral extension identifier when available." }, "name": { "type": "string", "description": "Party display name." }, "location": { "type": "string", "description": "RingCentral-provided geographic location." }, "recipientId": { "type": "string", "description": "RingCentral recipient identifier." }, "target": { "type": "boolean", "description": "Whether this party is the target recipient." }, "messageStatus": { "type": "string", "description": "Per-recipient RingCentral delivery status." } }, "additionalProperties": true, "description": "Sender or recipient identity on a RingCentral message." }, "RcMessage": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ], "description": "RingCentral message identifier used for de-duplication." }, "uri": { "type": "string", "format": "uri", "description": "RingCentral message-store resource URI." }, "extensionId": { "type": "string", "description": "RingCentral extension that owns the message." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" }, "description": "RingCentral message attachment metadata." }, "availability": { "type": "string", "enum": [ "Alive", "Deleted", "Purged" ], "description": "Current RingCentral message availability." }, "conversationId": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ], "description": "RingCentral conversation identifier." }, "conversation": { "type": "object", "additionalProperties": true, "description": "Additional RingCentral conversation metadata." }, "creationTime": { "type": "string", "format": "date-time", "description": "Message creation time." }, "lastModifiedTime": { "type": "string", "format": "date-time", "description": "Message last-modified time." }, "direction": { "type": "string", "enum": [ "Inbound", "Outbound" ], "description": "Inbound or outbound message direction." }, "from": { "$ref": "#/components/schemas/MessageParty" }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/MessageParty" }, "description": "RingCentral message recipients." }, "messageStatus": { "type": "string", "description": "Overall RingCentral message status." }, "priority": { "type": "string", "enum": [ "Normal", "High" ], "description": "RingCentral message priority." }, "readStatus": { "type": "string", "enum": [ "Read", "Unread" ], "description": "RingCentral read state." }, "smsDeliveryTime": { "type": "string", "format": "date-time", "description": "SMS delivery timestamp when available." }, "smsSendingAttemptsCount": { "type": "integer", "format": "int32", "description": "Number of SMS delivery attempts." }, "subject": { "type": "string", "description": "Message text or subject." }, "type": { "type": "string", "enum": [ "Fax", "SMS", "MMS", "VoiceMail", "Pager", "Text" ], "description": "RingCentral message type." }, "faxPageCount": { "type": "integer", "format": "int32", "description": "Number of fax pages." }, "faxResolution": { "type": "string", "description": "Fax resolution reported by RingCentral." }, "deliveryErrorCode": { "type": "string", "description": "RingCentral delivery error code." }, "segmentCount": { "type": "integer", "format": "int32", "description": "Number of SMS segments." }, "vmTranscriptionStatus": { "type": "string", "description": "Voicemail transcription state." }, "owner": { "type": "object", "additionalProperties": true, "description": "Additional RingCentral owner metadata." } }, "additionalProperties": true, "description": "RingCentral SMS, MMS, fax, voicemail, pager, or text record accepted for CRM logging." }, "MessageCorrespondent": { "type": "object", "required": [ "phoneNumber" ], "properties": { "phoneNumber": { "type": "string", "description": "Correspondent phone number." }, "name": { "type": "string", "description": "Correspondent display name." }, "type": { "type": "string", "description": "Connector-defined CRM entity type." }, "id": { "type": "string", "description": "Connector-assigned CRM record identifier." } }, "additionalProperties": true, "description": "CRM association for one external participant in a message conversation." }, "MessageConversationLog": { "type": "object", "required": [ "messages", "correspondents" ], "properties": { "conversationId": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ], "description": "RingCentral conversation identifier." }, "conversationLogId": { "type": "string", "description": "Client-generated shared conversation mapping identifier." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/RcMessage" }, "description": "RingCentral messages included in this logging request." }, "correspondents": { "type": "array", "items": { "$ref": "#/components/schemas/MessageCorrespondent" }, "description": "External participants and their CRM associations." }, "owner": { "type": "object", "properties": { "name": { "type": "string" } }, "additionalProperties": true, "description": "Conversation owner metadata used by supported connectors." }, "assignee": { "type": "object", "properties": { "name": { "type": "string" } }, "additionalProperties": true, "description": "Conversation assignee metadata used by supported connectors." }, "rcAccessToken": { "type": "string", "format": "password", "writeOnly": true, "description": "RingCentral OAuth access token used only to download fax or MMS attachments. Treat as secret; do not log or persist it." } }, "additionalProperties": true, "description": "RingCentral messages and CRM correspondents to log individually or as one shared conversation activity." }, "MessageLogRequest": { "type": "object", "required": [ "logInfo", "contactId" ], "properties": { "logInfo": { "$ref": "#/components/schemas/MessageConversationLog" }, "contactId": { "type": "string", "description": "Primary CRM contact identifier for the message activity." }, "contactType": { "type": "string", "description": "Connector-defined CRM entity type for contactId." }, "contactName": { "type": "string", "description": "Display name of the primary CRM contact." }, "additionalSubmission": { "$ref": "#/components/schemas/AdditionalSubmission" }, "overridingFormat": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "One or more connector-specific phone-number formats to try when resolving message parties." } }, "example": { "contactId": "crm-contact-123", "contactName": "Jane Smith", "contactType": "Contact", "logInfo": { "conversationId": 555100, "conversationLogId": "555100-2026-06-24", "correspondents": [ { "phoneNumber": "+14155550100", "name": "Jane Smith" } ], "messages": [ { "id": 1724099032020, "type": "SMS", "direction": "Inbound", "subject": "Can we talk later today?", "from": { "phoneNumber": "+14155550100", "name": "Jane Smith" }, "to": [ { "phoneNumber": "+16505550199", "extensionNumber": "101" } ], "creationTime": "2026-06-24T03:15:00.000Z" } ] } }, "description": "Message conversation, CRM association, and connector-specific fields used to create or update CRM message activities." }, "MessageLogResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "description": "Whether message logging completed without a connector error." }, "returnMessage": { "anyOf": [ { "$ref": "#/components/schemas/ReturnMessage" }, { "type": "string", "nullable": true, "enum": [ null ] } ], "description": "Optional connector status message; null is used when every message was already logged." }, "logIds": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Connector-defined entity identifier, represented as a string or number." }, "description": "RingCentral message or local conversation-mapping identifiers recorded by this request; an empty list can indicate a no-op." } }, "required": [ "successful" ], "additionalProperties": true, "description": "Result of logging an SMS, MMS, fax, voicemail, or message conversation.", "x-app-connect-generated-contract": true }, "AsyncPluginCallbackRequest": { "type": "object", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "description": "JSON boolean describing plugin work: true requests a CRM note update; false records task failure." }, "note": { "type": "string", "description": "Text appended to existing CRM Agent notes when successful is true. Ignored when false." }, "message": { "type": "string", "description": "Diagnostic result text. Stored as the task failure reason when successful is false; ignored on a successful callback." } }, "additionalProperties": true, "description": "Plugin completion report for a callback-enabled asynchronous call task." }, "AsyncPluginCallbackResponse": { "type": "object", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "description": "True when the callback report was recorded, including a plugin-reported failure; false for callback validation or processing errors." }, "message": { "type": "string", "description": "Human-readable validation or processing error when successful is false." } }, "description": "App Connect callback-processing result. successful describes whether the callback was accepted or processed, not whether the plugin background work succeeded." }, "AppointmentStatusUpdateRequest": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "description": "Requested connector status. The server normalizes this value to lowercase before dispatch." } }, "required": [ "status" ], "additionalProperties": false, "description": "Generic appointment status update request.", "x-app-connect-generated-contract": true }, "ServerVersionInfoResponse": { "type": "object", "properties": { "version": { "type": "string", "description": "Version declared by the default CRM manifest." } }, "required": [ "version" ], "additionalProperties": false, "description": "Legacy server version metadata retained for older App Connect clients.", "x-app-connect-generated-contract": true }, "ImplementedInterfacesResponse": { "type": "object", "properties": { "getAuthType": { "type": "boolean", "description": "Whether the connector implements getAuthType." }, "getOauthInfo": { "type": "boolean", "description": "For OAuth connectors, whether getOauthInfo is implemented." }, "getBasicAuth": { "type": "boolean", "description": "For API-key connectors, whether getBasicAuth is implemented." }, "getUserInfo": { "type": "boolean", "description": "Whether the connector implements getUserInfo." }, "createCallLog": { "type": "boolean", "description": "Whether the connector implements createCallLog." }, "updateCallLog": { "type": "boolean", "description": "Whether the connector implements updateCallLog." }, "getCallLog": { "type": "boolean", "description": "Whether the connector implements getCallLog." }, "createMessageLog": { "type": "boolean", "description": "Whether the connector implements createMessageLog." }, "updateMessageLog": { "type": "boolean", "description": "Whether the connector implements updateMessageLog." }, "createContact": { "type": "boolean", "description": "Whether the connector implements createContact." }, "findContact": { "type": "boolean", "description": "Whether the connector implements findContact." }, "listAppointments": { "type": "boolean", "description": "Whether the connector implements listAppointments." }, "createAppointment": { "type": "boolean", "description": "Whether the connector implements createAppointment." }, "updateAppointment": { "type": "boolean", "description": "Whether the connector implements updateAppointment." }, "refreshAppointment": { "type": "boolean", "description": "Whether the connector implements refreshAppointment." }, "confirmAppointment": { "type": "boolean", "description": "Whether the connector implements confirmAppointment." }, "cancelAppointment": { "type": "boolean", "description": "Whether the connector implements cancelAppointment." }, "unAuthorize": { "type": "boolean", "description": "Whether the connector implements unAuthorize." }, "upsertCallDisposition": { "type": "boolean", "description": "Whether the connector implements upsertCallDisposition." }, "findContactWithName": { "type": "boolean", "description": "Whether the connector implements findContactWithName." }, "getUserList": { "type": "boolean", "description": "Whether the connector implements getUserList." }, "getLicenseStatus": { "type": "boolean", "description": "Whether the connector implements getLicenseStatus." }, "getLogFormatType": { "type": "boolean", "description": "Whether the connector implements getLogFormatType." }, "refreshUserInfo": { "type": "boolean", "description": "Whether the connector implements refreshUserInfo." }, "cacheCallNote": { "type": "boolean", "description": "Whether this App Connect deployment enables the temporary call-note cache." } }, "required": [ "getAuthType", "getUserInfo", "createCallLog", "updateCallLog", "getCallLog", "createMessageLog", "updateMessageLog", "createContact", "findContact", "listAppointments", "createAppointment", "updateAppointment", "refreshAppointment", "confirmAppointment", "cancelAppointment", "unAuthorize", "upsertCallDisposition", "findContactWithName", "getUserList", "getLicenseStatus", "getLogFormatType", "refreshUserInfo", "cacheCallNote" ], "additionalProperties": true, "description": "Feature flags derived from the selected connector module and server configuration.", "x-app-connect-generated-contract": true }, "UserInfoHashResponse": { "type": "object", "properties": { "extensionId": { "type": "string", "minLength": 64, "maxLength": 64, "description": "SHA-256 hash of the supplied extension identifier." }, "accountId": { "type": "string", "minLength": 64, "maxLength": 64, "description": "SHA-256 hash of the supplied account identifier." } }, "required": [ "extensionId", "accountId" ], "additionalProperties": true, "description": "Server-keyed hashes of RingCentral account and extension identifiers.", "x-app-connect-generated-contract": true }, "DebugReportUrlResponse": { "type": "object", "properties": { "presignedUrl": { "type": "string", "format": "uri", "description": "Short-lived URL for uploading the debug report." } }, "required": [ "presignedUrl" ], "additionalProperties": true, "description": "Temporary object-storage upload destination for an App Connect debug report.", "x-app-connect-generated-contract": true }, "PluginRegisterRequest": { "type": "object", "properties": { "pluginId": { "type": "string", "minLength": 1, "description": "Plugin identifier from the developer portal." }, "rcAccountId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "RingCentral account that will receive the plugin." }, "ownerRcAccountId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "RingCentral account used to resolve a private or shared plugin manifest." }, "pluginAccess": { "type": "string", "description": "Manifest lookup mode: public uses the public catalog; private or shared uses ownerRcAccountId; when omitted, the server tries both." }, "pluginName": { "type": "string", "description": "Plugin platform key used to select the manifest entry when the manifest contains multiple platforms." }, "rcAccessToken": { "type": "string", "format": "password", "writeOnly": true, "deprecated": true, "description": "Legacy body location for a RingCentral access token. Use the X-RC-Access-Token header instead." } }, "required": [ "pluginId", "rcAccountId" ], "additionalProperties": false, "description": "Plugin catalog identity and RingCentral account context used for installation.", "x-app-connect-generated-contract": true }, "PluginMutationResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "description": "Whether the plugin installation or removal operation completed." }, "returnMessage": { "type": "string", "description": "Optional error or status message." } }, "required": [ "successful" ], "additionalProperties": true, "description": "Result of installing or removing an account-level plugin registration.", "x-app-connect-generated-contract": true }, "AuthValidationResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "description": "Whether the connector considers the stored CRM authorization valid." }, "returnMessage": { "description": "Optional connector message explaining the validation result.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful" ], "additionalProperties": true, "description": "Result of validating the current user's stored CRM authorization.", "x-app-connect-generated-contract": true }, "ManagedAuthStateResponse": { "type": "object", "properties": { "hasManagedAuth": { "type": "boolean", "description": "Whether the selected connector declares administrator-managed API-key fields." }, "allRequiredFieldsSatisfied": { "type": "boolean", "description": "Whether every required login field can be resolved from managed storage; required manual fields make this false." }, "visibleFieldConsts": { "nullable": true, "description": "Required credential field identifiers that the login form should display; null means no visibility override and allows the complete manual form.", "type": "array", "items": { "type": "string" } }, "missingRequiredFieldConsts": { "type": "array", "items": { "type": "string" }, "description": "Required credential field identifiers that are not currently available from managed storage, including unmanaged fields that must be entered manually." }, "fallbackToManualAuth": { "type": "boolean", "description": "Whether a previous managed-auth login failure marked this account and extension to retry with manual credentials." } }, "required": [ "hasManagedAuth", "allRequiredFieldsSatisfied", "visibleFieldConsts", "missingRequiredFieldConsts", "fallbackToManualAuth" ], "additionalProperties": true, "description": "Readiness of administrator-managed API-key credentials for a RingCentral account and extension.", "x-app-connect-generated-contract": true }, "ManagedOAuthStateResponse": { "type": "object", "properties": { "isAdmin": { "type": "boolean", "description": "Whether the supplied RingCentral token belongs to an account administrator." }, "hasAccountOAuth": { "type": "boolean", "description": "Whether completed account-scoped OAuth configuration exists for the connector." }, "hasPendingOAuth": { "type": "boolean", "description": "Whether administrator-supplied OAuth values are cached for an unfinished authorization flow." }, "oauthValues": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Completed managed OAuth values that are safe to return to the requesting client." }, "pendingValues": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Cached values for the administrator's in-progress OAuth setup. This object can contain sensitive client credentials." } }, "required": [ "isAdmin", "hasAccountOAuth", "hasPendingOAuth" ], "additionalProperties": true, "description": "Account-level managed OAuth setup state for the selected connector.", "x-app-connect-generated-contract": true }, "UserSetting": { "type": "object", "properties": { "value": { "description": "Setting value supplied by or returned to the client." }, "customizable": { "type": "boolean", "description": "Whether the user may override the account-managed value." }, "isCustomizable": { "type": "boolean", "description": "Legacy alias of customizable retained for older clients and connectors." }, "isRemoved": { "type": "boolean", "description": "Whether the setting has been removed and should be hidden by clients." }, "defaultValue": { "description": "Connector-manifest default used when no value is stored." }, "options": { "type": "array", "items": {}, "description": "Allowed or suggested values for selection-style settings." } }, "additionalProperties": true, "description": "One connector or App Connect user-setting entry.", "x-app-connect-generated-contract": true }, "UserSettings": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserSetting" }, "description": "User-setting entries keyed by their manifest setting identifier.", "x-app-connect-generated-contract": true }, "UserSettingsEnvelope": { "type": "object", "properties": { "userSettings": { "description": "Settings available to the user.", "allOf": [ { "$ref": "#/components/schemas/UserSettings" } ] } }, "additionalProperties": true, "description": "Optional wrapper used by settings preload and update operations.", "x-app-connect-generated-contract": true }, "UserSettingsUpdateRequest": { "type": "object", "properties": { "userSettings": { "description": "Setting entries to create or replace.", "allOf": [ { "$ref": "#/components/schemas/UserSettings" } ] }, "settingKeysToRemove": { "type": "array", "items": { "type": "string" }, "description": "Setting identifiers to remove from the user record." } }, "additionalProperties": true, "description": "Per-user settings upsert and removal request.", "x-app-connect-generated-contract": true }, "AdminSuccessMessage": { "type": "string", "description": "Plain-text confirmation returned after an administrator update succeeds.", "x-app-connect-generated-contract": true }, "AdminSettingsUpdateRequest": { "type": "object", "properties": { "adminSettings": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Account-level App Connect configuration, including user-setting overrides and optional custom-connector data." } }, "required": [ "adminSettings" ], "additionalProperties": true, "description": "Account-level App Connect settings submitted by a RingCentral administrator.", "x-app-connect-generated-contract": true }, "ManagedAuthFieldDefinition": { "type": "object", "properties": { "const": { "type": "string", "description": "Stable field identifier declared in the connector manifest." }, "required": { "type": "boolean", "description": "Whether login requires a value for this field." }, "managed": { "type": "boolean", "description": "Whether an administrator supplies this field." }, "managedScope": { "type": "string", "enum": [ "account", "user" ], "description": "Whether one value is shared by the RingCentral account or stored separately per extension." } }, "required": [ "const" ], "additionalProperties": true, "description": "Connector credential field that supports administrator-managed storage.", "x-app-connect-generated-contract": true }, "StoredFieldValue": { "type": "object", "properties": { "hasValue": { "type": "boolean", "description": "Whether a non-empty value is stored for the field." }, "value": { "description": "Sensitive decrypted value returned to the authenticated administrator, or an empty string when unset." } }, "required": [ "hasValue", "value" ], "additionalProperties": true, "description": "Administrator view of one stored managed-auth value.", "x-app-connect-generated-contract": true }, "ManagedAuthAdminUserValue": { "type": "object", "properties": { "rcExtensionId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "RingCentral extension that owns these user-scoped values." }, "rcUserName": { "type": "string", "description": "Display name associated with the RingCentral extension." }, "fields": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StoredFieldValue" }, "description": "Stored user-scoped values keyed by connector field identifier." } }, "required": [ "rcExtensionId", "rcUserName", "fields" ], "additionalProperties": true, "description": "Managed-auth values stored for one RingCentral extension.", "x-app-connect-generated-contract": true }, "ManagedAuthAdminResponse": { "type": "object", "properties": { "hasManagedAuth": { "type": "boolean", "description": "Whether the connector declares any administrator-managed authentication fields." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAuthFieldDefinition" }, "description": "All managed field definitions." }, "orgFields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAuthFieldDefinition" }, "description": "Managed fields whose values are shared across the RingCentral account." }, "userFields": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAuthFieldDefinition" }, "description": "Managed fields whose values are stored separately for each RingCentral extension." }, "orgValues": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StoredFieldValue" }, "description": "Account-scoped stored values keyed by connector field identifier." }, "userValues": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAuthAdminUserValue" }, "description": "User-scoped stored values grouped by RingCentral extension." } }, "required": [ "hasManagedAuth", "fields", "orgFields", "userFields", "orgValues", "userValues" ], "additionalProperties": true, "description": "Administrator-facing managed-auth definitions and currently stored values.", "x-app-connect-generated-contract": true }, "ManagedAuthUpdateRequest": { "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org" ], "description": "Update values shared by the RingCentral account." }, "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Field values to create or replace, keyed by field identifier." }, "fieldsToRemove": { "type": "array", "items": { "type": "string" }, "description": "Field identifiers whose stored values should be deleted." } }, "required": [ "scope" ], "additionalProperties": true }, { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "user" ], "description": "Update values for one RingCentral extension." }, "rcExtensionId": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "RingCentral extension that owns the values." }, "rcUserName": { "type": "string", "description": "Optional display name stored with the extension values." }, "values": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Field values to create or replace, keyed by field identifier." }, "fieldsToRemove": { "type": "array", "items": { "type": "string" }, "description": "Field identifiers whose stored values should be deleted." } }, "required": [ "scope", "rcExtensionId" ], "additionalProperties": true } ], "description": "Account-scoped or extension-scoped managed-auth value update.", "x-app-connect-generated-contract": true }, "ManagedOAuthValues": { "type": "object", "properties": { "clientId": { "type": "string", "description": "OAuth client identifier configured for the CRM provider." }, "clientSecret": { "type": "string", "format": "password", "writeOnly": true, "description": "OAuth client secret. Treat this value as sensitive and never log it." }, "accessTokenUri": { "type": "string", "description": "OAuth token endpoint URL." }, "authorizationUri": { "type": "string", "description": "OAuth authorization endpoint URL." }, "redirectUri": { "type": "string", "description": "Redirect URI registered with the CRM OAuth application." }, "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Requested OAuth scopes, supplied as one provider-formatted string or a list of scope names." }, "hostname": { "type": "string", "description": "Optional tenant-specific CRM hostname used by the OAuth flow." } }, "additionalProperties": true, "description": "Administrator-supplied values used to configure account-scoped CRM OAuth.", "x-app-connect-generated-contract": true }, "AdminManagedOAuthCacheRequest": { "type": "object", "properties": { "values": { "description": "OAuth values to hold until the administrator completes or cancels authorization.", "allOf": [ { "$ref": "#/components/schemas/ManagedOAuthValues" } ] } }, "additionalProperties": true, "description": "Pending managed OAuth configuration to cache for the RingCentral account.", "x-app-connect-generated-contract": true }, "AppointmentAttendee": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "CRM attendee or contact identifier." }, "name": { "type": "string", "description": "Attendee display name." }, "type": { "type": "string", "description": "Connector-specific attendee entity type." }, "status": { "type": "string", "description": "Connector-specific invitation or attendance status." }, "email": { "type": "string", "description": "Attendee email address." } }, "required": [ "id" ], "additionalProperties": true, "description": "Normalized attendee returned with an appointment.", "x-app-connect-generated-contract": true }, "AppointmentContactReference": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[1-9]\\d*$" }, { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } ], "description": "Positive CRM contact identifier." }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[1-9]\\d*$" }, { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 } ], "description": "Positive CRM contact identifier." }, "type": { "type": "string" }, "contactType": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ], "description": "CRM contact to associate with the appointment, as an id or typed reference.", "x-app-connect-generated-contract": true }, "AppointmentCreateRequest": { "anyOf": [ { "type": "object", "properties": { "payload": { "description": "Canonical appointment create payload.", "allOf": [ { "$ref": "#/components/schemas/AppointmentCreateInput" } ] } }, "required": [ "payload" ], "additionalProperties": false }, { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentCreateInput" } ] } ], "description": "Canonical wrapped appointment create request or deprecated direct payload.", "x-app-connect-generated-contract": true }, "AppointmentPatchRequest": { "anyOf": [ { "type": "object", "properties": { "patch": { "description": "Canonical partial appointment update.", "allOf": [ { "$ref": "#/components/schemas/AppointmentPatchInput" } ] } }, "required": [ "patch" ], "additionalProperties": false }, { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentPatchInput" } ] } ], "description": "Canonical wrapped appointment patch request or deprecated direct payload.", "x-app-connect-generated-contract": true }, "AppointmentListResponse": { "anyOf": [ { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Always true when the connector returned a list." }, "appointments": { "type": "array", "items": { "$ref": "#/components/schemas/IdentifiedAppointment" }, "description": "Appointments in the requested date window." } }, "required": [ "successful", "appointments" ], "additionalProperties": true, "description": "Successful appointment list result." }, { "$ref": "#/components/schemas/AppointmentFailureResponse" } ], "description": "Appointment list result, including connector-level failures returned with HTTP 200.", "x-app-connect-generated-contract": true }, "HealthResponse": { "type": "string", "enum": [ "OK" ], "description": "Literal liveness response. It does not verify databases, connectors, or upstream services.", "x-app-connect-generated-contract": true }, "ReleaseNoteItem": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "description": "Release-note category such as New or Fix." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable release-note text." } }, "required": [ "type", "description" ], "additionalProperties": false, "description": "One categorized App Connect or connector release note.", "x-app-connect-generated-contract": true }, "ReleaseNoteSections": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseNoteItem" } }, "description": "Release-note lists keyed by global or connector platform name.", "x-app-connect-generated-contract": true }, "ReleaseNotesResponse": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ReleaseNoteSections" }, "description": "App Connect and connector release notes grouped by connector-declared server version; global-only versions are not emitted.", "x-app-connect-generated-contract": true }, "AppointmentCreateInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Appointment title." }, "summary": { "type": "string", "description": "Appointment description or agenda." }, "startTimeUtc": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Appointment start timestamp, including its UTC offset." }, "durationMinutes": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Appointment duration in whole minutes." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentContactReference" }, "description": "CRM contacts to associate with or invite to the appointment." } }, "required": [ "title", "summary", "startTimeUtc", "durationMinutes" ], "additionalProperties": false, "description": "Fields required to create a connector appointment.", "x-app-connect-generated-contract": true }, "AppointmentPatchInput": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Replacement appointment title." }, "summary": { "type": "string", "description": "Replacement appointment description or agenda." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentContactReference" }, "description": "Replacement set of associated CRM contacts." } }, "additionalProperties": false, "minProperties": 1 }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Replacement appointment title." }, "summary": { "type": "string", "description": "Replacement appointment description or agenda." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentContactReference" }, "description": "Replacement set of associated CRM contacts." }, "startTimeUtc": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Replacement start timestamp, including its UTC offset." }, "durationMinutes": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Appointment duration in whole minutes." } }, "required": [ "startTimeUtc", "durationMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Replacement appointment title." }, "summary": { "type": "string", "description": "Replacement appointment description or agenda." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentContactReference" }, "description": "Replacement set of associated CRM contacts." }, "startTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Deprecated replacement start time in ISO 8601 form with an explicit offset. The paired durationMinutes field is required." }, "durationMinutes": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991, "description": "Appointment duration in whole minutes." } }, "required": [ "startTime", "durationMinutes" ], "additionalProperties": false, "deprecated": true } ], "description": "Appointment fields to replace; omitted fields remain unchanged.", "x-app-connect-generated-contract": true }, "AppointmentFailureResponse": { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ false ], "description": "Always false for a rejected appointment operation." }, "returnMessage": { "description": "Connector explanation of the failure.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful", "returnMessage" ], "additionalProperties": true, "description": "Connector-level appointment failure returned with HTTP 200.", "x-app-connect-generated-contract": true }, "AppointmentCreateResponse": { "anyOf": [ { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Always true when the connector created the appointment." }, "appointmentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Identifier assigned to the created appointment." }, "appointment": { "description": "Created appointment when the connector returns it.", "allOf": [ { "$ref": "#/components/schemas/IdentifiedAppointment" } ] }, "returnMessage": { "description": "Optional connector status message.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful", "appointmentId" ], "additionalProperties": true, "description": "Successful appointment creation result." }, { "$ref": "#/components/schemas/AppointmentFailureResponse" } ], "description": "Appointment creation result.", "x-app-connect-generated-contract": true }, "AppointmentRecordResponse": { "anyOf": [ { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Always true when the connector returned the updated record." }, "appointmentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Identifier of the affected appointment." }, "appointment": { "description": "Current appointment after the operation.", "allOf": [ { "$ref": "#/components/schemas/IdentifiedAppointment" } ] }, "returnMessage": { "description": "Optional connector status message.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful", "appointmentId", "appointment" ], "additionalProperties": true, "description": "Successful appointment update or refresh result with the current record." }, { "$ref": "#/components/schemas/AppointmentFailureResponse" } ], "description": "Appointment mutation or refresh result that returns the current record on success.", "x-app-connect-generated-contract": true }, "AppointmentActionResponse": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Always true when the connector completed the action." }, "appointmentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Identifier of the affected appointment." }, "appointment": { "description": "Current appointment after the action.", "allOf": [ { "$ref": "#/components/schemas/IdentifiedAppointment" } ] }, "returnMessage": { "description": "Optional connector status message.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful", "appointmentId", "appointment" ], "additionalProperties": true }, { "type": "object", "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Always true when the connector completed the action." }, "appointmentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Identifier of the affected appointment." }, "returnMessage": { "description": "Connector confirmation when no record is returned.", "allOf": [ { "$ref": "#/components/schemas/ReturnMessage" } ] } }, "required": [ "successful", "appointmentId", "returnMessage" ], "additionalProperties": true } ], "description": "Successful confirm or cancel result, with either the current record or a status message." }, { "$ref": "#/components/schemas/AppointmentFailureResponse" } ], "description": "Appointment confirmation or cancellation result.", "x-app-connect-generated-contract": true }, "IdentifiedAppointment": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Connector appointment identifier." }, "thirdPartyAppointmentId": { "anyOf": [ { "nullable": true, "type": "string" }, { "nullable": true, "type": "number" } ], "description": "CRM-native appointment identifier used when opening the record in the CRM." }, "title": { "nullable": true, "description": "Appointment title.", "type": "string" }, "description": { "nullable": true, "description": "Canonical appointment description returned by list operations.", "type": "string" }, "summary": { "nullable": true, "description": "Compatibility alias returned by some create, update, and refresh connectors.", "type": "string" }, "participantName": { "nullable": true, "description": "Compatibility display name for the primary participant.", "type": "string" }, "startTimeUtc": { "nullable": true, "description": "Appointment start timestamp, including its UTC offset.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "nullable": true, "description": "Appointment duration in minutes.", "type": "number", "minimum": 0 }, "status": { "nullable": true, "description": "Connector-specific appointment status.", "type": "string" }, "contactId": { "anyOf": [ { "nullable": true, "type": "string" }, { "nullable": true, "type": "number" } ], "description": "Primary related CRM contact identifier." }, "contactType": { "nullable": true, "description": "Primary related CRM contact type.", "type": "string" }, "attendees": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentAttendee" }, "description": "Normalized appointment attendees." }, "attendeeIds": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Connector-defined entity identifier, represented as a string or number." }, "description": "Compatibility representation returned by connectors that do not provide attendee objects." } }, "required": [ "id" ], "additionalProperties": true, "description": "Appointment record with the identifier required by list and mutation responses.", "x-app-connect-generated-contract": true }, "CallDownEntry": { "type": "object", "description": "Server-owned scheduled call-back entry scoped to one App Connect user.", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "Server-generated call-back entry identifier." }, "userId": { "type": "string", "description": "Internal App Connect user identifier. Clients should treat this value as opaque." }, "contactId": { "type": "string", "nullable": true, "description": "CRM contact identifier associated with the callback." }, "contactType": { "type": "string", "nullable": true, "description": "Connector-defined CRM entity type for contactId." }, "status": { "type": "string", "description": "Call-back state. Current normal values are scheduled and called." }, "scheduledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Requested callback time, or null when none was supplied." }, "lastCallAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Most recent call time after the entry is marked called." }, "createdAt": { "type": "string", "format": "date-time", "description": "Entry creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Entry last-update timestamp." } }, "additionalProperties": true }, "CallDownCreateRequest": { "type": "object", "description": "Fields accepted when scheduling a server-owned call-back entry.", "properties": { "contactId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "CRM contact identifier to persist with the entry." }, "contactType": { "type": "string", "description": "Connector-defined CRM entity type. Defaults to contact." }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Requested callback time." }, "contactName": { "type": "string", "description": "Contact display name sent by the current browser client but not retained by the current persistence model." }, "phoneNumber": { "type": "string", "description": "Callback phone number sent by the current browser client but not retained by the current persistence model." }, "note": { "type": "string", "description": "Callback note sent by the current browser client but not retained by the current persistence model." } }, "additionalProperties": true }, "CallDownPatchRequest": { "type": "object", "minProperties": 1, "description": "Allowed fields for updating a server-owned call-back entry.", "properties": { "contactId": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Replacement CRM contact identifier." }, "contactType": { "type": "string", "description": "Replacement connector-defined CRM entity type." }, "status": { "type": "string", "description": "Replacement status, normally scheduled or called." }, "scheduledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Replacement callback time." }, "lastCallAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Replacement last-call time." }, "contactName": { "type": "string", "description": "Replacement contact display name accepted by the handler but not retained by the current persistence model." }, "phoneNumber": { "type": "string", "description": "Replacement callback phone number accepted by the handler but not retained by the current persistence model." }, "note": { "type": "string", "description": "Replacement callback note accepted by the handler but not retained by the current persistence model." } }, "additionalProperties": false }, "CallDownCreateResponse": { "type": "object", "description": "Result of scheduling a call-back entry.", "required": [ "successful", "id" ], "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Whether the entry was scheduled." }, "id": { "type": "string", "description": "Generated call-back entry identifier." } }, "additionalProperties": false }, "CallDownListResponse": { "type": "object", "description": "Scheduled call-back entries owned by the current App Connect user.", "required": [ "successful", "items" ], "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Whether the list was loaded." }, "items": { "type": "array", "description": "Entries ordered by scheduledAt ascending.", "items": { "$ref": "#/components/schemas/CallDownEntry" } } }, "additionalProperties": false }, "CallDownMutationResponse": { "type": "object", "description": "Result of updating or deleting a call-back entry.", "required": [ "successful" ], "properties": { "successful": { "type": "boolean", "enum": [ true ], "description": "Whether the requested mutation completed." } }, "additionalProperties": false } }, "headers": { "RefreshedUserJwt": { "description": "Rotated App Connect user-session JWT. Clients should replace the token they sent when this header is present.", "schema": { "type": "string" } } } } }