Introduction

We provide API access to white label our phone service inside your own customer accounts. The API Process looks something like this:

We provide you with a Bearer Token so that you can make authenticated requests. If you need a token, please email sales@gbpn.com.

You make a request to check the availability of phone numbers per area code, or toll-free prefixes.

You make an authenticated request to add a user to the system. This request will require the following:

• Business Name
• Desired New Phone Number
• Existing Phone Number to send calls to
• Email Address of the customer
• Customer Timezone

This will create a user account (the end customer won't know this) on our system, create a business in that account, and assign the phone number to that business. Because you used an authentication key, it will remember that this new user account belongs to your affiliate account. It will also set up some sane default behavior:

• Make it so that the calls to the new number, ring through to the existing number.
• If no answer, send it to a default voicemail box

Once you have created a new user account for your customer, we provide an API endpoint to get an Authorization token per user account to make requests on behalf of the end user.

Items that can be configured via the API are:

• Business Hours/Time Conditions - during specified times, do different things.
• Send calls to multiple phone numbers.
• Play announcements, where it doesn't ever send to another number - for informational lines.
• Menu System/IVR - Press 1 for Sales, Press 2 for Support.
• Authorized Outbound Callers

Once things are configured, we can also send webhooks for specific events:

• Incoming Phone Call
• Outgoing Phone Call
• Call Finished
• Voicemail Received

Available Phone Numbers

curl "https://gbpn.com/api/available-phone-numbers?area_code=509"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

//// returns up to 30 results

// local
{
    "data": [
        {
           "friendly_name": "(509) 303-4931",
           "phone_number": "+15093034931",
           "locality": "Prosser",
           "region": "WA"
       },
    ]
}

// toll_free
{
    "data": [
        {
            "friendly_name": "(833) 537-1049",
            "phone_number": "+18335371049"
       },
    ]
}

curl "https://gbpn.com/api/available-phone-numbers?area_code=509&pattern=931"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

// returns up to 30 results
{
    "data": [
        {
           "friendly_name": "(509) 303-4931",
           "phone_number": "+15093034931",
           "locality": "Prosser",
           "region": "WA",
           "highlighted": "+15093034|931|" // Only returned if using the pattern parameter
       },
    ]
}

Use this API to see available phone numbers

HTTP Request

GET https://gbpn.com/api/available-phone-numbers

URL Parameters

Authorization

To authorize, use this code:

curl "api_endpoint_here"
    -H "Authorization: Bearer <token>"

Make sure to replace <token> with your API key.

GBPN expects the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <token>

Affiliate

Register Account

curl "https://gbpn.com/api/register"
    -X POST
    -H "Authorization: Bearer <your-token>"
    -d 'selected_phone_number=+15097743788'
    -d 'name=API TESTER'
    -d 'timezone=America/Chicago'
    -d 'phone=111-222-3333'
    -d 'email=foobar11@example.com'
    -d 'team=Acme, Inc.'
    -d 'plan=plan-name'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "access_token": "<user-token>",
        "user_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
}

Use this API to create an account

HTTP Request - Authorization Required

POST https://gbpn.com/api/register

POST Parameters

Account Login

curl "https://gbpn.com/api/auth"
    -X POST
    -d 'email=frodo@theshire.com'
    -d 'password=samismybestfriend'

The above command returns JSON structured like this:

{
    "success": true,
    "user": {
        "name": "Frodo Baggins",
        "email": "frodo@theshire.com"
    },
    "bearer_token": "<bearer-token>",
    "app_auth_token": "<app-token>"
}

Use this API login and get your bearer_token

HTTP Request

POST https://gbpn.com/api/auth

POST Parameters

Get Access Token

curl "https://gbpn.com/api/tokens/{user_uuid}"
    -H "Authorization: Bearer <your-token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "access_token": "<user-token>"
    }
}

Use this API to get the user access token

HTTP Request - Authorization Required

GET https://gbpn.com/api/tokens/{user_uuid}

URL Parameters

Who am I

curl "https://gbpn.com/api/who-am-i"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "Frodo Baggins",
        "email": "frodobaggins@the.shire",
        "companies": [
            {
                "uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                "name": "The Fellowship of The Ring",
                "phone_numbers": [
                    "+18448222255"
                ],
                "timezone": "America/Los_Angeles"
            }
        ]
    }
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/who-am-i

URL Parameters

None

Voicemails

List Voicemails

curl "https://gbpn.com/api/voicemail"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "success": true,
    "data": [
        {
            "id": "XXXXXXXXXXXX",
            "date": "2019-09-27 01:27:21",
            "caller": "+15554443333",
            "url": "https://gbpn.com/voicemail/XXXXXXXXXXXX/download"
        }
    ]
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/voicemail

