# provisionPhoneNumber

Buy a phone number from Twilio (a RECURRING monthly charge) and assign it to targetUserId. It shows at once in listCommunicationChannels, ready to send from. Confirm first: name the number, who gets it and the monthly charge. phoneNumber must be an E.164 number returned by searchAvailablePhoneNumbers (an unavailable number is rejected). targetUserId is normally the key owner (listCommunicationChannels.currentUser.id); a user outside your organization is rejected. A number past the phone numbers the plan includes adds $5/mo on top of the plan: it is refused (PHONE_NUMBER_ALLOWANCE_REFUSED) unless `confirmExtraPhoneNumberCharge` is true, which you send only once the person agreed to that extra charge. checkBillingAction tells you beforehand whether a number is included. ADMIN scope: the key owner must currently be an org admin. Idempotent: reuse an Idempotency-Key to make a retry safe.

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "provisionPhoneNumber", "variables": {...} }`
- Scope: `ADMIN`
- Type: mutation
- Idempotency: honors `Idempotency-Key` (24 h)
- Rate-limited: no

## Variables

- `phoneNumber`: `String!` (required)
- `targetUserId`: `ID!` (required)
- `confirmExtraPhoneNumberCharge`: `Boolean`

## Response (data, an example)

```json
{
  "twilioMutation": {
    "provisionPhoneNumber": {
      "id": "<ID>",
      "e164Number": "…",
      "isPrimary": true,
      "canSendSms": true
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "operationId": "provisionPhoneNumber",
    "variables": {
      "phoneNumber": "<String>",
      "targetUserId": "<targetUserId>"
    }
  }'
```