Common Workflows

This guide shows common API workflows that combine multiple TeamGrid resources. For copyable end-to-end examples, see Recipes.

Create a Project with Tasks

1. Create the project with POST /projects.
2. Store the returned project id.
3. Create tasks with POST /tasks and projectId.

curl https://api.teamgrid.app/projects \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer onboarding"
  }'

curl https://api.teamgrid.app/tasks \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prepare kickoff agenda",
    "projectId": "PROJECT_ID",
    "plannedTime": 60
  }'

Assign a Task

Fetch users with GET /users, then update the task with the selected userId.

curl https://api.teamgrid.app/tasks/TASK_ID \
  -X PUT \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "USER_ID"
  }'

Complete a Task

Use Update task to complete a task with PUT /tasks/{_id}.

curl https://api.teamgrid.app/tasks/TASK_ID \
  -X PUT \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completed": true
  }'

Import Contacts

Create companies and people with POST /contacts. Use type to distinguish them.

Company:

{
  "type": "company",
  "companyTitle": "Acme Inc."
}

Person:

{
  "type": "person",
  "firstname": "Alex",
  "lastname": "Morgan",
  "emails": [
    {
      "type": "business",
      "email": "[email protected]"
    }
  ]
}

Synchronize Time Entries

Use GET /times with date filters for incremental synchronization.

GET /times?startFrom=2026-07-01T00:00:00Z&startTo=2026-07-31T23:59:59Z

Store the TeamGrid _id of every synchronized time entry. Use update endpoints for follow-up changes instead of creating duplicate records.

React to Changes with Webhooks

Register webhook actions with POST /webhooks for the events your system needs.

Examples:

• task_created to mirror new tasks
• task_completed to trigger downstream workflow
• timeentry_created_manually to sync time reports
• project_completed to close project work in another system

Webhook handlers should be idempotent. TeamGrid can send rich event payloads, but your integration should still tolerate repeated or delayed deliveries.