API Reference

Overview

The Nexus EDI API is a RESTful API that allows you to programmatically manage healthcare claims, patients, providers, and payers. All API endpoints use HTTPS and return JSON responses.

Base URL

https://api.nexusedi.net/v1

API Versioning

The API version is specified in the URL path. The current version is v1. We maintain backward compatibility within major versions.

Note: All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

Authentication

API Keys

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Obtaining API Keys

Log in to your Nexus EDI account
Navigate to Settings → API Keys
Click Generate New API Key
Copy and securely store your API key

Security Warning: Never expose your API keys in client-side code or public repositories. Store them securely as environment variables.

Example Request

curl https://api.nexusedi.net/v1/claims \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

Rate Limits by Plan

Plan	Requests per Hour	Burst Limit
Starter	1,000	100/min
Professional	5,000	500/min
Enterprise	50,000	5,000/min

Rate Limit Headers

Each API response includes rate limit information in the headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1640995200

Handling Rate Limits

When rate limited, the API returns a 429 Too Many Requests status code. Your application should implement exponential backoff retry logic.

Error Handling

HTTP Status Codes

Code	Description
200	OK - Request succeeded
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error occurred

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: patient_id",
    "param": "patient_id",
    "type": "validation_error"
  }
}

Error Types

authentication_error - Invalid API key or expired token
validation_error - Request parameters failed validation
resource_not_found - Requested resource does not exist
rate_limit_error - Too many requests
server_error - Internal server error

Pagination

List endpoints return paginated results. Use query parameters to control pagination:

Pagination Parameters

Parameter	Type	Default	Description
limit	integer	25	Number of results per page (max 100)
page	integer	1	Page number to retrieve

Example Request

GET /v1/claims?limit=50&page=2

Response Format

{
  "data": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 10,
    "total_count": 250,
    "per_page": 50,
    "has_more": true
  }
}

Claims API

GET /v1/claims

Retrieve a list of claims

Query Parameters

Parameter	Type	Description
status	string	Filter by status: draft, submitted, accepted, rejected, paid
patient_id	string	Filter by patient ID
provider_id	string	Filter by provider ID
date_from	string	Filter by service date (ISO 8601 format)
date_to	string	Filter by service date (ISO 8601 format)

Example Request

curl https://api.nexusedi.net/v1/claims?status=submitted \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "clm_1234567890",
      "patient_id": "pat_abcdefghij",
      "provider_id": "prv_xyz123",
      "payer_id": "pyr_def456",
      "status": "submitted",
      "service_date": "2025-11-15",
      "total_charges": 250.00,
      "claim_number": "CLM-2025-001234",
      "created_at": "2025-11-16T10:30:00Z",
      "updated_at": "2025-11-16T11:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 125,
    "per_page": 25,
    "has_more": true
  }
}

GET /v1/claims/:id

Retrieve a specific claim by ID

Example Request

curl https://api.nexusedi.net/v1/claims/clm_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "clm_1234567890",
  "patient": {
    "id": "pat_abcdefghij",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1980-05-15",
    "member_id": "MEM123456"
  },
  "provider": {
    "id": "prv_xyz123",
    "name": "Dr. Jane Smith",
    "npi": "1234567890",
    "taxonomy": "207R00000X"
  },
  "payer": {
    "id": "pyr_def456",
    "name": "Blue Cross Blue Shield",
    "payer_id": "00590"
  },
  "diagnosis_codes": ["Z00.00", "E11.9"],
  "service_lines": [
    {
      "line_number": 1,
      "procedure_code": "99213",
      "modifiers": [],
      "units": 1,
      "charge_amount": 150.00,
      "diagnosis_pointers": [1]
    }
  ],
  "status": "submitted",
  "total_charges": 250.00,
  "created_at": "2025-11-16T10:30:00Z"
}

POST /v1/claims

Create a new claim

Request Body

