Find

Postal addresses for single UK postcode.

Postcode to Addresses

GET https://api.getAddress.io/find/{postcode}

Returns a list of addresses for a postcode.

GET https://api.getAddress.io/find/{postcode}/{house}

Returns an address for a postcode and house name/number.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your API key	Text
format	No	Formats the addresses as an arrays.	True/False
sort	No	Numerically sorts the addresses.	True/False
expand	No	Expands addresses in to individual named components, such as building number and thoroughfare.	True/False
fuzzy	No	Searches for the address with fuzzy logic, including synonyms, partial words and acronyms.	True/False

Examples

Request

GET https://api.getAddress.io/find/nn13er?api-key={api-key}

Response 200

{
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":
    ["10 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "12 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "14 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "16 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "18 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "2 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "20 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "22 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "24 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26a Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26b Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26c Watkin Terrace, , , , , Northampton, Northamptonshire",
    "26d Watkin Terrace, , , , , Northampton, Northamptonshire",
    "28 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "2a Watkin Terrace, , , , , Northampton, Northamptonshire",
    "30 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "32 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "36 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "38 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "4 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "40 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "40b Watkin Terrace, , , , , Northampton, Northamptonshire",
    "42 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "44 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "46 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "48 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "50 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "8 Watkin Terrace, , , , , Northampton, Northamptonshire",
    "Flat 1, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 1, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 2, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 2, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 3, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 3, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 4, 6 Watkin Terrace, , , , Northampton, Northamptonshire",
    "Flat 4, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 5, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 6, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 7, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 8, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire",
    "Flat 9, Watkin Court, Watkin Terrace, , , Northampton, Northamptonshire"]
}

Response Format

The Addresses property contains an array of addresses representing every address in the postcode.

{
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":["Line1,Line2,Line3,Line4,Locality,Town/City,County"]
}

Request with expand

GET https://api.getAddress.io/find/nn13er/10?api-key={api-key}&expand=true

Response 200

{
    "postcode": "NN1 3ER",
    "latitude": 52.24593734741211,
    "longitude": -0.891636312007904,
    "addresses":
    [
    {
    "formatted_address": [
        "10 Watkin Terrace",
        "",
        "",
        "Northampton",
        "Northamptonshire"
     ],
        "thoroughfare":  "Watkin Terrace",
        "building_name":  "",
        "sub_building_name":  "",
        "sub_building_number":  "",
        "building_number":  "10",
        "line_1":  "10 Watkin Terrace",
        "line_2":  "",
        "line_3":  "",
        "line_4":  "",
        "locality":  "",
        "town_or_city":  "Northampton",
        "county":  "Northamptonshire",
        "district":  "Northampton",
        "country":  "England"
    }
    ]
}

Testing

These postcodes yield both successful and unsuccessful responses to your request.

XX2 00X or TR19 7AA or KW1 4YT Returns a 'successful' response 200. Your request was successful.
XX4 04X Returns 'not found' response 404. No addresses could be found for this postcode.
XX4 00X Returns 'bad request' response400. Your postcode is not valid.
XX4 01X Returns 'unauthorized' response 401. Your api-key is not valid.
XX4 03X Returns 'forbidden' response 403. Your api-key is valid but you do not have permission to access to the resource.
XX4 29X Returns 'too many requests' response 429. You have made more requests than your allowed limit.
XX5 00X Returns 'server error' response 500. Server error, you should never see this.

Request made with these postcodes will not affect your usage.

(See: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes for more details on HTTP status codes.)

Autocomplete - Postcodes

Try it

These services are

All applications that use the Places API or Place Autocomplete service must adhere to the requirements described in the Places API Policies and the Google Maps Platform Terms of Service.

Example:

Request

GET https://api.getAddress.io/auto-complete/postcodes/{input}

Returns postcode predictions.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your API key	Text
google-api-key	Yes	Your Google Places API Key	Text
session-token	No	Optional session token	Text

Response

