What you can build

Use Collect when you already have a source’s phone number. Use instructions for what to ask, input for known context values, and output for the JSON Schema of the answers you need. Your application gets structured JSON after Thred collects the answers.

Information you can collect

Use case	What to ask
Business hours	Confirm opening hours, holiday hours, or the latest pickup time.
Product availability	Ask whether a specific item is in stock and what it costs.
Appointment information	Ask about availability, accepted appointment types, or what a customer needs to bring.
Department questions	Reach the right department or extension and ask about its services.

Example: check inventory

Set your API key using the quickstart, then create a collection. Replace to with the number you want to call. The input object supplies the product and currency for these instructions:

curl --fail-with-body https://api.thred.dev/v1/collect \
  --request POST \
  --header "Authorization: Bearer $THRED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+14155550123",
    "instructions": "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
    "input": { "product": "6-foot USB-C charging cable", "currency": "USD" },
    "output": {
      "properties": {
        "in_stock": {
          "type": "boolean",
          "description": "Whether a 6-foot USB-C charging cable is currently in stock."
        },
        "price_usd": {
          "type": ["number", "null"],
          "description": "The quoted price in USD, or null if the cable is unavailable."
        }
      },
      "required": ["in_stock", "price_usd"],
      "additionalProperties": false
    }
  }'

const response = await fetch("https://api.thred.dev/v1/collect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THRED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155550123",
    instructions: "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
    input: { product: "6-foot USB-C charging cable", currency: "USD" },
    output: {
      properties: {
        in_stock: {
          type: "boolean",
          description: "Whether a 6-foot USB-C charging cable is currently in stock.",
        },
        price_usd: {
          type: ["number", "null"],
          description: "The quoted price in USD, or null if the cable is unavailable.",
        },
      },
      required: ["in_stock", "price_usd"],
      additionalProperties: false,
    },
  }),
});

if (!response.ok) throw new Error(await response.text());
const collection = await response.json();
console.log(collection.id);

import os
import requests

response = requests.post(
    "https://api.thred.dev/v1/collect",
    headers={
        "Authorization": f"Bearer {os.environ['THRED_API_KEY']}",
    },
    json={
        "to": "+14155550123",
        "instructions": "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
        "input": { "product": "6-foot USB-C charging cable", "currency": "USD" },
        "output": {
            "properties": {
                "in_stock": {
                    "type": "boolean",
                    "description": "Whether a 6-foot USB-C charging cable is currently in stock.",
                },
                "price_usd": {
                    "type": ["number", "null"],
                    "description": "The quoted price in USD, or null if the cable is unavailable.",
                },
            },
            "required": ["in_stock", "price_usd"],
            "additionalProperties": False,
        },
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])

Thred returns the collection’s ID immediately. Retrieve the collection to check its status. Once status is completed, data contains the answers in your requested shape. If the result is incomplete, check partial_data for the answers it collected.

Shape the answers

Output fields can be strings, numbers, integers, booleans, objects, or arrays. Fields can also allow null, as the price does above. Give fields clear descriptions and list the answers you need under required. The output is always an object, so omit its top-level type. Define properties, list required fields, and set additionalProperties to false. Nested objects still need type: "object", properties, and additionalProperties: false; arrays need an items schema. Thred supports a small JSON Schema subset. The API reference lists the supported fields.

Add context and routing

Option	Use it to
`input`	Pass a JSON object of context values, such as a product name or reference number. Optional; defaults to `{}`.
`navigation`	Specify a contact name, department, extension, or language.
`max_duration_seconds`	Set how long the call can run within your workspace’s limit.
`metadata`	Attach your own identifiers so you can match the result to a record in your app.
`webhook_id`	Receive a signed completion event at an endpoint configured in the dashboard.

Start with the quickstart, then add these options as your workflow needs them.

Get started

Collect API

Account and utilities

What you can build

Information you can collect

Example: check inventory

Shape the answers

Add context and routing

​Information you can collect

​Example: check inventory

​Shape the answers

​Add context and routing

Information you can collect

Example: check inventory

Shape the answers

Add context and routing