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
}