{
"predictions":
[
            {
                "description": "Wandsworth Plain, London SW18 1ET, UK",
                "postcode": "SW18 1ET" 
            },
            {
                "description": "Upper Tooting Road, London SW17 7TN, UK",
                "postcode":"SW17 7TN" 
            },
            {
                "description": "London SW1H 9NH, UK",
                "postcode": "SW1H 9NH"
            }
]
}

Autocomplete - Places

Try it

These services are

All applications that use the Places API or Place Autocomplete service must adhere to the requirements described in the Places API Policies and the Google Maps Platform Terms of Service.

Example:

Request

GET https://api.getAddress.io/auto-complete/places/{input}

Returns place predictions.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your API key	Text
google-api-key	Yes	Your Google Places API Key	Text
session-token	No	Optional session token	Text

Response

{
"predictions":
[
            {
                "description": "Good Hope Hospital, Sutton Coldfield, UK",
                "google_place_id": "ChIJK4IOZqKlcEgRUz5tatg3mjg" 
            },
            {
                "description": "Google UK, Pancras Square, London, UK",
                "google_place_id":"ChIJ4abvVDwbdkgRDZVFR7A6Bcc" 
            },
            {
                "description": "Google London, Saint Giles High Street, London, UK",
                "google_place_id": "ChIJVSZzVR8FdkgR-HklrBMO0Hc"
            }
]
}

Request

GET https://api.getaddress.io/google/place-details/{google-place-id}

Returns place details.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your API key	Text
google-api-key	Yes	Your Google Places API Key	Text

Response

{
"postcode": "N1C 4AG",
"latitude": 51.533355,
"longitude": -0.1254794,
"address": {
            "formatted_address": [
            "Google UK Ltd",
            "7 Pancras Square",
            "",
            "London",
            ""
            ],
            "thoroughfare": "Pancras Square",
            "building_name": "",
            "sub_building_name": "Google UK Ltd",
            "sub_building_number": "",
            "building_number": "7",
            "line_1": "Google UK Ltd",
            "line_2": "7 Pancras Square",
            "line_3": "",
            "line_4": "",
            "locality": "",
            "town_or_city": "London",
            "county": "",
            "district": "Camden",
            "country": "England"
            }
}

Usage

Try it

Your API usage and daily limits.

Get

Returns the current day's usage and usage limits.

GET https://api.getAddress.io/v3/usage

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "usage_today": 99,
    "daily_limit": 2000,
    "monthly_buffer": 1000,
    "monthly_buffer_used": 100
}

Get

Returns the usage and limits for a given day, month and year.

GET https://api.getAddress.io/v3/usage/{day}/{month}/{year}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "usage_today": 99,
    "daily_limit": 2000,
    "monthly_buffer": 1000,
    "monthly_buffer_used": 100
}

Get

Returns the usage for a given date range

GET https://api.getAddress.io/usage/from/{from-day}/{from-month}/{from-year}/To/{to-day}/{to-month}/{to-year}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    {
    "date": 2019-12-26T00:00:00,
    "count": 29
    },
    {
    "date": 2019-12-27T00:00:00,
    "count": 19
    }
}

Subscription

Try it

Your Subscription Details

Subscription Details

GET https://api.getAddress.io/subscription

Returns the subscription's payment terms, limits and expiry date.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Examples

Request

GET https://api.getAddress.io/subscription?api-key={api-key}

Response 200

{
    "expiry_date": 2019-04-20T14:44:33.7395348Z,
    "first_daily_limit": 2000,
    "second_daily_limit": 3000,
    "amount": 100,
    "term": "Yearly"
}

Private Address List

Try it

Add addresses directly to your returned results.

Add

Adds an address to your private address list.

POST https://api.getAddress.io/private-address/{postcode}

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}

Response 200

{
    "message": "'postcode/id' has been added to your private address list.",
    "id": "zxy"
}

Remove

Removes an address from your private address list.

DELETE https://api.getAddress.io/private-address/{postcode}/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'{id}' has been removed from your private address list."
}

Get

Get an address from your private address list.

GET https://api.getAddress.io/private-address/{postcode}/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}

List

Lists addresses from your private address list.

