Import External Expense Claims to brioHR Payroll via API Integration

Audience & Scope

Audience: HR Admin / Payroll & Claims Manager / IT Admin

Module: Payroll

Country: Global

Pre-requisites: HR Module permission for the Payroll Module

Prerequisites & Setup

Before issuing API requests, ensure the following prerequisites are completed:

1. IP Whitelisting: The client system's outbound IP address must be whitelisted by brioHR.
2. API Credentials: Request username, password, and company ID from brioHR.

 

Overview & Operational Behavior

The Claim Import API enables external systems to push pre-approved expense claim reports directly into brioHR Payroll's Claims to Payroll > To process queue.

• Bypasses Approval Workflow: Claims pushed via this API must already be approved in the source system. brioHR does not trigger an in-app approval workflow; claims land directly in Payroll queue.
• Cycle Independence: Pushing claims does not require a payroll cycle to be open. Claims remain parked in the queue until a Payroll Admin processes them.
• Report Creation vs. Payslip Aggregation: Each API push creates its own report record in the Claims to Payroll UI. When added to payroll, claims mapped to the same reimbursement item are automatically aggregated into a single line item on the employee's final payslip.
• Internal ID Transformation: brioHR generates a deterministic internal MongoDB ObjectId derived from the client's externalClaimReportId for database storage. The original client ID is preserved in brioHR audit logs.

 

API Specification & Request Headers 

• Endpoint URL: https://static.api.briohr.com/v2/api/external/claims/import
• HTTP Method: POST
• Content-Type: application/json

 

Request Payload Schema

Each request should contain a reports array with 1 to 100 report objects per batch. Unknown extra fields are automatically stripped and ignored (HTTP 201). 

Schema Tree

reports [] (Array, Required, 1–100 elements)
 ├── externalClaimReportId (String, Required) - Unique report ID / Idempotency key
 ├── employeeEmail (String, Required) - Claimant's work email address
 ├── reportName    (String, Required) - Report label shown in brioHR
 ├── currency      (String, Required) - ISO 4217 uppercase code (e.g., MYR, SGD)
 └── claims []     (Array, Required, Non-empty) - Claim line items array
      ├── externalClaimId  (String, Required) - Unique claim line item ID
      ├── payrollItem      (String, Required) - Target reimbursement item label
      ├── claimableAmount  (Number, Required) - Min 0.01, max 2 decimal places
      ├── taxAmount        (Number, Optional) - Min 0, max 2 decimal places (Default: 0)
      ├── description      (String, Optional) - Line item description note
      └── transactAt       (String, Required) - Date incurred (ISO 8601 date string) 

Field Rules & Data Types

 

Payroll Item Label Resolution Rules

The payrollItem string maps claim lines to active Reimbursement Items in the employee's assigned Payroll Center.

1. Reimbursement Eligibility Only: Claims can only map to Reimbursement-type items (e.g., Expense Claims, Medical Reimbursement). Allowances, Deductions, and Basic Salary items are ineligible.
2. Flexible Label Matching: Matching ignores cosmetic variations:
   • Casing: eXpEnSe cLaImS resolves to Expense Claims.
   • Whitespace: Extra, leading, trailing, or repeated spaces are stripped.
   • Singular/Plural Forms: Expense Claim, Expense Claims, and Expenses claims resolve to the same item.
3. Ambiguity Prevention: If two items in a single payroll center normalize to the exact same string, the request is rejected with CLAIM_IMPORT_API.PAYROLL_ITEM_AMBIGUOUS.
4. Discovering Valid Items: There is no standalone lookup endpoint (calling GET /v2/api/external/payroll-items returns 404 Not Found). Failed label matches return CLAIM_IMPORT_API.PAYROLL_ITEM_NOT_FOUND along with an availableLabels array in the response metadata listing all valid labels for that Payroll Center.

 

Idempotency & Batch Atomicity Rules

Idempotency Matrix

Batch Atomicity & Upstream Error Handling

 

Critical Operational Behaviors & Potential Blockers

Blocker 1: Excluded Claims Cannot Be Re-Pushed Under the Same ID

When a Payroll Officer clicks Exclude on an imported claim in brioHR Payroll process, the claim is permanently removed from payroll processing.

• Behavior: Subsequent API pushes using the same externalClaimReportId will return already-parked and will not recreate the claim.

• Workaround: To resubmit an excluded claim, the third-party system must assign a new externalClaimReportId.

Blocker 2: Queue Visibility Requirements

Claims parked via the API only appear in the Validate Payroll items tab if an active payroll cycle exists that includes the claimant employee. If the API returns 201 status: parked but the claim is invisible in the web portal, verify that a running payroll cycle covers the employee.

Blocker 3: Skip vs. Exclude UI Actions

• Skip: Deferring a claim moves it to the Skipped tab (with an Undo option), allowing it to be included in a future cycle.
  
  
  

• Exclude: Permanently excludes the claim and displays: "This claim was sent via API and cannot be sent back to payroll once excluded".

Blocker 4: Office Country Validation Scope

The API validates only payload-present fields. A separate office-country vs. payroll-center-country check is not performed because currency matching (TRANSFER_CLAIM_REPORT.UNMATCH_CURRENCY_BASE) inherently blocks cross-country mismatches.

 

Error Code & Troubleshooting Reference 

All business rule failures return HTTP 400 Bad Request with per-report details in metadata.errors

 

Code Examples & Response Payloads

Sample cURL Request

