Phone numbers

Buy an extra number

Buys the offered number for the agent and adds its monthly price to the business’s bill, with the same checks as the dashboard. It costs money every month, so Idempotency-Key is required and accept_monthly_price_cents must repeat the offer’s price, or null for a free offer: anything else is a 400. Without the extra phone numbers add-on, from POST /billing/extra-numbers/checkout, a priced offer is a 409. A price that changed since the search is a 409 too; search again. Returns the claim at once; poll GET /phone-numbers/claims/ until its status is claimed or failed. Claims are limited to 3 an hour, 2 a day and 5 in 30 days, past which they are a 429.

POST

phone-numbers

extra

claims

Buy an extra number

curl --request POST \
  --url https://app.lobbystack.com/api/v1/phone-numbers/extra/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "offer_token": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "accept_monthly_price_cents": 4503599627370495
}
'

import requests

url = "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims"

payload = {
    "offer_token": "<string>",
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accept_monthly_price_cents": 4503599627370495
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    offer_token: '<string>',
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    accept_monthly_price_cents: 4503599627370495
  })
};

fetch('https://app.lobbystack.com/api/v1/phone-numbers/extra/claims', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offer_token' => '<string>',
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'accept_monthly_price_cents' => 4503599627370495
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims"

	payload := strings.NewReader("{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.lobbystack.com/api/v1/phone-numbers/extra/claims")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.lobbystack.com/api/v1/phone-numbers/extra/claims")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "pending",
    "phone_number": "<string>",
    "phone_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "replaces_phone_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "error": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

An API key from Settings > API keys (lsk_...), which acts on its own business, or a platform key from the PLATFORM_API_KEYS setting (lsp_...), which onboards and manages businesses. Scopes: business:read, business:write, calls:read, contacts:read, contacts:write, appointments:read, appointments:write, messages:read, knowledge:read, knowledge:write, webhooks:manage, billing:manage, phone_numbers:manage, team:manage, businesses:create, users:create, phone_numbers:purchase, partner:read, partner.businesses:write, partner.demos:write, partner.packages:write, partner.branding:write, partner.templates:write, partner.team:write, partner.billing:read, partner.billing:write. Only platform keys can hold businesses:create and users:create, and only a key a partner made in its console can hold the partner scopes, which the Partner endpoints use. Only a partner's owners grant partner.billing:read and partner.billing:write.

Headers

LobbyStack-Business

string<uuid>

The business a platform key acts on. Required with a platform key. A per-business key may leave it out; if it sends one, it must be the key's own business.

Idempotency-Key

string

required

Required. A unique value, up to 255 characters, that makes retries of this request safe.

Maximum string length: 255

Body

application/json

offer_token

string

required

An offer_token from POST /phone-numbers/extra/search.

Required string length: 1 - 4000

agent_id

string<uuid>

required

The agent whose calls the number takes.

accept_monthly_price_cents

integer | null

required

The offer's monthly_price.amount_cents, or null when its monthly_price is null. Anything else is a 400, so a script can't buy a number at a price it didn't read.

Required range: 0 <= x <= 9007199254740991

Response

Accepted

data

object

required

A request to buy a phone number for the business.

Show child attributes

Buy an extra number

curl --request POST \
  --url https://app.lobbystack.com/api/v1/phone-numbers/extra/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "offer_token": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "accept_monthly_price_cents": 4503599627370495
}
'

import requests

url = "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims"

payload = {
    "offer_token": "<string>",
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accept_monthly_price_cents": 4503599627370495
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    offer_token: '<string>',
    agent_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    accept_monthly_price_cents: 4503599627370495
  })
};

fetch('https://app.lobbystack.com/api/v1/phone-numbers/extra/claims', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offer_token' => '<string>',
    'agent_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'accept_monthly_price_cents' => 4503599627370495
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.lobbystack.com/api/v1/phone-numbers/extra/claims"

	payload := strings.NewReader("{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.lobbystack.com/api/v1/phone-numbers/extra/claims")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.lobbystack.com/api/v1/phone-numbers/extra/claims")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offer_token\": \"<string>\",\n  \"agent_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"accept_monthly_price_cents\": 4503599627370495\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "pending",
    "phone_number": "<string>",
    "phone_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "replaces_phone_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "error": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Get started

General

Agents

Settings

White label

API

AI assistants

API reference

Self-hosting

Buy an extra number

Authorizations

Headers

Body

Response