Lifetime JSON Statement Specification
Outlines the Lifetime specification for statement ingestion
Updated at April 22nd, 2025
The following outlines the specifications and minimum required fields for Lifetime statement ingestion via JSON file and SFTP.
| Object | Field | Required | Data Type | Description | Example |
| schema | N | string (13) | Identifies this statement file as a lifetime statement; hard-coded to "ppay-lifetime" | “schema” : “ppay-lifetime” | |
| version | N | string (10) | Identifies the version of the statement file; hard-coded to current schema version of "1.0.0" | “version” : “1.0.0” | |
| statements | The statements array contains one or more statement objects separated by comma | ||||
| statement | A statement object is a nested object that contains fields and nested objects pertaining to the statement or bill | ||||
| statementId | Y | string (64) | Uniquely identifies the statement/bill and must be unique per load since lifetime bills require iterative statement IDs | “statementId”: “SHA_01-03-2002-0830” | |
| statementDate | N | date (YYYY-MM-DD) | Date of the statement in format YYYY-MM-DD. If null, the date processed will be set as the statement date for calculating due date of payment in messages to patients. | “statementDate” : "2022-01-03" | |
| clientId | Y | string (40) | Uniquely identifies the practice/organization and must match an existing organization's client Id provisioned in our system. Must also be unique system-wide in PatientPay. NOTE: Case sensitive. | “clientId”: "SHA-15" | |
| totalBilled | Y | number (10,2) | The total amount charged and and billed to the insurance company or patient (pre-adjustments) | “totalBilled”: "969.00" | |
| totalBalance | Y | number (10,2) | The total amount remaining that is due from the patient. A totalBalance of $0 will mark the bill as Cancelled and no longer communicate to the patient. | “totalBalance”: "74.60" | |
| statementMessage | N | string (1000) | Allows for custom message to be displayed on the printed statement/letter for the patient | “statementMessage”: "There is a balance remaining on your account. If you have any questions, please contact our billing office at 888-555-1212." | |
| status | N | string (255) |
Sets the status of the bill. Supported values include: DUE = Due HOLD = Suspend with Reason Hold REBILLING INSURANCE = Suspend with Reason Rebilling Insurance DISPUTE REVIEW = Suspend with Reason Dispute Review PENDING REVIEW = Suspend with Pending Review VOID = Void COLLECTIONS = Sent to Collections If status is blank/null, and balance > $0, default is Due. If status is blank/null and balance = $0, default is Cancelled. |
“status”: “DUE” | |
| dunningStatus | N | string (20) |
Sets the specific dunning cycle for the bill which controls the print and electronic communication with the patient. Supported values include: A1 = Initial Bill Status A2 = Past Due Status A3 = Past Due Status A4 = Pre-Collection Letter A5 = Pre-Collection Letter A6 = Expired (no further comms but can be paid) Default is A1 if null. |
“dunningStatus”: “A1” | |
| billReset | N | boolean (true/false) | Resets Dunning by resetting the bill's EffectiveCreatedDate. A value of "true" must also be combined with feature flag RESET_BILL_ON_FLAG = "true" as well | "billReset": "true" | |
| electronicOptOut | N | string (20) |
Indicates whether to opt-out patient from electronic communications (email and SMS). Supported values include: E = Email only; opt-out from Text N = Neither; opt-out of Email/Text B = Both; Email and Text are opted-in M = Mobile only; opt-out from Email true = Neither; opt-out of Email/Text (legacy value) blank/null = Do nothing |
”electronicOptOut”: “true“ | |
| externalBillCode | N | string (20) | If specified, this will be used as the bill code for the Bill Code Login and printed on the statement. Otherwise, PatientPay will generate a unique bill code at the time we generate the print statement. | “externalBillCode” "sw266d42-6" | |
| eobRequired | N | string (1) |
Indicates whether to print the Explanation of Benefits (EOB). Supported values are: 0 = false 1 = true |
“eobRequired”: “0” | |
| invoiceRequired | N | string (1) |
Indicates whether to print the statement. Supported values are: 0 = false 1 = true |
“invoiceRequired”: “1” | |
| statement.dateFlags | dateFlags are flags which can be used for conditional dunning in our system | ||||
| flagName | N | string (255) | The name of the flag. This should match the flag name in our dunning configuration (dynamic dunning, date_flags column) | "dateFlags": [{"flagName": "getEOBFrom","flagValue": "CONFIG" }] | |
| flagValue | N | string (255) |
This value is used to calculate the date for conditional dunning. The supported values are: DEFAULT - date is derived by adding configuration value from customer_configuration table to effective_created_date. Set flag_date to effective_created_date. If value is number, it is added to the effective date. CONFIG - If exists, use value from customer_configuration value to set flag_date value in bill_date_flags table. It would be the effective_date + days value in the config (like due_date today).<Number> - Set flag_date value to bill_effective_date + <number> days. null - Add the flag in the new table but with value null – same as not having the flag but a more explicit option. Any invalid/unsupported value is considered to be null. If we parse any other value, we will process the bill but issue a warning to the Error Store in the DB. |
"dateFlags": [{"flagName": "getEOBFrom","flagValue": "CONFIG" }] | |
| statement.practice | Practice is a nested object that contains fields pertaining to a practice or organization | ||||
| taxId | N | string (45) | Practice Tax ID | "taxId": "851108519" | |
| npi | N | string (45) | Practice NPI | "npi": "1790309276" | |
| name | N | string (255) | Legal entity name for the practice/organization | "name" : "Practice, Inc." | |
| supportPhone | N | string (15) | Billing Support phone number for practice | "supportPhone" : “800-555-1212” | |
| addressLineOne | N | string (64) | First line of address for the practice | "addressLineOne" : "123 Main Street" | |
| addressLineTwo | N | string (64) | Second line of address for the practice | "addressLineTwo" : “Suite 100” | |
| city | N | string (64) | Practice city | "city" : "New York" | |
| state | N | string (2) | Two-letter state code for practice address | "state" : "NY" | |
| zip | N | string (10) | Five or Ten-digit postal code for practice address | "zip" : "10016-1111" | |
| country | N | string (4) | Two-character country code for practice address | "country" : "US" | |
| statement.guarantor | Guarantor is a nested object that contains fields pertaining the guarantor financially responsible for the patient | ||||
| lastName | Y | string (45) | Guarantor last name | "lastName": "Smith" | |
| firstName | Y | string (45) | Guarantor first name | "firstName": "Rick" | |
| gender | N | string (20) |
Guarantor's gender. Supported values include: M = Male F = Female NB = Non-Binary U = Unknown/Declined to Provide |
"gender": "M" | |
| dob | Y | date (YYYY-MM-DD) | Guarantor's date of birth in format YYYY-MM-DD. Must be populated on patient or guarantor or bill will be rejected. | "dob": "1980-01-02" | |
| employerDesc | N | string(100) | Employer for the guarantor | "employerDesc":"EBAY" | |
| guarantor.contactInfo | The contactInfo within the guarantor object contains fields that pertain to the guarantor's contact details - Phone, email, address etc. | ||||
| N | string (255) | Guarantor's email address - necessary for electronic dunning communications | "email" : "rick.smith@gmail.com" | ||
| mobilePhone | N | string (25) | Guarantor's mobile phone. Phone should be 10 digits - numeric only and not contain +, ( ) or -. | "mobilePhone": "9195551212" | |
| homePhone | N | string (25) | Guarantor's home phone. Phone should be 10 digits - numeric only and not contain +, ( ) or -. | "homePhone": "9195551212" | |
| addressLineOne | Y | string (55) | Guarantor's address line 1. At least one of the three addresses must have a value. | "addressLineOne": "123 Main Street" | |
| addressLineTwo | Y | string (55) | Guarantor's address line 2. At least one of the three addresses must have a value. | "addressLineTwo": "Suite 100" | |
| addressLineThree | Y | string (200) | Guarantor's address line 3. At least one of the three addresses must have a value. | "addressLineThree": " | |
| city | Y | string (45) | Guarantor city | "city" : "New York" | |
| state | Y | string (45) | Two-letter state code for guarantor address | "state" : "NY" | |
| zip | Y | string (45) | Five or Ten-digit postal code for guarantor address | "zip" : "10016" | |
| country | N | string (200) | Two-character country code for guarantor address (ISO-ALPHA2) | "country" : "US" | |
| statement.payers | payers is an array of payer objects. The payer contains fields pertaining to insurance. Can support up to n payers: Primary, Secondary, Tertiary etc. Only used if transactions are linked to payer_id. NOTE: the system first checks whether the statement has patient.visits.visitPayers and, if not present, uses payers from this array. | ||||
| payerIndex | N | string (10) | Payer Index (or order) that matches payer designation in customer system | "payerIndex": "1" | |
| payerId | N | string (45) | Payer ID from customer system. Must be included for service line transaction items. | "payerId": "94036" | |
| name | Y | string (75) | Payer Name that will be presented to the patient on print and digital bill | "name": "BLUE SHIELD OF SC" | |
| statement.patients | patients is an array of patient objects. The patient contains fields pertaining to the patient. Multiple patients can be transmitted using this array but only the first patient is used. | ||||
| accountId | Y | string (45) | Patient's account Id in sending system. This is the primary identifier for the patient and should be unique in the PMS/EMR. | "accountId": "TST2121212188" | |
| lastName | N | string (45) | Patient's last name | "lastName": "Smith" | |
| firstName | N | string (45) | Patient's first name | "lastName": "Rick" | |
| gender | N | string (20) |
Patient's gender. Supported values include: M = Male F = Female NB = Non-Binary U = Unknown/Declined to Provide |
"gender": "M" | |
| preferredLanguage | N | string (2) | The patient's preferred language using the ISO language code https://www.w3schools.com/tags/ref_language_codes.asp | "preferredLanguage": "EN" | |
| dob | N | date (YYYY-MM-DD) | Patient's date of birth in format YYYY-MM-DD. Must be populated on patient or guarantor or bill will be rejected. | "dob": "1980-01-02" | |
| patient.contactInfo | The contactInfo within the patient object contains fields that pertain to the patient's contact details - Phone, email, address etc | ||||
| N | string (255) | Patient's email address | "email" : "rick.smith@gmail.com" | ||
| mobilePhone | N | string (25) | Patient's mobile phone. Phone should be 10 digits - numeric only and not contain +, ( ) or -. | "mobilePhone": "9195551212" | |
| homePhone | N | string (25) | Patient's home phone. Phone should be 10 digits - numeric only and not contain +, ( ) or -. | "homePhone": "9195551212" | |
| addressLineOne | Y | string (55) | Patient address line 1. We require that one of three address lines have a value | "addressLineOne": "123 Main Street" | |
| addressLineTwo | Y | string (55) | Patient address line 2. We require that one of three address lines have a value | "addressLineTwo": "Suite 100" | |
| addressLineThree | Y | string (200) | Patient address line 3. We require that one of three address lines have a value | "addressLineThree": " | |
| state | Y | string (45) | Patient address city | "city" : "New York" | |
| city | Y | string (45) | Two-letter state code for patient address | "state" : "NY" | |
| zip | Y | string (45) | Five or ten-digit postal code for patient address | "zip" : "10016" | |
| country | N | string (200) | Two-character country code for patient address (ISO-ALPHA2) | "country" : "US" | |
| patient.visits | visits is an array of visit objects that contain fields pertaining to the visits for a patient. | ||||
| visitId | N | string (45) | Visit or encounter number for the patient visit. If the field is null, services will be associated to an empty visit. | "visitId": "27500" | |
| claimNo | N | string (45) | Claim number for the visit. | "claimNo": "848332" | |
| startDate | N | date (YYYY-MM-DD) | Start date of the visit. If visitId is null, then date should be null. | "startDate": "2021-11-12" | |
| locationName | N | string (100) | Location name where the patient visit occurred. | "locationName": “Green Bay Clinic" | |
| patient.visits.visitPayers | visitPayers is an array of payer objects. The payer contains fields pertaining to insurance. Can support up to n payers: Primary, Secondary, Tertiary etc. Only used if transactions are linked to payer_id. | ||||
| payerIndex | N | string (10) | Payer Index (or order) that matches payer designation in customer system | "payerIndex": "1" | |
| payerId | N | string (45) | Payer ID from customer system. Must be included for service line transaction items. | "payerId": "94036" | |
| payerName | N | string (75) | Payer Name that will be presented to the patient on print and digital bill | "payerName": "BLUE SHIELD OF SC" | |
| patient.visits.services | services is an array of service objects that contains fields pertaining to the services rendered for a patient | ||||
| serviceId | N | string (200) | Unique service id. The service id is controlled by the sending system. | "serviceId": "2907835" | |
| serviceDate | Y | date (YYYY-MM-DD) | Date that services were rendered for the patient. | "serviceDate": "2021-02-03" | |
| serviceProvider | N | string (255) | Provider name or entity that rendered the services to the patient. | "serviceProvider": "CASEY, KENNETH D CRNA" | |
| serviceProviderNPI | N | string (255) | NPI (level 1 or 2) of the individual or entity named in serviceProvider. | "serviceProviderNPI": "1366085755" | |
| serviceCode | N | string (45) | Service code of the services rendered, this can be CPT, HCPS, Jcodes, ICD10, etc. | "serviceCode": "99213" | |
| serviceDesc | N | string (100) | Service description of the serviceCode. Leave blank to lookup description based on serviceCode. | "serviceDesc": "" | |
| charge | Y | number (10,2) | Amount charged for this service. | "charge": "200.00" | |
| deductibleAmt | N | number (10,2) | Insurance deductible portion of the claim - dollar amount. | "deductibleAmt": "10.00" | |
| coinsAmt | N | number (10,2) | Coinsurance portion of the claim - dollar amount. | "coinsAmt": "26.00" | |
| copayAmt | N | number (10,2) | Copay of the claim - dollar amount. | "copayAmt": "12.00" | |
| eobIneligibleAmt | N | number (10,2) | The amount of the total charges (Service Cost) that was not covered or eligible under the member's plan. | "eobIneligibleAmt": "10.00" | |
| eobCode | N | number (10,2) | EOB code for the corresponding reason for denials or non-coverage. | "eobCode": "956078" | |
| serviceUnits | N | number | EOB service units total | "serviceUnits":"2" | |
| visit.services.transactions | transactions is an array of transaction objects that contains fields pertaining to the payment transactions related to the services provided | ||||
| transactionId | N | string (15) | Unique transaction ID for a service-level transaction | "transactionId": null | |
| transactionDate | Y | date (YYYY-MM-DD) | Transaction date | "transactionDate": "2021-02-03" | |
| transactionAmt | Y | number (10,2) |
Amount charged for this service. This can be the initial charged, or in a subsequent transaction an adjustment of payment by the insurance or patient. Must be number. - Positive amount = Credit posted - Negative amount = Debit posted |
"transactionAmt": "-50.00" | |
| transactionDesc | N | string (500) | Description of the transaction | "transactionDesc": "CONTRACTED INS PAYMENT" | |
| transactionAddDesc | N | string (500) | Any additional description of the transaction | "transactionAddDesc": "COINSURANCE AMOUNT" | |
| payerId | N | string (45) | Payer Id for the transaction, if available. | "payerId": null | |
| transactionType | N | string (45) | Type of transaction. Supported values: See Transaction Types tab. If null or blank, we will provide a default value of “14” for PatientAdjustment. | "transactionType": "12" | |
| visits.transactions | transactions is an array of transaction objects that contains fields pertaining to the payment transactions related to the visit provided. This allows claim/visit level transactions if the customer system records payments at the claim level | ||||
| transactionId | N | string (15) | Unique transaction ID for a visit-level transaction | "transactionId": null | |
| transactionDate | Y | date (YYYY-MM-DD) | Transaction date | "transactionDate": "2021-02-03" | |
| transactionAmt | Y | number (10,2) |
Amount charged for this service. This can be the initial charged, or in a subsequent transaction an adjustment of payment by the insurance or patient. Must be number. - Positive amount = Credit posted - Negative amount = Debit posted |
"transactionAmt": "-50.00" | |
| transactionDesc | N | string (500) | Description of the transaction | "transactionDesc": "CONTRACTED INS PAYMENT" | |
| transactionAddDesc | N | string (500) | Any additional description of the transaction | "transactionAddDesc": "COINSURANCE AMOUNT" | |
| payerId | N | string (45) | Payer Id for the transaction, if available. | "payerId": null | |
| transactionType | N | string (45) | Type of transaction. Supported values: See Transaction Types tab. If null or blank, we will provide a default value of “14” for PatientAdjustment. | "transactionType": "12" | |
| visits.otherProviders | otherProviders is an array for visits for designating other provider types for the patient visits. | ||||
| type | N | string (255) |
Type of providers related to a patient visit. Supported values include: - Referring - Rendering - Supervising - Billing - Ordering - Operating - Performing |
"type":"referring" | |
| npi | N | string (255) | NPI number for the provider | "npi":"12345" | |
| id | N | string (255) | Alternate ID for the provider if NPI is not used | "id":null | |
| name | N | string (255) | Name of the provider | "name":"John Bates Jr. M.D" | |
| statement.transaction | transactions is an array of transaction objects that contains fields pertaining to the payment transactions related to the entire statement. This is not to be confused with transactions at the patient and service level. | ||||
| transactionId | N | string (15) | Unique transaction ID for a statment-level transaction | "transactionId": null | |
| transactionDate | Y | date (YYYY-MM-DD) | Transaction date | "transactionDate": "2021-02-03" | |
| transactionAmt | Y | number (10,2) |
Amount charged for this service. This can be the initial charged, or in a subsequent transaction an adjustment of payment by the insurance or patient. Must be number. - Positive amount = Credit posted - Negative amount = Debit posted |
"transactionAmt": "-50.00" | |
| transactionDesc | N | string (500) | Description of the transaction | "transactionDesc": "CONTRACTED INS PAYMENT" | |
| transactionAddDesc | N | string (500) | Any additional description of the transaction | "transactionAddDesc": "COINSURANCE AMOUNT" | |
| payerId | N | string (45) | Payer Id for the transaction, if available. | "payerId": null | |
| transactionType | N | string (45) | Type of transaction. Supported values: See Transaction Types tab. If null or blank, we will provide a default value of “14” for PatientAdjustment. | "transactionType": "12" | |
The following represents the supported values for Transaction Type:
| Code | Description | Lifetime Code | Episodic Code |
| CWOFF | Contractual Write-Off | 5 | InsWriteOff |
| EXCOL | Transfer to External Collections | 9 | Collections |
| GPYMT | Guarantor Payment | 11 | PatientPayment |
| IPYMT | Insurance Payment | 12 | InsPayment |
| MADJN | Miscellaneous Negative Adjustment | 14 | PatientAdjustment |
| MADJP | Miscellaneous Positive Adjustment | 15 | PatientAdjustment |
| REFND | Refund | 19 | PatientAdjustment |
| RVCOL | External Collection Reversal | 22 | PatientAdjustment |
| RVCWO | Contractual Write-Off Reversal | 23 | InsWriteOff |
| RVPAY | Payment Reversal | 25 | PatientPayment |
| RVRFD | Refund Reversal | 26 | PatientPayment |
| RVWHD | Insurance Withholding Reversal | 27 | InsPayment |
| SVCFE | Service Line Fee | 30 | PatientAdjustment |
| WHOLD | Insurance Withholding | 32 | InsPayment |
| DISTR | Distribution of On-Account Funds | 37 | PatientPayment |
| RVACC | Reverse Payment – Move to On-Account | 38 | PatientAdjustment |
| RVSUS | Payment Reversal – Transfer to Suspense | 39 | PatientAdjustment |
| RVADJ | Reverse Payment Adjustment | 40 | InsWriteOff |
| GSUSP | Transfer from Guarantor Account | 41 | PatientAdjustment |
| SDISTR | Suspense Distribution to Guarantor Account | 42 | PatientPayment |
| RSCND | Rescinded Payment | 44 | InsPayment |
| ADCWO | Adjustment to Contractual Writeoff | 46 | InsWriteOff |
| ADWHD | Adjustment to Withhold | 47 | InsWriteOff |
| RVRSC | Reversal of Rescinded Payment | 54 | InsPayment |
Example Lifetime JSON:
{
"schema": "ppay-lifetime",
"version": "1.0.0",
"statements": [
{
"statementId": "TST-2222-3297",
"statementDate": "",
"clientId": "TEST-2222",
"totalBilled": "325.08",
"totalBalance": "74.36",
"statementMessage": "Prompt payment is appreciated",
"status":"DUE",
"dunningStatus": "A1",
"billReset":"true",
"electronicOptOut": "true",
"eobRequired": "0",
"invoiceRequired": "1",
"externalBillCode" : null,
"practice": {
"taxId": "851108519",
"npi": "1790309276",
"name": "Durham Spine And Pain",
"supportPhone": "(919) 222-6758",
"addressLineOne": "Dept. CH 17057",
"addressLineTwo": "",
"city": "Durham",
"state": "NC",
"zip": "53081-3169",
"country" : "US"
},
"guarantor": {
"lastName": "Jones",
"firstName": "Bob",
"gender": "M",
"dob": "1973-12-25",
"contactInfo": {
"email": "bjones@patientpay.com",
"mobilePhone": "9195551212",
"homePhone": "9208507828",
"addressLineOne": "123 Main Street",
"addressLineTwo": "",
"addressLineThree": "",
"city": "Raleigh",
"state": "NC",
"zip": "27502"
}
},
"patients": [
{
"accountId": "PID10388",
"lastName": "Jones",
"firstName": "Bob",
"gender": "M",
"preferredLanguage": "EN",
"dob": "1973-12-25",
"contactInfo": {
"email": "bjones@patientpay.com",
"mobilePhone": "9195551212",
"homePhone": "9195551212",
"addressLineOne": "123 Main Street",
"addressLineTwo": "",
"addressLineThree": "",
"city": "Raleigh",
"state": "NC",
"zip": "27502"
},
"visits": [
{
"visitId": "27500",
"claimNo": "848332",
"startDate": "2021-11-12",
"locationName": "Old Bay Clinic",
"visitPayers": [
{
"payerIndex": "1",
"payerId": "001",
"payerName": "BCBS NC"
}
],
"services": [
{
"serviceId": "2907835",
"serviceDate": "2021-02-03",
"serviceProvider": "CASEY, KENNETH D CRNA",
"serviceProviderNPI": "1366085755",
"serviceCode": "99213",
"serviceDesc": "",
"charge": "-200.00",
"deductibleAmt": "10.00",
"coinsAmt": "26.00",
"copayAmt": "12.00",
"eobIneligibleAmt": "10.00",
"eobCode": "956078",
"transactions": [{
"transactionId": "1",
"transactionDate": "2021-02-03",
"transactionAmt": "-50.00",
"transactionDesc": "CONTRACTED INS PAYMENT",
"transactionAddDesc": "COINSURANCE AMOUNT",
"payerId": "001",
"transactionType": "12"
}]
}
]
},
{
"visitId": "27501",
"claimNo": "848333",
"startDate": "2021-11-13",
"locationName": "Old Bay Clinic",
"visitPayers": [
{
"payerIndex": "1",
"payerId": "001",
"payerName": "BCBS NC"
}
],
"services": [
{
"serviceId": "2907835",
"serviceDate": "2021-11-13",
"serviceProvider": "Dr. Two Provider, MD",
"serviceProviderNPI": "1154374411",
"serviceCode": "74177",
"serviceDesc": "CT ABDOMEN & PELVIS W/CON",
"charge": "395.00",
"deductibleAmt": "10.00",
"coinsAmt": "26.00",
"copayAmt": "12.00",
"eobIneligibleAmt": "10.00",
"eobCode": "956078",
"transactions": [{
"transactionId": "1",
"transactionDate": "2021-11-13",
"transactionAmt": "-195.20",
"transactionDesc": "CONTRACTED INS PAYMENT",
"transactionAddDesc": "COINSURANCE AMOUNT",
"payerId": "001",
"transactionType": "12"
}, {
"transactionId": "2",
"transactionDate": "2021-11-13",
"transactionAmt": "-30.19",
"transactionDesc": "CONTRACTED INS ADJUSTMENT",
"transactionAddDesc": "",
"payerId": "001",
"transactionType": "5"
}]
}
]
}
]
}
]
}
]
}
Download Specification in Excel