NAV
shell php

Introduction

Welcome to the getCP API! You can use our API to access getCP API endpoints, which can get information on Communication Provider data, parsed from the Ofcom numbering spreadsheets.

We have language bindings in Shell and PHP for the moment! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This API documentation page was created with Slate.

Authentication

To authorize, use this code:

curl "https://api.getcp.io/v2/"
    -H "Authorization: Basic API_KEY"
    -X "POST"


    // Get cURL resource
    $ch = curl_init();

    // Set url
    curl_setopt($ch, CURLOPT_URL, 'https://api.getcp.io/v2/');

    // Set method
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

    // Set options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    // Set headers
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Basic API_KEY",
        ]
    );


    // Send the request and save response to $resp
    $resp = curl_exec($ch);

Make sure to replace API_KEY with your API key.

getCP uses API keys to allow access to the API. You need to have a getCP Admin account to get your API Keys.

getCP expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic

HTTP Basic authorization is commonly a concatenation of your username and password, separated by a colon. For example:

username:password

Replacing username and password with some test keys, for demonstration purposes of course:

pk_00000000-0000-0000-0000-000000000000:sk_00000000-0000-0000-000000000000

Upon base64 encoding this string, you would then pass this as your authorization header, like so:

Authorization: Basic cGtfMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDA6c2tfMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAwMDAw

Get API Credentials

Generate API Credentials

curl "https://api.getcp.io/createCreds.php?agreeToTerms=yes"
    -X "GET"


    // Get cURL resource
    $ch = curl_init();

    // Set url
    curl_setopt($ch, CURLOPT_URL, '
        https://api.getcp.io/createCreds.php?agreeToTerms=yes
    ');

    // Set method
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

    // Set options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    // Set headers
    curl_setopt($ch, CURLOPT_HTTPHEADER, []
    );

    // Send the request and save response to $resp
    $resp = curl_exec($ch);

    if(!$resp) {
        die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
    } else {
        echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
        echo "\nResponse HTTP Body : " . $resp;
    }

    // Close request to clear up some resources
    curl_close($ch);

The above command returns JSON structured like this:


[
    {
        "username":"pk_00000000-0000-0000-0000-000000000000",
        "password":"sk_00000000-0000-0000-0000-000000000000",
        "notes":"MAKE NOTE OF THESE, YOU WILL NOT BE ABLE TO ACCESS THEM AGAIN"
    }
]

This response will return a HTTP/1.1 201 Created if credential creation was successful.

This response will return a HTTP/1.1 403 Forbidden if credential creation was unsuccessful, this is usually because you have already created some credentials from your IP in a month.

This endpoint creates you some API credentials.

HTTP Request

GET https://api.getcp.io/createCreds.php?agreeToTerms=<DECISION>

Query Parameters

Parameter Description
decision This can be ‘yes’ or 'no’, depending on your decision to accept our terms of service. These are available at getCP.io, at the bottom of the page

Get CP Data

Get data on a number

curl "https://api.getcp.io/v2/03334433443"
    -H "Authorization: Basic API_KEY"
    -X "POST"


    // Get cURL resource
    $ch = curl_init();

    // Set url
    curl_setopt($ch, CURLOPT_URL, '
        https://api.getcp.io/v2/03334433443
    ');

    // Set method
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

    // Set options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    // Set headers
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Basic API_KEY",
        ]
    );

    // Send the request and save response to $resp
    $resp = curl_exec($ch);

    if(!$resp) {
        die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
    } else {
        echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
        echo "\nResponse HTTP Body : " . $resp;
    }

    // Close request to clear up some resources
    curl_close($ch);

The above command returns JSON structured like this:


[
    {
        "number":"0333443",
        "status":"Allocated",
        "cp":"Nexbridge Communications Limited",
        "num_length":null,
        "use":null,
        "last_fetched_timestamp":"2016-02-19 01:00:04"
    }
]

This response will return a HTTP/1.1 200 OK

This endpoint retrieves particular data on a single number.

HTTP Request

GET https://api.getcp.io/v2/<NUMBER>

Query Parameters

Parameter Description
NUMBER If a full number is provided, this will return data pertaining to the range associated to that number.

Get data on a range

curl "https://api.getcp.io/v2/03334"
    -H "Authorization: Basic API_KEY"
    -X "GET"


    // Get cURL resource
    $ch = curl_init();

    // Set url
    curl_setopt($ch, CURLOPT_URL, '
        https://api.getcp.io/v2/03334
    ');

    // Set method
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

    // Set options
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    // Set headers
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Basic API_KEY",
        ]
    );

    // Send the request and save response to $resp
    $resp = curl_exec($ch);

    if(!$resp) {
        die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
    } else {
        echo "Response HTTP Status Code : " . curl_getinfo($ch, CURLINFO_HTTP_CODE);
        echo "\nResponse HTTP Body : " . $resp;
    }

    // Close request to clear up some resources
    curl_close($ch);

The above command returns JSON structured like this:

[
    {
        "number":"0333400",
        "status":"Allocated",
        "cp":"Call Stream Limited",
        "num_length":null,
        "use":null,
        "last_fetched_timestamp":"2016-02-19 01:00:04"
    },
    {
        "number":"0333401",
        "status":"Free",
        "cp":null,
        "num_length":null,
        "use":null,
        "last_fetched_timestamp":"2016-02-19 01:00:04"
    },
    {
        "number":"0333402",
        "status":"Free",
        "cp":null,
        "num_length":null,
        "use":null,
        "last_fetched_timestamp":"2016-02-19 01:00:04"
    }...

This endpoint retrieves data based on a smaller number being submitted, this can produce anything from 1 result to several thousand.

If there is more data available, you will receive a HTTP/1.1 222 More Accuracy Available, as specified in our response codes below.

HTTP Request

GET https://api.getcp.io/v2/<NUMBER>

URL Parameters

Parameter Description
NUMBER The number or number range that you want data for

Response Codes

The getCP API uses the following HTTP Response codes:

Code Meaning
200 OK – The server was able to find data and has honoured your request with a response.
222 More Accuracy Available – While the server has returned data on the number range requested, if you provide more information, we may be able to provide more accuracy.

Errors

The getCP API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks and/or you haven’t specified the minimum number of digits, which is 3
401 Unauthorized – Your API key is incorrect or has expired
403 Forbidden – You’ve no doubt been banned. Stop being a douche
404 Not Found – The specified number range could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The server has gone, no idea where, possibly for a walk
418 I’m a teapot
429 Too Many Requests – You’ve made too many requests, contact us to up this limit or go a little easier, tiger
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
shell php