Create Claim

The claim object contains all the information required to send a claim to an insurer:

insurer
patient details
primary member details (can be same as patient details)
list of services

During claim submission, the API validates the claim payload against known insurer requirements and will reject claims that we know will be rejected by the insurer. However, this does not guarantee the opposite; a claim accepted by the API can still be rejected by the insurer. Insurers can change their claim requirements without notifying us. When this happens, as soon as we understand the new requirements, we will update the validation rules and inform you. It is advisable to be prepared to adopt the updated rules as quickly as possible.

{
    "patient": {
        "dob": "1998-02-11",
        "first_name": "Max",
        "last_name": "Smith",
        "type": "child",
        "address": {
            "line1": "String name",
            "city": "City",
            "zipcode": "12332",
            "state": "CA",
        },
    },
    "primary_member": {
        "address": {
            "city": "City",
            "line1": "String name",
            "state": "CA",
            "zipcode": "12332"
        },
        "dob": "1988-10-11",
        "first_name": "John",
        "insurer_code": "insurer:demo:vision",
        "last_name": "Smith",
        "member_id": "A123455",
        "phone": "0987654321",
        "ssn_last_four": "1242"
    },
    "services": [{
        "codes": ["S0504"],
        "cost": "12.22",
        "date": "2022-02-11",
        "quantity": "2"
        "diagnosis_codes": ["H52.10"],
    }, {
        "codes": ["V2781"],
        "cost": "44.21",
        "date": "2022-02-11",
        "quantity": "1"
    }],
    "paid_amount": "68.65"
}

{
    "code": "CLM21T",
    "patient": {
        "address": {
            "city": "City",
            "line1": "String name",
            "line2": null,
            "recipient": null,
            "state": "CA",
            "zipcode": "12332"
        },
        "dob": "1998-02-11",
        "email": null,
        "first_name": "Max",
        "last_name": "Smith",
        "member_id": null,
        "phone": null,
        "sex": null,
        "ssn_last_four": null,
        "type": "child"
    },
    "primary_member": {
        "address": {
            "city": "City",
            "line1": "String name",
            "line2": null,
            "recipient": null,
            "state": "CA",
            "zipcode": "12332"
        },
        "dob": "1988-10-11",
        "email": null,
        "employer": null,
        "first_name": "John",
        "individual_plan_name": null,
        "insurer_code": "insurer:demo:vision",
        "last_name": "Smith",
        "member_id": "A123455",
        "phone": "0987654321",
        "sex": null,
        "ssn_last_four": "1242"
    },
    "services": [{
        "codes": ["S0504"],
        "cost": "12.2200",
        "date": "2022-02-11",
        "quantity": 2
        "diagnosis_codes": ["H52.10"],
    }, {
        "codes": ["V2781"],
        "cost": "44.2100",
        "date": "2022-02-11",
        "quantity": 1
    }],
    "status": "ready",
    "paid_amount": "68.6500"
}

Request Parameters

The main fields of claim are:

patient: JSON object, representing patient details
primary_member: JSON object, representing primary patient member
services: list of JSON objects, representing services that can be reimbursed

Both patient and primary_member must be provided even if the claim is created for a primary member. In this case, both the patient object and primary_member object must contain the same data.

Authorizations

Authorization

string

header

required

Your API token prefaced with an "Api" prefix. Example value: "Api B3F4242424E3FDB4242424242A9C7642"

Body

application/json

paid_amount

number<double>

required

Amount paid by patient for services in claim

services

object[]

required

List of services in claim

Required array length: 1 - 6 elements

Show child attributes

services.quantity

integer

required

Required range: x >= 1

Example:

1

services.cost

string<double>

required

Cost of one service

Example:

"299.95"

services.date

string<date>

required

Date of service

Example:

"2025-04-15"

services.codes

string[]

required

List of CPT predefined codes

services.diagnosis_codes

string[]

HCPCS diagnosis codes (per service). Required in at least one service per claim for VSP.

primary_member

object

required

Information about primary member (primary subscriber)

Show child attributes

primary_member.member_id

string

required

Member ID or Subscriber ID. Optional for VSP and Cigna Vision when ssn_last_four is provided

Example:

