Bulk invoice items

This topic documents the Cloud API for bulk invoice items in ClaimCenter. It provides instructions and examples for how to use the endpoints, as well as some common business flows.

To learn more about bulk invoice items in ClaimCenter, refer to the Application Guide.

Querying for bulk invoice items

Use the following endpoints to query for a bulk invoice's line items:

  • GET /claim/v1/bulk-invoices/{bulkInvoiceId}/bulk-invoice-items
  • GET /claim/v1/bulk-invoices/{bulkInvoiceId}/bulk-invoice-items/{bulkInvoiceItemId}

Retrieve all bulk invoice items

The first endpoint retrieves all invoice line items associated with a bulk invoice by the bulk invoice's id. To learn how to find a bulk invoice's id, refer to Querying for bulk invoices.

The following example request retrieves all invoice line items, along with their amounts and other details, associated with a bulk invoice:

Command

GET /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "500.00",
                    "currency": "usd"
                },
                "claim": {
                    "displayName": "000-00-000046",
                    "id": "xc:SSHDtfBU7BeeVAVlenYCl",
                    "type": "Claim",
                    "uri": "/claim/v1/claims/cc:SSHDtfBU7BeeVAVlenYCl"
                },
                "id": "xc:SWtfIFpffJuhQKK6F6UUt",
                "status": {
                    "code": "draft",
                    "name": "Draft"
                }
            }
        },
        {
            "attributes": {
                "amount": {
                    "amount": "500.00",
                    "currency": "usd"
                },
                "claim": {
                    "displayName": "312-36-300870",
                    "id": "demo_sample:30005",
                    "type": "Claim",
                    "uri": "/claim/v1/claims/demo_sample:30005"
                },
                "id": "xc:SDuB2J89w5RHhW4zpbJGq",
                "status": {
                    "code": "draft",
                    "name": "Draft"
                }
            }
        }
    ]
}

Retrieve a bulk invoice item by ID

The second endpoint retrieves a specific bulk invoice line item by its id. In addition to only retrieving one specific bulk invoice line item, this endpoint retrieves additional useful details about the bulk invoice line item, such as relevant deductions or associated exposures, for example.

If you don't know the ID of the bulk invoice line item you want to retrieve, you can use the first endpoint to get the id. Then you can retrieve the bulk invoice line item by that id. For example, the following request retrieves the bulk invoice line item xc:SDuB2J89w5RHhW4zpbJGq:

Command

GET /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items/xc:SDuB2J89w5RHhW4zpbJGq

Response

{
    "data": {
        "attributes": {
            "amount": {
                "amount": "500.00",
                "currency": "usd"
            },
            "awaitingProcessing": false,
            "bulkInvoiceOrder": 2,
            "claim": {
                "displayName": "312-36-300870",
                "id": "demo_sample:30005",
                "type": "Claim",
                "uri": "/claim/v1/claims/demo_sample:30005"
            },
            "costCategory": {
                "code": "unspecified",
                "name": "Unspecified Cost Category"
            },
            "costType": {
                "code": "unspecified",
                "name": "Unspecified Cost Type"
            },
            "deductionsAmount": {
                "amount": "0.00",
                "currency": "usd"
            },
            "exposure": {
                "displayName": "(1) Medical Details",
                "id": "xc:SzSQHGuLGTPRiwI_2eZ6F",
                "type": "Exposure",
                "uri": "/claim/v1/claims/demo_sample:30005/exposures/cc:SzSQHGuLGTPRiwI_2eZ6F"
            },
            "id": "xc:SDuB2J89w5RHhW4zpbJGq",
            "nonEroding": false,
            "paymentType": {
                "code": "final",
                "name": "Final"
            },
            "reportingAmount": {
                "amount": "500.00",
                "currency": "usd"
            },
            "reservingCurrency": {
                "code": "usd",
                "name": "USD"
            },
            "status": {
                "code": "draft",
                "name": "Draft"
            }
        }
    }
}

The API responds with only the specified bulk invoice line item, along with additional details beyond what is returned when you retrieve all bulk invoice line items.

Creating bulk invoice items

Use the following endpoint to create a bulk invoice line item:

  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/bulk-invoice-items

Required fields

