> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Time Off Request

> Submit a time off request into the customer's HRIS.

Submitting a leave request writes a real record into the customer's HRIS. What happens next is the platform's decision rather than yours: which leave types it accepts, whether a manager has to approve it, and whether the employee has the balance for it.

<Info>
  **Before you start**

  * You've confirmed the integration supports this write - see [Check write support](/guides/reading-writing/writing-data/meta-apis).
  * You have the Bindbee `id` of the employee the request is for.
</Info>

## Steps

<Steps>
  <Step title="Fetch the schema">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/time-off/meta/post' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>'
    ```

    Pay attention to the leave-type enum and to any required `integration_params`. Both vary by platform - see [Fetch a schema](/guides/reading-writing/writing-data/meta-apis).

    **Result:** The exact contract for this integration.
  </Step>

  <Step title="Resolve the employee">
    Use the Bindbee employee `id`, not the employee number or the source system's identifier. If you're starting from an upstream identifier, resolve it first with `remote_id` - see [Filtering](/guides/reading-writing/reading-data/filters).

    **Result:** A valid employee reference.
  </Step>

  <Step title="Send the request with an idempotency key">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.bindbee.dev/api/hris/v1/time-off' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
      --header 'X-Connector-Token: <CONNECTOR_TOKEN>' \
      --header 'X-Idempotency-Key: <UNIQUE_KEY>' \
      --header 'Content-Type: application/json' \
      --data '{
        "employee": "019f618e-c850-716d-a510-74639514abf6",
        "request_type": "VACATION",
        "start_time": "2026-09-01T00:00:00Z",
        "end_time": "2026-09-05T00:00:00Z",
        "units": "DAYS",
        "amount": 5
      }'
    ```

    Use field names and enum values from the schema rather than the example above.

    <Warning>
      Always send `X-Idempotency-Key`. A retried request without one creates a duplicate leave request that someone has to find and cancel by hand - see [Idempotency](/guides/reading-writing/writing-data/idempotency).
    </Warning>

    **Result:** The request is created in the source system.
  </Step>

  <Step title="Confirm it landed">
    Read it back rather than trusting the response alone - see [Get Time Off](/hris/time-off/get-time-off-list).

    The record won't appear in Bindbee's synced data until the next sync. To confirm sooner, [force a resync](/guides/reading-writing/syncing).

    A new request lands as `REQUESTED`, not approved. The source system runs its own workflow, and `status` moves to `APPROVED`, `DECLINED` or `CANCELLED` there rather than through Bindbee.

    **Result:** Verified in the customer's system.
  </Step>
</Steps>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="The leave type is rejected">
    Leave types are platform-specific, and a customer can define their own categories. Use a value from the schema's `enum`, and read `enumInformation` for what each means rather than matching on the name.

    If the customer's own category isn't in the enum, it may need supplying through `integration_params` or `additional_attributes`.
  </Accordion>

  <Accordion title="Dates are rejected or land wrong">
    Send ISO 8601 with an explicit timezone. Where a platform works in whole days, a timestamp with a time component can shift the request by a day across timezone boundaries - check whether the schema expects a date or a datetime.
  </Accordion>

  <Accordion title="The write succeeds but nothing appears in Bindbee">
    Expected until the next sync. Reads serve synced data, so a record created seconds ago won't be there yet.
  </Accordion>

  <Accordion title="You created duplicates during a retry">
    An idempotency key prevents this. To clean up, cancel the duplicates in the source system - Bindbee doesn't own the record once created.
  </Accordion>

  <Accordion title="The request exceeds the employee's balance">
    Balances belong to the source system. Bindbee submits the request and the platform enforces the balance, so an over-balance request is rejected upstream rather than by Bindbee.
  </Accordion>

  <Accordion title="The employee reference is rejected">
    Confirm you're sending the Bindbee `id`, and that the employee belongs to this connector. IDs are per connector, so an ID from another customer's connector won't resolve.
  </Accordion>
</AccordionGroup>

## Related

* [Time & attendance](/guides/data-models/time-and-attendance) - the time-off models and how they link
* [Meta APIs](/guides/reading-writing/writing-data/meta-apis) - fetching the write schema for an integration
* [Create Time Off](/hris/time-off/create-time-off) - the endpoint
* [Writing data](/guides/reading-writing/writing-data) - how a write reaches the source system