URL Parameters

Delete Voicemail

curl "https://gbpn.com/api/voicemail/{voicemail_id}"
    -X DELETE
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1
}

HTTP Request - Authorization Required

DELETE https://gbpn.com/api/voicemail/{voicemail_id}

POST Parameters

None

Calls

List Call Records

curl "https://gbpn.com/api/calls"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": [
        {
            "from": "+15555555555",
            "to": "+18448222255",
            "status": "completed",
            "direction": "inbound",
            "forwarded_from": null,
            "from_city": "Spokane",
            "from_state": "WA",
            "from_zip": "99201",
            "from_country": "US",
            "to_city": "LIBERTY LAKE",
            "to_state": "WA",
            "to_zip": "99019",
            "to_country": "US",
            "duration": 5,
            "created_at": "2020-02-06 17:34:46"
        }
    ]
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/calls

URL Parameters

Destinations

Phone Number Destinations

curl "https://gbpn.com/api/destinations"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'name=Test Phone Number'
    -d 'call_forwarding[phone_numbers][]=555-444-3333'
    -d 'call_forwarding[enable_call_screening]=1'
    -d 'call_forwarding[enable_call_alerts]=1'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 2,
        "name": "Test Phone Number",
        "is_default": 0,
        "call_forwarding": {
            "enable_call_screening": true,
            "enable_call_alerts": true,
            "phone_numbers": [
                "+15554443333"
            ]
        }
    }
}

Available options for creating or updating Phone Number Destination

Available Parameters

Voicemail Destination

curl "https://gbpn.com/api/destinations"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'name=Test Voicemail'
    -d 'voicemail[message]=leave a message'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 271,
        "name": "Test Voicemail",
        "is_default": 0,
        "voicemail": {
            "message": "leave a message"
        }
    }
}

Available options for creating or updating Voicemail Destination

Available Parameters

Automated Attendant Destination

curl "https://gbpn.com/api/destinations"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'name=Test Automated Attendant'
    -d 'automated_attendant[message]=Press 1 for sales. Press 2 for Support.'
    -d 'automated_attendant[concluded_destination_id]=3'
    -d 'automated_attendant[concluded_destination_message]=Please select an option.'
    -d 'automated_attendant[options][0][key]=1'
    -d 'automated_attendant[options][0][destination_id]=1'
    -d 'automated_attendant[options][1][key]=2'
    -d 'automated_attendant[options][1][destination_id]=2'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 1,
        "name": "Test Automated Attendant",
        "is_default": 0,
        "automated_attendant": {
            "message": "Press 1 for sales. Press 2 for support.",
            "concluded_destination_id": 3,
            "concluded_destination_message": "Please select an option.",
            "options": [
                {
                    "key": 1,
                    "destination_id": 1
                },
                {
                    "key": 2,
                    "destination_id": 2
                }
            ]
        }
    }
}

Available options for creating or updating Automated Attendant Destination

Available Parameters

List Destinations

curl "https://gbpn.com/api/destinations/{?id}"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": [
        {
            "id": 1,
            "name": "Forward to 844-822-2255",
            "is_default": 0,
            "phone_numbers": {
                "enable_call_screening": true,
                "enable_call_alerts": true,
                "phone_numbers": [
                    "+18448222255"
                ]
            }
        },
        {
            "id": 2,
            "name": "Voicemail",
            "is_default": 1,
            "voicemail": {
                "message": "Thank You for calling GBPN, We are unable to answer the phone right now. Please leave your name and a brief message."
            }
        }
    ]
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/destinations/{?id}

URL Parameters

Create Destinations

curl "https://gbpn.com/api/destinations"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'name=Test Voicemail'
    -d 'voicemail[message]=leave a message'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 1,
        "name": "Test Voicemail",
        "is_default": 0,
        "voicemail": {
            "message": "leave a message"
        }
    }
}

HTTP Request - Authorization Required

POST https://gbpn.com/api/destinations/

POST Parameters

Update Destinations

curl "https://gbpn.com/api/destinations"
    -X PATCH
    -H "Authorization: Bearer <token>"
    -d 'name=Test Voicemail 2'
    -d 'voicemail[message]=please leave a message'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 1,
        "name": "Test Voicemail 2",
        "is_default": 0,
        "voicemail": {
            "message": "please leave a message"
        }
    }
}

HTTP Request - Authorization Required

PATCH https://gbpn.com/api/destinations/{id}

POST Parameters

Delete Destinations

curl "https://gbpn.com/api/destinations/{id}"
    -X DELETE
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1
}

HTTP Request - Authorization Required

DELETE https://gbpn.com/api/destinations/{id}

POST Parameters

None

Authorized Numbers

List Authorized Numbers