GET https://api.getAddress.io/private-address/{postcode}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
},
{
    "id": "{id}",
    "line1": "address line 1",
    "line2": "address line 2",
    "line3": "address line 3",
    "line4": "address line 4",
    "locality": "locality",
    "townOrCity": "town or city",
    "county": "county"
}
]

Distance

Try it

Gets the distance in meters between two postcodes

Get

The Haversine formula is used to calculate the distance between two postcodes

GET https://api.getAddress.io/distance/{postcode_from}/{postcode_to}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your API key	Text

Response 200

{
    "from": {
         "latitude": 50.065551,
         "longitude": -5.714262,
         "postcode": "TR19 7AA"
    },
    "to": {
         "latitude": 58.63568878173828,
         "longitude": -3.061519145965576,
         "postcode": "KW1 4YT"
    },
    "metres": 968978.0931119365
}

Domain Whitelist

Try it

Restrict API calls to allowed domains.

Do not use when calling from server side code. Please use the IP White List instead.

Add

Adds domain to white list.

POST https://api.getAddress.io/security/domain-whitelist

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "name": "your-domain-name"
}

Response 201

{
    "message": "'your-domain-name' has been added to your domain whitelist.",
    "id": "zxy"
}

Remove

Removes a domain from your white list.

DELETE https://api.getAddress.io/security/domain-whitelist/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'your-domain-name' has been removed from your domain whitelist."
}

Get

Get a domain from your white list.

GET https://api.getAddress.io/security/domain-whitelist/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "xyz",
    "name": "domain-name-1"
}

List

Lists all domains in your white list.

GET https://api.getAddress.io/security/domain-whitelist

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {"id": "zxf","name": "domain-1"},
    {"id": "abs","name": "domain-2"}
]

IP Address Whitelist

Try it

Restrict API calls to allowed IP Addresses.

Do not use when calling directly from client side code (JavaScript). Please the Domain White List instead.

Add

Adds an IP address to your white list.

POST https://api.getAddress.io/security/ip-address-whitelist

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "value": "your-ip-address"
}

Response 200

{
    "message": "'your-ip-address' has been added to your IP address whitelist.",
    "id": "zxy"
}

Remove

Removes an IP address from your white list.

DELETE https://api.getAddress.io/security/ip-address-whitelist/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'your-ip-address' has been removed from your IP address whitelist."
}

Get

Get an IP address from your white list.

GET https://api.getAddress.io/security/ip-address-whitelist/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "xyz",
    "value": "192.168.7.2"
}

List

Lists all IP addresses in your white list.

GET https://api.getAddress.io/security/ip-address-whitelist

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {"id": "zxf","value": "192.168.192.0"},
    {"id": "abs","value": "192.168.192.1"}
]

Email Address

Try it

Gets or updates your account's primary email address

Get

Gets the account's primary email address.

GET https://api.getAddress.io/email-address

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "email-address": "{your account's email address}"
}

Update

Updates the account's primary email address with a new email address.

PUT https://api.getAddress.io/email-address

Content-Type: application/json

An account's email address cannot be updated to another, existing, account's email address.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "new-email-address": "{your new email address}"
}

Response 204

 {no content}

Response 400

{
    "message": "account: '{your new email address}' already exists."
}

.NET SDK

.NET SDK for working with security and resources.

Install

Install from Nuget.


        PM> Install-Package getAddress.Sdk

Find

Find postal addresses for a UK postcode and optional house name/number.


        var apiKey = new ApiKey("YOUR API KEY");

        IAddressService addressService = new AddressService(apiKey);

        var result = await addressService.Get(new GetAddressRequest("POSTCODE", "OPTIONAL HOUSE NAME"));

        if (result.IsSuccess)
        {
            var successfulResult = result.SuccessfulResult;

            var latitude = successfulResult.Latitude;

            var Longitude = successfulResult.Longitude;

            foreach (var address in successfulResult.Addresses)
            {
                var line1 = address.Line1;
                var line2 = address.Line2;
                var line3 = address.Line3;
                var line4 = address.Line4;
                var locality = address.Locality;
                var townOrCity = address.TownOrCity;
                var county = address.County;
            }
        }

Usage