{
  "patient_id": "pat_abcdefghij",
  "provider_id": "prv_xyz123",
  "payer_id": "pyr_def456",
  "service_date": "2025-11-15",
  "place_of_service": "11",
  "diagnosis_codes": ["Z00.00", "E11.9"],
  "service_lines": [
    {
      "procedure_code": "99213",
      "modifiers": [],
      "units": 1,
      "charge_amount": 150.00,
      "diagnosis_pointers": [1]
    }
  ]
}

Response

{
  "id": "clm_9876543210",
  "status": "draft",
  "message": "Claim created successfully"
}

POST /v1/claims/:id/submit

Submit a claim to the clearinghouse

Example Response

{
  "id": "clm_1234567890",
  "status": "submitted",
  "submission_id": "sub_xyz789",
  "submitted_at": "2025-11-16T14:30:00Z"
}

DELETE /v1/claims/:id

Delete a draft claim (cannot delete submitted claims)

Example Response

{
  "id": "clm_1234567890",
  "deleted": true
}

Patients API

GET /v1/patients

Retrieve a list of patients

Query Parameters

Parameter	Type	Description
search	string	Search by name or member ID
date_of_birth	string	Filter by date of birth (YYYY-MM-DD)

GET /v1/patients/:id

Retrieve a specific patient

POST /v1/patients

Create a new patient

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1980-05-15",
  "sex": "M",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001"
  },
  "insurance": {
    "payer_id": "pyr_def456",
    "member_id": "MEM123456",
    "group_number": "GRP789",
    "relationship": "self"
  }
}

PUT /v1/patients/:id

Update a patient's information

DELETE /v1/patients/:id

Delete a patient (cannot delete if associated with claims)

Providers API

GET /v1/providers

List all providers

POST /v1/providers

Create a new provider

Request Body

{
  "type": "individual",
  "npi": "1234567890",
  "first_name": "Jane",
  "last_name": "Smith",
  "taxonomy": "207R00000X",
  "tax_id": "12-3456789",
  "address": {
    "street": "456 Medical Plaza",
    "city": "Boston",
    "state": "MA",
    "zip": "02101"
  }
}

Payers API

GET /v1/payers

List all payers

Query Parameters

Parameter	Type	Description
search	string	Search by payer name
type	string	Filter by type: commercial, medicare, medicaid

Eligibility API

POST /v1/eligibility/check

Check patient eligibility and benefits

Request Body

{
  "patient_id": "pat_abcdefghij",
  "payer_id": "pyr_def456",
  "service_date": "2025-11-20"
}

Response

{
  "eligible": true,
  "plan_status": "active",
  "coverage_dates": {
    "start": "2025-01-01",
    "end": "2025-12-31"
  },
  "benefits": {
    "deductible": {
      "individual": 1500.00,
      "met": 750.00,
      "remaining": 750.00
    },
    "copay": {
      "office_visit": 30.00,
      "specialist": 50.00
    }
  }
}

ERA/EOB API

GET /v1/era

Retrieve Electronic Remittance Advice files

Query Parameters

Parameter	Type	Description
payer_id	string	Filter by payer
date_from	string	Filter by payment date
date_to	string	Filter by payment date

GET /v1/era/:id

Retrieve a specific ERA file

Response

{
  "id": "era_123456",
  "payer_id": "pyr_def456",
  "check_number": "CHK789456",
  "check_amount": 1250.00,
  "payment_date": "2025-11-15",
  "claims": [
    {
      "claim_id": "clm_1234567890",
      "claim_number": "CLM-2025-001234",
      "billed_amount": 250.00,
      "paid_amount": 200.00,
      "adjustment_amount": 50.00,
      "adjustments": [
        {
          "reason_code": "45",
          "amount": 50.00,
          "description": "Charge exceeds fee schedule"
        }
      ]
    }
  ]
}

Reports API

POST /v1/reports/generate

Generate a custom report

Request Body

{
  "type": "claims_summary",
  "date_range": {
    "start": "2025-11-01",
    "end": "2025-11-30"
  },
  "filters": {
    "status": ["submitted", "paid"],
    "provider_id": "prv_xyz123"
  },
  "format": "csv"
}

