CRM Groups
List, create, update, and inspect contact groups in the Talkturo CRM — organize contacts into groups for campaigns, assistant routing, and segmentation.
curl --request GET \
--url "https://app.talkturo.com/api/crm/groups?teamId=team_9f2c1a7d&search=vip" \
--header "Authorization: Bearer tk_example_9xmk7q2r"
const response = await fetch(
"https://app.talkturo.com/api/crm/groups?teamId=team_9f2c1a7d&search=vip",
{
method: "GET",
headers: {
Authorization: "Bearer tk_example_9xmk7q2r"
}
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"groups": [
{
"id": "grp_2c7f4f91",
"team_id": "team_9f2c1a7d",
"name": "VIP Accounts",
"is_default": false,
"created_at": "2025-01-14T18:22:11.000Z",
"updated_at": "2025-01-14T18:22:11.000Z",
"created_by": "usr_7b6d2c18",
"contact_count": 42
},
{
"id": "grp_85b1d603",
"team_id": "team_9f2c1a7d",
"name": "VIP Renewals",
"is_default": false,
"created_at": "2025-02-03T09:41:27.000Z",
"updated_at": "2025-02-03T09:41:27.000Z",
"created_by": "usr_7b6d2c18",
"contact_count": 8
}
],
"count": 2
}
{
"error": "Missing teamId"
}
curl --request POST \
--url "https://app.talkturo.com/api/crm/groups" \
--header "Authorization: Bearer tk_example_9xmk7q2r" \
--header "Content-Type: application/json" \
--data '{
"teamId": "team_9f2c1a7d",
"name": "Assistant Overflow"
}'
const response = await fetch("https://app.talkturo.com/api/crm/groups", {
method: "POST",
headers: {
Authorization: "Bearer tk_example_9xmk7q2r",
"Content-Type": "application/json"
},
body: JSON.stringify({
teamId: "team_9f2c1a7d",
name: "Assistant Overflow"
})
});
const data = await response.json();
console.log(data);
{
"success": true,
"group": {
"id": "grp_d3e801aa",
"team_id": "team_9f2c1a7d",
"name": "Assistant Overflow",
"is_default": false,
"created_at": "2025-03-06T12:18:44.000Z",
"updated_at": "2025-03-06T12:18:44.000Z",
"created_by": "usr_7b6d2c18",
"contact_count": 0
}
}
{
"error": "A group with that name already exists"
}
curl --request GET \
--url "https://app.talkturo.com/api/crm/groups/grp_2c7f4f91" \
--header "Authorization: Bearer tk_example_9xmk7q2r"
const response = await fetch(
"https://app.talkturo.com/api/crm/groups/grp_2c7f4f91",
{
method: "GET",
headers: {
Authorization: "Bearer tk_example_9xmk7q2r"
}
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"group": {
"id": "grp_2c7f4f91",
"team_id": "team_9f2c1a7d",
"name": "VIP Accounts",
"is_default": false,
"created_at": "2025-01-14T18:22:11.000Z",
"updated_at": "2025-01-22T10:09:02.000Z",
"created_by": "usr_7b6d2c18",
"contacts": [
{
"id": "ctc_19f4b0d8",
"first_name": "Jane",
"last_name": "Chen",
"email": "jane.chen@northstarhealth.com",
"phone": "+14155550132",
"job_title": "Revenue Operations Director",
"lead_status": "qualified"
},
{
"id": "ctc_88ca60e2",
"first_name": "Marcus",
"last_name": "Reed",
"email": "marcus.reed@lakesideelectric.com",
"phone": "+14155550177",
"job_title": "VP of Sales",
"lead_status": "new"
}
],
"contact_count": 200
}
}
{
"error": "Group not found"
}
curl --request PUT \
--url "https://app.talkturo.com/api/crm/groups/grp_2c7f4f91" \
--header "Authorization: Bearer tk_example_9xmk7q2r" \
--header "Content-Type: application/json" \
--data '{
"name": "Strategic Accounts"
}'
const response = await fetch(
"https://app.talkturo.com/api/crm/groups/grp_2c7f4f91",
{
method: "PUT",
headers: {
Authorization: "Bearer tk_example_9xmk7q2r",
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Strategic Accounts"
})
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"group": {
"id": "grp_2c7f4f91",
"team_id": "team_9f2c1a7d",
"name": "Strategic Accounts",
"is_default": false,
"created_at": "2025-01-14T18:22:11.000Z",
"updated_at": "2025-03-06T13:09:55.000Z",
"created_by": "usr_7b6d2c18",
"contact_count": 200
}
}
{
"error": "Group name cannot be empty"
}
curl --request DELETE \
--url "https://app.talkturo.com/api/crm/groups/grp_2c7f4f91" \
--header "Authorization: Bearer tk_example_9xmk7q2r"
const response = await fetch(
"https://app.talkturo.com/api/crm/groups/grp_2c7f4f91",
{
method: "DELETE",
headers: {
Authorization: "Bearer tk_example_9xmk7q2r"
}
}
);
const data = await response.json();
console.log(data);
{
"error": "Groups cannot be deleted. Rename it instead, or leave it unused."
}
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/crm/groups | List groups for a workspace | Session cookie or API key |
POST | /api/crm/groups | Create a group | Session cookie or API key |
GET | /api/crm/groups/{id} | Get one group with contacts | Session cookie or API key |
PUT | /api/crm/groups/{id} | Rename a group | Session cookie or API key |
DELETE | /api/crm/groups/{id} | Not supported | Session cookie or API key |
GET | /api/crm/groups/{id}/contacts | List contacts in a group | Session cookie or API key |
POST | /api/crm/groups/{id}/contacts | Add a contact to a group | Session cookie or API key |
DELETE | /api/crm/groups/{id}/contacts | Remove a contact from a group | Session cookie or API key |
Use the base URL https://app.talkturo.com. These endpoints accept either a Talkturo session cookie or an Authorization header with a Bearer API key. For API key requests, the team is derived from the key and any teamId value in the request is ignored.
DELETE /api/crm/groups/{id} always returns 405 Method Not Allowed. Groups cannot be deleted. Rename the group instead, or leave it unused.
List groups
List all CRM groups in a workspace. Use search to filter groups by name.
Endpoint
GET https://app.talkturo.com/api/crm/groups
Query parameters
Workspace ID. Required when you authenticate with a session cookie. Ignored for API key requests because the API key already scopes the request to a team.
Case-insensitive filter applied to the group name.
Request example
Response example
Response fields
Indicates whether the request succeeded.
Array of groups that match the request filters.
Unique group ID.
Workspace ID that owns the group.
Group name. Names are unique within a team.
Whether the group is the default CRM group for the workspace.
Group creation timestamp in ISO 8601 format.
Last update timestamp in ISO 8601 format.
User ID of the creator. This value can be null in some records.
Exact number of contacts currently assigned to the group.
Number of groups returned in the groups array.
Error responses
| Status | Meaning |
|---|---|
400 | Missing teamId for a session-authenticated request |
500 | Database or server error |
Create group
Create a new contact group in a workspace. Group names must be unique within the team.
Endpoint
POST https://app.talkturo.com/api/crm/groups
Body parameters
Workspace ID. Required when you authenticate with a session cookie. Ignored for API key requests.
Group name. The name must be unique within the team.
Request example
Response example
Response fields
Indicates whether the request succeeded.
The newly created group.
Unique group ID.
Workspace ID that owns the group.
Group name.
Whether the group is the default CRM group.
Creation timestamp in ISO 8601 format.
Last update timestamp in ISO 8601 format.
User ID of the creator. This value can be null.
Number of contacts currently assigned to the group.
Error responses
| Status | Meaning |
|---|---|
400 | Missing teamId, missing name, or duplicate group name |
500 | Database or server error |
Get group with contacts
Fetch one group and the most recent contacts assigned to it. The response includes up to 100 contacts ordered by newest added_at first.
Endpoint
GET https://app.talkturo.com/api/crm/groups/{id}
This endpoint requires auth.accountId in addition to authentication. If the request identity does not include an account context, the API returns 401.
Path parameters
Group UUID.
Request example
Response example
Response fields
Indicates whether the request succeeded.
The requested group record with contact data.
Unique group ID.
Workspace ID that owns the group.
Group name.
Whether the group is the default CRM group.
Group creation timestamp in ISO 8601 format.
Last update timestamp in ISO 8601 format.
User ID of the creator. This value can be null.
Up to 100 contacts in the group, ordered by newest assignment first.
Unique contact ID.
Contact first name.
Contact last name.
Contact email address.
Contact phone number.
Contact job title.
Lead status for the contact.
Total number of contacts in the group. This can be larger than the length of group.contacts.
Error responses
| Status | Meaning |
|---|---|
401 | Missing authentication or missing account context |
404 | Group not found |
500 | Database or server error |
Update group
Rename an existing group. This endpoint does not let you change whether a group is the default.
Endpoint
PUT https://app.talkturo.com/api/crm/groups/{id}
Do not send is_default in the request body. This endpoint does not support changing it.
Path parameters
Group UUID.
Body parameters
New group name. If you send name, it must not be an empty string.
Request example
Response example
Response fields
Indicates whether the request succeeded.
The updated group record.
Unique group ID.
Workspace ID that owns the group.
Updated group name.
Whether the group is the default CRM group.
Creation timestamp in ISO 8601 format.
Last update timestamp in ISO 8601 format.
User ID of the creator. This value can be null.
Number of contacts currently assigned to the group.
Error responses
| Status | Meaning |
|---|---|
400 | Empty name or duplicate group name |
401 | Missing authentication or missing account context |
404 | Group not found |
500 | Database or server error |
Delete group
Deletion is not supported for CRM groups. The endpoint exists but always rejects the request.
Endpoint
DELETE https://app.talkturo.com/api/crm/groups/{id}
Path parameters
Group UUID.
Request example
Response example
Response fields
Human-readable error message explaining that group deletion is not supported.
Error responses
| Status | Meaning |
|---|---|
405 | Groups cannot be deleted |
Group contact membership
Manage which contacts belong to a CRM group. Add, remove, and list contacts within a group using these membership endpoints.
List contacts in a group
Retrieve paginated contacts for a specific group. Results are ordered by membership creation time, newest first.
Endpoint
GET https://app.talkturo.com/api/crm/groups/{id}/contacts
Path parameters
Group UUID.
Query parameters
Maximum number of contacts to return. Defaults to 100.
Number of contacts to skip for pagination. Defaults to 0.
Response fields
Indicates whether the request succeeded.
Array of contact records in the group.
Total number of contacts in the group.
Pagination limit used for this request.
Pagination offset used for this request.
Error responses
| Status | Meaning |
|---|---|
401 | Missing authentication or account context |
404 | Group not found or does not belong to the account |
Add a contact to a group
Add a contact to a CRM group. The contact and group must both belong to the same account. This operation is idempotent, so adding a contact that is already in the group returns success without creating a duplicate.
Endpoint
POST https://app.talkturo.com/api/crm/groups/{id}/contacts
Path parameters
Group UUID.
Body parameters
UUID of the contact to add. The contact must belong to the same account as the group.
API keys require the contacts:write scope for this endpoint.
Response fields
Returns true when the contact is added or was already a member.
Error responses
| Status | Meaning |
|---|---|
400 | Missing contactId |
401 | Missing authentication or account context |
404 | Group or contact not found |
Remove a contact from a group
Remove a contact from a CRM group by contact ID. Removing a contact that is not in the group still returns success.
Endpoint
DELETE https://app.talkturo.com/api/crm/groups/{id}/contacts?contactId={contactId}
Path parameters
Group UUID.
Query parameters
UUID of the contact to remove from the group.
API keys require the contacts:write scope for this endpoint.
Response fields
Returns true when the contact is removed or was not a member.
Error responses
| Status | Meaning |
|---|---|
400 | Missing contactId |
401 | Missing authentication or account context |
404 | Group not found or does not belong to the account |