Tookan MCP by usefulapi

The connected Tookan account (admin user): user_id, email, name, company name and address. Good first call. POST /v2/get_user_details.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List tasks (Tookan calls them jobs) of one task type within a date range of the task date (at most 31 days, within the last 31 days). Paginated: one Tookan page per call (page, default 1). Filter by status, agent (fleet_id), team, customer, job ids or your order ids. Task status codes: 0 assigned, 1 started, 2 successful, 3 failed, 4 in progress/arrived, 6 unassigned, 7 accepted/acknowledged, 8 declined, 9 cancelled, 10 deleted. POST /v2/get_all_tasks.

{
  "type": "object",
  "properties": {
    "job_type": {
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        }
      ],
      "description": "Task type: 0 = pickup, 1 = delivery, 2 = appointment, 3 = field workforce (FOS)."
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start of the task-date range, YYYY-MM-DD."
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "End of the task-date range, YYYY-MM-DD (at most 31 days after start_date)."
    },
    "job_status": {
      "description": "Only tasks in this status. Task status codes: 0 assigned, 1 started, 2 successful, 3 failed, 4 in progress/arrived, 6 unassigned, 7 accepted/acknowledged, 8 declined, 9 cancelled, 10 deleted.",
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        },
        {
          "type": "number",
          "const": 4
        },
        {
          "type": "number",
          "const": 6
        },
        {
          "type": "number",
          "const": 7
        },
        {
          "type": "number",
          "const": 8
        },
        {
          "type": "number",
          "const": 9
        },
        {
          "type": "number",
          "const": 10
        }
      ]
    },
    "fleet_id": {
      "description": "Only tasks of this agent (from list_agents).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "team_id": {
      "description": "Only tasks of this team (from list_teams).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "customer_id": {
      "description": "Only tasks of this customer (from list_customers).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "job_ids": {
      "description": "Only these task (job) ids.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "order_ids": {
      "description": "Only tasks with these order ids (your own reference).",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "custom_fields": {
      "description": "Include the tasks' custom-field data.",
      "type": "boolean"
    },
    "page": {
      "default": 1,
      "description": "Page number (default 1). Tookan pages are a fixed size.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 10000
    }
  },
  "required": [
    "job_type",
    "start_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Full details of up to 100 tasks by job id: customer, addresses, agent (fleet_id/fleet_name), status, timestamps (started/arrived/completed), tracking link, custom fields; optionally the status history. Task status codes: 0 assigned, 1 started, 2 successful, 3 failed, 4 in progress/arrived, 6 unassigned, 7 accepted/acknowledged, 8 declined, 9 cancelled, 10 deleted. POST /v2/get_job_details.

{
  "type": "object",
  "properties": {
    "job_ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      },
      "description": "Task (job) ids, e.g. [5145]."
    },
    "include_task_history": {
      "description": "Include each task's status history.",
      "type": "boolean"
    },
    "include_additional_info": {
      "description": "Include the job's additional info.",
      "type": "boolean"
    }
  },
  "required": [
    "job_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Full details of the tasks carrying the given order ids (the reference you set when creating a task). POST /v2/get_job_details_by_order_id.

{
  "type": "object",
  "properties": {
    "order_ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Order ids, e.g. [\"P000469\"]."
    },
    "include_task_history": {
      "description": "Include each task's status history.",
      "type": "boolean"
    }
  },
  "required": [
    "order_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Task counts per status (e.g. successful vs failed), optionally for one task type, one team and a date range. Task status codes: 0 assigned, 1 started, 2 successful, 3 failed, 4 in progress/arrived, 6 unassigned, 7 accepted/acknowledged, 8 declined, 9 cancelled, 10 deleted. POST /v2/user_task_stats.

{
  "type": "object",
  "properties": {
    "job_status": {
      "description": "Only these statuses, e.g. [2, 3].",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "number",
            "const": 0
          },
          {
            "type": "number",
            "const": 1
          },
          {
            "type": "number",
            "const": 2
          },
          {
            "type": "number",
            "const": 3
          },
          {
            "type": "number",
            "const": 4
          },
          {
            "type": "number",
            "const": 6
          },
          {
            "type": "number",
            "const": 7
          },
          {
            "type": "number",
            "const": 8
          },
          {
            "type": "number",
            "const": 9
          },
          {
            "type": "number",
            "const": 10
          }
        ]
      }
    },
    "job_type": {
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        }
      ],
      "description": "Task type: 0 = pickup, 1 = delivery, 2 = appointment, 3 = field workforce (FOS)."
    },
    "start_date": {
      "description": "Start date, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "description": "End date, YYYY-MM-DD.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "team_id": {
      "description": "Only tasks of this team.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List agents (drivers / field workers; Tookan calls them fleets) with fleet_id, name, phone, tags, team and live status (0 available, 1 offline, 2 busy). Filter by name, tags, availability or fleet ids. The API returns the whole list; this tool returns a window (limit/offset, next_offset). POST /v2/get_all_fleets.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Only agents whose name matches this text.",
      "type": "string"
    },
    "tags": {
      "description": "Comma-separated agent tags, e.g. \"mini,suv\".",
      "type": "string"
    },
    "match_any_tag": {
      "description": "With tags: true = agents having ANY of the tags, false = ALL of them.",
      "type": "boolean"
    },
    "status": {
      "description": "0 = only free agents, 1 = only busy agents.",
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        }
      ]
    },
    "fleet_type": {
      "description": "1 = captive agents, 2 = freelancers.",
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        }
      ]
    },
    "fleet_ids": {
      "description": "Only these agent ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "include_team_id": {
      "description": "Include each agent's team id.",
      "type": "boolean"
    },
    "limit": {
      "default": 50,
      "description": "Max items to return (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 0,
      "description": "Items to skip (use next_offset from the previous call).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One agent's profile (name, email, phone, tags, transport, location, rating, active state) and current tasks. Only profile fields are returned; app tokens and password hashes never are. POST /v2/view_fleet_profile.

{
  "type": "object",
  "properties": {
    "fleet_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Agent id (fleet_id from list_agents)."
    }
  },
  "required": [
    "fleet_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

An agent's last known coordinates (latitude/longitude). POST /v2/get_fleet_location.

{
  "type": "object",
  "properties": {
    "fleet_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Agent id (fleet_id from list_agents)."
    }
  },
  "required": [
    "fleet_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List teams (team_id, name, address, tags). With include_agents, each team also lists its agents. Returns a window (limit/offset, next_offset). POST /v2/view_all_team_only (or /v2/view_teams with agents).

{
  "type": "object",
  "properties": {
    "include_agents": {
      "description": "Also return each team's agents (larger reply).",
      "type": "boolean"
    },
    "limit": {
      "default": 50,
      "description": "Max items to return (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "default": 0,
      "description": "Items to skip (use next_offset from the previous call).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customers (customer_id, name, phone, email, address), optionally searched by name or phone. Paginated: one Tookan page per call (page, default 1). POST /v2/get_all_customers.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Search by customer name.",
      "type": "string"
    },
    "phone": {
      "description": "Search by customer phone number.",
      "type": "string"
    },
    "page": {
      "default": 1,
      "description": "Page number (default 1). Tookan pages are a fixed size.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 10000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find customers by exact phone number. POST /v2/find_customer_with_phone.

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "minLength": 3,
      "description": "Phone number, e.g. \"9897416008\" or \"+19897416008\"."
    }
  },
  "required": [
    "phone"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer's profile (contact details, address, coordinates). POST /v2/view_customer_profile.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Customer id (from list_customers)."
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a delivery task (job) for a customer address, due by job_delivery_datetime in the given timezone. Optionally assign it to an agent (fleet_id) or team, or let Tookan auto-assign it within the team. Returns job_id and tracking link. Always uses the address given here, not one saved for the customer's phone (ignore_customer_lat_long 1). POST /v2/create_task (has_pickup 0, has_delivery 1, layout_type 0).

{
  "type": "object",
  "properties": {
    "customer_address": {
      "type": "string",
      "minLength": 1,
      "description": "Delivery address."
    },
    "job_delivery_datetime": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}(:\\d{2})?$",
      "description": "Deliver before this local time, YYYY-MM-DD HH:MM:SS."
    },
    "timezone": {
      "type": "integer",
      "minimum": -840,
      "maximum": 720,
      "description": "Minutes to ADD to local time to get UTC (Tookan's convention): IST = -330, CET = -60, EST = 300, PST = 480."
    },
    "customer_username": {
      "description": "Customer name.",
      "type": "string"
    },
    "customer_phone": {
      "description": "Customer phone, e.g. \"+12015555555\".",
      "type": "string"
    },
    "customer_email": {
      "description": "Customer email.",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "order_id": {
      "description": "Your own reference for the task.",
      "type": "string"
    },
    "job_description": {
      "description": "What is to be delivered.",
      "type": "string"
    },
    "latitude": {
      "description": "Delivery latitude (else Tookan geocodes the address).",
      "type": "string"
    },
    "longitude": {
      "description": "Delivery longitude.",
      "type": "string"
    },
    "team_id": {
      "description": "Team to put the task in (from list_teams).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "fleet_id": {
      "description": "Agent to assign the task to (from list_agents).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "auto_assignment": {
      "description": "Let Tookan auto-assign the task to an agent of team_id.",
      "type": "boolean"
    },
    "tags": {
      "description": "Comma-separated agent tags used by auto-assignment.",
      "type": "string"
    },
    "notify": {
      "description": "Send the customer/agent notifications.",
      "type": "boolean"
    }
  },
  "required": [
    "customer_address",
    "job_delivery_datetime",
    "timezone"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: assign (or reassign) a task to an agent of a team; replaces any previous agent. Notifies the agent unless notify is false (so repeating the call notifies again). POST /v2/assign_fleet_to_task.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task (job) id."
    },
    "fleet_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Agent id (from list_agents)."
    },
    "team_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The agent's team id (from list_teams)."
    },
    "notify": {
      "description": "Notify the agent (default true).",
      "type": "boolean"
    }
  },
  "required": [
    "job_id",
    "fleet_id",
    "team_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE (DESTRUCTIVE): force a task's status, overriding the agent app. Completing (2 successful, 3 failed) or cancelling (9) closes the task and notifies per the account's settings; confirm with the user first. Deleting (10) is not offered. Settable: 0 assigned, 1 started, 2 successful, 3 failed, 4 arrived, 6 unassigned, 7 accepted, 8 declined, 9 cancelled. POST /v2/update_task_status.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task (job) id."
    },
    "job_status": {
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        },
        {
          "type": "number",
          "const": 4
        },
        {
          "type": "number",
          "const": 6
        },
        {
          "type": "number",
          "const": 7
        },
        {
          "type": "number",
          "const": 8
        },
        {
          "type": "number",
          "const": 9
        }
      ],
      "description": "New status code (0-4, 6-9; 10 deleted is not allowed)."
    }
  },
  "required": [
    "job_id",
    "job_status"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}