Company Management API
The Company Management API allows you to manage companies in your TaskIP CRM system. You can create, read, update, search, and delete companies, as well as perform bulk deletes.
Resource IDs: The {id} segment of the company routes only accepts digits. A non-numeric segment (for example /company/tags) is a 404.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/company | Get all companies |
POST | /api/public-v1/company | Create a new company |
GET | /api/public-v1/company/{id} | Get a specific company |
PUT / PATCH | /api/public-v1/company/{id} | Update a company |
DELETE | /api/public-v1/company/{id} | Delete a company |
POST | /api/public-v1/company/bulk-delete | Delete multiple companies |
GET | /api/public-v1/company-search | Search companies by name |
GET | /api/public-v1/company-tag | List company tags |
POST | /api/public-v1/company-tag | Create a company tag |
Get All Companies
Retrieve a paginated list of all companies in your system.
GET /api/public-v1/companyRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination (default: 1) |
item | integer | No | Companies per page (default: 10). Use 0 to return all companies without pagination |
search | string | No | Search by company name, email, or phone number |
industry_id | integer or array | No | Filter by industry ID(s), e.g. industry_id[]=2&industry_id[]=5 |
industry_is_empty | boolean | No | When true, only companies without an industry are returned (overrides industry_id) |
number_of_employees_operator | string | No | Employee-count comparison: equals, gt, gte, lt, lte, or between. Used together with number_of_employees_value |
number_of_employees_value | integer | No | Value to compare against |
number_of_employees_value2 | integer | No | Upper bound when the operator is between |
number_of_employees_is_empty | boolean | No | When true, only companies without an employee count are returned (overrides the operator filter) |
Results are ordered by id descending.
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/company?page=1&item=20&search=acme" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"JavaScript Example
const response = await fetch('https://public-api.taskip.net/api/public-v1/company?page=1&item=20', {
method: 'GET',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
});
const companies = await response.json();Example Response
{
"message": "Company list",
"data": [
{
"id": 1,
"name": "Acme Corporation",
"email": "info@acme.com",
"phone_number": "+1-555-0100",
"website": "https://www.acme.com",
"c_size": 3,
"c_type": 5,
"size": "51-200 employees",
"type": "Technology",
"number_of_employees": 120,
"industry_id": 4,
"industry": "Software",
"country_id": 1,
"city_id": 10,
"state_id": 5,
"country": "United States",
"state": "New York",
"city": "New York City",
"address": "123 Business Street, New York, NY 10001",
"zip_code": "10001",
"vat_id": null,
"description": null,
"created_at": "2024-01-10T09:30:00.000000Z",
"image": null,
"tags": [
{ "id": 3, "name": "Partner", "color": "#22c55e" }
],
"custom_fields": [],
"company_members": [],
"deals_count": 2,
"invoices_count": 5,
"clients": [
{
"id": 12,
"user_id": 40,
"company_id": 1,
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"email": "john.doe@acme.com",
"position": "CTO",
"phone_number": "555-0123",
"details": null,
"reference": null,
"access_portal": 0,
"image": null
}
]
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/company?page=1",
"last": "https://public-api.taskip.net/api/public-v1/company?page=3",
"prev": null,
"next": "https://public-api.taskip.net/api/public-v1/company?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https://public-api.taskip.net/api/public-v1/company",
"per_page": 20,
"to": 20,
"total": 45
}
}When search is supplied, meta.search echoes the search term. When item=0, the response contains only message and data.
Create a Company
Create a new company in your system.
POST /api/public-v1/companyRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Company name (max 191 characters) |
email | string | Yes | Company email. Must not already belong to a user, another company, or a lead (unless your workspace allows duplicate company emails) |
phone_number | string | No | Company phone number |
website | string | No | Company website, must be a valid URL such as https://example.com (max 191 characters) |
c_size | integer | No | Company size ID (numeric) |
c_type | integer | No | Company type ID (numeric) |
number_of_employees | integer | No | Number of employees (min 0) |
industry_id | integer | No | Industry ID |
country_id | integer | No | Country ID |
state_id | integer | No | State/Province ID |
city_id | integer | No | City ID |
address | string | No | Company address |
zip_code | string | No | ZIP/postal code (max 20 characters) |
vat_id | string | No | VAT ID (max 100 characters) |
tags | array of integers | No | Tag IDs to put on the company, from Company Tags. An ID that does not exist is a 422 and nothing is saved |
company_members | array | No | Array of user IDs (each must exist in users) |
custom_fields | array | No | Custom field data. Required custom fields defined in your workspace are enforced |
description | string | No | Free-text description |
Persisted fields: Create and update store name, email, phone_number, website, c_size, c_type, number_of_employees, industry_id, country_id, state_id, city_id, address, zip_code, vat_id, description, tags, company_members and custom_fields. When tags, company_members or custom_fields is empty or left out, the company keeps what it already has.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/company" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"name": "Green Energy Solutions",
"email": "contact@greenenergy.com",
"phone_number": "+1-555-0102",
"website": "https://www.greenenergy.com",
"c_size": 4,
"c_type": 12,
"country_id": 1,
"state_id": 15,
"city_id": 120,
"address": "789 Sustainability Blvd, Austin, TX 78701",
"tags": [12]
}'Python Example
import requests
headers = {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
company_data = {
"name": "Green Energy Solutions",
"email": "contact@greenenergy.com",
"phone_number": "+1-555-0102",
"website": "https://www.greenenergy.com",
"c_size": 4,
"c_type": 12,
"country_id": 1,
"state_id": 15,
"city_id": 120,
"address": "789 Sustainability Blvd, Austin, TX 78701"
}
response = requests.post(
'https://public-api.taskip.net/api/public-v1/company',
headers=headers,
json=company_data
)
result = response.json()Example Response
The response status is 201 Created.
{
"msg": "Company Created",
"data": {
"id": 46,
"name": "Green Energy Solutions",
"email": "contact@greenenergy.com",
"phone_number": "+1-555-0102",
"website": "https://www.greenenergy.com",
"c_size": 4,
"c_type": 12,
"size": "201-500 employees",
"type": "Renewable Energy",
"number_of_employees": null,
"industry_id": null,
"industry": null,
"country_id": 1,
"city_id": 120,
"state_id": 15,
"country": "United States",
"state": "Texas",
"city": "Austin",
"address": "789 Sustainability Blvd, Austin, TX 78701",
"zip_code": null,
"vat_id": null,
"description": null,
"created_at": "2024-01-25T10:30:00.000000Z",
"image": null,
"tags": [],
"custom_fields": [],
"company_members": [],
"deals_count": 0,
"invoices_count": 0,
"clients": []
}
}Get a Specific Company
Retrieve details of a specific company by ID.
GET /api/public-v1/company/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Company ID (digits only) |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/company/46" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"message": "Company detail",
"data": {
"id": 46,
"name": "Green Energy Solutions",
"email": "contact@greenenergy.com",
"phone_number": "+1-555-0102",
"website": "https://www.greenenergy.com",
"c_size": 4,
"c_type": 12,
"size": "201-500 employees",
"type": "Renewable Energy",
"number_of_employees": null,
"industry_id": null,
"industry": null,
"country_id": 1,
"city_id": 120,
"state_id": 15,
"country": "United States",
"state": "Texas",
"city": "Austin",
"address": "789 Sustainability Blvd, Austin, TX 78701",
"zip_code": null,
"vat_id": null,
"description": null,
"created_at": "2024-01-25T10:30:00.000000Z",
"image": {
"id": 205,
"title": "green-energy-logo.png",
"ext": "png",
"size": 20480,
"url": "https://cdn.taskip.net/companies/green-energy-logo.png",
"media_type": "company",
"createdAt": "25-01-2024 10:30:00"
},
"tags": [],
"custom_fields": [],
"company_members": [],
"deals_count": 0,
"invoices_count": 0,
"clients": []
}
}If the company does not exist the API returns 404 with {"message": "Company not found"}.
Update a Company
Update an existing company’s information.
PUT /api/public-v1/company/{id}
PATCH /api/public-v1/company/{id}PUT and PATCH are handled identically and share the same validation rules as create. The company in the URL is the one updated; no new company is created.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Company ID to update (digits only) |
Request Body
Same fields as Create a Company. name and email are required on every update, even with PATCH. A company can keep its own current email.
tags replaces the company’s tags with the IDs you send. To add a tag without touching the others, send the full list including the existing ones. Leaving tags out, or sending an empty list, keeps the current tags. Additionally:
| Field | Type | Required | Description |
|---|---|---|---|
image | integer | No | Media upload ID. Replaces the company’s current image |
Example Request
curl -X PUT "https://public-api.taskip.net/api/public-v1/company/46" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"name": "Green Energy Solutions Updated",
"email": "info@greenenergy.com",
"phone_number": "+1-555-0103",
"c_size": 5,
"address": "789 Sustainability Blvd, Suite 200, Austin, TX 78701"
}'Example Response
The response status is 202 Accepted.
{
"msg": "Company update success"
}Delete a Company
Delete a specific company from your system.
DELETE /api/public-v1/company/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Company ID to delete (digits only) |
Warning: Deleting a company also removes its image. This action cannot be undone.
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/company/46" \
-H "X-Secret-Key: your-secret-key-here"Example Response
The response status is 204 No Content and the body is empty. A company that does not exist returns 404.
Bulk Delete Companies
Delete multiple companies at once.
POST /api/public-v1/company/bulk-deleteRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array | Yes | Array of company IDs to delete (1 to 1000 items) |
ids.* | integer | Yes | Each ID must be an integer that exists in the companies table |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/company/bulk-delete" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"ids": [44, 45, 47, 48]
}'JavaScript Example
const bulkDeleteData = {
ids: [44, 45, 47, 48]
};
const response = await fetch('https://public-api.taskip.net/api/public-v1/company/bulk-delete', {
method: 'POST',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify(bulkDeleteData)
});
const result = await response.json();Example Response
The response status is 202 Accepted.
{
"msg": "companies deleted."
}Search Companies
Search companies by name. Returns every company whose name contains the search term.
GET /api/public-v1/company-searchQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
search | string | No | Text to match against the company name (partial match). When omitted, all companies are returned |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/company-search?search=acme" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
This endpoint is not paginated and returns the raw company records (not the Company Object).
{
"msg": "Company list found",
"data": [
{
"id": 1,
"name": "Acme Corporation",
"email": "info@acme.com",
"phone_number": "+1-555-0100",
"website": "https://www.acme.com",
"c_size": 3,
"c_type": 5,
"country_id": 1,
"city_id": 10,
"state_id": 5,
"address": "123 Business Street, New York, NY 10001",
"created_at": "2024-01-10T09:30:00.000000Z",
"updated_at": "2024-01-10T09:30:00.000000Z"
}
]
}Company Tags
A tag is a coloured label such as Company, Individual or Trust. Companies take tags by ID, so create each tag once, keep its ID, and send that ID in tags when you create or update companies. Tags created here are always company tags, whatever type you send.
List Company Tags
GET /api/public-v1/company-tag| Parameter | Type | Required | Description |
|---|---|---|---|
search | string | No | Search tags by name |
item | integer | No | Tags per page |
page | integer | No | Page number |
curl -X GET "https://public-api.taskip.net/api/public-v1/company-tag?search=trust" \
-H "X-Secret-Key: your-secret-key-here"{
"data": [
{ "id": 12, "name": "Trust", "color": "#336699", "type": "company" }
],
"links": { "first": "...", "last": "...", "prev": null, "next": null },
"meta": { "current_page": 1, "per_page": 10, "total": 1 }
}Create a Company Tag
POST /api/public-v1/company-tag| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tag name (max 191 characters) |
color | string | Yes | Tag colour, for example #336699 (max 50 characters) |
curl -X POST "https://public-api.taskip.net/api/public-v1/company-tag" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Trust", "color": "#336699" }'The response status is 201 Created.
{
"msg": "Tag created",
"data": { "id": 12, "name": "Trust", "color": "#336699", "type": "company" }
}Tag IDs can be large. Keep them as 64-bit integers (or strings) in your own code, and send the IDs exactly as the API returned them.
Unknown tag IDs
If any ID in tags does not exist, the request is refused with 422 and no company is created or changed:
{
"error": {
"tags.0": ["The selected tags.0 is invalid."]
}
}Tag companies when you import them
GET /company-tag?search=Trustand, if it is not there,POST /company-tag. Store the ID forCompany,IndividualandTrust.POST /companywith"tags": [<id>]for each new company.- For a company that already exists,
PUT /company/{id}with the tag intags. Send every tag the company should have, since the list replaces the current one.
Error Responses
Common Error Codes
| Status Code | Error Type | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing X-Secret-Key |
404 | Not Found | Company not found, or a non-numeric ID in the path |
422 | Validation Error | Request data failed validation |
429 | Too Many Requests | Rate limit exceeded |
Example Error Response
Validation failures return 422 with the failing fields under error:
{
"error": {
"name": ["The name field is required."],
"email": ["The email field must be a valid email address."],
"website": ["Website must be a valid URL (example: https://example.com)."]
}
}Response Schemas
Company Object
{
"id": "integer",
"name": "string",
"email": "string",
"phone_number": "string|null",
"website": "string|null",
"c_size": "integer|null",
"c_type": "integer|null",
"size": "string|null",
"type": "string|null",
"number_of_employees": "integer|null",
"industry_id": "integer|null",
"industry": "string|null",
"country_id": "integer|null",
"city_id": "integer|null",
"state_id": "integer|null",
"country": "string|null",
"state": "string|null",
"city": "string|null",
"address": "string|null",
"zip_code": "string|null",
"vat_id": "string|null",
"description": "string|null",
"created_at": "string (ISO 8601)",
"image": "object|null",
"tags": "array of {id, name, color}",
"custom_fields": "array|object",
"company_members": "array",
"deals_count": "integer",
"invoices_count": "integer",
"clients": "array"
}Image Object
{
"id": "integer",
"title": "string",
"ext": "string",
"size": "integer",
"url": "string|null",
"media_type": "string",
"createdAt": "string (d-m-Y h:i:s)"
}Best Practices
Company Creation
- Use consistent naming: Keep company names consistent across your CRM
- Use unique emails: Company emails are checked against users, other companies and leads
- Industry categorization: Use standardized industry IDs for better filtering
- Complete profiles: Add as much company information as possible for better CRM insights
Data Management
- Regular updates: Keep company information current
- Bulk operations: Use bulk delete for efficient data management
- Search optimization: Use descriptive names for better searchability with
company-search
Tip: Use the industry_id and number_of_employees_* filters in the GET /company endpoint to segment your companies. This is particularly useful for targeted marketing campaigns or industry-specific reporting.