canonical: https://jentic.com/apis/bilflo.com/bilflo

# Bilflo API

Jentic publishes the only available OpenAPI specification for Bilflo API, keeping it validated and agent-ready. Bilflo is a back-office platform for staffing and recruitment agencies, exposing endpoints for client records, contract jobs, client contacts, addresses, agreements, and configurable company settings such as workers' comp codes, payment terms, and pay-bill items. The API also covers dashboards and custom fields used to extend the underlying client and job model. Authentication is by bearer token, scoped to the agency's Bilflo tenant.

## For AI agents

Manage staffing-agency clients, contract jobs, contacts, addresses, and agreements in Bilflo, and read company-settings reference data and dashboards.

## Scope

Does not handle candidate sourcing, applicant tracking pipelines, or payroll disbursement - use for Bilflo agency client, contract job, and back-office configuration only.

## Capabilities

- List, create, and update agency clients via /v1/Clients
- Add client contacts, addresses, and agreements through dedicated POST endpoints
- Create and update contract jobs and terminate them with /v1/ContractJobs/terminate
- Read configured workers' comp codes, payment terms, and states from /v1/CompanySettings
- Enumerate pay-bill items used to price contract roles
- List custom field definitions and their available items via /v1/CustomFields
- Create and read agency dashboards through /dash/v1/Dashboards

## Use cases

### Onboard a New Staffing Client

Staffing agencies onboard a new client by creating the company record, adding the primary billing and worksite addresses, capturing the day-one contact, and recording the signed agreement. Bilflo exposes POST /v1/Clients, /v1/Clients/contact, /v1/Clients/address, and /v1/Clients/agreements as the four-step pipeline. Running this through the API removes manual rekeying when the agency captures clients via a CRM or a sales-form intake.

Example prompt: Call POST /v1/Clients, then POST /v1/Clients/contact, /v1/Clients/address, and /v1/Clients/agreements with the matching clientId

### Place and Terminate Contract Workers

Recruiters track placements as contract jobs in Bilflo - opening a job when a candidate starts, updating it for rate or extension changes, and terminating it when the contract ends. POST /v1/ContractJobs creates the job, PUT /v1/ContractJobs/{jobId} updates rates or end dates, and POST /v1/ContractJobs/terminate closes it cleanly so downstream pay-bill runs are accurate.

Example prompt: Call POST /v1/ContractJobs with clientId, candidate details and bill rate, then later POST /v1/ContractJobs/terminate with the jobId and termination date

### Reference Data for Onboarding Forms

Internal tools that build staffing onboarding forms need the agency's configured reference lists - workers' comp codes, payment terms, pay-bill items, and US states. Bilflo's /v1/CompanySettings endpoints expose each list so the form keeps in sync with the back-office configuration without hard-coding values. /v1/CustomFields and /v1/CustomFields/items pull custom-field definitions for any extended attributes.

Example prompt: Call GET /v1/CompanySettings/workersCompCodes, /v1/CompanySettings/paymentTerms, /v1/CompanySettings/payBillItems and merge into the onboarding form dropdowns

### Agent-Driven Staffing Operations via Jentic

An AI back-office agent connected through Jentic answers 'add Acme Corp as a new client and link John Smith as the primary contact' by chaining the Bilflo client and contact create operations. The bearer token sits in your Jentic One instance scoped to the agency tenant, so the agent never sees the raw secret and can repeat the workflow for every new client without bespoke glue code. Use cases extend to placement creation and termination flows.

Example prompt: Search Jentic for 'create a staffing client', load Bilflo POST /v1/Clients, execute, then load /v1/Clients/contact and execute with the returned clientId

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v1/Clients | List staffing clients |
| POST | /v1/Clients | Create a new client record |
| POST | /v1/Clients/contact | Add a contact to a client |
| POST | /v1/Clients/agreements | Add a client agreement |
| POST | /v1/ContractJobs | Create a contract job placement |
| POST | /v1/ContractJobs/terminate | Terminate an existing contract job |
| GET | /v1/CompanySettings/workersCompCodes | List workers' comp codes |
| GET | /v1/CompanySettings/payBillItems | List pay-bill items |

## Key resources

- **Clients** — Manage agency client records, contacts, addresses, and agreements
- **Contract Jobs** — Open, update, and terminate contract job placements
- **Company Settings** — Read agency configuration: workers' comp codes, payment terms, pay-bill items, and states
- **Custom Fields** — Enumerate custom field definitions and selectable items
- **Dashboards** — List and create dashboard configurations under /dash/v1/Dashboards

## Why Jentic

- **Setup:** Wiring the Bilflo API by hand means carrying a per-tenant bearer token on every call and building each client, contract-job, and company-settings path yourself. Through Jentic you install once, import Bilflo from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Bilflo addresses clients and contract jobs as collections and passes their identifiers in the request body rather than the path, so limit the agent to the operations it needs, such as creating a client or reading company settings. You choose that set, so terminating a contract job is not reachable unless you include it.
- **Credential handling:** Your Bilflo bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a staffing client' or 'terminate a contract job', and Jentic returns the matching Bilflo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bullhorn API** — Established staffing CRM and ATS with broad ecosystem coverage
- **Greenhouse Harvest API** — Hiring platform optimized for in-house recruiting and structured interviews
- **Lever API** — Talent acquisition suite with CRM-style nurture and pipeline management

## FAQ

### Why is there no official OpenAPI spec for Bilflo API?

Bilflo exposes its API surface via Swagger UI at api.bilflo.com/swagger but does not publish the underlying OpenAPI document for distribution. Jentic generates and maintains a structured OpenAPI specification so AI agents and developers can call Bilflo API via tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Bilflo API use?

Bilflo uses HTTP bearer authentication. The token is issued from the Bilflo platform and scoped to the agency tenant. Through Jentic, the token is held encrypted in the vault and attached to outbound calls so the raw secret never enters the agent's context.

### Can I create a contract job placement through the API?

Yes. POST /v1/ContractJobs accepts the client ID, role, candidate details, and bill/pay rates, returning the job ID. Update later with PUT /v1/ContractJobs/{jobId}, and close out with POST /v1/ContractJobs/terminate when the contract ends.

### What are the rate limits for the Bilflo API?

Bilflo does not publish rate limits in this OpenAPI spec - limits are enforced per agency plan. For high-volume reference-data syncs, cache the /v1/CompanySettings results, since workers' comp codes and pay-bill items change infrequently.

### How do I add a new client through Jentic?

Run `pip install jentic`, then `await client.search('create a staffing client')`, `await client.load(...)` for Bilflo POST /v1/Clients, and `await client.execute(...)` with the client name and details. Chain into /v1/Clients/contact and /v1/Clients/address for contacts and addresses.

### Are custom fields supported on clients and contract jobs?

Yes. GET /v1/CustomFields returns the agency's custom field definitions and GET /v1/CustomFields/items returns the selectable values for picklist-style fields. Use these to render dynamic forms or validate values before posting client and contract-job records.

### Can I limit what my agent is allowed to do with the Bilflo API?

Yes. Because Jentic One is self-hosted, you decide which Bilflo operations the agent may call, so you can allow it to create a client with POST /v1/Clients or read reference lists from /v1/CompanySettings while excluding everything else. Bilflo addresses clients and contract jobs as collections and passes their identifiers in the request body rather than the path, so you scope by the operation set you grant rather than by resource path. A destructive call like POST /v1/ContractJobs/terminate stays unreachable unless you explicitly include it, and your bearer token is attached at execution time under your own rules so the agent never sees the raw secret.