# Schedule Activities API

{% hint style="success" %}
**Audience:** Developers and Solution Architects

**Purpose:** Enables programmatic creation, scheduling, and updating of Activities in <code class="expression">space.vars.Kizen\_company\_name</code> with clear, accurate, modern API documentation.
{% endhint %}

## Overview

Use the **Schedule Activities** endpoint to create <code class="expression">space.vars.activities</code> scheduled for a future date and time. Scheduled Activities allow external systems to manage upcoming actions (e.g. calls, tasks, events) and associate them with other records.

The material on this page builds on information covered on the [Activities Core Concepts](/docs/concepts/activities/activities-core-concepts.md) and [Activities Data Model](/docs/concepts/activities/activities-data-model.md).

### Why Use this API?

You can use the Scheduling <code class="expression">space.vars.activities</code> API when you need to:

* Sync reminders, tasks, or appointments from other platforms into <code class="expression">space.vars.Kizen\_company\_name</code>
* Assign tasks to team members
* Create multi-step sequences (e.g., onboarding, sales cadences)
* Sync reminders or appointments from other platforms into <code class="expression">space.vars.Kizen\_company\_name</code>
* Schedule upcoming calls, meetings, or check-ins tied to specific records

{% hint style="danger" %}
**Warning:** The API shown below can also log <code class="expression">space.vars.activities</code>, but logging through the use of this API is discouraged because partial or incorrect payloads can overwrite existing <code class="expression">space.vars.activity</code> data.
{% endhint %}

### Scheduling Activity API Behavior

Use this endpoint to schedule <code class="expression">space.vars.activities</code> for a future date and time and manage their lifecycle through the platform. It:

* Displays <code class="expression">space.vars.activities</code> with a `due_datetime` in the UI as future tasks
* May trigger an `activity.completed` webhook when a scheduled <code class="expression">space.vars.activity</code> is completed
* Maintains a Scheduled status until the <code class="expression">space.vars.activity</code> is logged, at which point it transitions to Completed
* Returns a response structured according to the [Activities Data Model](/docs/concepts/activities/activities-data-model.md) schema

***

## Schedule Activity Endpoint