Returns the current day's usage and usage limits.


        var adminKey = new AdminKey("YOUR ADMINISTRATION KEY");

        IUsageService usageService = new UsageService(adminKey);

        var result = await usageService.Get();

        if (result.IsSuccess)
        {
            var successfulResult = result.SuccessfulResult;

            var count = successfulResult.Usage.Count;

            var limit1 = successfulResult.Usage.Limit1;

            var limit2 = successfulResult.Usage.Limit2;
        }

Returns the usage and limits for a given day, month and year.


        var adminKey = new AdminKey("YOUR ADMINISTRATION KEY");

        IUsageService usageService = new UsageService(adminKey);

        var result = await usageService.Get(new GetUsageRequest(DAY,MONTH,YEAR));

        if (result.IsSuccess)
        {
            var successfulResult = result.SuccessfulResult;

            var count = successfulResult.Usage.Count;

            var limit1 = successfulResult.Usage.Limit1;

            var limit2 = successfulResult.Usage.Limit2;
        }

JQuery

The jQuery plug-in is the simplest way to integrate your web page with our API.

Basic Integration

HTML

<!-- Postcode field -->
<div id="postcode_lookup"></div>  

<!-- Add to your existing form -->
<label>First Address Line</label>
<input id="line1" type="text"> 

<label>Second Address Line</label>
<input id="line2" type="text">   

<label>Third Address Line</label>
<input id="line3" type="text">  

<label>Town</label>
<input id="town" type="text">

<label>County</label>
<input id="county" type="text">

<label>Postcode</label>
<input id="postcode" type="text">

Javascript

<!-- Include JQuery v2+ -->
<script src="jquery.js"></script>
<!-- Include plugin file -->
<script src="https://getaddress-cdn.azureedge.net/scripts/jquery.getAddress-3.0.2.min.js"></script>

<!-- Add after your form -->
<script>
$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
    }
});
</script>

Additional Output Fields

Property	Description
latitude	Latitudedinal coordinates +/-90.
longitude	Longitudinal coordinates +/-180.
building_number	The building's number.
building_name	The building's name.
building_name_or_number	The building's name or, if the name is not availible, the number.
sub_building_number	The sub-building's number.
sub_building_name	The sub-building's name.
sub_building_name_or_number	The sub-building's name or, if the name is not availible, the number.

Example
Basic Usage

Securiy (optional)

To your protect your account from unauthorised use, please add your domain(s) to your white-list.

Style Options

Postcode Textbox

Property	Default	Description
input_label	"Enter your Postcode"	Placeholder text
input_class	""	CSS class name
input_id	"getaddress_input"	textbox id
input_name	"getaddress_input"	textbox name

Look-up Button

Property	Default	Description
button_label	"Find your Address"	Button text
button_class	""	CSS class name
button_disabled_message	"Fetching Addresses..."	Button text when fetching addresses
button_id	"getaddress_button"	Button id

Dropdown Address List

Property	Default	Description
button_label	"Find your Address"	Button text
dropdown_class	""	CSS class name
dropdown_select_message	"Select your Address"	First line text
dropdown_id	"getaddress_dropdown"	dropdown id

Error Messages

Property	Default	Description
error_message_id	"getaddress_error_message"	Error message id
error_message_postcode_invalid	"Please recheck your postcode, it seems to be incorrect"	Invalid postcode message
error_message_postcode_not_found	"Your postcode could not be found. Please type in your address"	Postcode not found message
error_message_default	"We were not able to find your address from your Postcode. Please input your address manually"	Default look-up failed message
error_message_class	""	Error message CSS class

Example

$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:
        {
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
        },
    input_label:'Please enter your postcode',
    input_class:'form-control',
    button_label:'Search',
    button_class:'btn btn-primary'
});

Callbacks

Example

$('#postcode_lookup').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:
        {
        line_1: '#line1',
        line_2: '#line2',
        line_3: '#line3',
        post_town: '#town',
        county: '#county',
        postcode: '#postcode'
        },
    <!--  Optionally register callbacks at specific stages -->
    onLookupSuccess: function(data){/* Your custom code */},
    onLookupError: function(){/* Your custom code */},
    onAddressSelected: function(elem,index){/* Your custom code */}
});
});

