Approve Fund Release

Overview

The Approve Funding endpoint allows a TPA to authorize the release of adjudicated claim funds to one or more providers following service verification and claim adjudication. This endpoint initiates a Stripe Connect transfer from the health plan to the provider's settlement account. Once initiated, the transfer is irreversible and funds are typically settled within 1-2 business days.

warning

This is an irreversible financial transaction. After approval, funds will be transferred via Stripe Connect to the provider's registered banking details. Ensure adjudication is complete and correct before calling this endpoint.

Endpoint

POST /v1/funding/approve/

Authentication Required: Yes (X-API-Key header) Content-Type: application/json Rate Limit: 10 approvals per minute per API key

---

Request

Schema

Field	Type	Required	Description
encounter_id	string	Yes	Unique encounter/claim identifier for tracking
amount	number	Yes	Amount in USD to transfer (must match adjudicated benefit amount)
authorization_code	string	Yes	Human-generated authorization (e.g., "AUTH-20240217-001") for audit trail
notes	string	No	Optional notes for internal audit (max 500 chars)

Request Example

{
  "encounter_id": "ENC-2024-098765",
  "amount": 1900.00,
  "authorization_code": "AUTH-20240217-TPA-SHARP-001",
  "notes": "Colonoscopy with EGD, post-adjudication approval"
}

---

Response

Success Response (200 OK)

Field	Type	Description
status	string	APPROVED
stripe_transfer_id	string	Stripe transfer identifier (e.g., tr_1Oz9rZA1g7yLGa7e0xYzFxVK)
estimated_arrival	string	ISO 8601 date when funds expected in provider account
settlement_record_id	string	Internal settlement tracking ID for ledger reconciliation

{
  "status": "APPROVED",
  "stripe_transfer_id": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
  "estimated_arrival": "2024-02-19T23:59:59Z",
  "settlement_record_id": "SETTLE-2024-098765-001"
}

Bad Request / Amount Mismatch (409 Conflict)

{
  "error": "Amount mismatch",
  "expected_amount": 1900.00,
  "submitted_amount": 1850.00,
  "message": "Approved amount does not match adjudicated benefit amount"
}

Invalid State (400 Bad Request)

Encounter not yet adjudicated or already funded.

{
  "error": "Cannot approve funding for this encounter",
  "reason": "CLAIM_NOT_ADJUDICATED",
  "encounter_id": "ENC-2024-098765",
  "message": "Claim response not yet available. Check /claims/{submission_id}/response/"
}

Duplicate Approval (400 Bad Request)

{
  "error": "Funding already approved for this encounter",
  "previous_stripe_transfer_id": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
  "encounter_id": "ENC-2024-098765"
}

Not Found (404 Not Found)

{
  "error": "Encounter not found",
  "encounter_id": "ENC-INVALID"
}

---

Examples

cURL

curl -X POST https://api.turquoise.health/tpa-api/v1/funding/approve/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "encounter_id": "ENC-2024-098765",
    "amount": 1900.00,
    "authorization_code": "AUTH-20240217-TPA-SHARP-001",
    "notes": "Colonoscopy with EGD, verified and adjudicated"
  }'

Python

import requests
from datetime import datetime

api_key = "YOUR_API_KEY"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

# Assume encounter adjudication returned benefit_amount
encounter_id = "ENC-2024-098765"
benefit_amount = 1900.00

# Generate authorization code for audit trail
auth_code = f"AUTH-{datetime.now().strftime('%Y%m%d')}-TPA-SHARP-001"

payload = {
    "encounter_id": encounter_id,
    "amount": benefit_amount,
    "authorization_code": auth_code,
    "notes": "Post-adjudication approval, verified against contract rates"
}

response = requests.post(
    "https://api.turquoise.health/tpa-api/v1/funding/approve/",
    json=payload,
    headers=headers
)

