Passthrough

Passthrough forwards a raw HTTP request to the third-party system a connector is linked to and returns that system’s response untouched. It is the way out when the unified models do not carry what you need. Reach for it when an endpoint is not unified yet, when a vendor exposes an action of its own, for a one-off administrative call, or for a write with no unified equivalent.

In passthrough, you directly interact with the vendor API. Responses are not normalized, andpathis vendor-specific. Consult the vendor’s documentation.Use custom fields, if the value you want is already in raw_data.

Anatomy of a request

Every call is the same envelope: describe the request you want made upstream, and Bindbee makes it.

{
  "method": "GET",              // required: the upstream HTTP method
  "path": "/employees/123",     // required: vendor path, resolved against their base URL
  "headers": {},                // required: send {} if you have none
  "params": { "limit": 50 },    // optional: query string
  "data": null,                 // optional: request body
  "request_format": "JSON",     // optional: JSON | XML | MULTIPART
  "response_format": "JSON",    // optional: JSON | XML | MULTIPART | BINARY
  "timeout": 300                // optional: seconds to wait for the vendor
}

Authenticate as you would any Bindbee call: Authorization: Bearer <BINDBEE_API_KEY> plus the X-Connector-Token of the end user whose system you are calling. The connector token selects the target system and the customer whose credentials get used. Full schema and response codes are in the Passthrough Request.

A worked example

An end user is on BambooHR, and you need a field Bindbee does not model. The unified employee record does not carry it, and it is not in raw_data, so custom fields cannot reach it either. BambooHR exposes it on its own employee endpoint.

curl --request POST \
  --url https://api.bindbee.dev/api/v1/passthrough \
  --header 'Authorization: Bearer <BINDBEE_API_KEY>' \
  --header 'X-Connector-Token: <CONNECTOR_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "GET",
    "path": "/employees/3235005483341316245",
    "headers": {},
    "params": { "fields": "customBadgeNumber,customParkingSpot" }
  }'

const res = await fetch("https://api.bindbee.dev/api/v1/passthrough", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BINDBEE_API_KEY}`,
    "X-Connector-Token": connectorToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    method: "GET",
    path: `/employees/${remoteId}`,
    headers: {},
    params: { fields: "customBadgeNumber,customParkingSpot" },
  }),
});

const raw = await res.json();

raw = requests.post(
    "https://api.bindbee.dev/api/v1/passthrough",
    headers={
        "Authorization": f"Bearer {os.environ['BINDBEE_API_KEY']}",
        "X-Connector-Token": connector_token,
        "Content-Type": "application/json",
    },
    json={
        "method": "GET",
        "path": f"/employees/{remote_id}",
        "headers": {},
        "params": {"fields": "customBadgeNumber,customParkingSpot"},
    },
).json()

What comes back is BambooHR’s payload with no unified envelope around it:

Response

{
  "id": "3235005483341316245",
  "customBadgeNumber": "BD-4471",
  "customParkingSpot": "L2-18"
}

On a Workday connector, the same requirement would mean a different path, parameter style and response shape. The path uses remote_id, not Bindbee’s id - vendor APIs know nothing about Bindbee’s UUIDs. See id vs remote_id.

Variations

Change the envelope, not the approach. Each row below shows only what differs from the example above.

To do this	Set
Write	`"method": "POST"` with the vendor’s payload in `data`
Call a SOAP or XML endpoint	`"request_format": "XML"`, `"response_format": "XML"`, `data` as a string
Download a document or export	`"response_format": "BINARY"`
Upload a file	`"request_format": "MULTIPART"`

Write example

{
  "method": "POST",
  "path": "/time_off/requests",
  "headers": { "Content-Type": "application/json" },
  "data": {
    "employeeId": "3235005483341316245",
    "start": "2026-08-10",
    "end": "2026-08-14"
  }
}

Before building a write here, check whether it is supported natively. Meta APIs return the exact schema a connector expects for Create Employee, Create Employee Payroll Run, Create Timesheet, Create Time Off and Create Candidate.

SOAP example

{
  "method": "POST",
  "path": "/soap/EmployeeService",
  "headers": { "SOAPAction": "getEmployees" },
  "data": "<soapenv:Envelope>...</soapenv:Envelope>",
  "request_format": "XML",
  "response_format": "XML",
  "timeout": 120
}

Older enterprise HR platforms often speak XML rather than JSON.

Response

A 200 returns the third party’s response as is, parsed according to response_format. The shape is entirely the vendor’s, down to their own pagination.

A 200 confirms Bindbee reached the vendor. Many APIs return 200 alongside an error object in the body, so read the payload to confirm the call did what you wanted.

Make Passthrough Request

POST /api/v1/passthrough. Full schema, parameters and response codes.

Authentication

API keys and connector tokens.

Rate limits

Limits, headers and retry behavior.

Custom fields

Surface extra upstream values on the unified model instead.

Reading & Writing Data

Extending the Model

SDK & MCP

Data Models

Workspace & Access

Going Live

Troubleshooting

Anatomy of a request

A worked example

Variations

Response

Make Passthrough Request

Authentication

Rate limits

Custom fields

​Anatomy of a request

​A worked example

​Variations

​Response

​Related

Make Passthrough Request

Authentication

Rate limits

Custom fields

Anatomy of a request

A worked example

Variations

Response

Related