Skip to main content

Your Implementation Required

These endpoints must be implemented on your server
Genesy creates tasks in your CRM when sequences trigger task actions. Your API must implement the following task endpoints.

​
Single Task Operations

​
Create Task

Creates a new task in your CRM. 
POST /tasks

​
Request Body

FieldTypeRequiredDescription
subjectstring✅ YesThe task title/subject
descriptionstringNoDetailed description or notes for the task
typestringNoTask type (e.g., “call”, “email”, “meeting”)
ownerIdstringNoID of the user who owns the task in your system
dueDatestring (ISO 8601)NoWhen the task is due (e.g., 2024-01-15T10:00:00Z)
contactIdstringNoID of the associated contact/lead in your CRM
companyIdstringNoID of the associated company in your CRM

​
Example Request

{
  "subject": "Follow up with John",
  "description": "Discuss pricing proposal from last meeting",
  "type": "call",
  "ownerId": "user-123",
  "dueDate": "2024-01-15T10:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789"
}

​
Response

Return the created task with at least an id field: 
{
  "id": "task-abc123",
  "subject": "Follow up with John",
  "description": "Discuss pricing proposal from last meeting",
  "type": "call",
  "ownerId": "user-123",
  "dueDate": "2024-01-15T10:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789",
  "completed": false
}
The id field is required in the response. Genesy uses this to track the task.

​
Get Task

Retrieves a single task by ID. 
GET /tasks/:taskId

​
Path Parameters

ParameterTypeDescription
taskIdstringThe task ID returned from create

​
Response

{
  "id": "task-abc123",
  "subject": "Follow up with John",
  "description": "Discuss pricing proposal from last meeting",
  "type": "call",
  "ownerId": "user-123",
  "dueDate": "2024-01-15T10:00:00Z",
  "contactId": "contact-456",
  "companyId": "company-789",
  "completed": false,
  "completedAt": null
}

​
Update Task (Complete)

Updates a task, typically to mark it as completed. 
PATCH /tasks/:taskId

​
Path Parameters

ParameterTypeDescription
taskIdstringThe task ID to update

​
Request Body

FieldTypeDescription
completedbooleanSet to true to mark the task as completed

​
Example Request

{
  "completed": true
}

​
Response

Return the updated task: 
{
  "id": "task-abc123",
  "subject": "Follow up with John",
  "completed": true,
  "completedAt": "2024-01-15T11:30:00Z"
}

​
Batch Operations

Genesy uses batch endpoints to minimize API calls and improve performance. Instead of making individual requests for each task, Genesy will batch multiple operations into single requests.

​
Get Tasks Batch

Retrieves multiple tasks in a single request. 
POST /tasks/batch

​
Request Body

FieldTypeRequiredDescription
idsstring[]✅ YesArray of task IDs to retrieve

​
Example Request

{
  "ids": ["task-abc123", "task-def456", "task-ghi789"]
}

​
Response

Return an array of tasks. Tasks that don’t exist should be omitted from the response (don’t return errors for missing tasks). 
[
  {
    "id": "task-abc123",
    "subject": "Follow up with John",
    "completed": false
  },
  {
    "id": "task-def456",
    "subject": "Send proposal",
    "completed": true,
    "completedAt": "2024-01-15T11:30:00Z"
  }
]
If a task ID doesn’t exist, simply omit it from the response array rather than returning an error.

​
Complete Tasks Batch

Marks multiple tasks as completed in a single request. 
PATCH /tasks/batch

​
Request Body

FieldTypeRequiredDescription
idsstring[]✅ YesArray of task IDs to complete
completedboolean✅ YesSet to true to mark tasks as completed

​
Example Request

{
  "ids": ["task-abc123", "task-def456"],
  "completed": true
}

​
Response

Return an array of the updated tasks: 
[
  {
    "id": "task-abc123",
    "subject": "Follow up with John",
    "completed": true,
    "completedAt": "2024-01-15T14:22:00Z"
  },
  {
    "id": "task-def456",
    "subject": "Send proposal",
    "completed": true,
    "completedAt": "2024-01-15T14:22:00Z"
  }
]

​
Task Schema Reference

FieldTypeRequiredDescription
idstring✅ YesUnique identifier for the task
subjectstring✅ YesTask title/subject
descriptionstringNoDetailed notes
typestringNoTask category
ownerIdstringNoAssigned user ID
dueDatestring (ISO 8601)NoDue date/time
contactIdstringNoAssociated contact ID
companyIdstringNoAssociated company ID
completedbooleanNoCompletion status
completedAtstring (ISO 8601)NoWhen the task was completed

​
Testing Your Tasks API

Before connecting to Genesy, test your task endpoints:
1

Test Task Creation

curl -X POST https://your-api.com/tasks \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Test task", "description": "Testing integration"}'
2

Test Batch Get Tasks

curl -X POST https://your-api.com/tasks/batch \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["task-id-1", "task-id-2"]}'
3

Test Batch Complete Tasks

curl -X PATCH https://your-api.com/tasks/batch \
  -H "X-API-Key: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["task-id-1", "task-id-2"], "completed": true}'