# {tenant_name} Platform API — AI Agent Documentation
# https://llmstxt.org/

> {tenant_name} is a staffing platform OS that connects jobseekers with clients (employers) through shifts, orders, timesheets, invoices, and payroll.

## Quick Start

- Base URL: https://{host_name}/api/v2
- Authentication: POST `/sessions` with `{ email, password }` → receive Bearer token
- All requests require: `Authorization: Bearer {token}`
- API Key (no expiry): create via POST `/authentication/api_keys`
- Interactive Reference: https://{host_name}/api/reference

## Response Format

All responses follow this structure:

```json
{
  "status": 200,
  "data": { ... },
  "message": "Success"
}
```

Error responses:

```json
{
  "success": false,
  "errors": ["Validation message"],
  "status": 422
}
```

## Pagination

List endpoints accept:
- `page` — page number (default: 1)
- `per_page` — items per page (default: 10, max: 100)

Response meta:

```json
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 123,
    "per_page": 10
  }
}
```

## Error Codes

- 401: Missing or invalid Bearer token
- 403: Insufficient permissions for this action
- 404: Resource not found
- 422: Validation failed (check `errors` array)
- 429: Rate limit exceeded

## Users & Roles

- **Jobseeker (Freelancer)**: Workers who apply to and work shifts
- **Client (Company)**: Employers who post orders and hire workers
- **Sub-User**: Delegated company users with scoped permissions
- **Admin**: Platform administrators with full access

Role determines which endpoints are accessible and what data is returned by serializers.

## Entity Relationships

```
Company (Client)
  ├── Sub-Users (delegated users)
  ├── Rate Cards (pricing tiers)
  ├── Proposals (quotes)
  └── Orders (Campaigns)
        └── Shifts (date/time slots)
              └── Tenders / ShiftApplications (worker applications)
                    └── Timesheets (clock in/out records)
                          └── Accounting Journal Entries
                                ├── Invoices (billed to client)
                                └── Payouts (paid to worker)

Jobseeker (Freelancer)
  ├── Education (academic history)
  ├── Experience (work history)
  │     └── References
  ├── Credentials (certifications/documents)
  ├── Skill Assessments (test results)
  ├── Availability Blocks (when available)
  ├── Bank Details (payment info)
  └── Tenders / ShiftApplications (applied/assigned shifts)
```

---

## API Endpoints by Domain

### Getting Started

#### Authentication
- POST `/sessions` — Login with email/password, receive JWT token
- DELETE `/sessions` — Logout / invalidate token
- POST `/sign_in` — Alternative sign-in endpoint
- POST `/sign_out` — Alternative sign-out endpoint
- POST `/sign_up` — Create a new user account
- POST `/registrations` — User registration
- POST `/request_otp` — Request one-time password
- POST `/request_one_time_password` — Request OTP (alternative)
- POST `/reset_password` — Reset user password
- POST `/email_verification` — Verify email address
- GET `/authentication/api_keys` — List API keys
- POST `/authentication/api_keys` — Create an API key (no expiry)
- DELETE `/authentication/api_keys/{id}` — Revoke an API key

#### Platform
- GET `/status` — Platform health check
- GET `/status/summary` — Detailed platform status summary
- GET `/test/health` — Health check endpoint
- GET `/components` — List platform components

---

### Talent — Front Office

Resources for managing the jobseeker lifecycle: onboarding, profile, credentials, assessments, and job discovery.

#### Onboarding
- GET `/custom_packets` — List onboarding packets
- POST `/custom_packets` — Create an onboarding packet
- GET `/custom_packets/{id}` — Get onboarding packet details
- PUT `/custom_packets/{id}` — Update an onboarding packet
- GET `/packet_assignments` — List packet assignments for jobseekers
- POST `/packet_assignments` — Assign a packet to a jobseeker
- PUT `/packet_assignments/{packet_id}` — Update packet assignment
- PUT `/jobseekers_onboarding` — Update jobseeker onboarding status
- PUT `/jobseekers/update_onboarding_fields` — Update onboarding field values

#### Jobseeker Profile
- GET `/jobseekers` — List jobseekers (admin/client filtered)
- POST `/jobseekers` — Create a new jobseeker
- GET `/jobseekers/{id}` — Get jobseeker profile
- PUT `/jobseekers/{id}` — Update jobseeker profile
- DELETE `/jobseekers/{id}` — Deactivate jobseeker
- PUT `/jobseekers/{id}/revive` — Reactivate a deactivated jobseeker
- PUT `/jobseekers_revive` — Reactivate jobseeker (alternative)
- GET `/jobseekers_npi` — Verify jobseeker NPI number
- GET `/job_seeker/specific_data` — Get jobseeker-specific data
- GET `/job_seeker/subscriptions_status` — Get subscription status