Multiple Forms

Example

<script>
$('#postcode_lookup_1').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1_1',
        line_2: '#line2_1',
        line_3: '#line3_1',
        post_town: '#town_1',
        county: '#county_1',
        postcode: '#postcode_1'
    }
});

$('#postcode_lookup_2').getAddress(
    {
    api_key: 'YOUR_API_KEY',  
    output_fields:{
        line_1: '#line1_2',
        line_2: '#line2_2',
        line_3: '#line3_2',
        post_town: '#town_2',
        county: '#county_2',
        postcode: '#postcode_2'
    }
});
</script>

First Limit Reached

Try it

First limit reached webhook is fired when a plan's daily limit is reached.

Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/first-limit-reached

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": "Webhook : 'https://your-domain.com/action' has been created.",
    "id": "123"
}

Invalid or unresponsive URL's are automatically deleted.

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/first-limit-reached/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/first-limit-reached

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/first-limit-reached/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/first-limit-reached/test

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"first_limit_reached",
    "created_at":"2017-08-14T12:58:01.0006757Z",
    "details":
    {
        "limit":50,
        "time_penaly":5000,
        "next_limit":100,
        "upgrade_link":"https://getaddress.io/upgrade?emailaddress=your-email-address@domain.com"
    },
    "type":"usage"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

Second (Final) Limit Reached

Try it

Second limit reached webhook is fired when a plan's daily usage limit is reached. Subsequent requests will receive a 429 response.

Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/second-limit-reached

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": "Webhook : 'https://your-domain.com/action' has been created.",
    "id": "123"
}

Invalid or unresponsive URL's are automatically deleted.

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/second-limit-reached/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/second-limit-reached

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/second-limit-reached/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/second-limit-reached/test

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"second_limit_reached",
    "created_at":"2018-08-14T12:58:01.0006757Z",
    "details":
    {
        "limit":50,
        "upgrade_link":"https://getaddress.io/upgrade?emailaddress=your-email-address@domain.com"
    },
    "type":"usage"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

Payment Failed

Try it

Payment failed webhook is fired when a Credit Card or Direct Debit payment failed to process.

Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/payment-failed

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": "Webhook : 'https://your-domain.com/action' has been created.",
    "id": "123"
}

Invalid or unresponsive URL's are automatically deleted.

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/payment-failed/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/payment-failed

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/payment-failed/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/payment-failed/test

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"payment_failed",
    "created_at":"2019-02-14T12:58:01.0006757Z",
    "details":
    {
        "update_card_details_link":"https://getaddress.io/updatecarddetails?emailaddress=your-email-address@domain.com"
    },
    "type":"billing"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

Account Expired

Try it

An Account expired webhook is fired when an application has made an API call to our service with an expired account.

Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/expired

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": "Webhook : 'https://your-domain.com/action' has been created.",
    "id": "123"
}

Invalid or unresponsive URL's are automatically deleted.

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/expired/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/expired

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/expired/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/expired/test

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"expired",
    "created_at":"2019-02-14T12:58:01.0006757Z",
    "details":
    {
        "update_card_details_link":"https://getaddress.io/updatecarddetails?emailaddress=your-email-address@domain.com"
    },
    "type":"billing"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

Track

Try it

Track account activity.

Add

Adds URL to be called. Webhook data is sent as JSON in the POST request body.

POST https://api.getAddress.io/webhook/track

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "url": "https://your-domain.com/action"
}

Response 200

{
    "message": "Webhook : 'https://your-domain.com/action' has been created.",
    "id": "123"
}

Invalid or unresponsive URL's are automatically deleted.

Remove

Removes webhook.

DELETE https://api.getAddress.io/webhook/track/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'https://your-domain.com/action' has been removed from your webhooks."
}

List

Lists webhook URLs.

GET https://api.getAddress.io/webhook/track

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
        "id": "123",
        "url": "https://your-domain.com/action"
    }
]

Get

Gets webhook URL.