"M1328422"

primary_member.first_name

string

required

First name

primary_member.last_name

string

required

Last name

primary_member.dob

string<date>

required

Date of Birth

Example:

"1985-03-15"

primary_member.address

object

required

Member address

Show child attributes

primary_member.address.line1

string

required

Example:

"Long st. 65"

primary_member.address.city

string

required

Example:

"Santa Monica"

primary_member.address.zipcode

string

required

Example:

99577

primary_member.address.state

string

required

Example:

"CA"

primary_member.address.line2

string

Example:

"ap. 231"

primary_member.address.recipient

string

Example:

"Mr Smith"

primary_member.phone

string

required

Member phone

Example:

"1234567890"

primary_member.insurer_code

string

required

Insurer identifier

Example:

"insurer:vision:vsp"

primary_member.ssn_last_four

string

SSN Last Four

Example:

"0924"

primary_member.sex

enum<string>

Member sex. Required for VSP

Available options:

male,

female

primary_member.email

string<email>

Member email

Example:

"[email protected]"

patient

object

required

Information about patient

Show child attributes

patient.type

enum<string>

required

Type of patient. self in case of primary member

Available options:

self,

spouse,

child,

other

Example:

"spouse"

patient.member_id

string

required

Optional for VSP, Cigna Vision, Davis Vision, Spectera, and Superior Vision

patient.first_name

string

required

First name

patient.last_name

string

required

Last name

patient.dob

string<date>

required

Date of Birth

Example:

"1985-03-15"

patient.address

object

required

Member address

Show child attributes

patient.address.line1

string

required

Example:

"Long st. 65"

patient.address.city

string

required

Example:

"Santa Monica"

patient.address.zipcode

string

required

Example:

"99577"

patient.address.state

string

required

Example:

"CA"

patient.address.line2

string

Example:

"ap. 231"

patient.address.recipient

string

Example:

"Mr Smith"

patient.ssn_last_four

string

SSN Last Four

Example:

"0924"

patient.sex

enum<string>

Member sex. Required for VSP

Available options:

male,

female

patient.email

string<email>

Member email

Example:

"[email protected]"

patient.phone

string

Member phone

Example:

"1234567890"

patient.account_number

string

Patient account number in an external system

Maximum string length: 25

is_aob_enabled

boolean

Whether to accept the assignment of the benefits. false by default

metadata

object

Allows to store arbitrary metadata within the claim. You should use patient.account_number to link claims to your system.

location_code

string

Identifies the location that the claim will be linked to. When this field is empty, the claim will be linked with the default location. Example: LOC4242B

Response

200 - application/json

paid_amount

string<double>

required

services

object[]

required

Show child attributes

services.quantity

integer

required

services.cost

string<double>

required

services.date

string<date>

required

services.codes

string[]

required

services.diagnosis_codes

string[]

required

primary_member

object

required

Show child attributes

primary_member.first_name

string

required

primary_member.last_name

string

required

primary_member.dob

string<date>

required

primary_member.address

object

required

Show child attributes

primary_member.address.line1

string

required

primary_member.address.city

string

required

primary_member.address.zipcode

string

required

primary_member.address.state

string

required

primary_member.address.line2

string

primary_member.address.recipient

string

primary_member.phone

string

required

primary_member.insurer_code

string

required

primary_member.member_id

string

primary_member.ssn_last_four

string

primary_member.sex

enum<string>

Available options:

male,

female

primary_member.email

string

patient

object

required

Show child attributes

patient.type

string

required

patient.first_name

string

required

patient.last_name

string

required

patient.dob

string<date>

required

patient.address

object

required

Show child attributes

patient.address.line1

string

required

patient.address.city

string

required

patient.address.zipcode

string

required

patient.address.state

string

required

patient.address.line2

string

patient.address.recipient

string

patient.member_id

string

patient.ssn_last_four

string

patient.sex

enum<string>

Available options:

male,

female

patient.email

string

patient.phone

string

patient.account_number

string

is_aob_enabled

boolean

metadata

object

API Documentation

Endpoints

Request Parameters

Authorizations

Body

Response

API Documentation

Endpoints

​Request Parameters

Authorizations

Body

Response

Request Parameters