#### Education & Experience
- GET `/freelancers/{id}/educations` — List education records
- POST `/freelancers/{id}/educations` — Add education record
- GET `/freelancers/{id}/educations/{id}` — Get education detail
- PUT `/freelancers/{id}/educations/{id}` — Update education record
- DELETE `/freelancers/{id}/educations/{id}` — Delete education record
- GET `/freelancers/{id}/experiences` — List work experiences
- POST `/freelancers/{id}/experiences` — Add work experience
- GET `/freelancers/{id}/experiences/{id}` — Get experience detail
- PUT `/freelancers/{id}/experiences/{id}` — Update work experience
- DELETE `/freelancers/{id}/experiences/{id}` — Delete work experience

#### Credentials
- GET `/credentials` — List all credentials (admin view)
- GET `/credentials/compliance_report_index` — Compliance report for jobseekers
- POST `/freelancers/{id}/credentials` — Upload a credential
- PUT `/freelancers/{id}/credentials` — Update credential
- GET `/freelancers/{id}/credentials/{id}` — Get credential detail
- DELETE `/freelancers/{id}/credentials/{id}` — Delete credential
- PUT `/freelancers/{id}/credentials/change_status` — Approve/reject credential

#### Skill Assessments
- GET `/skill_assessments` — List skill assessments
- POST `/skill_assessments` — Create a skill assessment
- PUT `/skill_assessments/{id}` — Update skill assessment
- POST `/skill_assessments/allocate` — Allocate assessment to jobseeker
- GET `/skill_assessments/allocations` — List allocations
- GET `/skill_assessments/allocation_questions` — Get allocation questions
- GET `/skill_assessments/questions` — List assessment questions
- POST `/skill_assessments/create_update_question` — Create/update question
- POST `/skill_assessments/save_freelancer_responses` — Submit responses

#### References
- GET `/references` — List references
- GET `/references/{experience_id}` — Get reference for experience
- POST `/references/{experience_id}` — Add/manage reference

#### Availability
- GET `/availability_blocks` — List availability blocks
- POST `/availability_blocks` — Create availability block
- GET `/availability_blocks/{id}` — Get availability block
- PUT `/availability_blocks/{id}` — Update availability block
- GET `/availability_autos` — List automatic availability rules
- POST `/availability_autos` — Create auto-availability rule
- GET `/availability_autos/{id}` — Get auto-availability rule
- PUT `/availability_autos/{id}` — Update auto-availability rule

#### Opportunities
- GET `/opportunities` — List available shifts for jobseekers
- GET `/opportunities/{id}` — Get opportunity details
- GET `/opportunities/client_list` — List opportunities by client

#### Applications (Tenders)
- GET `/shift_applications` — List shift applications
- GET `/jobseekers/{id}/shift_applications` — Jobseeker's applications
- POST `/jobseekers/{id}/shift_applications` — Apply to a shift
- PUT `/jobseekers/{id}/shift_applications` — Update application status
- GET `/tenders` — List tenders (admin/client view)
- POST `/tenders` — Create a tender
- GET `/tenders/{shift_id}/{freelancer_id}` — Get specific tender
- PUT `/tenders/{shift_id}/{freelancer_id}` — Update tender (assign/decline)
- GET `/long_order_applications` — List long-term order applications
- POST `/long_order_applications` — Manage order application
- GET `/long_order_applications/{order_id}` — List by order
- GET `/long_order_applications/{order_id}/{jobseeker_id}` — Get specific

---

### Talent — Middle Office

Resources for time tracking, scheduling, and supplemental payments during active assignments.

#### Timesheets
- GET `/timesheets/index` — List timesheets
- GET `/timesheets/show/{shift_id}` — Get timesheet by shift
- GET `/timesheets/show_by_id/{id}` — Get timesheet by ID
- POST `/timesheets/{shift_id}/check_in` — Clock in (with lat/lng)
- POST `/timesheets/{shift_id}/check_out` — Clock out (with lat/lng)
- POST `/timesheets/{shift_id}/start_break` — Start break
- POST `/timesheets/{shift_id}/end_break` — End break
- PUT `/timesheets/{shift_id}/update` — Update timesheet
- PUT `/timesheets/{shift_id}/update_v2` — Update timesheet (v2)
- POST `/timesheets/{shift_id}/feedback_message` — Add feedback
- GET `/timesheets/{shift_id}/preview` — Preview timesheet changes
- PUT `/timesheets/{freelancer_id}/bulk_update` — Bulk update timesheets