GET https://api.getAddress.io/webhook/track/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": "123",
    "url": "https://your-domain.com/action"
}

Test

Sends a webhook to each endpoint.

POST https://api.getAddress.io/webhook/track/test

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Webhook has been sent"
}

Data

Data sent as JSON in the POST request body

{
    "version":"1.0.0.0",
    "action":"track",
    "created_at":"2019-12-14T12:58:01.0006757Z",
    "details":
    {
        "ip_address":"192.168.0.1"
        "postcode":"SW1 A2AA"
        "referer":"https://api.getaddress.io"
    },
    "type":"usage"
}

Tools

PIPE DREAM

Reliably inspect any HTTP traffic to observe and debug your apps and webhook integrations. Create an endpoint to get started for free.

Open API (Swagger)

The OpenAPI specification (formerly known as the Swagger Specification) is a powerful definition format to describe RESTful APIs. The specification creates a RESTful interface for easily developing and consuming an API by effectively mapping all the resources and operations associated with it. It’s easy-to-learn, language agnostic, and both human and machine readable.

URL

https://getaddress.io/contract/openapi

Tools

SWAGGER CODEGEN

Build APIs quicker and improve consumption of your Swagger-defined APIs in every popular language with Swagger Codegen. Swagger Codegen can simplify your build process by generating server stubs and client SDKs from your Swagger specification, so your team can focus better on your API’s implementation and adoption.

SWAGGER UI

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.

SWAGGER EDITOR

Design, describe, and document your API on the first open source editor fully dedicated to Swagger-based APIs. The Swagger Editor is great for quickly getting started with the Swagger specification. It’s clean, efficient, and armed with a number of features to help you design and document your RESTful interfaces, straight out of the box.

API Key

Try it

Gets or creates a new API key

Get

Gets the account's current API key.

GET https://api.getAddress.io/security/api-key

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "api-key": "{your current API key}"
}

Update

Updates the account's current API key with a new API key.

PUT https://api.getAddress.io/security/api-key

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 201

{
    "api-key": "{your new API key}"
}

Updates are irreversible, a new API key will be created.

Permissions

Try it

Grants additional users access to functionality

Get

Gets additional user's permissions.

GET https://api.getAddress.io/permission/{email-address}/

The email address must be followed by a forward slash (/) in the URL.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "email_address": "email@address.com",
    "expires": "9999-12-31T23:59:59.9999999Z",
    "permissions": {
    "view_invoices": true,
    "unsubscribe": false,
    "update_card_details": false
    }
}

List

Lists all permissions.

GET https://api.getAddress.io/permission

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
{
    "email_address": "email@address.com",
    "expires": "9999-12-31T23:59:59.9999999Z",
    "permissions": {
    "view_invoices": true,
    "unsubscribe": false,
    "update_card_details": false
    }
},
{
    "email_address": "email@address.com",
    "expires": "9999-12-31T23:59:59.9999999Z",
    "permissions": {
    "view_invoices": true,
    "unsubscribe": false,
    "update_card_details": false
    }
},
]

Update

Updates additional user's permissions.

PUT https://api.getAddress.io/permission

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "expires": "9999-12-31T23:59:59.9999999Z",
    "email_address": "email@address.com",
    "permissions": {
    "view_invoices": true,
    "unsubscribe": false,
    "update_card_details": true
    }
}

Response 201

{
    "message": "Permission updated"
}

Add

Create permissions for an additional user.

POST https://api.getAddress.io/permission

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "expires": "9999-12-31T23:59:59.9999999Z",
    "email_address": "email@address.com",    
    "permissions": {
    "view_invoices": true,
    "unsubscribe": true,
    "update_card_details": true
    }
}

Response 201

{
    "message": "Permission created"
}

Remove

Removes all permissions for an additional user.

DELETE https://api.getAddress.io/permission/{email-address}/

The email address must be followed by a forward slash (/) in the URL.

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "Permission deleted"
}

CC Invoices

Try it

Copy (CC) recipients to your emailed invoices

Add

Adds copied recipient to your emailed invoices

POST https://api.getAddress.io/cc/invoices

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "email-address": "recipient-email-address"
}

