JSON API for Managing Number Portability

Requests

This request has multiple formats in which it can be sent:

{
    "request": "get_series",
    "node": "npdb",
    "params": {}
}
{
    "request": "get_series",
    "node": "npdb",
    "params": {
        "limit": "Integer. Number of series to return.",
        "offset": "Optional, integer, default is 0. The starting point to return series."
    }
}
{
    "request": "get_series",
    "node": "npdb",
    "params": {
        "series_start": "Integer. The starting MSISDN for this series.",
        "series_end": "Integer. The ending MSISDN for this series."
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "count": "The number of series."
}
{
    "code": 0,
    "series": [
        {
            "series_start": "The starting MSISDN for this series.",
            "series_end": "The ending MSISDN for this series.",
            "target": "The code associated to the operator where the number was ported.",
            "description": "Description for this series."
        }
    ]
}
{
    "code": 0,
    "series": [
        {
            "series_start": "The starting MSISDN for this series.",
            "series_end": "The ending MSISDN for this series.",
            "target": "The code associated to the operator where the number was ported.",
            "description": "Description for this series."
        }
    ]
}

Errors

{
    "code": 502,
    "message": "Database error."
}

Examples: get_series

Retrieve count of series.

Request

{
    "request": "get_series",
    "node": "npdb",
    "params": {}
}

Response

{
    "code": 0,
    "count": 3
}

Retrieve a list of series by specifying 'limit' and 'offset'.
Series are ordered ascending by series start.

Request

{
    "request": "get_series",
    "node": "npdb",
    "params": {
        "limit": 2,
        "offset": 1
    }
}

Response

{
    "code": 0,
    "series": [
        {
            "series_start": "40744334420",
            "series_end": "40744334429",
            "target": "18750",
            "description": ""
        },
        {
            "series_start": "40744334430",
            "series_end": "40744334439",
            "target": "18750",
            "description": ""
        }
    ]
}

Retrieve a single series of ported numbers by specifying 'series_start' and 'series_end'.
If not found, empty array will be returned.

Request

{
    "request": "get_series",
    "node": "npdb",
    "params": {
        "series_start": "40744334420",
        "series_end": "40744334429"
    }
}

Response

{
    "code": 0,
    "series": [
        {
            "series_start": "40744334420",
            "series_end": "40744334429",
            "target": "18750",
            "description": ""
        }
    ]
}

Request: set_series

Add or edit series of ported numbers.
If the series exist, it will be edited, othwerise it will be added.
Series must not overlap and must be unique.

Requests

{
    "request": "set_series",
    "node": "npdb",
    "params": {
        "series_start": "Mandatory, integer. The starting MSISDN for this series.",
        "series_end": "Mandatory, integer. The ending MSISDN for this series.",
        "target": "Mandatory, string, max 20 characters. The code associated to the operator where the number was ported.",
        "comment__target": "Example of operator codes: RO: '1875', NL: '015', DE: 'D250', RU: '710'",
        "description": "Optional, string, max 200 characters. A short description about this series."
    }
}

Responses

{
    "code": 0,
    "count": 1
}

Errors

{
    "code": 401,
    "message": "Series start/end should be valid integer."
}
{
    "code": 401,
    "message": "The series start and end must have the same length."
}
{
    "code": 401,
    "message": "Series start 'NNNN' must be less or equal than end 'NNNN'."
}
{
    "code": 402,
    "message": "Missing required series_start/series_end/target."
}
{
    "code": 402,
    "message": "Found 1 colliding entries."
}
{
    "code": 502,
    "message": "Database error."
}

Examples: set_series

Add a series of ported numbers.

Request

{
    "request": "set_series",
    "node": "npdb",
    "params": {
        "series_start": "40744334410",
        "series_end": "40744334419",
        "target": "18750"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Edit 'description' at a series of ported numbers by specifying 'series_start' and 'series_end'.

Request

{
    "request": "set_series",
    "node": "npdb",
    "params": {
        "series_start": "40744334410",
        "series_end": "40744334419",
        "description": "Romania Operator Code"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Request: del_series

Delete a series of ported numbers by specifying 'series_start' and 'series_end'.

Requests

{
    "request": "del_series",
    "node": "npdb",
    "params": {
        "series_start": "Mandatory, integer. The starting MSISDN for this series.",
        "series_end": "Mandatory, integer. The ending MSISDN for this series."
    }
}

Responses

{
    "code": 0,
    "count": 1
}

Errors

{
    "code": 401,
    "message": "Series start/end should be valid integer."
}
{
    "code": 401,
    "message": "The series start and end must have the same length."
}
{
    "code": 401,
    "message": "Series start 'NNNN' must be less or equal than end 'NNNN'."
}
{
    "code": 402,
    "message": "Missing required series_start/series_end."
}
{
    "code": 404,
    "message": "Entity not found."
}
{
    "code": 502,
    "message": "Database error."
}

Examples: del_series

Delete a series of ported numbers.

Request

{
    "request": "del_series",
    "node": "npdb",
    "params": {
        "series_start": "40744334410",
        "series_end": "40744334420"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Request: get_ported

Retrieve ported numbers.

Requests

This request has multiple formats in which it can be sent:

{
    "request": "get_ported",
    "node": "npdb",
    "params": {}
}
{
    "request": "get_ported",
    "node": "npdb",
    "params": {
        "limit": "Number of ported numbers to return.",
        "offset": "Optional, integer, default is 0. The starting point to return ported numbers."
    }
}
{
    "request": "get_ported",
    "node": "npdb",
    "params": {
        "number": "String. The phone number."
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "count": "The number of ported numbers. "
}
{
    "code": 0,
    "ported": [
        {
            "number": "The phone number.",
            "target": "The code associated to the operator where the number was ported."
        }
    ]
}
{
    "code": 0,
    "ported": [
        {
            "number": "The phone number.",
            "target": "The code associated to the operator where the number was ported."
        }
    ]
}

Errors

{
    "code": 502,
    "message": "Database error."
}

Examples: get_ported

Retrieve count of ported numbers.

Request

{
    "request": "get_ported",
    "node": "npdb",
    "params": {}
}

Response

{
    "code": 0,
    "count": 3
}

Retrieve a list of ported numbers by specifying 'limit' and 'offset'.

Request

{
    "request": "get_ported",
    "node": "npdb",
    "params": {
        "limit": 2,
        "offset": 1
    }
}

Response

{
    "code": 0,
    "ported": [
        {
            "number": "40744334456",
            "target": "18750"
        },
        {
            "number": "40744334457",
            "target": "18750"
        }
    ]
}

Retrieve a single ported number.

Request

{
    "request": "get_ported",
    "node": "npdb",
    "params": {
        "number": "40744334456"
    }
}

Response

{
    "code": 0,
    "ported": [
        {
            "number": "40744334456",
            "target": "18750"
        }
    ]
}

Request: set_ported

Add or edit a ported number
If the ported number exist, it will be edited, othwerise it will be added.

Requests

{
    "request": "set_ported",
    "node": "npdb",
    "params": {
        "number": "Mandatory, string. The phone number.",
        "target": "Mandatory, string, max 20 characters. The code associated to the operator where the number was ported.",
        "comment__target": "Example of operator codes: RO: '1875', NL: '015', DE: 'D250', RU: '710'"
    }
}

Responses

{
    "code": 0,
    "count": 1
}

Errors

{
    "code": 401,
    "message": "Field 'target' can have maximum 20 characters."
}
{
    "code": 402,
    "message": "Missing required number/target."
}
{
    "code": 502,
    "message": "Database error."
}

Examples: set_ported

Add/Edit a ported number.

Request

{
    "request": "set_ported",
    "node": "npdb",
    "params": {
        "number": "40744334455",
        "target": "18750"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Request: del_ported

Delete a ported number by specifying the phone 'number'.

Requests

{
    "request": "del_ported",
    "node": "npdb",
    "params": {
        "number": "Mandatory, string. Phone number."
    }
}

Responses

{
    "code": 0,
    "count": 1
}

Errors

{
    "code": 402,
    "message": "Missing required number."
}
{
    "code": 404,
    "message": "Entity not found."
}
{
    "code": 502,
    "message": "Database error."
}

Examples: del_ported

Delete a ported number.

Request

{
    "request": "del_ported",
    "node": "npdb",
    "params": {
        "number": "40744334455"
    }
}

Response

{
    "code": 0,
    "count": 1
}

Request: search_ported

Search if a number is ported in series or in individually ported numbers.

Requests

{
    "request": "search_ported",
    "node": "npdb",
    "params": {
        "number": "Mandatory, string. Phone number to search for.",
        "required": "Optional, bool. If true and not found 404 error will be returned, otherwise empty positive response"
    }
}

Responses

Response has multiple formats depending on the sent request:

{
    "code": 0,
    "ported": {
        "number": "Mandatory, string. The phone number.",
        "target": "Mandatory, string, max 20 characters. The code associated to the operator where the number was ported."
    }
}
{
    "code": 0,
    "series": {
        "series_start": "The starting MSISDN for this series.",
        "series_end": "The ending MSISDN for this series.",
        "target": "The code associated to the operator where the number was ported.",
        "description": "Description for this series."
    }
}
{
    "code": 0
}
{
    "code": 404,
    "message": "Entity not found"
}

Examples: search_ported

Search if a number is ported and retrieve the series that contains it.

Request

{
    "request": "search_ported",
    "node": "npdb",
    "params": {
        "number": "40744334415"
    }
}

Response

{
    "code": 0,
    "series": {
        "series_start": "40744334410",
        "series_end": "40744334419",
        "description": "Romania Operator Code",
        "target": "18750"
    }
}

Search if a number is ported and retrieve that it's ported individually.

Request

{
    "request": "search_ported",
    "node": "npdb",
    "params": {
        "number": "40744334400"
    }
}

Response

{
    "code": 0,
    "ported": {
        "number": "40744334400",
        "target": "18750"
    }
}

See if a number is ported, and it's not.

Request

{
    "request": "search_ported",
    "node": "npdb",
    "params": {
        "number": "40744334400"
    }
}

Response

{
    "code": 0
}

See if a number is ported, but request 404 error if it's not.