#### Supplemental Items
- GET `/analytics/obtain_extra_payments` — List supplemental items
- POST `/analytics/create_update_extra_payment` — Create/update item
- DELETE `/analytics/remove_extra_payment` — Remove item
- PUT `/analytics/change_status_supplemental_payment` — Change status
- POST `/analytics/create_update_category_extra_payment` — Manage categories
- GET `/analytics_extra_payments` — List extra payments (legacy)
- POST `/analytics_create_extra_payment` — Create extra payment (legacy)
- POST `/analytics_create_category_extra_payment` — Create category (legacy)
- DELETE `/analytics_remove_extra_payment` — Remove payment (legacy)
- PUT `/analytics_change_status` — Change status (legacy)

#### Schedules
- GET `/schedules` — List schedules
- POST `/schedules/create_or_update` — Create or update schedule
- GET `/schedules/list_by_client` — List schedules by client
- POST `/schedules/create_category` — Create schedule category
- GET `/schedules/show_category` — Get schedule category
- PUT `/schedules/update_category` — Update schedule category
- GET `/schedules/contract_schedule` — Get contract schedule
- POST `/schedules/ai_create` — AI-assisted schedule creation
- GET `/schedules/ai_list` — List AI-generated schedules

---

### Finance & Billing

Resources for invoicing, payouts, accounting journals, and financial configuration.

#### Invoices
- GET `/invoices` — List invoices
- GET `/invoices/{id}` — Get invoice details
- POST `/invoices/{id}/charge` — Charge an invoice
- GET `/invoices/{id}/groups` — Get invoice line item groups
- DELETE `/invoices/{id}/line_items/{acj_id}` — Remove line item
- PUT `/invoices/{id}/set_payment_method` — Set payment method
- POST `/invoices/{id}/undo_finalized` — Revert finalized invoice

#### Accounting Journals
- GET `/accounting_journals` — List journal entries
- POST `/accounting_journals` — Create journal entry
- GET `/accounting_journals/{id}` — Get journal entry
- PUT `/accounting_journals/{id}` — Update journal entry

#### Bills
- GET `/bills` — List bills/payment records

#### Payouts
- POST `/payouts/unified_timesheets` — Process payout for timesheets

#### Bank Details
- GET `/bank_details` — Get bank details
- POST `/bank_details` — Add bank details
- PUT `/bank_details` — Update bank details
- DELETE `/bank_details` — Remove bank details
- GET `/bank_details/bank_connection_links` — Get bank connection links
- GET `/jobseekers/{id}/bank_details` — Get jobseeker bank details
- POST `/jobseekers/{id}/bank_details` — Add jobseeker bank details
- PUT `/jobseekers/{id}/bank_details` — Update jobseeker bank details
- DELETE `/jobseekers/{id}/bank_details` — Delete jobseeker bank details
- DELETE `/job_seeker/delete_bank_account` — Admin delete bank account

#### Financial Configuration
- GET `/alternative_work_schedules` — List alternative work schedules
- POST `/alternative_work_schedules` — Create work schedule
- GET `/alternative_work_schedules/{id}` — Get work schedule
- PUT `/alternative_work_schedules/{id}` — Update work schedule
- DELETE `/alternative_work_schedules/{id}` — Delete work schedule
- GET `/entries/{id}` — Get/update rate card entry

---

### Client Acquisition

Resources for managing clients, sub-users, proposals, rate cards, contracts, and CRM pipelines.

#### Companies
- GET `/companies` — List companies
- POST `/companies` — Create a company
- GET `/companies/{id}` — Get company details
- PUT `/companies/{id}` — Update company

#### Sub-Users
- GET `/sub_users` — List sub-users
- POST `/sub_users/{company_id}` — Create sub-user for company
- GET `/sub_users/{company_id}/{id}` — Get sub-user details
- PUT `/sub_users/{company_id}/{id}` — Update sub-user
- GET `/sub_users/{id}/accounts` — Get sub-user account details

