Incorrect Type Definition: Payment.id should be 'str', not 'Optional[str]' in the response

[NandoSangenetto]

Description

I encountered a type mismatch between the Finch Python SDK and the official Finch API documentation regarding the payment.id field.

Currently, the SDK defines payment.id as str | None (Optional). However, the Official API Documentation for Payroll Payment specifies that the id field is a unique UUID and is strictly required (it does not indicate it can be null or undefined).

references

• Documentation: Finch API Reference - Payment Response
• SDK Location: finch.types.payroll.Payment (or relevant model location)

Current Behavior

When using strict type checking (e.g., Mypy or Pyright), accessing payment.id triggers a warning that the value could be None.

# Example of unnecessary boilerplate currently required
if payment.id:
    process_payment(payment.id) # Mypy is happy
else:
    # Dead code path that theoretically shouldn't exist
    raise ValueError("Payment ID is missing")

Expected Behavior

The id field on the Payment object for the response should be typed as str (required). This aligns with the API contract and removes the need for unnecessary null checks in consumer code.

[NandoSangenetto]

This appears to be an issue with the Payment model, not just limited to the id field.

I noticed that all properties in the Payment object are currently typed as Optional in the SDK, despite the documentation explicitly marking several of them as required.

Discrepancy Examples:

• pay_period: Docs say Required -> SDK types as Optional
• debit_date: Docs say Required -> SDK types as Optional
• company_debit: Docs say Required -> SDK types as Optional
• gross_pay: Docs say Required -> SDK types as Optional
• and so on.

Most, if not all, properties will be returned as their type or null. The most important property is the id.

Impact:
This forces consumers to write defensive code (null checks) for every single field, even when the API guarantees a value. It suggests that the underlying API definition used to generate this SDK might be missing validation for the required fields.

[NandoSangenetto]

These are the types expected during response:

class PaymentResponse:
    id: str
    company_debit: Money | None
    debit_date: str | None
    employee_taxes: Money | None
    employer_taxes: Money | None
    gross_pay: Money | None
    individual_ids: List[str] | None
    net_pay: Money | None
    pay_date: str | None
    pay_frequencies: (
        List[
            Literal[
                "annually",
                "semi_annually",
                "quarterly",
                "monthly",
                "semi_monthly",
                "bi_weekly",
                "weekly",
                "daily",
                "other",
            ]
        ]
        | None
    )
    pay_group_ids: List[str] | None
    pay_period: PayPeriod | None

[jordanbrauer]

hey @NandoSangenetto , thanks for the report. we're looking into it !

[dtmeadows]

Hey @NandoSangenetto happy to help on this one! I'm not actually seeing the issue you're describing in the SDK though. The Payment type does have this id as required here:

finch-api-python/src/finch/types/hris/payment.py

Lines 18 to 21 in 7a8046b

	class Payment(BaseModel):
	id: str
	"""The unique id for the payment."""

When I write out a simple integration using this I don't run into a problem either:

from finch import Finch

client = Finch(
    access_token="My Access Token",
)

async def main() -> None:
    for payment in client.hris.payments.list(start_date="2023-01-01", end_date="2023-12-31"):
        print(payment.id)

asyncio.run(main())

Are you looking at a different type in the SDK? If so, mind linking to it?

[NandoSangenetto]

@dtmeadows, we've updated the SDK to the latest version yesterday. It could be a problem in a previous version.

[karpetrosyan]

Hey! The id property was None because the OpenAPI schema from which we generate the SDK contained a non-required id field at some point, and was fixed by this commit. Other fields you mentioned (pay_period, debit_date, etc.) are nullable because they are explicitly mentioned as nullable in the schema. I assume it's just an OpenAPI schema issue. cc @jordanbrauer