Skip to Content
Company Management API

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

MethodEndpointDescription
GET/api/public-v1/companyGet all companies
POST/api/public-v1/companyCreate 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-deleteDelete multiple companies
GET/api/public-v1/company-searchSearch companies by name
GET/api/public-v1/company-tagList company tags
POST/api/public-v1/company-tagCreate a company tag

Get All Companies

Retrieve a paginated list of all companies in your system.

GET /api/public-v1/company

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination (default: 1)
itemintegerNoCompanies per page (default: 10). Use 0 to return all companies without pagination
searchstringNoSearch by company name, email, or phone number
industry_idinteger or arrayNoFilter by industry ID(s), e.g. industry_id[]=2&industry_id[]=5
industry_is_emptybooleanNoWhen true, only companies without an industry are returned (overrides industry_id)
number_of_employees_operatorstringNoEmployee-count comparison: equals, gt, gte, lt, lte, or between. Used together with number_of_employees_value
number_of_employees_valueintegerNoValue to compare against
number_of_employees_value2integerNoUpper bound when the operator is between
number_of_employees_is_emptybooleanNoWhen 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/company

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Request Body

FieldTypeRequiredDescription
namestringYesCompany name (max 191 characters)
emailstringYesCompany email. Must not already belong to a user, another company, or a lead (unless your workspace allows duplicate company emails)
phone_numberstringNoCompany phone number
websitestringNoCompany website, must be a valid URL such as https://example.com (max 191 characters)
c_sizeintegerNoCompany size ID (numeric)
c_typeintegerNoCompany type ID (numeric)
number_of_employeesintegerNoNumber of employees (min 0)
industry_idintegerNoIndustry ID
country_idintegerNoCountry ID
state_idintegerNoState/Province ID
city_idintegerNoCity ID
addressstringNoCompany address
zip_codestringNoZIP/postal code (max 20 characters)
vat_idstringNoVAT ID (max 100 characters)
tagsarray of integersNoTag IDs to put on the company, from Company Tags. An ID that does not exist is a 422 and nothing is saved
company_membersarrayNoArray of user IDs (each must exist in users)
custom_fieldsarrayNoCustom field data. Required custom fields defined in your workspace are enforced
descriptionstringNoFree-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

ParameterTypeRequiredDescription
idintegerYesCompany 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

ParameterTypeRequiredDescription
idintegerYesCompany 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:

FieldTypeRequiredDescription
imageintegerNoMedia 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

ParameterTypeRequiredDescription
idintegerYesCompany 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-delete

Request Body

FieldTypeRequiredDescription
idsarrayYesArray of company IDs to delete (1 to 1000 items)
ids.*integerYesEach 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-search

Query Parameters

ParameterTypeRequiredDescription
searchstringNoText 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
ParameterTypeRequiredDescription
searchstringNoSearch tags by name
itemintegerNoTags per page
pageintegerNoPage 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
FieldTypeRequiredDescription
namestringYesTag name (max 191 characters)
colorstringYesTag 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

  1. GET /company-tag?search=Trust and, if it is not there, POST /company-tag. Store the ID for Company, Individual and Trust.
  2. POST /company with "tags": [<id>] for each new company.
  3. For a company that already exists, PUT /company/{id} with the tag in tags. Send every tag the company should have, since the list replaces the current one.

Error Responses

Common Error Codes

Status CodeError TypeDescription
401UnauthorizedInvalid or missing X-Secret-Key
404Not FoundCompany not found, or a non-numeric ID in the path
422Validation ErrorRequest data failed validation
429Too Many RequestsRate 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

  1. Use consistent naming: Keep company names consistent across your CRM
  2. Use unique emails: Company emails are checked against users, other companies and leads
  3. Industry categorization: Use standardized industry IDs for better filtering
  4. Complete profiles: Add as much company information as possible for better CRM insights

Data Management

  1. Regular updates: Keep company information current
  2. Bulk operations: Use bulk delete for efficient data management
  3. 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.

Last updated on