Skip to Content
Contact Management API

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

MethodEndpointDescription
GET/api/public-v1/contactGet all contacts
POST/api/public-v1/contactCreate a new contact
GET/api/public-v1/contact/{id}Get a specific contact
GET/api/public-v1/contact/find-by-emailFind 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-deleteDelete 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/contact

Request Headers

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

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination (default: 1)
itemintegerNoContacts per page (default: 10). Use 0 to return all contacts without pagination
searchstringNoSearch by contact name, email, phone number, or company name
has_portal_accessany non-empty valueNoWhen 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/contact

Request Headers

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

Request Body

FieldTypeRequiredDescription
first_namestringYesContact’s first name (max 191 chars). Markup and characters other than letters, spaces, apostrophes, hyphens and dots are stripped
last_namestringNoContact’s last name (max 191 chars). Sanitized the same way as first_name
emailstringNoValid 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_codestringNoPhone country code (max 5 chars)
phone_numberstringNoContact’s phone number (max 18 chars)
mobile_phonestringNoMobile number (max 18 chars)
preferred_contact_method_idintegerNoID of an existing preferred contact method
company_idintegerNoAssociated company ID (must exist)
positionstringNoJob position/title
country_idintegerNoCountry ID
state_idintegerNoState ID
city_idintegerNoCity ID
addressstringNoContact’s address
zip_codestringNoZIP/postal code (max 20 chars)
vat_idstringNoVAT ID (max 100 chars)
industry_idintegerNoIndustry ID
number_of_employeesintegerNoNumber of employees (min 0)
timezonestringNoContact’s timezone (max 191 chars)
imageintegerNoProfile image media ID
access_portalintegerNoPortal access (0 or 1)
passwordstringRequired if access_portal = 1Password (min 6, max 191 chars)
descriptionstringNoFree-text description
tagsarrayNoArray of tags
groupsarrayNoArray of groups
company_membersarrayNoArray of company members
is_company_contactbooleanNoMarks the contact as a company contact
custom_fieldsarrayNoCustom field data. Required custom fields defined in your workspace are enforced
invite_clientbooleanNoSend 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

ParameterTypeRequiredDescription
idintegerYesContact 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-email

Query Parameters

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

StatusWhenBody
422email is missing or not a valid email address{"msg": "Please provide a valid email address.", "data": null}
404No 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

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

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

Request Body

FieldTypeRequiredDescription
idsarrayYesArray 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" }
StatusWhenBody
422ids is missing or empty{"error": {"msg": ["Missing or invalid contact"]}}
404None 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

ParameterTypeRequiredDescription
idintegerYesContact 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" }
StatusWhenBody
422Contact not found, or the contact has no email address{"error": {"msg": ["Contact not found"]}} / {"error": {"msg": ["This contact has no email address."]}}
429An 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 CodeError TypeDescription
401UnauthorizedInvalid or missing X-Secret-Key
404Not FoundContact not found (show, or a non-numeric ID in the path)
422Validation ErrorRequest data failed validation, or the operation was rejected (for example a duplicate email)
429Too Many RequestsRate 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.

Last updated on