Answer calls on your number

Find a number

Search what is available to buy. Search covers US numbers; narrow it with area_code or with digits the number should contain.

curl "https://api.myleadsfactory.tech/api/phone-numbers/available?area_code=415&limit=5" \
  -H "Authorization: Bearer $MLF_API_KEY"

{
  "data": [
    { "phoneNumber": "+14155550123", "friendlyName": "(415) 555-0123", "countryCode": "US" }
  ]
}

Buy it

Buying registers the number in your project in the same step. An org-wide key also sends project_id.

curl -X POST https://api.myleadsfactory.tech/api/phone-numbers/purchase \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number": "+14155550123", "project_id": "'"$MLF_PROJECT_ID"'" }'

{
  "data": {
    "id": "pn_9a3c5e7b1d2f4a6c8e0b2d4f6a8c0e1b",
    "e164": "+14155550123",
    "provider": "twilio",
    "assistant_id": null,
    "status": "active"
  }
}

Already have a number? Import it instead with POST/api/phone-numbers. Importing records a number you already own; it does not buy anything. For a Twilio number, include its SID so the platform can route it:

{
  "e164": "+14155550123",
  "project_id": "proj_2f9c41d0a8b34e6f9d1c7a5b3e8f0a12",
  "provider_metadata": { "twilioNumberSid": "PN0123456789abcdef0123456789abcdef" }
}

As with purchase, project_id is required with an org-wide key and can be left out with a project key.

Attach the assistant

Attaching points the number's incoming calls at the assistant and applies the routing at the carrier. The number and the assistant must be in the same project.

curl -X POST https://api.myleadsfactory.tech/api/phone-numbers/pn_9a3c5e7b1d2f4a6c8e0b2d4f6a8c0e1b/attach \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "assistant_id": "asst_7d2e9b14c6a04f3e8b5d1a9c0e7f6b23", "routing_mode": "pv_webhook" }'

routing_mode is required and picks how calls reach the assistant:

Start with pv_webhook unless you know you want a SIP trunk. Switch later with POST/api/phone-numbers/{id}/mode; it re-applies the carrier settings.

Call it

Ring the number. The assistant answers with its first_message if it has one. Each call appears in GET/api/calls with call_type inbound, and fires the same call.started, call.connected and call.ended webhooks as an outbound call, with caller_number and called_number in the event data.