> ## 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. # Get Document By Id > **Beta.** The Documents API is in beta and its contract may change. Returns a Document object with the given id, including the parsed `data` object when `data_status` is `AVAILABLE`. This is the only endpoint that returns `data`; it is otherwise identical to the list response. export const IntegrationSupport = ({category = "HRIS", model, direction = "read"}) => { const SHEET_BASE = "https://docs.google.com/spreadsheets/d/e/2PACX-1vTx0G0yItXlZKO4Zep8wstZuvvO7bgOxFXBVK_1vvQnxpG8H2hP9n9M8kmZMfIoo7ZO4e7_utrz3_XB/pub"; const SHEET_GIDS = { HRIS: { read: "0", write: "1626747715" }, ATS: { read: "1962490874" }, LMS: { read: "1106223511" } }; const LOGO_ROW = "logo link"; const HEADER_ROW = "model"; const TYPE_ROW = "connection type"; const parseCsv = text => { const rows = []; let row = []; let field = ""; let quoted = false; for (let i = 0; i < text.length; i++) { const c = text[i]; if (quoted) { if (c === '"') { if (text[i + 1] === '"') { field += '"'; i++; } else { quoted = false; } } else { field += c; } } else if (c === '"') { quoted = true; } else if (c === ",") { row.push(field); field = ""; } else if (c === "\n" || c === "\r") { if (c === "\r" && text[i + 1] === "\n") i++; row.push(field); rows.push(row); row = []; field = ""; } else { field += c; } } if (field !== "" || row.length) { row.push(field); rows.push(row); } return rows; }; const cell = (row, i) => (row && row[i] || "").trim(); const parseSheet = (csv, wanted) => { const rows = parseCsv(csv); let header = null; let labelCol = -1; rows.slice(0, 12).forEach(r => { if (header) return; for (let i = 0; i < Math.min(r.length, 6); i++) { if (cell(r, i).toLowerCase() === HEADER_ROW) { header = r; labelCol = i; return; } } }); const find = label => rows.find(r => cell(r, labelCol).toLowerCase() === label); const types = header ? find(TYPE_ROW) : null; const logos = header ? find(LOGO_ROW) : null; if (!header || !types) return null; const providers = []; for (let i = labelCol + 1; i < header.length; i++) { const name = cell(header, i); const t = cell(types, i).toUpperCase(); if (!name || t !== "A" && t !== "S") continue; providers.push({ name, type: t === "S" ? "SFTP" : "API", col: i, uid: name + "#" + i, logo: cell(logos, i) }); } const target = String(wanted || "").toLowerCase(); const row = rows.find(r => cell(r, labelCol).toLowerCase() === target); if (!providers.length || !row) return null; const pool = providers; const supported = []; pool.forEach(p => { const v = cell(row, p.col).toUpperCase(); if (v === "Y" || v === "B") supported.push({ ...p }); }); if (!supported.length) return { none: true }; return { total: pool.length, supported }; }; const CSS = ` .bb-is { --bb-border: #e5e3df; --bb-border-strong: #d4d1cc; --bb-bg: #fcfcfb; --bb-bg-sub: #f5f4f3; --bb-text: #1c1b1a; --bb-text-dim: #6e6c68; --bb-accent: #f57e21; --bb-chip: #eceae7; font-size: 14px; color: var(--bb-text); border: 1px solid var(--bb-border); border-radius: 6px; background: var(--bb-bg); margin: 1.5rem 0; overflow: hidden; } html.dark .bb-is { --bb-border: #242424; --bb-border-strong: #333333; --bb-bg: #090909; --bb-bg-sub: #141414; --bb-text: #ededed; --bb-text-dim: #a1a1a1; --bb-chip: #1b1b1b; } .bb-is-head { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 8px; padding: 11px 14px; background: var(--bb-bg-sub); border-bottom: 1px solid var(--bb-border); } .bb-is-title { display: inline-flex; align-items: center; gap: 7px; font-weight: 600; font-size: 16px; } /* Mintlify's paints itself via a mask, so this makes it take the title's colour instead of staying its own. */ .bb-is-title .icon { background-color: currentColor !important; } .bb-is-count { font-size: 12px; color: var(--bb-text-dim); } .bb-is-chips { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; padding: 12px 14px; } /* Collapsed by default: one row of chips, the next row fading out under a gradient so it reads as "there is more" rather than as a hard crop. The wrapper does the clipping so the chips keep their own padding. */ .bb-is-chips-wrap { position: relative; } .bb-is-chips-wrap[data-open="false"] .bb-is-chips { max-height: 47px; overflow: hidden; } .bb-is-fade { position: absolute; left: 0; right: 0; bottom: 0; height: 28px; pointer-events: none; background: linear-gradient(to bottom, rgba(252, 252, 251, 0), var(--bb-bg)); } html.dark .bb-is-fade { background: linear-gradient(to bottom, rgba(9, 9, 9, 0), var(--bb-bg)); } .bb-is-toggle { display: inline-flex; align-items: center; gap: 5px; padding: 4px 10px; border: 1px solid var(--bb-border-strong); border-radius: 999px; background: var(--bb-bg); color: var(--bb-text-dim); font-size: 12.5px; font-weight: 500; line-height: 1.5; cursor: pointer; } .bb-is-toggle:hover { color: var(--bb-text); border-color: var(--bb-text-dim); } .bb-is-headright { display: inline-flex; align-items: center; gap: 10px; } .bb-is-chip { display: inline-flex; align-items: center; gap: 6px; padding: 4px 9px; border: 1px solid var(--bb-border); border-radius: 999px; background: var(--bb-bg-sub); font-size: 12.5px; line-height: 1.4; white-space: nowrap; } .bb-is-logo { width: 15px; height: 15px; object-fit: contain; border-radius: 3px; flex: none; } .bb-is-badge { font-size: 9.5px; font-weight: 600; letter-spacing: 0.03em; padding: 1px 5px; border-radius: 3px; background: var(--bb-chip); color: var(--bb-text-dim); } /* Muted on purpose - the provider name should catch the eye in this list, not its connection-type badge. --bb-chip sat too close to the chip's own --bb-bg-sub to read as a separate shape, so the fill is a step further from it in each theme - darker in light mode, and lighter (not literally "darker") in dark mode, since going darker there would fade it into the near-black page instead of separating it. */ .bb-is-badge[data-type="SFTP"] { color: var(--bb-text-dim); background: #ddd9d3; } html.dark .bb-is-badge[data-type="SFTP"] { background: #292929; } .bb-is-foot { padding: 9px 14px; border-top: 1px solid var(--bb-border); font-size: 14px; color: var(--bb-text-dim); } .bb-is-foot a { color: var(--bb-accent); text-decoration: none; } .bb-is-foot a:hover { text-decoration: underline; } .bb-is-none { padding: 16px 14px; font-size: 14px; line-height: 1.5; color: var(--bb-text-dim); } .bb-is-none a { color: var(--bb-accent); text-decoration: none; } .bb-is-none a:hover { text-decoration: underline; } .bb-is-loading { display: flex; align-items: center; justify-content: center; gap: 10px; padding: 28px 14px; font-size: 12.5px; color: var(--bb-text-dim); } .bb-is-spinner { width: 18px; height: 18px; border: 2px solid var(--bb-border); border-top-color: var(--bb-accent); border-radius: 50%; animation: bb-is-spin 0.7s linear infinite; flex: none; } @keyframes bb-is-spin { to { transform: rotate(360deg); } } /* Keep a motion cue for anyone who asked for less of it, just a calmer one. */ @media (prefers-reduced-motion: reduce) { .bb-is-spinner { animation-duration: 2.4s; } } `; const [data, setData] = useState(null); const [open, setOpen] = useState(false); useEffect(() => { let live = true; const tabs = SHEET_GIDS[category] || ({}); const gid = tabs[direction]; if (!gid) return; const url = SHEET_BASE + "?gid=" + encodeURIComponent(gid) + "&single=true&output=csv&_=" + Date.now(); fetch(url, { cache: "no-store" }).then(res => res.ok ? res.text() : Promise.reject(res.status)).then(text => { if (live) setData(parseSheet(text, model) || ({ hide: true })); }).catch(() => { if (live) setData({ hide: true }); }); return () => { live = false; }; }, [category, model, direction]); if (data && data.hide) return null; const none = !!(data && data.none); const verb = direction === "write" ? "writing" : "reading"; const mailto = "mailto:support@bindbee.dev?subject=" + encodeURIComponent("Integration request: " + verb + " " + model + " (" + category + ")"); const collapsible = !!(data && !none && data.supported.length > 4); return
Supported integrations {data && !none ? {data.supported.length} integration{data.supported.length === 1 ? "" : "s"} {collapsible ? : null} : null}
{!data ?
: none ?
No integration supports {verb} {model} yet.{" "} Tell us which one you need
:
{data.supported.map(p => {p.logo ? { e.currentTarget.style.display = "none"; }} /> : null} {p.name} {p.type === "SFTP" ? SFTP : null} )}
{collapsible && !open ? : null}
}
Coverage varies by integrations {" "} See the full availability matrix
; }; ## OpenAPI ````yaml get /api/hris/v1/documents/{id} openapi: 3.1.0 info: title: Bindbee APIs version: 0.1.0 servers: - url: https://api.bindbee.dev - url: https://api-eu.bindbee.dev security: [] paths: /api/hris/v1/documents/{id}: get: tags: - Documents summary: Get Document By Id description: >- **Beta.** The Documents API is in beta and its contract may change. Returns a Document object with the given id, including the parsed `data` object when `data_status` is `AVAILABLE`. This is the only endpoint that returns `data`; it is otherwise identical to the list response. operationId: get_document_by_id_api_hris_v1_documents__id__get parameters: - name: id in: path required: true schema: type: string format: uuid title: Id - name: include_raw_data in: query required: false schema: type: boolean description: >- Whether to include the original data Bindbee fetched from the third-party to produce these models. examples: - false default: false title: Include Raw Data description: >- Whether to include the original data Bindbee fetched from the third-party to produce these models. - name: include_custom_fields in: query required: false schema: type: boolean description: Whether to include custom fields in the response. examples: - false default: false title: Include Custom Fields description: Whether to include custom fields in the response. - name: expand in: query required: false schema: type: string description: >- Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. You can also specify required fields in [] for each relation name. examples: - manager[first_name,last_name] title: Expand description: >- Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. You can also specify required fields in [] for each relation name. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HrisDocument' '401': description: Missing or invalid bearer authentication credentials. headers: WWW-Authenticate: description: Bearer authentication challenge. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer X-RateLimit-Reset: description: >- Unix timestamp (seconds since epoch) at which the current rate-limit window resets. schema: type: integer Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] ConnectorToken: [] components: schemas: HrisDocument: properties: id: type: string format: uuid title: Id examples: - 018b18ef-c487-703c-afd9-0ca478ccd9d6 remote_id: anyOf: - type: string - type: 'null' title: Remote Id description: The third-party API ID of the matching object. examples: - '123321' modified_at: type: string title: Modified At description: This is the datetime that this object was last updated by Bindbee examples: - '2021-10-16T00:00:00Z' raw_data: anyOf: - additionalProperties: true type: object - type: 'null' title: Raw Data description: This is the Raw data examples: - key_1: Platform dependent data 1 key_2: Platform dependent data 2 custom_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Custom Fields description: The custom fields related to the model examples: - category_group: REG disability_type: ASBERG hire_date: '1991-03-16T00:00:00' hire_source: REFER nationality: USA original_hire_date: '1991-03-16T00:00:00' employee: anyOf: - {} - type: 'null' title: Employee description: >- The employee this document belongs to. This is the join key used to retrieve a single employee's documents. examples: - 018af1fe-1250-772d-87c5-6f725a579e8a type: anyOf: - type: string - type: 'null' enum: - W4 - I9 - OTHER - '-' title: Type description: >- The normalised document type, set from the provider's own category or, where that is missing, from content anchors in the file itself. If the value is not one of the defined enum values, the original value passed through will be returned. examples: - W4 remote_type: anyOf: - type: string - type: 'null' title: Remote Type description: >- The third-party's own document category, passed through verbatim. Use this when you need finer granularity than `type` provides. examples: - Tax Documents / Federal W-4 filename: anyOf: - type: string - type: 'null' title: Filename description: The name of the document file in the third-party system. examples: - Charlotte_Danielle_Abbott_W-4.pdf data_status: anyOf: - type: string - type: 'null' enum: - AVAILABLE - PENDING - UNSUPPORTED - FAILED title: Data Status description: >- Whether parsed field values are available for this document. `AVAILABLE`: use `data`. `PENDING`: extraction is still running, wait for the `document.data.available` webhook. `UNSUPPORTED`: Bindbee does not parse this document type, download the file instead. `FAILED`: extraction was attempted and did not succeed, download the file instead. Returned on both the list and the detail endpoint, so you can tell which documents are worth fetching in full without fetching any of them. examples: - AVAILABLE data: anyOf: - $ref: '#/components/schemas/HrisDocumentW4Data' - type: 'null' title: Data description: >- The parsed field values for this document, discriminated on `type`. Only returned by the Get Document By Id endpoint, and only when `data_status` is `AVAILABLE`; null in every other case. Only `W4` documents carry a schema today. is_deleted: anyOf: - type: boolean - type: 'null' title: Is Deleted description: >- Whether the document no longer exists in the third-party system. Deleted documents are tombstoned rather than removed, so incremental syncs can observe the deletion. examples: - false type: object required: - id - remote_id - modified_at - custom_fields - employee - type - remote_type - filename - data_status - is_deleted title: HrisDocument description: >- The Document object represents a file held in an HR or payroll system for an employee, together with the field values Bindbee parsed out of it where the document type follows a standard form. ErrorResponse: type: object required: - detail properties: detail: type: string HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError HrisDocumentW4Data: properties: source: anyOf: - type: string - type: 'null' enum: - FORM_FIELDS - OCR title: Source description: >- How the values were read. `FORM_FIELDS` means they were read deterministically off the PDF's form fields; `OCR` means they were inferred from a scan. Use this when a value feeds a withholding calculation and you need to know how much to trust it. examples: - FORM_FIELDS form_year: anyOf: - type: integer - type: 'null' title: Form Year description: The year printed on the form header. examples: - 2026 form_version: anyOf: - type: string - type: 'null' enum: - '2020' - PRE_2020 title: Form Version description: >- Which era of the W-4 this is. `2020` is the redesigned form; `PRE_2020` is the allowances-based form. Source systems return both through the same structure with no version flag, so Bindbee derives this from the signature date and the filled fields. examples: - '2020' effective_date: anyOf: - type: string - type: 'null' title: Effective Date description: The signature date from Step 5 of the form. examples: - '2026-01-15' filing_status: anyOf: - type: string - type: 'null' enum: - SINGLE_OR_MARRIED_FILING_SEPARATELY - MARRIED_FILING_JOINTLY - HEAD_OF_HOUSEHOLD - SINGLE - MARRIED - MARRIED_BUT_WITHHOLD_AT_HIGHER_SINGLE_RATE title: Filing Status description: >- The filing status from Step 1(c). The 2020 form uses `SINGLE_OR_MARRIED_FILING_SEPARATELY`, `MARRIED_FILING_JOINTLY` and `HEAD_OF_HOUSEHOLD`; the pre-2020 form uses `SINGLE`, `MARRIED` and `MARRIED_BUT_WITHHOLD_AT_HIGHER_SINGLE_RATE`. examples: - MARRIED_FILING_JOINTLY multiple_jobs: anyOf: - type: boolean - type: 'null' title: Multiple Jobs description: >- The Step 2(c) checkbox, set when the employee holds more than one job or is married filing jointly with a working spouse. Null on a pre-2020 form, which has no such box. examples: - false qualifying_children_amount: anyOf: - type: number - type: integer - type: 'null' title: Qualifying Children Amount description: >- Step 3(a), the credit claimed for qualifying children under 17. Null on a pre-2020 form. examples: - 2000 other_dependents_amount: anyOf: - type: number - type: integer - type: 'null' title: Other Dependents Amount description: >- Step 3(b), the credit claimed for other dependents. Null on a pre-2020 form. examples: - 500 dependents_total_amount: anyOf: - type: number - type: integer - type: 'null' title: Dependents Total Amount description: >- The Step 3 total. This is not always the sum of 3(a) and 3(b), since the line can include other credits, so all three values are returned separately. Null on a pre-2020 form. examples: - 2500 other_income: anyOf: - type: number - type: integer - type: 'null' title: Other Income description: Step 4(a), other income not from jobs. Null on a pre-2020 form. examples: - 0 deductions: anyOf: - type: number - type: integer - type: 'null' title: Deductions description: >- Step 4(b), deductions other than the standard deduction. Null on a pre-2020 form. examples: - 0 extra_withholding: anyOf: - type: number - type: integer - type: 'null' title: Extra Withholding description: >- Step 4(c), any additional tax the employee wants withheld each pay period. Present on both form versions. examples: - 50 is_exempt: anyOf: - type: boolean - type: 'null' title: Is Exempt description: >- Whether the employee claimed exemption from withholding. Present on both form versions. examples: - false allowances: anyOf: - type: integer - type: 'null' title: Allowances description: >- Line 5 of the pre-2020 form, the number of withholding allowances claimed. Null on a 2020 or later form, which removed allowances entirely. examples: - 2 type: object required: - source - form_year - form_version - effective_date - filing_status - multiple_jobs - qualifying_children_amount - other_dependents_amount - dependents_total_amount - other_income - deductions - extra_withholding - is_exempt - allowances title: HrisDocumentW4Data description: >- The parsed values of a Form W-4. Fields that belong to the other era's form are returned as null rather than zero: a zero is a claim the employee made, a null is a box that did not exist on the form they signed. Source systems commonly return zero for both, so this normalisation is Bindbee's. A blank Step 3 or Step 4 box on a filled 2020 or later form is an affirmative zero, not a null. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer x-default: description: >- Your Bindbee API key, sent as `Authorization: Bearer `. Required on every request. ConnectorToken: type: apiKey in: header name: X-Connector-Token x-default: description: >- The connector token for one customer's connection. This is not your Bindbee API key. Required on requests that read or write a single customer's data. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.