Call2Me Phone Provisioning API

openapi: 3.2.0
info:
  title: Call2Me Phone Provisioning API
  description: '# Call2Me Voice AI Platform API


    Programmatic interface to build, deploy and operate voice AI agents that can place

    and receive phone calls in real time. Designed to be consumed by humans **and** by

    AI agent frameworks (function-calling LLMs, MCP servers, automation platforms like

    Composio, Pipedream, Zapier, n8n).


    ## What you can do


    - **Place outbound calls** — give an agent a phone number to dial; the AI handles

    the conversation end-to-end and returns a transcript + recording.

    - **Manage AI agents** — create personalities, attach voices, system prompts,

    knowledge bases and post-call actions.

    - **Schedule calls** — one-shot or recurring (cron-like) outbound calls.

    - **Knowledge base (RAG)** — upload documents/URLs so the agent answers from your

    data with reduced hallucination.

    - **Inbound** — provision phone numbers that route to your agents.


    ## Common LLM tool-calling use cases


    | Goal | Endpoint |

    |------|----------|

    | "Call this person and read them this script" | `POST /v1/calls` |

    | "Schedule a follow-up tomorrow at 14:00" | `POST /v1/schedules` |

    | "Get the transcript of last call" | `GET /v1/calls/{id}` |

    | "Add this PDF to the agent''s brain" | `POST /v1/knowledge-base/{id}/sources` |


    ## Authentication


    Every request requires a Bearer token issued from the dashboard:


    ```

    Authorization: Bearer c2m_sk_xxxxxxxxxxxxxxxx

    ```


    Get your API key from the API Keys page.

    Keys are scoped per-workspace and can be rotated/revoked any time.


    ## Rate Limits


    | Plan | Requests/min | Concurrent Calls |

    |------|-------------|------------------|

    | Free | 60 | 1 |

    | Pro | 600 | 10 |

    | Enterprise | Unlimited | Unlimited |


    ## SDKs & Integrations


    - Python SDK

    - Node.js SDK

    - OpenAPI 3.1 spec: `/openapi.json` (use it to generate clients or register the

    service with AI tool platforms)


    ## Support


    - Email: support@call2me.app

    - Docs: https://docs.call2me.app

    - Discord: https://discord.gg/call2me'
  version: 1.0.0
  x-logo:
    url: https://call2me.app/logo.png
    altText: Call2Me Logo
  contact:
    name: Call2Me Support
    url: https://call2me.app/support
    email: support@call2me.app
  license:
    name: Commercial — see Terms of Service
    url: https://call2me.app/terms
  termsOfService: https://call2me.app/terms
servers:
- url: https://api.call2me.app
  description: Production
- url: http://localhost:8000
  description: Local Development