#### Proposals
- GET `/proposals` — List proposals
- GET `/proposal/{proposal_uid}` — Get proposal by UID
- GET `/proposal_preview/{campaign_ids}` — Preview proposal
- POST `/proposal/approve_shifts` — Approve proposal shifts
- POST `/proposal/submit_force_proposal` — Force submit proposal
- PUT `/proposal/update` — Update proposal
- POST `/proposals/{company_id}/bulk_update` — Bulk update proposals
- POST `/proposals/add_to_proposal` — Add order to proposal
- DELETE `/proposals/remove_order` — Remove order from proposal
- GET `/proposals/retrieve_proposal_relations_info` — Get proposal relations

#### Rate Cards
- GET `/rate_cards/{id}` — Get rate card details
- PUT `/entries/{id}` — Update rate card entry

#### Contracts
- GET `/contracts` — List contracts
- GET `/contracts/{order_id}` — List contracts by order
- GET `/contracts/{order_id}/{jobseeker_id}` — Get specific contract
- PUT `/contracts/{order_id}/{jobseeker_id}` — Update contract

#### Assignments
- GET `/assignments` — List assignments
- PUT `/assignments/{id}` — Update assignment
- POST `/assignments/set_draft_rates` — Set draft rates for assignment

#### Pipelines (CRM/ATS)
- GET `/pipelines` — List pipelines
- POST `/pipelines` — Create pipeline
- PUT `/pipelines/{id}` — Update pipeline
- DELETE `/pipelines/{id}` — Delete pipeline
- GET `/pipelines/stages` — List all stages
- POST `/pipelines/stages` — Create stage
- PUT `/pipelines/stages/{id}` — Update stage
- DELETE `/pipelines/stages/{id}` — Delete stage
- GET `/pipelines/{id}/kanban/cards` — List kanban cards
- POST `/pipelines/{id}/kanban/cards` — Create kanban card
- PUT `/pipelines/{id}/kanban/cards/{object_id}` — Move/update card
- GET `/pipeline_stages` — List order pipeline stages

---

### Demand Generation

Resources for creating and managing job orders, shifts, and candidate outreach.

#### Orders
- GET `/orders` — List orders/campaigns
- POST `/orders` — Create an order
- GET `/orders/{id}` — Get order details
- PUT `/orders/{id}` — Update an order
- DELETE `/orders/{id}` — Cancel/delete an order

#### Shifts
- GET `/shifts` — List shifts
- POST `/shifts` — Create shifts for an order
- GET `/shifts/{id}` — Get shift details
- PUT `/shifts/{id}` — Update shift
- DELETE `/shifts/{id}` — Cancel shift

#### Outreach
- GET `/outreach` — List outreach campaigns
- POST `/outreach` — Create outreach to jobseekers
- DELETE `/outreach` — Delete outreach
- GET `/outreach/{order_id}/{jobseeker_id}` — Get outreach for specific match
- POST `/outreach/expedite` — Expedite outreach delivery
- PUT `/outreach/manage_status` — Update outreach status
- GET `/outreach/preview` — Preview outreach message
- POST `/outreach/resend` — Resend outreach

---

### Platform & Configuration

Resources for tenant configuration, taxonomy, custom forms, webhooks, and administration.

#### Configuration
- GET `/client_configs` — Get tenant configuration
- GET `/client_configs/{id}` — Get specific config
- POST `/analytics_system_config` — Update system configuration

#### Job Types & Pricing
- GET `/job_types` — List job types
- POST `/job_types` — Create job type
- GET `/job_types/{id}` — Get job type details
- PUT `/job_types/{id}` — Update job type
- GET `/pricings` — List pricing configurations
- GET `/pricings/{id}` — Get pricing details
- GET `/custom_pricings` — List custom pricings
- POST `/custom_pricings` — Create custom pricing
- GET `/custom_pricings/{id}` — Get custom pricing
- PUT `/custom_pricings/{id}` — Update custom pricing
- DELETE `/custom_pricings/{id}` — Delete custom pricing

#### Taxonomy
- GET `/taxonomy/competencies` — List competencies
- GET `/taxonomy/job_types` — List job type taxonomy
- GET `/taxonomy/job_types/{job_type}/{id}` — Get taxonomy entry
- GET `/competencies` — List competencies
- POST `/competencies` — Create competency
- GET `/competencies/{id}` — Get competency
- PUT `/competencies_key` — Update competency key

#### Markets & Geography
- GET `/core/markets` — List markets/regions
- POST `/core/markets` — Create market
- PUT `/core/markets/{id}` — Update market
- DELETE `/core/markets/{id}` — Delete market
- GET `/countries` — List countries
- GET `/cities` — List cities
- GET `/geo_level_ones` — List regions/states