The following fields are required to create a bulk invoice line item with a bulk invoice total that is split equally:

  • claim: This object specifies the claim the bulk invoice line item is associated with. You must specify the claim's id within the object. To learn how to find a claim's id, refer to Querying for claims associated with you.
  • costCategory: This object specifies the cost category for the bulk invoice line item. You must specify the code within the object, something like medical or property_repair.
  • costType: This object specifies the cost type for the bulk invoice line item. You must specify the code within the object, something like claimcost or aoexpense.
  • paymentType: This object specifies the payment type for the bulk invoice line item. You must specify the code within the object, something like partial or final.
  • reservingCurrency: This object specifies the reserving currency for the bulk invoice line item. You must specify the code within the object, something like usd or jpy.

The following field is required to create a bulk invoice line item with a bulk invoice total that is not split equally, which means that you must enter the individual amounts for each bulk invoice line item:

  • amount: This object specifies the amount for the bulk invoice line item. You must specify the amount and the currency within the object, something like 1000.00 and usd.

Bulk invoice item with total split equally

The following request creates a bulk invoice line item for a bulk invoice that is set to split a total amount equally between all line items:

Command

/claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items

Request

{
    "data": {
        "attributes": {
            "claim": {
                "id": "demo_sample:30005"
            },
            "costCategory": {
                "code": "medical"
            },
            "costType": {
                "code": "claimcost"
            },
            "paymentType": {
                "code": "final"
            },
            "reservingCurrency": {
                "code": "usd"
            }
        }
    }
}

When the request is successful, the API responds with the created bulk invoice line item. Its amount is automatically calculated based on the bulk invoice total divided by the number of bulk invoice line items.

Bulk invoice item with specified individual amount

The following request creates a bulk invoice line item for a bulk invoice that is set so that each line item must have its amount specified individually:

Command

/claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items

Request

{
    "data": {
        "attributes": {
            "claim": {
                "id": "demo_sample:30005"
            },
            "costCategory": {
                "code": "medical"
            },
            "costType": {
                "code": "claimcost"
            },
            "paymentType": {
                "code": "final"
            },
            "reservingCurrency": {
                "code": "usd"
            },
            "amount": {
                "amount": "1000.00",
                "currency": "usd"
            }
        }
    }
}

When the request is successful, the API responds with the created bulk invoice line item, along with the amount specified in the request.

Deleting bulk invoice items

Use the following endpoint to delete a bulk invoice line item by its id:

  • DELETE /claim/v1/bulk-invoices/{bulkInvoiceId}/bulk-invoice-items/{bulkInvoiceItemId}

For example, the following request deletes a specific bulk invoice line item:

Command

DELETE /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items/xc:SDuB2J89w5RHhW4zpbJGq

When the request is successful, the API responds with an empty body. You can then verify that the bulk invoice line item has been successfully deleted.

Modifying bulk invoice items

Use the following endpoint to modify an existing bulk invoice line item:

  • PATCH /claim/v1/bulk-invoices/{bulkInvoiceId}/bulk-invoice-items/{bulkInvoiceItemId}

PATCHable fields

You can modify the following fields for any bulk invoice line item:

  • claim: This object specifies the claim associated with the bulk invoice line item. You can modify the id within the object to change the claim.
  • nonEroding: This Boolean specifies whether the payment should erode reserves. This is false, by default.
  • paymentType: This object specifies the payment type for the bulk invoice line item. You can modify the code within the object to change the payment type, something like partial or final.
  • reservingCurrency: This object specifies the reserving currency for the bulk invoice line item. You can modify the code within the object to change the reserving currency, something like usd or jpy.

You can modify the following field only for a bulk invoice line item for a bulk invoice whose amounts must be specified individually, not split equally:

  • amount: This object specifies the amount for the bulk invoice line item. To change the amount, you must modify the amount and the currency within the object, something like 1000.00 and usd.

Bulk invoice item modification examples

The following request modifies the nonEroding property for a bulk invoice line item:

Command

PATCH /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items/xc:SxSBsEJyIOoP7Dmc8AoI1

Request

{
    "data": {
        "attributes": {
            "nonEroding": true
        }
    }
}

When the request is successful, the API responds with the updated bulk invoice line item and its updated nonEroding flag.

The following request modifies the amount for a bulk invoice line item whose bulk invoice requires that all amounts be specified for individual line items:

Command

PATCH /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/bulk-invoice-items/xc:SxSBsEJyIOoP7Dmc8AoI1

Request

{
    "data": {
        "attributes": {
            "amount": {
                "amount": "2000.00",
                "currency": "usd"
            }
        }
    }
}

When the request is successful, the API responds with the updated bulk invoice line item and its updated amount.