Want to try the API out? Visit our [Swagger ](https://app.go.kizen.com/api/docs/public/swagger#/activities/activities_scheduled_activity_create)docs.

## POST /api/activities/scheduled-activity

> Create scheduled activity

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"ScheduledActivityV2WriteRequest":{"type":"object","properties":{"activity_object_id":{"type":"string","format":"uuid"},"activity_object_name":{"type":"string","nullable":true,"minLength":1},"due_datetime":{"type":"string","format":"date-time"},"original_due_datetime":{"type":"string","format":"date-time"},"employee_id":{"type":"string","format":"uuid","nullable":true},"role_id":{"type":"string","format":"uuid","nullable":true},"note":{"type":"string"},"mentions":{"type":"array","items":{"type":"string","format":"uuid","nullable":true}},"notifications":{"type":"array","items":{"$ref":"#/components/schemas/_ScheduledActivityNotificationV2WriteRequest"}},"associated_entities":{"type":"array","items":{"$ref":"#/components/schemas/_AssociatedEntityWriteRequest"},"nullable":true},"notify_mentioned":{"type":"boolean","default":false}}},"_ScheduledActivityNotificationV2WriteRequest":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/_ScheduledActivityNotificationV2WriteTypeEnum"},"time_amount":{"type":"integer","maximum":2147483647,"minimum":1},"time_unit":{"$ref":"#/components/schemas/TimeUnitEnum"}},"required":["time_amount","time_unit","type"]},"_ScheduledActivityNotificationV2WriteTypeEnum":{"enum":["email","text"],"type":"string","description":"* `email` - email\n* `text` - text"},"TimeUnitEnum":{"enum":["minute","hour","day"],"type":"string","description":"* `minute` - minute\n* `hour` - hour\n* `day` - day"},"_AssociatedEntityWriteRequest":{"type":"object","properties":{"custom_object_id":{"type":"string","format":"uuid","nullable":true,"description":"This field is deprecated, use custom_object instead.","deprecated":true},"entity_id":{"type":"string","format":"uuid","nullable":true,"description":"This field is deprecated, use entity instead.","deprecated":true},"custom_object":{"allOf":[{"$ref":"#/components/schemas/_CustomObjectRequest"}],"nullable":true},"entity":{"allOf":[{"$ref":"#/components/schemas/EntityRequest"}],"nullable":true}}},"_CustomObjectRequest":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n    IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n        defined in subclasses.\n\nMethods:\n    get_identifier_field(): Determines the alternate identifier field name.\n    validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n    get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Required if \"id\" is not provided."}}},"EntityRequest":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n    IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n        defined in subclasses.\n\nMethods:\n    get_identifier_field(): Determines the alternate identifier field name.\n    validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n    get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of entity or email of contact."}}},"ScheduledActivityV2Read":{"type":"object","properties":{"associated_entities":{"type":"array","items":{"$ref":"#/components/schemas/_AssociatedEntityRead"}},"id":{"type":"string","format":"uuid"},"note":{"type":"string"},"due_datetime":{"type":"string","format":"date-time"},"original_due_datetime":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"logged_activity_id":{"type":"string","format":"uuid"},"activity_object":{"type":"string"},"employee":{"type":"string"},"role":{"$ref":"#/components/schemas/SimpleRole"},"mentions":{"$ref":"#/components/schemas/EmployeeSerpy"},"associated_fields":{"type":"string"},"notifications":{"type":"string"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","activity_object","associated_entities","associated_fields","completed_at","created","due_datetime","employee","id","logged_activity_id","mentions","note","notifications","original_due_datetime","role"]},"_AssociatedEntityRead":{"type":"object","properties":{"custom_object":{"$ref":"#/components/schemas/_CustomObjectRead"},"entity":{"$ref":"#/components/schemas/_EntityRead"},"custom_object_id":{"type":"string","format":"uuid","deprecated":true},"object_name":{"type":"string","deprecated":true},"object_api_name":{"type":"string","deprecated":true},"entity_id":{"type":"string","format":"uuid","deprecated":true},"name":{"type":"string","readOnly":true,"deprecated":true},"display_name":{"type":"string","readOnly":true,"deprecated":true}},"required":["custom_object","custom_object_id","display_name","entity","entity_id","name","object_api_name","object_name"]},"_CustomObjectRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_name":{"type":"string"}},"required":["id","name","object_name"]},"_EntityRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","readOnly":true},"display_name":{"type":"string","readOnly":true}},"required":["display_name","email","id","name"]},"SimpleRole":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","maxLength":200},"default_for_new_users":{"type":"boolean"}},"required":["id","name"]},"EmployeeSerpy":{"type":"object","properties":{"picture_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"display_name":{"type":"string"},"account_type":{"type":"string"}},"required":["account_type","display_name","email","first_name","id","last_name","picture_url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}},"paths":{"/api/activities/scheduled-activity":{"post":{"operationId":"activities_scheduled_activity_create","description":"Create scheduled activity","tags":["activities"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledActivityV2WriteRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledActivityV2Read"}}},"description":""}}}}}}
```

### Scheduled Activity Schemas

## The ScheduledActivityV2WriteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"ScheduledActivityV2WriteRequest":{"type":"object","properties":{"activity_object_id":{"type":"string","format":"uuid"},"activity_object_name":{"type":"string","nullable":true,"minLength":1},"due_datetime":{"type":"string","format":"date-time"},"original_due_datetime":{"type":"string","format":"date-time"},"employee_id":{"type":"string","format":"uuid","nullable":true},"role_id":{"type":"string","format":"uuid","nullable":true},"note":{"type":"string"},"mentions":{"type":"array","items":{"type":"string","format":"uuid","nullable":true}},"notifications":{"type":"array","items":{"$ref":"#/components/schemas/_ScheduledActivityNotificationV2WriteRequest"}},"associated_entities":{"type":"array","items":{"$ref":"#/components/schemas/_AssociatedEntityWriteRequest"},"nullable":true},"notify_mentioned":{"type":"boolean","default":false}}},"_ScheduledActivityNotificationV2WriteRequest":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/_ScheduledActivityNotificationV2WriteTypeEnum"},"time_amount":{"type":"integer","maximum":2147483647,"minimum":1},"time_unit":{"$ref":"#/components/schemas/TimeUnitEnum"}},"required":["time_amount","time_unit","type"]},"_ScheduledActivityNotificationV2WriteTypeEnum":{"enum":["email","text"],"type":"string","description":"* `email` - email\n* `text` - text"},"TimeUnitEnum":{"enum":["minute","hour","day"],"type":"string","description":"* `minute` - minute\n* `hour` - hour\n* `day` - day"},"_AssociatedEntityWriteRequest":{"type":"object","properties":{"custom_object_id":{"type":"string","format":"uuid","nullable":true,"description":"This field is deprecated, use custom_object instead.","deprecated":true},"entity_id":{"type":"string","format":"uuid","nullable":true,"description":"This field is deprecated, use entity instead.","deprecated":true},"custom_object":{"allOf":[{"$ref":"#/components/schemas/_CustomObjectRequest"}],"nullable":true},"entity":{"allOf":[{"$ref":"#/components/schemas/EntityRequest"}],"nullable":true}}},"_CustomObjectRequest":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n    IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n        defined in subclasses.\n\nMethods:\n    get_identifier_field(): Determines the alternate identifier field name.\n    validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n    get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Required if \"id\" is not provided."}}},"EntityRequest":{"type":"object","description":"A serializer that accepts either an 'id' field or an alternate identifier field.\n\nThis serializer class automatically detects which identifier field is being used and\nperforms validation to ensure at least one identifier is provided. It also provides\nutility methods for retrieving objects by their identifiers.\n\nAttributes:\n    IDENTIFIER_FIELD (str): The name of the alternate identifier field. Should be\n        defined in subclasses.\n\nMethods:\n    get_identifier_field(): Determines the alternate identifier field name.\n    validate(attrs): Ensures either 'id' or the alternate identifier is provided.\n    get_identifier_values(data, values_map, queryset): Retrieves objects by their identifiers.","properties":{"id":{"type":"string","format":"uuid","nullable":true,"description":"Required if \"name\" is not provided."},"name":{"type":"string","nullable":true,"minLength":1,"description":"Name of entity or email of contact."}}}}}}
```

## The ScheduledActivityV2Read object

```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"ScheduledActivityV2Read":{"type":"object","properties":{"associated_entities":{"type":"array","items":{"$ref":"#/components/schemas/_AssociatedEntityRead"}},"id":{"type":"string","format":"uuid"},"note":{"type":"string"},"due_datetime":{"type":"string","format":"date-time"},"original_due_datetime":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"logged_activity_id":{"type":"string","format":"uuid"},"activity_object":{"type":"string"},"employee":{"type":"string"},"role":{"$ref":"#/components/schemas/SimpleRole"},"mentions":{"$ref":"#/components/schemas/EmployeeSerpy"},"associated_fields":{"type":"string"},"notifications":{"type":"string"},"created":{"type":"string","format":"date-time"},"access":{"$ref":"#/components/schemas/AccessSerpy"}},"required":["access","activity_object","associated_entities","associated_fields","completed_at","created","due_datetime","employee","id","logged_activity_id","mentions","note","notifications","original_due_datetime","role"]},"_AssociatedEntityRead":{"type":"object","properties":{"custom_object":{"$ref":"#/components/schemas/_CustomObjectRead"},"entity":{"$ref":"#/components/schemas/_EntityRead"},"custom_object_id":{"type":"string","format":"uuid","deprecated":true},"object_name":{"type":"string","deprecated":true},"object_api_name":{"type":"string","deprecated":true},"entity_id":{"type":"string","format":"uuid","deprecated":true},"name":{"type":"string","readOnly":true,"deprecated":true},"display_name":{"type":"string","readOnly":true,"deprecated":true}},"required":["custom_object","custom_object_id","display_name","entity","entity_id","name","object_api_name","object_name"]},"_CustomObjectRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"object_name":{"type":"string"}},"required":["id","name","object_name"]},"_EntityRead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","readOnly":true},"display_name":{"type":"string","readOnly":true}},"required":["display_name","email","id","name"]},"SimpleRole":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","maxLength":200},"default_for_new_users":{"type":"boolean"}},"required":["id","name"]},"EmployeeSerpy":{"type":"object","properties":{"picture_url":{"type":"string"},"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"display_name":{"type":"string"},"account_type":{"type":"string"}},"required":["account_type","display_name","email","first_name","id","last_name","picture_url"]},"AccessSerpy":{"type":"object","properties":{"view":{"type":"boolean"},"edit":{"type":"boolean"},"remove":{"type":"boolean"}},"required":["edit","remove","view"]}}}}
```

***

## What's Next?

After scheduling <code class="expression">space.vars.activities</code> via the API, you can:

* Create scheduled <code class="expression">space.vars.activities</code> as business needs change.
* Understand when a scheduled <code class="expression">space.vars.activity</code> becomes a logged <code class="expression">space.vars.activity</code>.
* Use Scheduled <code class="expression">space.vars.activities</code> alongside <code class="expression">space.vars.automations</code> that depend on <code class="expression">space.vars.activity</code> timing.

For more information on <code class="expression">space.vars.activities</code>, check out the following topics:

<details>

<summary>Related Topics</summary>

* [Activities](/docs/concepts/activities.md)
* [Activities Core Concepts](/docs/concepts/activities/activities-core-concepts.md)
* [Activities Data Model](/docs/concepts/activities/activities-data-model.md)
* [Activity Permissions](/docs/concepts/activities/activity-permissions.md)
* [Advanced Activity Rules](/docs/concepts/activities/advanced-activity-rules.md)
* [Activities API & Webhooks](/docs/concepts/activities/activities-api-and-webhooks.md)

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.kizen.com/docs/concepts/activities/activities-api-and-webhooks/schedule-activities-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.