Contact Management API
The Contact Management API allows you to manage contacts (clients) in your TaskIP CRM system. You can create, read, update, and delete contacts, look a contact up by email, perform bulk deletes, and invite contacts to the client portal.
Resource IDs: The {id} / {contact} segment of the contact routes only accepts digits. A non-numeric segment (for example /contact/foo) is a 404.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/contact | Get all contacts |
POST | /api/public-v1/contact | Create a new contact |
GET | /api/public-v1/contact/{id} | Get a specific contact |
GET | /api/public-v1/contact/find-by-email | Find a contact by email address |
PUT / PATCH | /api/public-v1/contact/{id} | Update a contact |
DELETE | /api/public-v1/contact/{id} | Delete a contact |
POST | /api/public-v1/contact/bulk-delete | Delete multiple contacts |
POST | /api/public-v1/contact/invite-client/{id} | Invite a contact to the client portal |
Get All Contacts
Retrieve a list of all contacts in your system.
GET /api/public-v1/contactRequest 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 | Contacts per page (default: 10). Use 0 to return all contacts without pagination |
search | string | No | Search by contact name, email, phone number, or company name |
has_portal_access | any non-empty value | No | When present (and not 0), only contacts that have client portal access are returned |
Results are ordered by id descending.
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/contact?page=1&item=20" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"message": "All contacts successfully fetched",
"data": [
{
"id": 1,
"user_id": 123,
"user_uuid": "9c1d2c7e-6d8e-4a43-b0b4-0a5a5f3c1e11",
"company": {
"id": 5,
"name": "Acme Corp",
"email": "info@acmecorp.com",
"website": "https://acmecorp.com"
},
"company_id": 5,
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"email": "john.doe@example.com",
"position": "Software Engineer",
"phone_number": "555-0123",
"mobile_phone": null,
"preferred_contact_method_id": null,
"country_id": 1,
"country": "United States",
"state_id": 5,
"state": "California",
"city_id": 10,
"city": "San Francisco",
"address": "123 Tech Street",
"zip_code": "94105",
"timezone": "America/Los_Angeles",
"details": null,
"reference": null,
"reference_name": null,
"access_portal": 1,
"billings": {
"name": "John Doe",
"email": "billing@example.com",
"tax_id": "TX-123456789",
"address": "123 Tech Street",
"phone_number": "555-0123"
},
"languages": [
{ "value": 1, "label": "🇺🇸 English [en]" }
],
"image": null,
"custom_fields": [],
"tags": [
{ "id": 3, "name": "VIP", "color": "#ef4444" }
],
"activities": []
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/contact?page=1",
"last": "https://public-api.taskip.net/api/public-v1/contact?page=3",
"prev": null,
"next": "https://public-api.taskip.net/api/public-v1/contact?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https://public-api.taskip.net/api/public-v1/contact",
"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 (no links / meta pagination block).
Create a Contact
Create a new contact in your system.
POST /api/public-v1/contactRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string | Yes | Contact’s first name (max 191 chars). Markup and characters other than letters, spaces, apostrophes, hyphens and dots are stripped |
last_name | string | No | Contact’s last name (max 191 chars). Sanitized the same way as first_name |
email | string | No | Valid email address. Must not already belong to a user, another contact, or a lead. Required when is_company_contact is 1, when access_portal is 1, or when invite_client is true |
phone_code | string | No | Phone country code (max 5 chars) |
phone_number | string | No | Contact’s phone number (max 18 chars) |
mobile_phone | string | No | Mobile number (max 18 chars) |
preferred_contact_method_id | integer | No | ID of an existing preferred contact method |
company_id | integer | No | Associated company ID (must exist) |
position | string | No | Job position/title |
country_id | integer | No | Country ID |
state_id | integer | No | State ID |
city_id | integer | No | City ID |
address | string | No | Contact’s address |
zip_code | string | No | ZIP/postal code (max 20 chars) |
vat_id | string | No | VAT ID (max 100 chars) |
industry_id | integer | No | Industry ID |
number_of_employees | integer | No | Number of employees (min 0) |
timezone | string | No | Contact’s timezone (max 191 chars) |
image | integer | No | Profile image media ID |
access_portal | integer | No | Portal access (0 or 1) |
password | string | Required if access_portal = 1 | Password (min 6, max 191 chars) |
description | string | No | Free-text description |
tags | array | No | Array of tags |
groups | array | No | Array of groups |
company_members | array | No | Array of company members |
is_company_contact | boolean | No | Marks the contact as a company contact |
custom_fields | array | No | Custom field data. Required custom fields defined in your workspace are enforced |
invite_client | boolean | No | Send the client portal invitation email (requires email) |
Persisted fields: On create, first_name, last_name, email, company_id, phone_number, country_id, state_id, city_id, address, zip_code, timezone, access_portal, custom_fields and invite_client are stored. On update, position and image are stored as well. Other validated fields are currently accepted but not saved by this endpoint.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/contact" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Alice",
"last_name": "Johnson",
"email": "alice.johnson@example.com",
"phone_number": "555-0125",
"company_id": 7,
"address": "123 Business Ave",
"zip_code": "12345",
"timezone": "America/New_York",
"invite_client": true
}'JavaScript Example
const contactData = {
first_name: "Alice",
last_name: "Johnson",
email: "alice.johnson@example.com",
phone_number: "555-0125",
company_id: 7,
address: "123 Business Ave",
zip_code: "12345",
timezone: "America/New_York",
invite_client: true
};
const response = await fetch('https://public-api.taskip.net/api/public-v1/contact', {
method: 'POST',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify(contactData)
});
const result = await response.json();Example Response
{
"msg": "Contact Created",
"data": {
"id": 151,
"user_id": 245,
"user_uuid": "9c1d2c7e-6d8e-4a43-b0b4-0a5a5f3c1e11",
"company": {
"id": 7,
"name": "Marketing Pro",
"email": "info@marketingpro.com"
},
"company_id": 7,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"email": "alice.johnson@example.com",
"position": null,
"phone_number": "555-0125",
"mobile_phone": null,
"preferred_contact_method_id": null,
"country_id": 1,
"country": "United States",
"state_id": 5,
"state": "New York",
"city_id": 10,
"city": "New York",
"address": "123 Business Ave",
"zip_code": "12345",
"timezone": "America/New_York",
"details": null,
"reference": null,
"reference_name": null,
"access_portal": 1,
"billings": null,
"languages": [],
"image": null,
"custom_fields": [],
"tags": [],
"activities": []
}
}The response status is 200.
Get a Specific Contact
Retrieve details of a specific contact by ID.
GET /api/public-v1/contact/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Contact ID (digits only) |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/contact/151" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"msg": "Contact Details",
"data": {
"id": 151,
"user_id": 245,
"user_uuid": "9c1d2c7e-6d8e-4a43-b0b4-0a5a5f3c1e11",
"company": {
"id": 7,
"name": "Marketing Pro",
"email": "info@marketingpro.com",
"website": "https://marketingpro.com"
},
"company_id": 7,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"email": "alice.johnson@example.com",
"position": "Marketing Director",
"phone_number": "555-0125",
"mobile_phone": null,
"preferred_contact_method_id": null,
"country_id": 1,
"country": "United States",
"state_id": 5,
"state": "New York",
"city_id": 10,
"city": "New York",
"address": "123 Business Ave",
"zip_code": "12345",
"timezone": "America/New_York",
"details": null,
"reference": null,
"reference_name": null,
"access_portal": 1,
"billings": {
"name": "Alice Johnson",
"email": "billing@example.com",
"tax_id": "TX-123456789",
"address": "123 Business Ave",
"phone_number": "555-0125"
},
"languages": [
{ "value": 1, "label": "🇺🇸 English [en]" }
],
"image": {
"id": 42,
"title": "alice-johnson.jpg",
"ext": "jpg",
"size": 125843,
"url": "https://taskip.net/storage/profile/alice-johnson.jpg",
"media_type": "profile",
"createdAt": "25-01-2024 11:20:00"
},
"custom_fields": [],
"tags": [],
"activities": []
}
}A contact that does not exist returns 404.
Find a Contact by Email
Look up a single contact by its email address. The response is the same contact object returned by Get a Specific Contact.
GET /api/public-v1/contact/find-by-emailQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | A valid email address |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/contact/find-by-email?email=alice.johnson@example.com" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"msg": "Contact Details",
"data": {
"id": 151,
"user_id": 245,
"first_name": "Alice",
"last_name": "Johnson",
"full_name": "Alice Johnson",
"email": "alice.johnson@example.com"
}
}(Abbreviated; the data object contains every field shown in Get a Specific Contact.)
Error Responses
| Status | When | Body |
|---|---|---|
422 | email is missing or not a valid email address | {"msg": "Please provide a valid email address.", "data": null} |
404 | No contact has that email address | {"msg": "No contact found with that email address.", "data": null} |
Update a Contact
Update an existing contact’s information.
PUT /api/public-v1/contact/{id}
PATCH /api/public-v1/contact/{id}PUT and PATCH are handled identically and share the same validation rules as create. Updates are partial: fields you omit keep their stored values.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Contact ID to update (digits only) |
Request Body
Same fields as Create a Contact. first_name is required on every update. Every other field is optional: an omitted field keeps its stored value (only the fields you send are changed). To clear a field, send it explicitly as null. The contact’s own current email is not treated as a duplicate. A contact that already has portal access cannot have its email removed.
Example Request
curl -X PUT "https://public-api.taskip.net/api/public-v1/contact/151" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Alice",
"last_name": "Johnson",
"email": "alice.johnson@example.com",
"position": "Senior Marketing Director",
"phone_number": "555-0126"
}'Python Example
import requests
headers = {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
update_data = {
"first_name": "Alice",
"last_name": "Johnson",
"email": "alice.johnson@example.com",
"position": "Senior Marketing Director",
"phone_number": "555-0126"
}
response = requests.put(
'https://public-api.taskip.net/api/public-v1/contact/151',
headers=headers,
json=update_data
)
result = response.json()Example Response
{
"msg": "Contact Updated"
}Delete a Contact
Delete a specific contact from your system.
DELETE /api/public-v1/contact/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Contact ID to delete (digits only) |
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/contact/151" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"msg": "Contact Deleted"
}If the contact does not exist the API returns 422 with {"error": {"msg": ["Contact not found"]}}.
Bulk Delete Contacts
Delete multiple contacts at once.
POST /api/public-v1/contact/bulk-deleteRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array | Yes | Array of contact IDs to delete |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/contact/bulk-delete" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"ids": [151, 152, 153, 154]
}'Example Response
{
"msg": "Contacts Deleted"
}| Status | When | Body |
|---|---|---|
422 | ids is missing or empty | {"error": {"msg": ["Missing or invalid contact"]}} |
404 | None of the supplied IDs match a contact | {"msg": "Contacts not found"} |
Invite Client
Send (or re-send) the client portal invitation email to a contact. The contact is granted portal access and must have an email address.
POST /api/public-v1/contact/invite-client/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Contact ID to invite |
Request Body
This endpoint takes no request body.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/contact/invite-client/150" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"msg": "Invitation sent successfully"
}| Status | When | Body |
|---|---|---|
422 | Contact not found, or the contact has no email address | {"error": {"msg": ["Contact not found"]}} / {"error": {"msg": ["This contact has no email address."]}} |
429 | An invitation was sent less than 2 minutes ago | {"msg": "Please wait before resending the invitation", "retry_after_sec": 87} |
Error Responses
Common Error Codes
| Status Code | Error Type | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing X-Secret-Key |
404 | Not Found | Contact not found (show, or a non-numeric ID in the path) |
422 | Validation Error | Request data failed validation, or the operation was rejected (for example a duplicate email) |
429 | Too Many Requests | Rate limit exceeded, or an invitation was re-sent too soon |
Example Validation Error Response
Validation failures return 422 with the failing fields under error:
{
"error": {
"first_name": ["The first name field is required."],
"email": ["The email field must be a valid email address."]
}
}Operation errors (for example a plan limit or missing permission) return 422 in this shape. When creating a contact, the workspace’s contacts plan limit is checked first, and once it is reached the request is rejected with the plan’s limit message:
{
"error": {
"msg": ["You do not have permission to add contacts"]
}
}Response Schemas
Contact Object
{
"id": "integer",
"user_id": "integer",
"user_uuid": "string|null",
"company": "object|null",
"company_id": "integer|null",
"first_name": "string",
"last_name": "string",
"full_name": "string|null",
"email": "string|null",
"position": "string|null",
"phone_number": "string|null",
"mobile_phone": "string|null",
"preferred_contact_method_id": "integer|null",
"country_id": "integer|null",
"country": "string|null",
"state_id": "integer|null",
"state": "string|null",
"city_id": "integer|null",
"city": "string|null",
"address": "string|null",
"zip_code": "string|null",
"timezone": "string|null",
"details": "string|null",
"reference": "string|null",
"reference_name": "string|null",
"access_portal": "integer (0 or 1)",
"billings": "object|null",
"languages": "array of {value, label}",
"image": "object|null",
"custom_fields": "array|object",
"tags": "array of {id, name, color}",
"activities": "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)"
}Pagination Meta Object
{
"current_page": "integer",
"from": "integer|null",
"last_page": "integer",
"path": "string",
"per_page": "integer",
"to": "integer|null",
"total": "integer"
}Tip: Use the search parameter in the GET /contact endpoint to quickly find contacts by name, email, phone number or company name, or use GET /contact/find-by-email when you already know the exact address.