#### Custom Forms
- GET `/custom_forms` — List custom forms
- POST `/custom_forms` — Create custom form
- GET `/custom_forms/{id}` — Get custom form
- PUT `/custom_forms/{id}` — Update custom form

#### Custom Requirements
- GET `/custom_requirements` — List custom field definitions
- POST `/custom_requirements` — Create custom requirement
- GET `/custom_requirements_show` — Get custom requirement
- PUT `/custom_requirements_update` — Update custom requirement
- PATCH `/custom_requirements_update` — Patch custom requirement
- GET `/custom_values` — List custom field values
- POST `/custom_values` — Set custom value
- GET `/custom_values/{id}` — Get custom value
- PUT `/custom_values/{id}` — Update custom value
- POST `/custom_values/bulk_reset` — Bulk reset custom values

#### Certificate Requests
- GET `/certificate_requests` — List credential requirement templates
- POST `/certificate_requests` — Create certificate request
- GET `/certificate_requests/{id}` — Get certificate request
- PUT `/certificate_requests/{id}` — Update certificate request
- DELETE `/certificate_requests/{id}` — Delete certificate request

#### Documents (E-Signature)
- POST `/documents/callbacks` — Document signing callback
- GET `/documents/fetch_edit_url_template` — Get template edit URL
- POST `/documents/request_template` — Request document template
- POST `/documents/save_to_aws` — Save document to storage
- PUT `/documents/update_template_files` — Update template files

#### Webhooks
- GET `/event_subscriptions` — List webhook subscriptions
- POST `/event_subscriptions` — Create webhook subscription
- DELETE `/event_subscriptions/{id}/unsubscribe` — Delete subscription

Webhook events include:
- `shift.created`, `shift.updated`, `shift.cancelled`
- `tender.applied`, `tender.assigned`, `tender.completed`
- `timesheet.submitted`, `timesheet.approved`
- `invoice.created`, `invoice.finalized`
- `jobseeker.created`, `jobseeker.updated`

#### Notifications
- GET `/notifications` — List user notifications

#### Users & Admin
- PUT `/users/{id}/re_active` — Reactivate user account
- GET `/audit_logs` — List audit log entries

#### Business Intelligence
- GET `/bi_data_fulfillment_summary` — Fulfillment summary report

---

## Common Workflows

### 1. Authenticate and Explore

```
POST /sessions { email: "user@example.com", password: "..." }
→ { token: "eyJ..." }

GET /opportunities  (jobseeker: discover available work)
GET /orders          (client/admin: see job orders)
```

### 2. Create an Order with Shifts

```
POST /orders {
  company_id: 123,
  pricing_id: 1,
  title: "Weekend Event Staff",
  description: "...",
  shifts_attributes: [
    { date: "2026-04-01", start_time: "09:00", end_time: "17:00", slots: 5 }
  ]
}
```

### 3. Hire a Worker

```
GET /orders/{id}                     → order details
GET /shifts?order_id={id}            → shifts for the order
GET /tenders?shift_id={id}           → applicants for shift
PUT /tenders/{shift_id}/{js_id}      → { status: "assigned" }
```

### 4. Worker Clock In/Out

```
POST /timesheets/{shift_id}/check_in   { latitude: 37.77, longitude: -122.41 }
POST /timesheets/{shift_id}/start_break
POST /timesheets/{shift_id}/end_break
POST /timesheets/{shift_id}/check_out  { latitude: 37.77, longitude: -122.41 }
```

### 5. Check Compliance

```
GET /freelancers/{id}/credentials
GET /credentials/compliance_report_index?jobseeker_ids[]={id}
```

### 6. Invoice and Pay

```
GET /invoices?company_id={id}
GET /invoices/{id}
POST /invoices/{id}/charge
GET /payouts/unified_timesheets
```

---

## Status Values

### Tender (ShiftApplication)
- `pending` — Applied, awaiting decision
- `assigned` — Hired for the shift
- `declined` — Rejected by client
- `cancelled` — Application withdrawn
- `completed` — Shift finished
- `no_show` — Worker did not attend

### Timesheet
- `pending` — Awaiting approval
- `approved` — Hours confirmed
- `disputed` — Hours contested
- `paid` — Payment processed

### Credential
- `pending` — Awaiting review
- `approved` — Verified
- `rejected` — Not accepted
- `expired` — Past expiration date

### Invoice
- `draft` — Being prepared
- `finalized` — Ready for payment
- `paid` — Payment received

---

## Full Documentation

- Interactive API Reference: https://{host_name}/api/reference