Invoice registration

The Accounts Receivable Invoices endpoint in Osigu Payments allows healthcare providers to register one or more invoices issued to payers. This endpoint accepts a JSON payload with specific attributes required for each invoice item. Below is the detailed structure for the request and response, including the essential data fields and response attributes.

Request Structure

Each invoice item should include the following fields in the JSON request body:

issue_date: The date the invoice was issued.
payer: An inner object containing the payer’s details:
- country_code: The payer’s country code.
- tax_id: The payer’s tax identifier.
  These two fields locate the payer within the pre-configured percentages and fees set up during onboarding. If the payer is not found, the invoice will still be registered but ineligible for a cash advance.
invoice_number: The unique invoice number.
total_amount: The total amount owed by the payer.
filing_date (optional): The date the invoice was submitted to the payer.
filing_reference (optional): The submission reference number or code provided by the payer after the invoice was filed.

Example Request Body

{
  "invoices": [
    {
      "issue_date": "2024-06-01",
      "payer": {
        "country_code": "US",
        "tax_id": "123456789"
      },
      "currency_code": "USD",
      "invoice_number": "INV-1001",
      "total_amount": 1500.00,
      "filing_date": "2024-06-05",
      "filing_reference": "REF123456"
    }
  ]
}

Response Structure

Upon successfully registering the invoices, the system returns an array of items corresponding to each invoice with the following information:

id: The UUID of the invoice as registered within Osigu Payments.
invoice_number: The unique invoice number, as submitted.
payment_status: The payment status, typically PENDING. If the payer configuration is missing or if the expected due date is approaching, the status may change to NOT_ELIGIBLE.
risk_level: The calculated risk level for the invoice is determined based on data sources (e.g., ERP, RCM, CLAIMS) and available information.
fee_percentage: The applicable fee percentage over the amount if the status is PENDING.
eligible_advance_percentage: The percentage of the total amount eligible for an advance.
eligible_advance_amount: The calculated amount eligible for an advance based on the percentage and total invoice amount.
additional_info_complete: A boolean indicating if all required additional information is complete.
due_date: Osigu calculates the expected payment date. As this date approaches, the invoice will no longer be eligible for an advance based on the onboarding configuration.
additional_information: An inner object detailing required supporting documents or additional data. This object specifies the data type (file or data) and whether the information is still pending (initially set to pending upon first registration).
cashout_request_id: This will always return as null immediately after the invoice(s) are registered.

{
  "invoices": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
      "invoice_number": "INV-1001",
      "payment_status": "PENDING",
      "source": "PROVIDER_ERP",
      "risk_level": "HIGH",
      "currency_code": "USD",
      "fee_type": "MONTHLY",
      "fee_percentage": 50.00,
      "eligible_advance_percentage": 80,
      "eligible_advance_amount": 1200.00,
      "additional_info_complete": false,
      "due_date": "2023-12-01",
      "additional_information": [
        {
          "info_type": "Electronic Invoice File",
          "data_type": "FILE", 
          "allowed_file_types": "XML",
          "status": "PENDING",
          "is_mandatory": "TRUE"
        },
        {
          "info_type": "Payer Filing Acceptance File ",
          "data_type": "FILE", 
          "allowed_file_types": "XML",
          "status": "PENDING",
          "is_mandatory": "FALSE"
        }
      ],
      "cashout_request_id": null
    }
  ]
}

Additional Information Endpoint

To complete or update an invoice registration, the Additional Information endpoint allows for adding required data or files linked to specific invoices. This additional information can impact the invoice’s risk level, potentially making it eligible for different terms based on the new data provided.

Path Variable: account_receivable_invoice_id – The UUID of the invoice to which additional information is added.
Data Submission:
- When submitting additional data (not files), include in the request body:
  - info_type: The key represents the additional information type (e.g., "filing_acceptance").
  - info_description: The corresponding value or description of the data.
Example Request (Data Submission):
```
{
  "info_type": "filing_acceptance",
  "info_description": "20240629-X39017"
}
```
File Submission:
For submitting files, use:
- Path Variable: account_receivable_invoice_id (UUID of the invoice).
- Query Parameter: info_type – Identifies the type of additional information corresponding to the file.

The invoice’s risk level may be recalculated each time additional information is uploaded. For synchronous analyses, risk level adjustments occur immediately. However, if the analysis is asynchronous, any changes to the risk level and terms will be updated after processing.

For detailed information on using this endpoint, please refer to the API Reference.