Skip to main content

Creating a Claim from Form Boxes

This is the lowest-friction way to create a claim through the API. You send the CMS-1500 (professional) or UB-04 (institutional) form exactly as its numbered boxes read, as JSON. ClaimRev maps the boxes, builds the 837 (P or I), and submits it through the same pipeline as an uploaded file. You don't construct X12 EDI, and you don't need to know the editor/loop model.

This endpoint
EndpointPOST /api/ManualClaimEntry/v1/CreateClaimFromForm
Claim typesProfessional (837P) and institutional (837I)
InputCMS-1500 boxes (box…) or UB-04 locators (fl…) as JSON
You provideThe form fields. ClaimRev handles mapping, EDI, control numbers, submission.

If your system already emits X12 837 EDI, or already has the structured editor model, see the two other paths in Submitting a Claim. This guide is the no-EDI, paper-shaped option.

Permission. This endpoint requires your client to be granted manual claim entry access for the account (ClaimRev provisions this). If it isn't, the API returns 403 — see Authentication. The claim is always created under your authenticated account.

Request​

Send exactly one of cms1500 or ub04. The field names are the literal form boxes/locators (e.g. CMS-1500 box1a_InsuredIdNumber, UB-04 fl51_HealthPlanId), so you can map your data straight off the paper form.

POST /api/ManualClaimEntry/v1/CreateClaimFromForm
Authorization: Bearer <token>
Content-Type: application/json

CMS-1500 (professional) example​

{
  "cms1500": {
    "carrierName": "Acme Health Plan",
    "carrierPayerId": "ACME01",

    "box1_InsuranceType": "CI",
    "box1a_InsuredIdNumber": "MBR123456",

    "box2_PatientLastName": "Doe",
    "box2_PatientFirstName": "John",
    "box3_PatientDob": "19800115",
    "box3_PatientSex": "M",
    "box5_PatientAddress1": "100 Main St",
    "box5_PatientCity": "Bixby",
    "box5_PatientState": "OK",
    "box5_PatientZip": "74008",
    "box6_PatientRelationshipToInsured": "self",

    "box21_IcdIndicator": "0",
    "box21_DiagnosisCodes": ["E119", "I10"],

    "box24_ServiceLines": [
      {
        "dateOfServiceFrom": "20240305",
        "placeOfService": "11",
        "procedureCode": "99213",
        "modifier1": "25",
        "diagnosisPointer": "AB",
        "charges": "150",
        "daysOrUnits": "1"
      }
    ],

    "box25_FederalTaxId": "751234567",
    "box25_FederalTaxIdType": "EI",
    "box26_PatientAccountNumber": "ACCT-001",
    "box28_TotalCharge": "150",

    "box33_BillingProviderName": "Bixby Medical Group",
    "box33_BillingProviderAddress1": "200 Clinic Rd",
    "box33_BillingProviderCity": "Bixby",
    "box33_BillingProviderState": "OK",
    "box33_BillingProviderZip": "740081234",
    "box33a_BillingProviderNpi": "1234567893",
    "box33b_BillingProviderTaxonomy": "207Q00000X"
  }
}

UB-04 (institutional) example​

Send the ub04 object instead, keyed by FL locators:

{
  "ub04": {
    "fl01_BillingProviderName": "General Hospital",
    "fl56_BillingProviderNpi": "1234567893",
    "fl04_TypeOfBill": "0111",
    "fl06_StatementFromDate": "20240301",
    "fl06_StatementToDate": "20240303",
    "fl08_PatientLastName": "Doe",
    "fl08_PatientFirstName": "John",
    "fl50_PayerName": "Acme Health Plan",
    "fl51_HealthPlanId": "ACME01",
    "fl59_PatientRelationship": "self",
    "fl60_SubscriberId": "MBR123456",
    "fl66_IcdVersionIndicator": "0",
    "fl67_DiagnosisCodes": ["J189", "E119"],
    "fl42_49_ServiceLines": [
      { "fl42_RevenueCode": "0120", "fl45_ServiceDate": "20240301", "fl46_ServiceUnits": "3", "fl47_TotalCharges": "3000" }
    ]
  }
}

The full set of boxes/locators (including the less-common ones — occurrence/value codes, DRG, other procedures, pay-to, etc.) is in the API Reference under Cms1500Form / Ub04Form.

Response​

On success you get the envelope control numbers ClaimRev stamped and a submission id:

{
  "success": true,
  "validationFailures": [],
  "isaControlNumber": "000000001",
  "groupControlNumber": "1",
  "transactionControlNumber": "0001",
  "submissionId": "..."
}

Use these (and the patient control number you supplied) to find the claim afterwards — see Claim Search.

Submission gates (HTTP 400)​

A few things must be present for a claim to be accepted. When one is missing you get HTTP 400 with success: false and the reasons in validationFailures — nothing is submitted:

{
  "success": false,
  "validationFailures": [
    "no payer number. Provide the payer id (CMS-1500 carrier payer id / UB-04 FL51)."
  ]
}
  • Payer id is required and must be recognized. Supply carrierPayerId (CMS-1500) or fl51_HealthPlanId (UB-04); it must resolve to a payer that supports the claim type.
  • Outside lab (CMS-1500 Box 20) needs a service facility. If box20_OutsideLab is set with a charge, also supply the outside lab as the service facility (box32_… / box32a_ServiceFacilityNpi) — that NPI carries the purchased-service charge. Otherwise the charge would be dropped, so the request is rejected.

When to use this vs. the other paths​

You have…Use
Form-shaped data, want the least workThis endpoint — CreateClaimFromForm (P and I)
Raw X12 837 EDI alreadyRaw EDI upload
The structured editor model (837P)JSON → EDI

All three feed the same downstream processing; pick whichever matches the data you already hold.