security:
- BearerAuth: []
tags:
- name: Phone Provisioning
paths:
  /v1/numbers/allowed-countries:
    get:
      tags:
      - Phone Provisioning
      summary: List Allowed Countries
      description: 'List countries where numbers can be purchased.


        Used by dashboard to populate the country dropdown.

        Returns only no-regulatory-requirement countries (no document upload needed).'
      operationId: list_allowed_countries_v1_numbers_allowed_countries_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Allowed Countries V1 Numbers Allowed Countries Get
  /v1/numbers/address-request:
    post:
      tags:
      - Phone Provisioning
      summary: Request Number With Address
      description: 'Adres/belge isteyen ülkede numara için concierge talebi (elle halledilir).


        Patrona event stream (relay) üzerinden Telegram''a düşer. Kullanıcı başına

        saatte en fazla 3 talep.'
      operationId: request_number_with_address_v1_numbers_address_request_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequestBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Request Number With Address V1 Numbers Address Request Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/search:
    get:
      tags:
      - Phone Provisioning
      summary: Search Available
      description: 'Search available numbers (Telnyx or Twilio).


        provider verilmezse ülkeye göre otomatik (US/CA→telnyx, diğer→twilio).

        Returns numbers with OUR sell price.'
      operationId: search_available_v1_numbers_search_get
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
          default: US
          title: Country
      - name: locality
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Locality
      - name: area_code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Area Code
      - name: phone_number_type
        in: query
        required: false
        schema:
          type: string
          default: local
          title: Phone Number Type
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/purchase:
    post:
      tags:
      - Phone Provisioning
      summary: Purchase Number
      description: 'Purchase a phone number from Telnyx, charge user, bind to their account.


        Security rules:

        - User must have made at least one paid top-up (not just signup bonus).

        Trial users cannot spend their bonus on number rentals.

        - Balance must cover upfront charge.

        - Only allowed countries (platform_settings.telnyx_allowed_countries).'
      operationId: purchase_number_v1_numbers_purchase_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/checkout:
    post:
      tags:
      - Phone Provisioning
      summary: Checkout Number
      description: 'Create a Paddle checkout session for buying a phone number.


        Flow for trial users (no paid top-up yet):

        1. Validate the number is still available on Telnyx.

        2. Create a pending_number_purchases row (soft lock, 30 min TTL).

        3. Open Paddle checkout with custom_data = {intent: ''BUY_NUMBER'', pending_id}.

        4. Webhook fires on payment → we order from Telnyx & bind to the user.


        Paid users should just use /purchase directly — this endpoint is explicitly

        for the first-time/no-balance path.'
      operationId: checkout_number_v1_numbers_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__routers__v1__phone_provisioning__CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/numbers/{phone_number}:
    delete:
      tags:
      - Phone Provisioning
      summary: Release Number
      description: Release a phone number (stops monthly billing).
      operationId: release_number_v1_numbers__phone_number__delete
      parameters:
      - name: phone_number
        in: path
        required: true
        schema:
          type: string
          title: Phone Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Release Number V1 Numbers  Phone Number  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AddressRequestBody:
      properties:
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO2
        company_name:
          type: string
          maxLength: 200
          minLength: 1
          title: Company Name
        contact_email:
          type: string
          format: email
          title: Contact Email
        note:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Note
      type: object
      required:
      - country
      - company_name
      - contact_email
      title: AddressRequestBody
    src__routers__v1__phone_provisioning__CheckoutResponse:
      properties:
        pending_id:
          type: string
          title: Pending Id
        paddle_transaction_id:
          type: string
          title: Paddle Transaction Id
        upfront_usd:
          type: number
          title: Upfront Usd
        monthly_usd:
          type: number
          title: Monthly Usd
        expires_at:
          type: string
          title: Expires At
      type: object
      required:
      - pending_id
      - paddle_transaction_id
      - upfront_usd
      - monthly_usd
      - expires_at
      title: CheckoutResponse
    AvailableNumber:
      properties:
        phone_number:
          type: string
          title: Phone Number
        country_code:
          type: string
          title: Country Code
        phone_number_type:
          type: string
          title: Phone Number Type
        telnyx_cost_usd:
          type: number
          title: Telnyx Cost Usd
        monthly_price_usd:
          type: number
          title: Monthly Price Usd
        upfront_price_usd:
          type: number
          title: Upfront Price Usd
        features:
          items:
            type: string
          type: array
          title: Features
        locality:
          anyOf:
          - type: string
          - type: 'null'
          title: Locality
        provider:
          type: string
          title: Provider
          default: telnyx
      type: object
      required:
      - phone_number
      - country_code
      - phone_number_type
      - telnyx_cost_usd
      - monthly_price_usd
      - upfront_price_usd
      - features
      title: AvailableNumber
    PurchaseResponse:
      properties:
        success:
          type: boolean
          title: Success
        phone_number:
          type: string
          title: Phone Number
        order_id:
          type: string
          title: Order Id
        monthly_price_usd:
          type: number
          title: Monthly Price Usd
        balance_after_usd:
          type: number
          title: Balance After Usd
        message:
          type: string
          title: Message
      type: object
      required:
      - success
      - phone_number
      - order_id
      - monthly_price_usd
      - balance_after_usd
      - message
      title: PurchaseResponse
    PurchaseRequest:
      properties:
        phone_number:
          type: string
          minLength: 8
          title: Phone Number
          description: E.164 format, e.g., +12125551234
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent to bind (optional)
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: telnyx | twilio (auto by country if omitted)
      type: object
      required:
      - phone_number
      title: PurchaseRequest
    CheckoutRequest:
      properties:
        phone_number:
          type: string
          minLength: 8
          title: Phone Number
          description: E.164 format
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent to bind after purchase
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: telnyx | twilio (auto by country if omitted)
      type: object
      required:
      - phone_number
      title: CheckoutRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SearchResponse:
      properties:
        numbers:
          items:
            $ref: '#/components/schemas/AvailableNumber'
          type: array
          title: Numbers
        total:
          type: integer
          title: Total
        requires_payment:
          type: boolean
          title: Requires Payment
          default: false
        upfront_price_usd:
          type: number
          title: Upfront Price Usd
          default: 0.0
        address_required:
          type: boolean
          title: Address Required
          default: false
      type: object
      required:
      - numbers
      - total
      title: SearchResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app