{"openapi":"3.1.0","info":{"title":"Deel (BYOK) API","version":"0.1.0","description":"Deel (BYOK) lets an AI assistant read your own Deel data through the Deel API with a key you supply (Deel API token (organization token with read scopes)). Read-only: 12 tools (get_organization, list_contracts, get_contract, list_people, get_person, list_teams, list_departments, list_legal_entities, list_invoices, list_time_off_requests, list_timesheets, list_managers). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-deel.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-deel/docs"},"termsOfService":"https://connectorbay.com/byok-deel/terms"},"servers":[{"url":"https://byok-deel.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-deel/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_organization":{"post":{"operationId":"get_organization","summary":"Show the Deel organization the token belongs to: id and name. Use for \"Which Deel organization is this token connected t","description":"Show the Deel organization the token belongs to: id and name. Use for \"Which Deel organization is this token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organizationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_contracts":{"post":{"operationId":"list_contracts","summary":"List contract summaries with title, type, status, worker, client entity, dates and archive flag; filter by status, type,","description":"List contract summaries with title, type, status, worker, client entity, dates and archive flag; filter by status, type, country, currency or a name search. Needs the contracts:read scope. Use for \"Which contracts are in progress right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["new","under_review","waiting_for_employee_contract","waiting_for_client_sign","processing_payment","waiting_for_contractor_sign","waiting_for_eor_sign","waiting_for_employee_sign","awaiting_deposit_payment","in_progress","completed","cancelled","user_cancelled","rejected","waiting_for_client_payment","onboarding","onboarded"],"type":"string"},{"type":"null"}],"default":null,"description":"Contract status filter, for example in_progress, waiting_for_client_sign, completed or cancelled.","title":"Status"},"type":{"anyOf":[{"enum":["ongoing_time_based","milestones","time_based","pay_as_you_go_time_based","commission","payg_milestones","payg_tasks","eor","peo","employee","global_payroll","hris_direct_employee","contractor_outside_deel"],"type":"string"},{"type":"null"}],"default":null,"description":"Contract type filter, for example ongoing_time_based, milestones, eor or global_payroll.","title":"Type"},"country":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Only contracts in this country (ISO code such as US or GB).","title":"Country"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Only contracts paid in this currency (ISO code such as USD).","title":"Currency"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only contracts whose name or worker name contains this text.","title":"Search"},"team_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only contracts of this team id.","title":"Team Id"},"legal_entity_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only contracts of this legal entity id.","title":"Legal Entity Id"},"sort_by":{"anyOf":[{"enum":["contract_title","worker_name"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field.","title":"Sort By"},"order_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order.","title":"Order Direction"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 100).","title":"Limit"},"after_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from page.cursor of the previous answer to get the next page.","title":"After Cursor"}},"title":"list_contractsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_contract":{"post":{"operationId":"get_contract","summary":"Get one contract by id with title, type, status, worker, client, dates, job title, scope of work, notice period and comp","description":"Get one contract by id with title, type, status, worker, client, dates, job title, scope of work, notice period and compensation details. Needs the contracts:read scope. Use for \"Show the details and pay terms of contract 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contract_id":{"description":"Deel contract id.","maxLength":200,"title":"Contract Id","type":"string"},"expand":{"anyOf":[{"enum":["cost_centers","custom_fields"],"type":"string"},{"type":"null"}],"default":null,"description":"Optionally embed more data.","title":"Expand"}},"required":["contract_id"],"title":"get_contractArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_people":{"post":{"operationId":"list_people","summary":"List people with name, job title, hiring type and status, country, start date, department, manager, legal entity and rep","description":"List people with name, job title, hiring type and status, country, start date, department, manager, legal entity and report count; search by name or filter by hiring status and type. Needs the people:read scope. Use for \"Who joined the company in the last quarter and what are their roles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only people whose name contains this text.","title":"Search"},"hiring_status":{"anyOf":[{"enum":["pending_invite","draft","invited","onboarding","onboarding_at_risk","onboarding_overdue","onboarded","offboarding","active","inactive","in_review","quote_requires_changes"],"type":"string"},{"type":"null"}],"default":null,"description":"Only people with this hiring status.","title":"Hiring Status"},"hiring_type":{"anyOf":[{"enum":["contractor","eor","peo","hris_direct_employee","hris_direct_contractor","direct_employee","contractor_outside_deel","person_without_contract"],"type":"string"},{"type":"null"}],"default":null,"description":"Only people hired this way.","title":"Hiring Type"},"sort_by":{"anyOf":[{"enum":["first_name","last_name","full_name","country","hiring_type","start_date","team","job_title","hiring_status"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order.","title":"Sort Order"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Offset"}},"title":"list_peopleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_person":{"post":{"operationId":"get_person","summary":"Get one person by their Deel profile id with name, job title, hiring type and status, country, start date, department, m","description":"Get one person by their Deel profile id with name, job title, hiring type and status, country, start date, department, manager, legal entity and report count. Needs the people:read scope. Use for \"Show the profile of person 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile_id":{"description":"Deel person (HRIS profile) id.","maxLength":200,"title":"Profile Id","type":"string"}},"required":["profile_id"],"title":"get_personArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List the teams of the organization with id and name. Use for \"What teams do we have in Deel\".","description":"List the teams of the organization with id and name. Use for \"What teams do we have in Deel\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_departments":{"post":{"operationId":"list_departments","summary":"List the departments of the organization with id, name and parent. Use for \"What departments do we have in Deel\".","description":"List the departments of the organization with id, name and parent. Use for \"What departments do we have in Deel\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_departmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_legal_entities":{"post":{"operationId":"list_legal_entities","summary":"List legal entities with name, status, type, country, tax id, registration number and industry; filter by country or typ","description":"List legal entities with name, status, type, country, tax id, registration number and industry; filter by country or type. Needs the organizations:read and accounting:read scopes. Use for \"Which legal entities do we have and where\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities in this country.","title":"Country"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities of this type.","title":"Type"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include archived legal entities.","title":"Include Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from page.cursor of the previous answer to get the next page.","title":"Cursor"}},"title":"list_legal_entitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices issued to the organization with label, status, totals, VAT, Deel fee, dates and contract id; filter by iss","description":"List invoices issued to the organization with label, status, totals, VAT, Deel fee, dates and contract id; filter by issue date. Set status to all to include unpaid ones, otherwise only paid invoices come back. Needs the accounting:read scope. Use for \"Which invoices were issued last month and are any overdue\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"const":"all","type":"string"},{"type":"null"}],"default":null,"description":"Set to all to include unpaid invoices; leave empty for paid invoices only.","title":"Status"},"issued_from_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or after this date (YYYY-MM-DD).","title":"Issued From Date"},"issued_to_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued before this date (YYYY-MM-DD).","title":"Issued To Date"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from page.cursor of the previous answer to get the next page.","title":"Cursor"}},"title":"list_invoicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_time_off_requests":{"post":{"operationId":"list_time_off_requests","summary":"List time-off requests across the organization with status, dates, amount, reason, contract and policy type; filter by s","description":"List time-off requests across the organization with status, dates, amount, reason, contract and policy type; filter by status or date range. Needs the time-off:read scope. Use for \"Who has approved time off next month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["REQUESTED","APPROVED","REJECTED","USED","CANCELED","DELETED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only requests in this status.","title":"Status"},"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only requests starting on or after this date (YYYY-MM-DD).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only requests ending on or before this date (YYYY-MM-DD).","title":"End Date"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 50).","title":"Page Size"},"next":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from next of the previous answer to get the next page.","title":"Next"}},"title":"list_time_off_requestsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_timesheets":{"post":{"operationId":"list_timesheets","summary":"List timesheet entries with contract, hours or quantity, amount, status, submitter and payment cycle; filter by contract","description":"List timesheet entries with contract, hours or quantity, amount, status, submitter and payment cycle; filter by contract, status or submission dates. Needs the timesheets:read scope. Use for \"Which timesheets are still pending approval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contract_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only timesheets of this contract id.","title":"Contract Id"},"status":{"anyOf":[{"enum":["approved","declined","not_payable","paid","pending","processing"],"type":"string"},{"type":"null"}],"default":null,"description":"Only timesheets in this status.","title":"Status"},"date_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only timesheets submitted on or after this date (YYYY-MM-DD).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only timesheets submitted before this date (YYYY-MM-DD).","title":"Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Offset"}},"title":"list_timesheetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_managers":{"post":{"operationId":"list_managers","summary":"List managers with name and email. Use for \"Who are the managers in Deel\".","description":"List managers with name and email. Use for \"Who are the managers in Deel\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip, for paging (0 for the first page).","title":"Offset"}},"title":"list_managersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}