Guides

API Testing Guide

This guide walks you through testing your ICHRA Connect API integration end-to-end in the staging environment before going live in production.

Important: Please ensure you only use test members in the staging environment.

Step 1: Verify Connectivity

Confirm your mTLS certificate is working by hitting the health check endpoint:

curl -v \
  --cert your-vendor.staging.vendors.external.pem \
  --key your-vendor.staging.vendors.external.key \
  https://ichra-api-staging.hioscar.com:444/

What to verify:

You should get the following response:

Welcome to Oscar's ICHRA API!

If you receive a 401 or TLS handshake error, verify your certificate and key file paths are correct and that your certificate has been registered by Oscar.

Step 2: Create a Membership

Enroll a new member by calling the CreateMembership endpoint. If you are enrolling a member outside of Open Enrollment, a qualifying life event (qle_info) is required.

What to verify:

  • The oscar_id was contained in the response. Save the returned oscar_id -- you will need it for the remaining steps. Also save the application_id for troubleshooting with Oscar support.

Step 3: Get Membership

Retrieve the membership you just created with the GetMembership endpoint to check the member's enrollment status.

What to verify:

  • The memberships array contains the enrollee you created
  • effectuation_status reflects the expected state (e.g., EFFECTUATED)
  • coverage_start and coverage_end match the enrollment dates

Step 4: Update Membership

Add a dependent to the existing enrollment with the UpdateMembership endpoint.

What to verify:

  • The response contains the newly added dependent with a resolved oscar_id
  • Calling get-membership again returns both the policy holder and the new dependent

Step 5: Get Balance

Check the billing balance for the member with the GetBalance endpoint.

What to verify:

  • The response includes overdue_balance, upcoming_due_balance, credit_amount, and overall_balance_amount
  • Premium amounts reflect the expected values

Step 6: Upsert Payment Preference

Set up autopay for the member with the UpsertPaymentPreference endpoint.

What to verify:

  • The response confirms is_autopay_enabled is true
  • payment_method_owner reflects VENDOR
  • Calling get-payment-preferences returns the preference you just set

Step 7: Get Payment Preferences

Retrieve the current autopay settings with the GetPaymentPreference endpoint.

What to verify:

  • The response contains payment preference

Step 8: Testing Error Handling

After completing the happy-path sequence above, verify your integration handles errors correctly.

ACTIONABLE Errors (400 Bad Request)

Submit requests with intentionally invalid data to confirm your system parses structured error responses:

  • Invalid SSN format -- submit a non-numeric or wrong-length SSN
  • Missing required fields -- omit policy_info or enrollees
  • Missing policy holder -- submit enrollees without a POLICY_HOLDER relationship type
  • Duplicate SSN -- submit two enrollees with the same SSN

Expected behavior: Your system should read the error_code and field from the response and surface actionable feedback to the user.

RETRY Errors (503 Service Unavailable)

These occur during transient failures (e.g., pending transactions for the member).

Expected behavior: Your system should retry with exponential backoff:

  • 1st retry: wait 1 second
  • 2nd retry: wait 2 seconds
  • 3rd retry: wait 4 seconds
  • Maximum 5 retries before failing

ESCALATE Errors (500 Internal Server Error)

These indicate internal errors that require Oscar intervention.

Expected behavior: Your system should log the application_id from the response and alert your operations team. Contact Oscar support with the application_id for resolution.

See the Error Handling Guide for the full error code reference.

Updated 19 days ago