> ## Documentation Index
> Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom function examples

> Ready-to-adapt Bolna custom function schemas for GET and POST APIs you can copy into your voice agent.

Complete [custom function](/docs/tool-calling/custom-function-calls) schemas you can adapt. Each field is documented in the [schema reference](/docs/tool-calling/custom-function-schema).

<Note>
  The following examples use **illustrative endpoints and credentials** to demonstrate the schema structure. Replace the URLs, tokens, and parameter values with your own API details when implementing.
</Note>

<Tabs>
  <Tab title="GET Requests">
    <AccordionGroup>
      <Accordion title="Check Order Status">
        A customer calls and asks *"Where is my order?"* The agent collects the order ID and fetches the status from your backend.

        **What the agent says:** *"Let me check the status of your order."*

        **What Bolna sends:**

        ```bash theme={"system"}
        curl --location 'https://api.yourstore.com/orders?order_id=ORD-78234' \
        --header 'Authorization: Bearer sk_live_abc123'
        ```

        **Function schema:**

        ```json theme={"system"}
        {
          "name": "check_order_status",
          "description": "Use this function when the customer asks about their order status, delivery update, shipping progress, or tracking information. The customer must provide their order ID.",
          "pre_call_message": "Let me check the status of your order.",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "description": "The customer's order ID. Usually starts with ORD- followed by numbers, e.g., ORD-78234."
              }
            },
            "required": ["order_id"]
          },
          "key": "custom_task",
          "value": {
            "method": "GET",
            "param": {
              "order_id": "%(order_id)s"
            },
            "url": "https://api.yourstore.com/orders",
            "api_token": "Bearer sk_live_abc123",
            "headers": {}
          }
        }
        ```

        **Example API response the LLM receives:**

        ```json theme={"system"}
        {
          "order_id": "ORD-78234",
          "status": "shipped",
          "estimated_delivery": "March 15, 2026",
          "tracking_number": "1Z999AA10123456784"
        }
        ```

        The agent would then say something like: *"Your order ORD-78234 has been shipped and is expected to arrive by March 15th. Your tracking number is 1Z999AA10123456784."*
      </Accordion>

      <Accordion title="Look Up Account Balance">
        A customer calls and asks *"What's my current balance?"* The agent verifies their identity using their registered phone number and account ID, then fetches the balance.

        **What the agent says:** *"Let me pull up your account details."*

        **What Bolna sends:**

        ```bash theme={"system"}
        curl --location 'https://api.yourbank.com/accounts/balance?account_id=ACC-991042&phone=%2B919876543210' \
        --header 'Authorization: Bearer fin_api_key_001' \
        --header 'X-Request-Source: voice-agent'
        ```

        **Function schema:**

        ```json theme={"system"}
        {
          "name": "get_account_balance",
          "description": "Use this function when the customer asks about their account balance, available credit, remaining amount, or account summary. Requires the customer's account ID and phone number for verification.",
          "pre_call_message": "Let me pull up your account details.",
          "parameters": {
            "type": "object",
            "properties": {
              "account_id": {
                "type": "string",
                "description": "The customer's account ID, usually starts with ACC- followed by numbers."
              },
              "phone": {
                "type": "string",
                "description": "The customer's registered phone number for identity verification."
              }
            },
            "required": ["account_id", "phone"]
          },
          "key": "custom_task",
          "value": {
            "method": "GET",
            "param": {
              "account_id": "%(account_id)s",
              "phone": "%(phone)s"
            },
            "url": "https://api.yourbank.com/accounts/balance",
            "api_token": "Bearer fin_api_key_001",
            "headers": {
              "X-Request-Source": "voice-agent"
            }
          }
        }
        ```

        **Example API response the LLM receives:**

        ```json theme={"system"}
        {
          "account_id": "ACC-991042",
          "name": "Rahul Verma",
          "current_balance": 24500.75,
          "currency": "INR",
          "last_transaction": "2026-03-12"
        }
        ```

        The agent would then say something like: *"Your current account balance is Rs. 24,500.75. Your last transaction was on March 12th."*

        <Tip>
          The `phone` parameter can be auto-injected using the `{{from_number}}` [context variable](/docs/prompting/using-context), so the caller does not need to repeat their number.
        </Tip>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="POST Requests">
    <AccordionGroup>
      <Accordion title="Book an Appointment">
        A caller wants to schedule a consultation. The agent collects their name, preferred date, and time, then creates the booking.

        **What the agent says:** *"I'm booking that appointment for you now."*

        **What Bolna sends:**

        ```bash theme={"system"}
        curl --location 'https://api.yourclinic.com/v1/appointments' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer clinic_token_xyz' \
        --data '{
            "patient_name": "Priya Sharma",
            "preferred_date": "2026-03-20",
            "preferred_time": "10:30 AM",
            "reason": "General consultation"
        }'
        ```

        **Function schema:**

        ```json theme={"system"}
        {
          "name": "book_appointment",
          "description": "Use this function when the caller wants to book, schedule, or set up an appointment, consultation, or visit. Collect the patient's name, their preferred date and time, and the reason for the visit.",
          "pre_call_message": "I'm booking that appointment for you now.",
          "parameters": {
            "type": "object",
            "properties": {
              "patient_name": {
                "type": "string",
                "description": "Full name of the patient"
              },
              "preferred_date": {
                "type": "string",
                "description": "Preferred appointment date in YYYY-MM-DD format"
              },
              "preferred_time": {
                "type": "string",
                "description": "Preferred time, e.g., '10:30 AM' or '2:00 PM'"
              },
              "reason": {
                "type": "string",
                "description": "Brief reason for the appointment, e.g., 'General consultation' or 'Follow-up'"
              }
            },
            "required": ["patient_name", "preferred_date", "preferred_time"]
          },
          "key": "custom_task",
          "value": {
            "method": "POST",
            "param": {
              "patient_name": "%(patient_name)s",
              "preferred_date": "%(preferred_date)s",
              "preferred_time": "%(preferred_time)s",
              "reason": "%(reason)s"
            },
            "url": "https://api.yourclinic.com/v1/appointments",
            "api_token": "Bearer clinic_token_xyz",
            "headers": {
              "Content-Type": "application/json"
            }
          }
        }
        ```

        <Note>
          The `reason` field is optional (not in the `required` array). If the caller mentions a reason, the LLM includes it. If not, it is skipped without asking.
        </Note>
      </Accordion>

      <Accordion title="Create a Support Ticket">
        A customer calls with a complaint or issue. The agent collects the details and creates a support ticket in your helpdesk system.

        **What the agent says:** *"I'm creating a support ticket for this issue right away."*

        **What Bolna sends:**

        ```bash theme={"system"}
        curl --location 'https://api.yourhelpdesk.com/tickets' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer helpdesk_key_789' \
        --data '{
            "caller_phone": "+919876543210",
            "issue_category": "billing",
            "description": "Customer was charged twice for their February subscription",
            "priority": "high"
        }'
        ```

        **Function schema:**

        ```json theme={"system"}
        {
          "name": "create_support_ticket",
          "description": "Use this function when the customer reports a problem, complaint, issue, or bug. Create a support ticket with the issue category, a summary of the problem, and priority level. The caller's phone number is automatically available.",
          "pre_call_message": "I'm creating a support ticket for this issue right away.",
          "parameters": {
            "type": "object",
            "properties": {
              "caller_phone": {
                "type": "string",
                "description": "The customer's phone number"
              },
              "issue_category": {
                "type": "string",
                "description": "Category of the issue: billing, technical, account, shipping, or other"
              },
              "description": {
                "type": "string",
                "description": "A brief summary of the customer's issue in 1-2 sentences"
              },
              "priority": {
                "type": "string",
                "description": "Priority level: low, medium, or high. Set to high if the customer is upset or the issue is time-sensitive."
              }
            },
            "required": ["caller_phone", "issue_category", "description"]
          },
          "key": "custom_task",
          "value": {
            "method": "POST",
            "param": {
              "caller_phone": "%(caller_phone)s",
              "issue_category": "%(issue_category)s",
              "description": "%(description)s",
              "priority": "%(priority)s"
            },
            "url": "https://api.yourhelpdesk.com/tickets",
            "api_token": "Bearer helpdesk_key_789",
            "headers": {
              "Content-Type": "application/json"
            }
          }
        }
        ```

        <Tip>
          The `caller_phone` can be auto-injected using [context variables](/docs/prompting/using-context). Add `{{from_number}}` to your agent prompt, and the LLM will use it automatically instead of asking the caller for their number.
        </Tip>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.