Bash
curl --location 'https://static.api.briohr.com/v2/api/external/claims/import' \
--header 'Authorization: Basic YWRtaW51c2VyOnBhc3N3b3JkMTIz' \
--header 'x-api-context-company: 627c63693329540009b1d0ff' \
--header 'x-resource-type: claim-import' \
--header 'Content-Type: application/json' \
--data '{
    "reports": [
        {
            "externalClaimReportId": "MESI-2026-07-001",
            "employeeEmail": "employee5active@yopmail.com",
            "reportName": "August Travel & Meal Claims",
            "currency": "MYR",
            "claims": [
                {
                    "externalClaimId": "MESI-2026-07-001-L1",
                    "payrollItem": "Expense Claims",
                    "claimableAmount": 120.50,
                    "taxAmount": 0,
                    "description": "Grab to client site",
                    "transactAt": "2026-07-15"
                },
                {
                    "externalClaimId": "MESI-2026-07-001-L2",
                    "payrollItem": "Expense Claims",
                    "claimableAmount": 45.00,
                    "taxAmount": 0,
                    "description": "Client lunch",
                    "transactAt": "2026-07-16"
                }
            ]
        }
    ]
}'


---

### Response Examples

#### 1. Success Response (`HTTP 201 Created`)

```json
[
    {
        "externalClaimReportId": "MESI-2026-07-001",
        "status": "parked"
    }
]


#### 2. Safe Retry Response (`HTTP 201 Created`)

```json
[
    {
        "externalClaimReportId": "MESI-2026-07-001",
        "status": "already-parked"
    }
]


#### 3. Schema Validation Error Response (`HTTP 400 Bad Request`)

```json
{
    "id": "0c2e7320-8a55-11f1-869b-15639df20a9d",
    "code": null,
    "type": "unhandled",
    "message": "Bad Request Exception",
    "metadata": [
        "0.currency must be one of the following values: MYR, SGD, EUR, USD, ...",
        "0.claims.0.claimableAmount must be a number with at most 2 decimal places",
        "0.claims.0.transactAt must be a valid ISO 8601 date string"
    ],
    "isBrioError": true
}


#### 4. Business Rule Error Response (`HTTP 400 Bad Request`)

```json
{
    "id": "ce3ff901-beb2-4130-ab9b-42bf78a19f95",
    "code": "U",
    "type": "user",
    "message": "",
    "metadata": {
        "errors": [
            {
                "resourceId": "MESI-2026-07-004",
                "resourceType": "claim-report",
                "error": [
                    {
                        "code": "CLAIM_IMPORT_API.EMPLOYEE_NOT_FOUND",
                        "variables": {
                            "metadata": {
                                "value": {
                                    "email": "nobody@nowhere.com"
                                },
                                "type": "object"
                            }
                        }
                    }
                ]
            },
            {
                "resourceId": "MESI-2026-07-005",
                "resourceType": "claim-report",
                "error": [
                    {
                        "code": "CLAIM_IMPORT_API.PAYROLL_ITEM_NOT_FOUND",
                        "variables": {
                            "metadata": {
                                "value": {
                                    "label": "Does Not Exist",
                                    "payrollCenterId": "627c636aed34fa000816bf84",
                                    "availableLabels": [
                                        "Expense Claims"
                                    ]
                                },
                                "type": "object"
                            }
                        }
                    }
                ]
            }
        ],
        "isSilent": true
    },
    "isBrioError": true
}


#### 5. Idempotency Conflict Error Response (`HTTP 400 Bad Request`)

```json
{
    "id": "2b6daa64-8cd9-48ff-99e5-ed0bca428430",
    "code": "CLAIM_IMPORT_API.CONFLICT",
    "type": "user",
    "message": "externalClaimReportId was already ingested with a different payload",
    "metadata": {
        "externalClaimReportId": "MESI-2026-07-002"
    },
    "isBrioError": true
}

 

Common Issues/FAQ

Q1: What should I do if an imported claim was excluded by mistake in brioHR Payroll?

Once a Payroll Officer excludes an imported claim in brioHR, it is permanently removed from processing and cannot be moved back to payroll. Re-pushing the request using the same externalClaimReportId will return an HTTP 201 status: already-parked response and will not recreate the claim in the queue. To resubmit an excluded claim, your system must send the request using a new, unique externalClaimReportId.

Q2: How can I find the correct payrollItem label to map claims? Is there an API endpoint to list them?

There is no separate endpoint for listing payroll items; issuing a GET request to /v2/api/external/payroll-items will return 404 Not Found. brioHR automatically tolerates minor variations in casing, leading/trailing whitespace, and singular/plural wording when matching labels. If an item label fails to match, the API returns an HTTP 400 error with the code CLAIM_IMPORT_API.PAYROLL_ITEM_NOT_FOUND, which includes an availableLabels array in the response metadata listing all valid reimbursement labels for that employee's Payroll Center.  

Q3: The API returned HTTP 201 status: parked, but the claim is not visible in the Claims to Payroll queue. Why?

Pushed claims only appear in the Claims to Payroll queue for a payroll cycle that covers the claimant employee. If a claim was successfully accepted by the API but does not appear in the brioHR web interface, verify that an active payroll cycle including that employee is currently running.

Q4: What happens to a claim item if it was 'added to payroll' then deleted (under the employee's pay item list)?

A4: The claim item will go back to the 'Validate payroll items'> Claims tab. You can choose to add it back to payroll, skip, or exclude the item.

 

Related Articles

Managing Approved Claims in the Payroll Module 

 

Ownership

By: Aqilah