Response 200

{
    "email-address": "'recipient-email-address' will be CC'd in your invoice emails.",
    "id": 1
}

Remove

Removes a copied recipient.

DELETE https://api.getAddress.io/cc/invoices/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'recipient-email-address' has been removed from your invoice CC list."
}

Get

Gets copied recipient.

GET https://api.getAddress.io/cc/invoices/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": 1,
    "email-address": "recipient-email-address"
}

List

Lists all copied recipients.

GET https://api.getAddress.io/cc/invoices

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {"id": 1,"email-address": "recipient-email-address"},
    {"id": 2,"email-address": "recipient-email-address"}
]

CC Expired Emails

Try it

Copy (CC) recipients to your expired account emails

Add

Adds copied recipient to your expired account emails

POST https://api.getAddress.io/cc/expired

Content-Type: application/json

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Request Body

{
    "email-address": "recipient-email-address"
}

Response 200

{
    "email-address": "'recipient-email-address' will be CC'd in your expired account emails.",
    "id": 1
}

Remove

Removes a copied recipient.

DELETE https://api.getAddress.io/cc/expired/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "message": "'recipient-email-address' has been removed from your expired account CC list."
}

Get

Gets copied recipient.

GET https://api.getAddress.io/cc/expired/{id}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "id": 1,
    "email-address": "recipient-email-address"
}

List

Lists all copied recipients.

GET https://api.getAddress.io/cc/expired

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {"id": 1,"email-address": "recipient-email-address"},
    {"id": 2,"email-address": "recipient-email-address"}
]

Invoices

Try it

Your invoices

Get

Gets an invoice

GET https://api.getAddress.io/invoices/{number}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

{
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number
}

List

Returns the invoices for a given date range

GET https://api.getAddress.io/invoices/from/{from-day}/{from-month}/{from-year}/To/{to-day}/{to-month}/{to-year}

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Examples

Request

GET https://api.getAddress.io/invoices/from/1/2/2018/To/1/2/2018

Response 200

[
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 1",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 1
    },
    {
    "date": "2018-02-01T00:02:37Z",
    "number": "invoice number 2",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 
    }
]

List

Lists all invoices

GET https://api.getAddress.io/invoices

Query Parameters

Property	Required	Description	Type
api-key	Yes	Your administration API key	Text

Response 200

[
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 1",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 1
    },
    {
    "date": "2018-01-01T00:02:37Z",
    "number": "invoice number 2",
    "address_1": "address line 1",
    "address_2": "address line 2",
    "address_3": "address line 3",
    "address_4": "address line 4",
    "address_5": "address line 5",
    "address_6": "address line 6",
    "total": 12,
    "tax": 2,
    "invoice_lines": [
    {
      "quantity": 1,
      "details": "getAddress.io subscription",
      "unit_price": 10,
      "subtotal": 10
    }
    ],
    "pdf_url": https://getaddress.io/invoice/invoice number 
    }
]

Slack

All getAddress() webhooks integrate directy with the Incoming Webhooks App.

Documentation

Find

Postcode to Addresses

Query Parameters

Examples

Request

Response 200

Response Format

Request with expand

Response 200

Testing

Autocomplete - Postcodes

Request

Query Parameters

Response

Autocomplete - Places

Request

Query Parameters

Response

Request

Query Parameters

Response

Usage

Get

Query Parameters

Response 200

Get

Query Parameters

Response 200

Get

Query Parameters

Response 200

Subscription

Subscription Details

Query Parameters

Examples

Request

Response 200

Private Address List

Add

Content-Type: application/json

Query Parameters

Request Body

Response 200

Remove

Query Parameters

Response 200

Get

Query Parameters

Response 200

List

Query Parameters

Response 200

Distance

Get

Query Parameters

Response 200

Domain Whitelist

Add

Content-Type: application/json

Query Parameters

Request Body

Response 201

Remove

Query Parameters

Response 200

Get

Query Parameters

Response 200

List

Query Parameters

Response 200

IP Address Whitelist

Add

Content-Type: application/json

Query Parameters

Request Body

Response 200

Remove

Query Parameters