How to Integrate a
Medical Coding API
into an RCM Workflow

import time
import uuid
import logging
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("MedicalCodingAPIClient")

API_BASE = "https://api.example-coding-provider.com/v1"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

def get_session_with_retries():
    """Configures HTTP session with exponential backoff for 429 and 5xx errors."""
    session = requests.Session()
    retries = Retry(
        total=4,
        backoff_factor=1.5,
        status_forcelist=[429, 500, 502, 503, 504],
        raise_on_status=False
    )
    session.mount("https://", HTTPAdapter(max_retries=retries))
    return session

def analyze_encounter(note_text: str, specialty: str, encounter_id: str):
    session = get_session_with_retries()
    request_id = f"req_{uuid.uuid4().hex[:12]}"
    
    # 1. Fetch Bearer Token
    token_resp = session.post(
        f"{API_BASE}/oauth/token",
        data={"grant_type": "client_credentials", "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET},
        timeout=10
    )
    token_resp.raise_for_status()
    token = token_resp.json()["access_token"]
    
    # 2. Send Clinical Document for Automated Code Extraction
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "X-Request-ID": request_id,
        "Idempotency-Key": f"idemp_{encounter_id}"
    }
    payload = {
        "encounter_id": encounter_id,
        "specialty": specialty,
        "date_of_service": "2026-11-02",
        "place_of_service": "11",
        "clinical_text": note_text,
        "require_explanations": True
    }
    
    logger.info(f"Submitting encounter {encounter_id} [X-Request-ID: {request_id}]")
    resp = session.post(f"{API_BASE}/encounters/suggest-codes", json=payload, headers=headers, timeout=25)
    
    if resp.status_code == 200:
        data = resp.json()
        logger.info(f"Received {len(data['suggested_codes'])} codes. Server Request-ID: {resp.headers.get('X-Request-ID')}")
        return data
    else:
        logger.error(f"Coding API Error {resp.status_code}: {resp.text}")
        resp.raise_for_status()

# Example usage with de-identified clinical note
if __name__ == "__main__":
    sample_note = "Patient presents with persistent right knee pain following a sports twist. Exam confirms joint line tenderness. MRI confirms right lateral meniscus tear."
    results = analyze_encounter(sample_note, specialty="orthopedics", encounter_id="ENC-90212")
    print(results)

import crypto from 'crypto';

const API_BASE = 'https://api.example-coding-provider.com/v1';

async function fetchWithRetry(url, options, maxRetries = 3) {
  let attempt = 0;
  while (attempt < maxRetries) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429 || response.status >= 500) {
        attempt++;
        const retryAfter = response.headers.get('Retry-After');
        const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;
        console.warn(`[HTTP ${response.status}] Retrying in ${delayMs}ms (Attempt ${attempt}/${maxRetries})...`);
        await new Promise(r => setTimeout(r, delayMs));
        continue;
      }
      return response;
    } catch (err) {
      attempt++;
      if (attempt >= maxRetries) throw err;
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}

export async function processClinicalNote(clinicalText, specialty, encounterId) {
  const requestId = `req_${crypto.randomBytes(6).toString('hex')}`;

  // 1. Authenticate with OAuth 2.0
  const tokenResp = await fetch(`${API_BASE}/oauth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.CODING_API_CLIENT_ID,
      client_secret: process.env.CODING_API_SECRET
    })
  });
  const { access_token } = await tokenResp.json();

  // 2. Transmit Clinical Data
  const response = await fetchWithRetry(`${API_BASE}/encounters/suggest-codes`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'Content-Type': 'application/json',
      'X-Request-ID': requestId,
      'Idempotency-Key': `idemp_${encounterId}`
    },
    body: JSON.stringify({
      encounter_id: encounterId,
      specialty: specialty,
      date_of_service: '2026-11-02',
      clinical_text: clinicalText
    })
  });

  const codingResult = await response.json();
  console.log(`[Success] Extracted codes for ${encounterId}:`, codingResult.suggested_codes);
  return codingResult;
}

package com.codesformd.rcm.client;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.UUID;

public class MedicalCodingApiClient {
    private static final String API_BASE = "https://api.example-coding-provider.com/v1";
    private final HttpClient client;

    public MedicalCodingApiClient() {
        this.client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_2)
                .connectTimeout(Duration.ofSeconds(10))
                .build();
    }

    public String submitEncounterForCoding(String jwtToken, String encounterId, String noteJson) throws Exception {
        String requestId = "req_" + UUID.randomUUID().toString().substring(0, 8);
        int maxRetries = 3;

        for (int attempt = 1; attempt <= maxRetries; attempt++) {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(API_BASE + "/encounters/suggest-codes"))
                    .timeout(Duration.ofSeconds(20))
                    .header("Authorization", "Bearer " + jwtToken)
                    .header("Content-Type", "application/json")
                    .header("X-Request-ID", requestId)
                    .header("Idempotency-Key", "idemp_" + encounterId)
                    .POST(HttpRequest.BodyPublishers.ofString(noteJson))
                    .build();

            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.printf("[Audit] Successfully coded %s on attempt %d%n", encounterId, attempt);
                return response.body();
            } else if (response.statusCode() == 429 || response.statusCode() >= 500) {
                long backoff = (long) (Math.pow(2, attempt) * 1000);
                System.err.printf("[Warning] HTTP %d: Backing off %d ms%n", response.statusCode(), backoff);
                Thread.sleep(backoff);
            } else {
                throw new RuntimeException("API Call Failed: " + response.statusCode() + " " + response.body());
            }
        }
        throw new RuntimeException("Exhausted retries for encounter " + encounterId);
    }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

namespace CodesForMD.RCM.Integration
{
    public class MedicalCodingService
    {
        private readonly HttpClient _httpClient;
        private const string ApiBase = "https://api.example-coding-provider.com/v1";

        public MedicalCodingService(HttpClient httpClient)
        {
            _httpClient = httpClient;
            _httpClient.Timeout = TimeSpan.FromSeconds(30);
        }

        public async Task<string> SuggestCodesAsync(string bearerToken, string encounterId, object clinicalPayload)
        {
            var requestId = $"req_{Guid.NewGuid():N}";
            var jsonBody = JsonSerializer.Serialize(clinicalPayload);

            var request = new HttpRequestMessage(HttpMethod.Post, $"{ApiBase}/encounters/suggest-codes")
            {
                Content = new StringContent(jsonBody, Encoding.UTF8, "application/json")
            };

            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);
            request.Headers.Add("X-Request-ID", requestId);
            request.Headers.Add("Idempotency-Key", $"idemp_{encounterId}");

            // Execute call (Polly resilience pipeline handles 429/5xx backoff in production)
            var response = await _httpClient.SendAsync(request);

            if (response.IsSuccessStatusCode)
            {
                var content = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"[Audit] Coding API Success for {encounterId} [ReqId: {requestId}]");
                return content;
            }

            var err = await response.Content.ReadAsStringAsync();
            throw new HttpRequestException($"Coding API returned {response.StatusCode}: {err}");
        }
    }
}