Clients

Manage employer clients the same way as Dashboard → Clients → Create client. Use client_id on jobs when recruiting for a client (see Jobs API).

List query parameters (GET)

GET /api/v1/clients
Field	Type	Required	Description
search	string	No	Name, email, or contact person
status	"active" \| "inactive"	No	Filter by status
industry	string	No	Filter by industry
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Client object
Field	Type	Required	Description
name	string	POST	Client / company name (max 255 chars)
email	string \| null	No	Contact email
phone	string \| null	No	Phone number (max 50 chars)
address	string \| null	No	Street address (multiline)
contact_person	string \| null	No	Primary contact name
website	string \| null	No	Company website URL
industry	string \| null	No	e.g. Technology, Healthcare
status	"active" \| "inactive"	No	Default active
tags	string[]	No	Labels for categorization
notes	string \| null	No	Free-text notes
metadata	object	No	Custom key-value JSON (e.g. external_id from CRM)

Response body

Client resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Client id
name	string	—	Client / company name (max 255 chars)
email	string \| null	—	Contact email
phone	string \| null	—	Phone number (max 50 chars)
address	string \| null	—	Street address (multiline)
contact_person	string \| null	—	Primary contact name
website	string \| null	—	Company website URL
industry	string \| null	—	e.g. Technology, Healthcare
status	"active" \| "inactive"	—	Default active
tags	string[]	—	Labels for categorization
notes	string \| null	—	Free-text notes
metadata	object	—	Custom key-value JSON (e.g. external_id from CRM)
jobs_count	integer	—	Total jobs linked to this client
active_jobs_count	integer	—	Jobs with status active
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Last updated timestamp

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

GET/api/v1/clients

List clients.

GET/api/v1/clients/{id}

Get one client.

POST/api/v1/clients

Create a client. Returns 201.

Example

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+91 98765 43210",
  "address": "123 Business Park, Bangalore",
  "contact_person": "Jane Smith",
  "website": "https://acme.com",
  "industry": "Technology",
  "status": "active",
  "tags": ["enterprise", "priority"],
  "notes": "Primary staffing client",
  "metadata": { "external_id": "CRM-10042" }
}

PUT/api/v1/clients/{id}

Partial update.

Clients

Manage employer clients the same way as Dashboard → Clients → Create client. Use client_id on jobs when recruiting for a client (see Jobs API).

List query parameters (GET)

GET /api/v1/clients
Field	Type	Required	Description
search	string	No	Name, email, or contact person
status	"active" \| "inactive"	No	Filter by status
industry	string	No	Filter by industry
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Client object
Field	Type	Required	Description
name	string	POST	Client / company name (max 255 chars)
email	string \| null	No	Contact email
phone	string \| null	No	Phone number (max 50 chars)
address	string \| null	No	Street address (multiline)
contact_person	string \| null	No	Primary contact name
website	string \| null	No	Company website URL
industry	string \| null	No	e.g. Technology, Healthcare
status	"active" \| "inactive"	No	Default active
tags	string[]	No	Labels for categorization
notes	string \| null	No	Free-text notes
metadata	object	No	Custom key-value JSON (e.g. external_id from CRM)

Response body

Client resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Client id
name	string	—	Client / company name (max 255 chars)
email	string \| null	—	Contact email
phone	string \| null	—	Phone number (max 50 chars)
address	string \| null	—	Street address (multiline)
contact_person	string \| null	—	Primary contact name
website	string \| null	—	Company website URL
industry	string \| null	—	e.g. Technology, Healthcare
status	"active" \| "inactive"	—	Default active
tags	string[]	—	Labels for categorization
notes	string \| null	—	Free-text notes
metadata	object	—	Custom key-value JSON (e.g. external_id from CRM)
jobs_count	integer	—	Total jobs linked to this client
active_jobs_count	integer	—	Jobs with status active
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Last updated timestamp

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

GET/api/v1/clients

List clients.

GET/api/v1/clients/{id}

Get one client.

POST/api/v1/clients

Create a client. Returns 201.

Example

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+91 98765 43210",
  "address": "123 Business Park, Bangalore",
  "contact_person": "Jane Smith",
  "website": "https://acme.com",
  "industry": "Technology",
  "status": "active",
  "tags": ["enterprise", "priority"],
  "notes": "Primary staffing client",
  "metadata": { "external_id": "CRM-10042" }
}

PUT/api/v1/clients/{id}

Partial update.

Clients

Manage employer clients the same way as Dashboard → Clients → Create client. Use client_id on jobs when recruiting for a client (see Jobs API).

List query parameters (GET)

GET /api/v1/clients
Field	Type	Required	Description
search	string	No	Name, email, or contact person
status	"active" \| "inactive"	No	Filter by status
industry	string	No	Filter by industry
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Client object
Field	Type	Required	Description
name	string	POST	Client / company name (max 255 chars)
email	string \| null	No	Contact email
phone	string \| null	No	Phone number (max 50 chars)
address	string \| null	No	Street address (multiline)
contact_person	string \| null	No	Primary contact name
website	string \| null	No	Company website URL
industry	string \| null	No	e.g. Technology, Healthcare
status	"active" \| "inactive"	No	Default active
tags	string[]	No	Labels for categorization
notes	string \| null	No	Free-text notes
metadata	object	No	Custom key-value JSON (e.g. external_id from CRM)

Response body

Client resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Client id
name	string	—	Client / company name (max 255 chars)
email	string \| null	—	Contact email
phone	string \| null	—	Phone number (max 50 chars)
address	string \| null	—	Street address (multiline)
contact_person	string \| null	—	Primary contact name
website	string \| null	—	Company website URL
industry	string \| null	—	e.g. Technology, Healthcare
status	"active" \| "inactive"	—	Default active
tags	string[]	—	Labels for categorization
notes	string \| null	—	Free-text notes
metadata	object	—	Custom key-value JSON (e.g. external_id from CRM)
jobs_count	integer	—	Total jobs linked to this client
active_jobs_count	integer	—	Jobs with status active
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Last updated timestamp

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

GET/api/v1/clients

List clients.

GET/api/v1/clients/{id}

Get one client.

POST/api/v1/clients

Create a client. Returns 201.

Example

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+91 98765 43210",
  "address": "123 Business Park, Bangalore",
  "contact_person": "Jane Smith",
  "website": "https://acme.com",
  "industry": "Technology",
  "status": "active",
  "tags": ["enterprise", "priority"],
  "notes": "Primary staffing client",
  "metadata": { "external_id": "CRM-10042" }
}

PUT/api/v1/clients/{id}

Partial update.