Remote HTTP Service APIs

The Remote HTTP Service APIs let you configure outbound HTTP integrations used by RingCX routing and scripting flows. Use them to maintain service groups, services, service inputs, activation state, and external authentication configurations from code.

Strategic Overview

Remote HTTP services define reusable external endpoints that RingCX can call from IVR, scripting, or integration workflows. They are useful when the same CRM, middleware, or data-enrichment service must be configured consistently across many queues, scripts, or sub-accounts.

IVR WWW nodes, scripting nodes, and other workflow steps reference these service definitions so the workflow does not need to duplicate endpoint URLs, headers, credentials, and input mappings.

Key Use Cases

• Integration Provisioning: Create service definitions during customer onboarding.
• Credential Rotation: Update OAuth or external auth configurations without rebuilding scripts.
• Environment Promotion: Clone or update service definitions as configurations move from test to production.
• Operational Control: Activate or deactivate a remote service during outages or endpoint migrations.

Required Permissions & Scopes

1. Configure OAuth Scopes

To authenticate, your application must be configured with the following permission in the Developer Portal:

• ReadAccounts: Required to validate account context and access RingCX integration configuration APIs.

2. Enable RingCX Admin Access

The authenticating user must have RingCX permissions that match the action being performed. Each endpoint in this set declares the permission it requires (READ on Account, CREATE on Account, READ, UPDATE, DELETE, etc., on the Remote HTTP Service Group, HTTP Service, HTTP Service Input, or External Auth Config resource). Grant the corresponding role permissions in the RingCX Admin Portal under Users & Permissions.

{
  "errorCode": "access.denied.exception",
  "generalMessage": "You do not have permission to access this resource",
  "timestamp": 1611847650696
}

Manage Service Groups

Service groups organize related remote HTTP services.

Manage HTTP Services

HTTP service records describe the external endpoint and how RingCX calls it.

Configure Service Inputs

Inputs define the values RingCX passes into the remote service request. Keep these in sync with the service contract expected by your external endpoint.

External Auth Configurations

External auth configurations store reusable authentication settings for remote services. Use these APIs when integrations require OAuth or other reusable credentials.

Recommended Workflow

1. Create or select a service group.
2. Create the remote HTTP service with the external endpoint details.
3. Add service inputs that map RingCX values into the outbound request.
4. Attach or update external auth configuration when the service requires credentials.
5. Activate the service after validation.
6. Clone the service when creating a similar integration for another environment or workflow.

Request Examples

Create a Service Group

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups

{
  "groupName": "CRM enrichment",
  "isDefault": false
}

Create an HTTP Service

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices

The serviceType enum controls how RingCX calls the remote endpoint. For SOAP services populate soapEndpoint plus the SOAP-specific fields (soapPortname, soapServicename, soapOperationname, soapAction, targetNamespace); for HTTP services populate httpServiceConfig with the full HTTP request specification (URL, headers, etc.). Reusable credentials are linked through authConfigId.

{
  "accountId": "123456",
  "serviceType": "HTTP_POST",
  "serviceDescription": "Lookup customer by ANI",
  "httpServiceConfig": "{\"url\":\"https://api.example.com/customers/lookup\",\"headers\":{\"Content-Type\":\"application/json\"}}",
  "authConfigId": "60629848-0ddf-4757-8868-de5b76d54bb7",
  "isEnabled": false,
  "isDebug": false,
  "enableMappings": true
}

Create a Service Input

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/httpServiceGroups/{serviceGroupId}/httpServices/{serviceId}/inputs

[
  {
    "name": "ani",
    "type": "PARAMETER",
    "simpleDataType": "STRING",
    "value": "",
    "rank": "0"
  }
]

The service input save endpoint accepts an array of RemoteHttpServiceInput objects.

Create API Key Auth

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/apiKey

providerName and apiKey are required. authConfigId is supplied as a path parameter and does not need to appear in the body for create operations.

{
  "providerName": "CRM API key",
  "description": "Service account key for the CRM lookup integration",
  "authType": "APIKEY",
  "apiKey": "secret-value"
}

Create Basic Auth

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/basic

providerName, username, and password are required.

{
  "providerName": "CRM basic auth",
  "description": "Basic credentials for CRM lookup",
  "authType": "BASIC",
  "username": "ringcx-service",
  "password": "secret-value"
}

Create OAuth Auth

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/external/authConfigs/{authConfigId}/oauth

providerName, clientId, secret, tokenUrl, and grantType are required. The client secret field is named secret (not clientSecret).

{
  "providerName": "CRM OAuth",
  "description": "OAuth credentials for CRM lookup",
  "authType": "OAUTH",
  "grantType": "CLIENT_CREDENTIALS",
  "clientId": "ringcx-client",
  "secret": "secret-value",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "clientCredentialsSupplyIn": "BODY"
}

Example HTTP Service Response

{
  "serviceId": 4567,
  "accountId": "123456",
  "serviceType": "HTTP_POST",
  "serviceDescription": "Lookup customer by ANI",
  "httpServiceConfig": "{\"url\":\"https://api.example.com/customers/lookup\",\"headers\":{\"Content-Type\":\"application/json\"}}",
  "authConfigId": "60629848-0ddf-4757-8868-de5b76d54bb7",
  "isEnabled": false,
  "isDebug": false,
  "enableMappings": true,
  "permissions": ["READ", "UPDATE"]
}

Resource Notes

Common Errors

Sample Implementation (Python)

import json
import requests

BASE_URL = "https://ringcx.ringcentral.com/voice/api"

def provision_remote_service(token, account_id, auth_config_id):
    headers = {"Authorization": f"Bearer {token}"}

    group = requests.post(
        f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups",
        headers=headers,
        json={"groupName": "CRM enrichment", "isDefault": False},
    )
    group.raise_for_status()
    group_id = group.json()["serviceGroupId"]

    service = requests.post(
        f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices",
        headers=headers,
        json={
            "accountId": account_id,
            "serviceType": "HTTP_POST",
            "serviceDescription": "Lookup customer by ANI",
            "httpServiceConfig": json.dumps({
                "url": "https://api.example.com/customers/lookup",
                "headers": {"Content-Type": "application/json"},
            }),
            "authConfigId": auth_config_id,
            "isEnabled": False,
            "enableMappings": True,
        },
    )
    service.raise_for_status()
    service_id = service.json()["serviceId"]

    input_response = requests.post(
        f"{BASE_URL}/v1/admin/accounts/{account_id}/httpServiceGroups/{group_id}/httpServices/{service_id}/inputs",
        headers=headers,
        json=[
            {
                "name": "ani",
                "type": "PARAMETER",
                "simpleDataType": "STRING",
                "value": "",
                "rank": "0",
            }
        ],
    )
    input_response.raise_for_status()
    return {"group": group.json(), "service": service.json(), "input": input_response.json()}

• Last updated:
• Contributors