> For the complete documentation index, see [llms.txt](https://answeringservicecare.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://answeringservicecare.com/docs/api-reference/user-portal-apis/to-dos/create-a-to-do.md).

# Create a To Do

## Create a To Do

> Create a new To Do. The body is flat (no \`to\_do\` wrapper) and always carries \`account\_number\`, \`delivery\_type\`, and a \`schedule\` object. The remaining required fields depend on the channel:\
> \
> \- \`sms\` — \`from\`, \`contact\`, \`message\_text\`\
> \- \`email\` — \`contact\`, \`message\_text\`, \`from\_email\`\
> \- \`call\` — \`instructions\`\
> \- \`ai\_outbound\_call\` — \`contact\`, \`instructions\`\
> \
> In \`schedule\`, set \`rule\` to \`immediately\` to send once right away, or to \`today\` to send once today at each entry in \`times\`. Omit \`rule\` to create a recurring To Do driven by \`frequency\`, \`times\`, \`interval\`, and \`days\`.

```json
{"openapi":"3.0.3","info":{"title":"Answering Service Care API","version":"1.0.0"},"tags":[{"name":"Create a To Do"}],"servers":[{"url":"https://secure.answeringservicecare.com","description":"Answering Service Care host"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API token","description":"Answering Service Care uses bearer token authentication. Generate API tokens from your user profile under **Application Keys**."}},"schemas":{"ToDoRequest":{"type":"object","description":"Flat create payload — there is no `to_do` wrapper. `account_number`, `delivery_type`, and `schedule` are always required; every other field is required per channel.","required":["account_number","delivery_type","schedule"],"properties":{"account_number":{"type":"string","description":"Account number of the DID the To Do runs against. The authenticated user must be an admin or a member of that account."},"delivery_type":{"type":"string","enum":["sms","email","call","ai_outbound_call"],"description":"Delivery channel, matched case-insensitively. `ai_outbound_call` places an AI-handled outbound call and requires a Telnyx AI Assistant attached to the account's number; it is not yet released to production."},"schedule":{"$ref":"#/components/schemas/ToDoSchedule"},"name":{"type":"string","description":"Label for the To Do. Defaults to the creation timestamp when omitted."},"contact":{"type":"string","description":"Recipient — phone number for `sms` and `ai_outbound_call`, email address for `email`. Required for those three channels."},"message_text":{"type":"string","description":"Message body. Required for `sms` and `email`."},"instructions":{"type":"string","description":"What the agent or AI assistant should say. Required for `call` and `ai_outbound_call`."},"from":{"type":"string","description":"Sending number for `sms`. Required, and validated against the account's SMS-enabled numbers; a leading `+1` is stripped."},"from_email":{"type":"string","description":"Sending address for `email`. Required, must not be blacklisted, and its domain must be an authenticated SendGrid domain on the account."},"sender_name":{"type":"string","description":"Optional display name for `email`."},"subject":{"type":"string","description":"Optional subject line for `email`."}}},"ToDoSchedule":{"type":"object","description":"Scheduling instructions. Send `rule` for a one-shot To Do, or omit `rule` and send `frequency` for a recurring one. No field inside `schedule` is unconditionally required.","properties":{"rule":{"type":"string","enum":["immediately","today"],"description":"`immediately` sends the To Do once, right away, and does not need `times`. `today` sends it once today at each entry in `times`, in the phone's time zone. Omit `rule` entirely for a recurring To Do."},"frequency":{"type":"string","enum":["daily","weekly","monthly"],"description":"Recurrence for To Dos created without a `rule`. Maps to `IceCube::{Frequency}Rule`. Reference data advertises these three values; `yearly` also resolves but is not officially supported."},"times":{"type":"array","items":{"type":"string"},"description":"One or more `H:MM AM/PM` strings. Required unless `rule` is `immediately`."},"interval":{"type":"integer","default":1,"description":"How often the To Do recurs, in units of `frequency`. Defaults to 1 when omitted."},"days":{"type":"array","items":{"type":"string","enum":["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"]},"description":"Day names for `weekly` and `monthly` recurrence, matched case-insensitively. The field is `days` (plural); sending an empty array is rejected with 422."}}},"ToDoEnvelope":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ToDo"}}},"ToDo":{"type":"object","description":"A To Do record — the stored row, plus a nested `schedule`.","properties":{"id":{"type":"integer"},"name":{"type":"string","nullable":true},"phone_id":{"type":"integer","nullable":true},"delivery_type":{"type":"string","enum":["sms","email","call","ai_outbound_call"]},"contact":{"type":"string","nullable":true},"message_text":{"type":"string","nullable":true},"instructions":{"type":"string","nullable":true},"from":{"type":"string","nullable":true},"from_email":{"type":"string","nullable":true},"sender_name":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true},"sendgrid_authenticated_domain_id":{"type":"integer","nullable":true},"ai_assistant_id":{"type":"string","nullable":true,"description":"Telnyx AI Assistant resolved from the account's number. Set only on `ai_outbound_call` To Dos."},"times":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Run times for one-shot To Dos (`rule` of `immediately` or `today`). Null for recurring To Dos, which carry a `schedule` instead."},"is_sending":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"schedule":{"allOf":[{"$ref":"#/components/schemas/ScheduleRecord"}],"nullable":true,"description":"Populated for recurring To Dos; null for one-shot To Dos."}}},"ScheduleRecord":{"type":"object","properties":{"id":{"type":"integer"},"schedulable_id":{"type":"integer"},"schedulable_type":{"type":"string"},"rule":{"type":"object","additionalProperties":true,"description":"IceCube rule object."},"times":{"type":"array","items":{"type":"string"}},"previous_occurrence":{"type":"string","format":"date-time","nullable":true},"next_occurrence":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorSimple":{"type":"object","description":"Compact error response (used for 401/422/400).","properties":{"error":{"type":"string"}}}},"responses":{"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorSimple"}}}},"Unauthorized":{"description":"Missing or invalid bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorSimple"}}}},"ValidationError":{"description":"Missing or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorSimple"}}}}}},"paths":{"/api/v2/to-dos":{"post":{"summary":"Create a To Do","description":"Create a new To Do. The body is flat (no `to_do` wrapper) and always carries `account_number`, `delivery_type`, and a `schedule` object. The remaining required fields depend on the channel:\n\n- `sms` — `from`, `contact`, `message_text`\n- `email` — `contact`, `message_text`, `from_email`\n- `call` — `instructions`\n- `ai_outbound_call` — `contact`, `instructions`\n\nIn `schedule`, set `rule` to `immediately` to send once right away, or to `today` to send once today at each entry in `times`. Omit `rule` to create a recurring To Do driven by `frequency`, `times`, `interval`, and `days`.","tags":["Create a To Do"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToDoRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToDoEnvelope"}}}},"400":{"$ref":"#/components/responses/ServerError"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://answeringservicecare.com/docs/api-reference/user-portal-apis/to-dos/create-a-to-do.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.