if response.status_code == 200:
    result = response.json()
    print(f"Funding approved!")
    print(f"Stripe Transfer ID: {result['stripe_transfer_id']}")
    print(f"Estimated Arrival: {result['estimated_arrival']}")
    print(f"Settlement Record: {result['settlement_record_id']}")

    # Store settlement_record_id for ledger reconciliation
    settlement_id = result["settlement_record_id"]
else:
    print(f"Error: {response.status_code}")
    error = response.json()
    print(error)

    # Handle specific error cases
    if response.status_code == 409:
        print(f"Amount mismatch: Expected {error['expected_amount']}, got {error['submitted_amount']}")
    elif response.status_code == 400 and "not adjudicated" in error.get("reason", ""):
        print("Claim has not been adjudicated yet. Check claim response endpoint.")

Python (Pre-Approval Verification)

import requests

def verify_and_approve_funding(encounter_id, api_key):
    """
    Verify claim adjudication before approving funding.
    """
    headers = {
        "X-API-Key": api_key,
        "Content-Type": "application/json"
    }

    # Step 1: Get encounter details from ledger
    ledger_response = requests.get(
        f"https://api.turquoise.health/tpa-api/v1/ledger/entries/{encounter_id}/",
        headers=headers
    )

    if ledger_response.status_code != 200:
        print(f"Encounter not found: {encounter_id}")
        return False

    encounter = ledger_response.json()
    financial_summary = encounter["financial_summary"]
    benefit_amount = financial_summary["payer_resp"]

    print(f"Encounter: {encounter_id}")
    print(f"Service Date: {encounter['service_date']}")
    print(f"Provider: {encounter['provider']['npi']}")
    print(f"Benefit Amount: ${benefit_amount:.2f}")

    # Confirm with user before proceeding
    confirm = input("Approve this funding? (yes/no): ")
    if confirm.lower() != "yes":
        return False

    # Step 2: Approve funding
    auth_code = f"AUTH-{encounter_id}"

    approval_response = requests.post(
        "https://api.turquoise.health/tpa-api/v1/funding/approve/",
        json={
            "encounter_id": encounter_id,
            "amount": benefit_amount,
            "authorization_code": auth_code,
            "notes": f"Verified via ledger, service date {encounter['service_date']}"
        },
        headers=headers
    )

    if approval_response.status_code == 200:
        result = approval_response.json()
        print(f"\nFunding approved!")
        print(f"Stripe Transfer: {result['stripe_transfer_id']}")
        print(f"Expected Arrival: {result['estimated_arrival']}")
        return True
    else:
        print(f"Approval failed: {approval_response.json()}")
        return False

# Usage
verify_and_approve_funding("ENC-2024-098765", "YOUR_API_KEY")

---

Settlement Timeline

info

Expected Settlement Schedule:

• T+0 (Approval Day): Transfer initiated, funds routed to Stripe
• T+1: Stripe processes (typically overnight)
• T+1 to T+2: Provider receives funds (depends on bank processing)

ACH transfers via Stripe Connect typically settle within 1 business day during standard processing hours.

Pre-Approval Checklist

Before calling Approve Funding, ensure:

1. Claim is adjudicated — Check via Get Claim Response endpoint
2. Amount matches adjudicated benefit — Do not submit modified amounts
3. Provider has valid banking details — Configured in Stripe Connect account
4. Authorization is documented — Use auth_code for audit trail
5. Encounter is not already funded — Check ledger to avoid duplicate payments

Authorization Code Format

tip

Create authorization codes in a consistent format for auditing:

AUTH-[DATE]-[ORGANIZATION]-[SEQUENCE]

Examples:

• AUTH-20240217-TPA-SHARP-001
• AUTH-20240217-TPA-SHARP-002
• AUTH-20240217-BULK-BATCH-001

This enables easy tracking of who authorized what funding and when.

Reconciliation

After approval, track the settlement via:

1. Stripe Transfer ID — Query Stripe API for real-time status
2. Settlement Record ID — Use for internal ledger reconciliation
3. Encounter Ledger — Check GET /v1/ledger/entries/{encounter_id}/ for updated status