Numbers

Explore detailed documentation on utilizing our Phone Number Management API for comprehensive control over searching, booking, and managing your communication channels' phone numbers.

GET/api/numbers/available

Available Numbers

This endpoint lets you search for available phone numbers based on the provided search criteria. The search criteria can include the country code, area code, and the number type. The response will include a list of available phone numbers that match the search criteria.

Parameters

Name
country
Type
string
Optional
Optional
Description
The ISO 3166-1 alpha-2 country code of the country to search for available numbers in.
Name
features_sms
Type
boolean
Optional
Optional
Description
If set to true, only numbers that support SMS will be returned.
Name
features_a2p_sms
Type
boolean
Optional
Optional
Description
If set to true, only numbers that support A2P SMS will be returned.
Name
features_voice
Type
boolean
Optional
Optional
Description
If set to true, only numbers that support voice will be returned.

GET

/api/numbers/available

curl -X GET "https://gateway.seven.io/api/numbers/available?country=DK" \
    -H "x-api-key: YOUR_API_KEY"

{
    "availableNumbers": [
        {
            "country": "DK",
            "number": "4523854818",
            "number_parsed": "+45 23 85 48 18",
            "fees": {
                "monthly": {
                    "basic_charge": 29.9,
                    "setup": 19.9
                },
                "annually": {
                    "basic_charge": 238.8,
                    "setup": 9.9
                },
                "sms_mo": 0,
                "voice_mo": 0.01
            },
            "features": {
                "sms": true,
                "a2p_sms": true,
                "voice": true
            }
        },
        {
            // ...
        }
    ]
}

POST/api/numbers/order

Order a Number

Order a phone number by providing the desired number. The response will include the details of the number you ordered.

Parameters

Name
number
Type
phonenumber
Description
The phone number to order.
Name
payment_interval
Type
enum
Optional
Optional
Description
The payment interval for the number. Possible values are monthly and annually (default).

POST

/api/numbers/available

curl -X POST "https://gateway.seven.io/api/numbers/order" \
    -H "x-api-key: YOUR_API_KEY" \
    -d 'number=4523854818'

{
    "success": true,
    "error": null,
}

GET/api/numbers/active

Active numbers

Get a list of all active numbers that are currently associated with your account.

GET

/api/numbers/active

curl -X GET "https://gateway.seven.io/api/numbers/active" \
-H "x-api-key: YOUR_API_KEY"

{
    "activeNumbers": [
       {
            "country": "DE",
            "number": "4915170264838",
            "friendly_name": "",
            "billing": {
                "fees": {
                    "setup": 19.9,
                    "basic_charge": 238.8,
                    "sms_mo": 0,
                    "voice_mo": 0
                },
                "payment_interval": "annually"
            },
            "features": {
                "sms": true,
                "a2p_sms": false,
                "voice": true
            },
            "forward_sms_mo": {
                "sms": {
                    "number": [
                        "4917612345678"
                    ],
                    "enabled": true
                },
                "email": {
                    "address": [
                        "j.doe@acme.inc",
                        "john@doe.com"
                    ],
                    "enabled": true
                }
            },
            "expires": null,
            "created": "2024-01-31 17:06:27"
        },
        {
            // ...
        }
    ]
}

GET/api/numbers/active/:number

Get single active number

Get a single active number by providing the phone number.

Path Parameters

Name
number
Type
phonenumber
Description
The phone number to get details for.

GET

/api/numbers/active/49176123456789

curl -X GET "https://gateway.seven.io/api/numbers/active/49176123456789" \
    -H "x-api-key: YOUR_API_KEY"

{
    "country": "DE",
    "number": "49176123456789",
    "friendly_name": "",
    "billing": {
        "fees": {
            "setup": 19.9,
            "basic_charge": 238.8,
            "sms_mo": 0,
            "voice_mo": 0
        },
        "payment_interval": "annually"
    },
    "features": {
        "sms": true,
        "a2p_sms": false,
        "voice": true
    },
    "forward_sms_mo": {
        "sms": {
            "number": [
                "4917612345678"
            ]
            "enabled": true
        },
        "email": {
            "address": [
                "j.doe@acme.inc",
                "john@doe.com"
            ],
            "enabled": true
        }
    },
    "expires": null,
    "created": "2024-01-31 17:06:27"
}

PATCH/api/numbers/active/:number

Update number

Update the details of a single active number by providing the phone number. Currently you can update the friendly name and whether or not you would like to forward incoming SMS via SMS or email. As response you will get the updated number details.

Path Parameters

Name
number
Type
phonenumber
Description
The phone number to update details for.

Parameters

Name
friendly_name
Type
string
Optional
Optional
Description
The updated friendly name for the number.
Name
sms_forward
Type
array
Optional
Optional
Description
The phone number to forward incoming SMS to. If empty, incoming SMS won't be forwarded by SMS.
Name
email_forward
Type
array
Optional
Optional
Description
The email address to forward incoming SMS to. If empty, incoming SMS won't be forwarded by email.

PATCH

/api/numbers/active/49176123456789

curl -X PATCH "https://gateway.seven.io/api/numbers/active/49176123456789" \
    -H "x-api-key: YOUR_API_KEY" \
    -d 'friendly_name=New Friendly Name'

{
    "country": "DE",
    "number": "49176123456789",
    "friendly_name": "New Friendly Name",
    "billing": {
        "fees": {
            "setup": 19.9,
            "basic_charge": 238.8,
            "sms_mo": 0,
            "voice_mo": 0
        },
        "payment_interval": "annually"
    },
    "features": {
        "sms": true,
        "a2p_sms": false,
        "voice": true
    },
    "forward_sms_mo": {
        "sms": {
            "number": "49176123456789",
            "enabled": true
        },
        "email": {
            "address": [
                "j.doe@acme.inc",
                "john@doe.com"
            ],
            "enabled": true
        }
    },
    "expires": null,
    "created": "2024-01-31 17:06:27"
}

DELETE/api/numbers/active/:number

Delete number

Delete a single active number by providing the phone number.

Path Parameters

Name
number
Type
phonenumber
Description
The phone number to delete.

Parameters

Name
delete_immediately
Type
boolean
Optional
Optional
Description
If set to true, the number will be deleted immediately. If set to false, the number will be deleted at the end of the current billing period.

DELETE

/api/numbers/active/49176123456789

curl -X DELETE "https://gateway.seven.io/api/numbers/active/49176123456789" \
    -H "x-api-key: YOUR_API_KEY"

{
    "success": true
}