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

# Provision Phone Number

> Purchase and provision a phone number for your account

Purchase an available phone number and add it to your account. Use the Search Numbers endpoint first to find available numbers.

## Request Body

<ParamField body="phone_number" type="string" required>
  The phone number to provision from search results.

  **Example:** `+16045551234`
</ParamField>

<ParamField body="friendly_name" type="string">
  Display name for the number.

  **Example:** `Main Line`
</ParamField>

<ParamField body="agent_id" type="string">
  Agent UUID to assign to this number immediately.
</ParamField>

## Response

Returns the provisioned phone number object.

<ResponseField name="id" type="string">
  Unique identifier for this phone number.
</ResponseField>

<ResponseField name="phone_number" type="string">
  The phone number in E.164 format.
</ResponseField>

<ResponseField name="friendly_name" type="string">
  Display name.
</ResponseField>

<ResponseField name="agent_id" type="string">
  Assigned agent UUID (if any).
</ResponseField>

<ResponseField name="capabilities" type="object">
  Number capabilities: `voice`, `sms`, `mms`.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the number is active.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when provisioned.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/provision-phone-number \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number": "+16045551234",
      "friendly_name": "Main Line",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/provision-phone-number',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        phone_number: '+16045551234',
        friendly_name: 'Main Line',
        agent_id: '550e8400-e29b-41d4-a716-446655440000'
      }),
    }
  );

  const number = await response.json();
  console.log('Provisioned:', number.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/provision-phone-number',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'phone_number': '+16045551234',
          'friendly_name': 'Main Line',
          'agent_id': '550e8400-e29b-41d4-a716-446655440000'
      }
  )

  number = response.json()
  print(f"Provisioned: {number['id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "a1b2c3d4-5678-9012-3456-789012345678",
    "phone_number": "+16045551234",
    "friendly_name": "Main Line",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "capabilities": {
      "voice": true,
      "sms": true,
      "mms": true
    },
    "is_active": true,
    "provider": "signalwire",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json Error Response theme={null}
  {
    "error": {
      "code": "number_limit_reached",
      "message": "You have reached your phone number limit. Upgrade your plan to add more numbers."
    }
  }
  ```
</ResponseExample>