curl "https://gbpn.com/api/authorized-numbers"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": [
        {
            "id": 1,
            "phone_number": "8448222255"
        }
    ]
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/authorized-numbers

URL Parameters

None

Create Authorized Numbers

curl "https://gbpn.com/api/authorized-numbers"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'phone_number=8448222255'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "phone_number": "8448222255",
        "id": 1
    }
}

HTTP Request - Authorization Required

POST https://gbpn.com/api/authorized-numbers

POST Parameters

Delete Authorized Numbers

curl "https://gbpn.com/api/authorized-numbers/{id}"
    -X DELETE
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1
}

HTTP Request - Authorization Required

DELETE https://gbpn.com/api/authorized-numbers/{id}

POST Parameters

None

Business Hours

List Business Hours

curl "https://gbpn.com/api/business-hours"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": [
        {
            "id": 1,
            "destination_id": 1,
            "name": "Standard Business Hours",
            "timezone": "America/Los_Angeles",
            "schedule": {
                "sunday": {
                    "disabled": true
                },
                "monday": {
                    "start": "09:00",
                    "end": "17:00"
                },
                "tuesday": {
                    "start": "09:00",
                    "end": "17:00"
                },
                "wednesday": {
                    "start": "09:00",
                    "end": "17:00"
                },
                "thursday": {
                    "start": "09:00",
                    "end": "17:00"
                },
                "friday": {
                    "start": "09:00",
                    "end": "17:00"
                },
                "saturday": {
                    "disabled": true
                }
            }
        }
    ]
}

HTTP Request - Authorization Required

GET https://gbpn.com/api/business-hours

URL Parameters

None

Create Business Hours

curl "https://gbpn.com/api/business-hours"
    -X POST
    -H "Authorization: Bearer <token>"
    -d 'destination_id=1'
    -d 'name=Normal Hours'
    -d 'timezone=pst'
    -d 'schedule[monday][start]=0800'
    -d 'schedule[monday][end]=1700'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 1,
        "name": "Normal Hours",
        "destination_id": "1",
        "timezone": "pst",
        "schedule": {
            "sunday": {
                "disabled": true
            },
            "monday": {
                "start": "08:00",
                "end": "17:00"
            },
            "tuesday": {
                "disabled": true
            },
            "wednesday": {
                "disabled": true
            },
            "thursday": {
                "disabled": true
            },
            "friday": {
                "disabled": true
            },
            "saturday": {
                "disabled": true
            }
        }
    }
}

HTTP Request - Authorization Required

POST https://gbpn.com/api/business-hours

POST Parameters

Update Business Hours

curl "https://gbpn.com/api/business-hours/{id}"
    -X PATCH
    -H "Authorization: Bearer <token>"
    -d 'destination_id=1'
    -d 'name=Normal Hours'
    -d 'timezone=pst'
    -d 'schedule[monday][start]=0800'
    -d 'schedule[monday][end]=1800'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "id": 1,
        "name": "Normal Hours",
        "destination_id": "1",
        "timezone": "pst",
        "schedule": {
            "sunday": {
                "disabled": true
            },
            "monday": {
                "start": "08:00",
                "end": "18:00"
            },
            "tuesday": {
                "disabled": true
            },
            "wednesday": {
                "disabled": true
            },
            "thursday": {
                "disabled": true
            },
            "friday": {
                "disabled": true
            },
            "saturday": {
                "disabled": true
            }
        }
    }
}

HTTP Request - Authorization Required

PATCH https://gbpn.com/api/business-hours/{id}

POST Parameters

Delete Business Hours

curl "https://gbpn.com/api/business-hours/{id}"
    -X DELETE
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "success": "true"
    }
}

HTTP Request - Authorization Required

DELETE https://gbpn.com/api/business-hours/{id}

POST Parameters

None

Account Cancellation

curl "https://gbpn.com/api/cancel"
    -X POST
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "status": 1,
    "data": "XXXXXXXXXXXXX"
}

HTTP Request - Authorization Required

POST https://gbpn.com/api/cancel

POST Parameters

Webhooks

Set Webhook URL

curl "https://gbpn.com/api/webhook"
    -X PUT
    -H "Authorization: Bearer <token>"
    -d 'url=https://example.com/webhook'

The above command returns JSON structured like this:

{
    "status": 1,
    "data": {
        "secret": "XXXXXXXXXXXXXXXX"
    }
}

Use this API to set the url to send webhooks to

HTTP Request

PUT https://gbpn.com/api/webhook

PUT Parameters

Errors

The GBPN API uses the following error codes:

curl "https://gbpn.com/api/abcdefg"
    -H "Authorization: Bearer <token>"

The above command returns JSON structured like this:

{
    "success": false,
    "message": "Route not found.",
    "errors": null
}