Response

{
  "report_id": "rpt_abc123",
  "status": "processing",
  "download_url": null,
  "estimated_completion": "2025-11-16T15:00:00Z"
}

GET /v1/reports/:id

Check report status and download

Response

{
  "report_id": "rpt_abc123",
  "status": "completed",
  "download_url": "https://reports.nexusedi.net/download/rpt_abc123.csv",
  "expires_at": "2025-11-17T15:00:00Z"
}

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account.

Setting Up Webhooks

Navigate to Settings → Webhooks
Click Add Webhook Endpoint
Enter your endpoint URL (must be HTTPS)
Select events to subscribe to
Save and receive a webhook secret for verification

Available Events

claim.created - New claim created
claim.submitted - Claim submitted to clearinghouse
claim.accepted - Claim accepted by clearinghouse
claim.rejected - Claim rejected
claim.paid - Payment received for claim
era.received - New ERA file received
patient.created - New patient added
patient.updated - Patient information updated

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "claim.submitted",
  "created": 1640995200,
  "data": {
    "object": {
      "id": "clm_1234567890",
      "status": "submitted",
      "patient_id": "pat_abcdefghij"
    }
  }
}

Verifying Webhooks

Verify webhook authenticity by checking the X-Webhook-Signature header using your webhook secret.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

SDKs & Libraries

Official SDKs

We provide official SDKs for popular programming languages:

Node.js / TypeScript

npm install @nexusedi/node

const Nexus = require('@nexusedi/node');
const client = new Nexus('YOUR_API_KEY');

const claims = await client.claims.list({
  status: 'submitted',
  limit: 25
});

Python

pip install nexusedi

import nexusedi
nexusedi.api_key = 'YOUR_API_KEY'

claims = nexusedi.Claim.list(
  status='submitted',
  limit=25
)

Ruby

gem install nexusedi

require 'nexusedi'
Nexusedi.api_key = 'YOUR_API_KEY'

claims = Nexusedi::Claim.list(
  status: 'submitted',
  limit: 25
)

PHP

composer require nexusedi/nexusedi-php

require_once('vendor/autoload.php');
\Nexusedi\Nexusedi::setApiKey('YOUR_API_KEY');

$claims = \Nexusedi\Claim::all([
  'status' => 'submitted',
  'limit' => 25
]);

Community Libraries

Community-maintained libraries are available for additional languages. Check our GitHub organization for the latest.

🔌 Nexus EDI API Reference

API Reference

Overview

Base URL

API Versioning

Authentication

API Keys

Obtaining API Keys

Example Request

Rate Limiting

Rate Limits by Plan

Rate Limit Headers

Handling Rate Limits

Error Handling

HTTP Status Codes

Error Response Format

Error Types

Pagination

Pagination Parameters

Example Request

Response Format

Claims API

GET /v1/claims

Query Parameters

Example Request

Example Response

GET /v1/claims/:id

Example Request

Example Response

POST /v1/claims

Request Body

Response

POST /v1/claims/:id/submit

Example Response

DELETE /v1/claims/:id

Example Response

Patients API

GET /v1/patients

Query Parameters

GET /v1/patients/:id

POST /v1/patients

Request Body

PUT /v1/patients/:id

DELETE /v1/patients/:id

Providers API

GET /v1/providers

POST /v1/providers

Request Body

Payers API

GET /v1/payers

Query Parameters

Eligibility API

POST /v1/eligibility/check

Request Body

Response

ERA/EOB API

GET /v1/era

Query Parameters

GET /v1/era/:id

Response

Reports API

POST /v1/reports/generate

Request Body

Response

GET /v1/reports/:id

Response

Webhooks

Setting Up Webhooks

Available Events

Webhook Payload

Verifying Webhooks

SDKs & Libraries

Official SDKs

Node.js / TypeScript

Python

Ruby

PHP

Community Libraries