---
canonical_url: "https://docs.composio.dev/toolkits/idealpostcodes"
markdown_url: "https://docs.composio.dev/toolkits/idealpostcodes.md"
product: "platform"
version: null
last_updated: null
---

# Ideal Postcodes

Ideal Postcodes provides UK and international address search, postcode lookup, address cleansing, and contact validation APIs.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 9
- **Triggers:** 0
- **Slug:** `IDEALPOSTCODES`
- **Version:** 00000000_00

## Tools

### Find Address Suggestions

**Slug:** `IDEALPOSTCODES_FIND_ADDRESS_SUGGESTIONS`

Return ranked address suggestions for a partial address without resolving them; resolving a selected suggestion is a separate paid lookup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `box` | string | No | Bounding box used to restrict results, in the provider's comma-separated coordinate format. |
| `limit` | integer | No | Maximum suggestions to return (1-100). |
| `query` | string | Yes | Partial address to search for (maximum 150 characters). |
| `bias_ip` | string | No | IP address used to geographically bias suggestion ranking. |
| `context` | string | No | Country context used to interpret the query, such as GBR or USA. |
| `country` | string | No | Country name used to restrict suggestions. |
| `datasets` | array | No | Enabled address datasets to search, such as paf or mr; omit to use the key's defaults. |
| `postcode` | string | No | Exact postcode used to restrict suggestions. |
| `post_town` | string | No | Post town used to restrict suggestions. |
| `bias_lonlat` | string | No | Longitude and latitude used to rank nearby suggestions, formatted as 'longitude,latitude'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find Place Suggestions

**Slug:** `IDEALPOSTCODES_FIND_PLACE_SUGGESTIONS`

Return ranked country, city, and administrative-area suggestions without resolving them; resolving a selected place is a separate paid lookup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Place name or partial place name to search for. |
| `bias_ip` | string | No | IP address used to geographically bias result ranking. |
| `bias_lonlat` | string | No | Longitude and latitude used to rank nearby places, formatted as 'longitude,latitude'. |
| `country_iso` | string | No | ISO 3166-1 alpha-3 country code used to restrict results, such as GBR. |
| `bias_country_iso` | string | No | ISO 3166-1 alpha-3 country code used to rank matching places. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Address by Identifier

**Slug:** `IDEALPOSTCODES_GET_ADDRESS_BY_IDENTIFIER`

Retrieve a UK address by UDPRN or UMPRN. This consumes a paid lookup, and UMPRN requires the optional Multiple Residence dataset.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter` | string | No | Comma-separated address fields to include in the result. |
| `identifier` | string | Yes | UDPRN or UMPRN value identifying the address. |
| `identifier_type` | string ("UDPRN" | "UMPRN") | Yes | Identifier kind. UMPRN requires the optional Multiple Residence dataset. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Lookup Postcode

**Slug:** `IDEALPOSTCODES_LOOKUP_POSTCODE`

Return addresses at a UK postcode, or an Irish Eircode when enabled; successful results consume paid lookups.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | string | No | Tags to attach to paid lookups for usage reporting. |
| `filter` | string | No | Comma-separated address fields to include in each result. |
| `postcode` | string | Yes | UK postcode, or Irish Eircode when enabled, to look up. |
| `next_cursor` | string | No | Opaque continuation cursor returned by a previous lookup of the same postcode. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Resolve Address Suggestion

**Slug:** `IDEALPOSTCODES_RESOLVE_ADDRESS_SUGGESTION`

Resolve an address suggestion ID to a complete GBR or USA address. This consumes a paid lookup, and USA resolution requires an enabled USA dataset.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | string | No | Tags to attach to the paid lookup for usage reporting. |
| `country` | string ("GBR" | "USA") | Yes | Dataset route for the suggestion. USA requires the optional USA dataset. |
| `suggestion_id` | string | Yes | Address suggestion ID returned by Find Address Suggestions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Resolve Place

**Slug:** `IDEALPOSTCODES_RESOLVE_PLACE`

Resolve a place suggestion ID to full geography and coordinates. This consumes a paid lookup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | string | No | Tags to attach to the paid lookup for usage reporting. |
| `place_id` | string | Yes | Place suggestion ID returned by Find Place Suggestions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Addresses

**Slug:** `IDEALPOSTCODES_SEARCH_ADDRESSES`

Search complete UK address records by text, filters, or coordinates; successful results consume paid lookups.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `box` | string | No | Bounding box used to restrict results, in the provider's comma-separated coordinate format. |
| `tags` | string | No | Tags to attach to paid lookups for usage reporting. |
| `limit` | integer | No | Maximum addresses requested for this page (1-100); valid-postcode searches may force 100. |
| `query` | string | No | Address text to search; omit when using coordinates or filters. |
| `filter` | string | No | Comma-separated address fields to include in each result. |
| `country` | string | No | Country name used to restrict results. |
| `latitude` | number | No | Latitude for reverse geocoding; provide together with longitude. |
| `postcode` | string | No | Exact postcode used to restrict results. |
| `longitude` | number | No | Longitude for reverse geocoding; provide together with latitude. |
| `post_town` | string | No | Post town used to restrict results. |
| `next_cursor` | string | No | Continuation cursor returned by a previous call for the same search. |
| `postcode_outward` | string | No | Outward postcode used to restrict results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Address

**Slug:** `IDEALPOSTCODES_VALIDATE_ADDRESS`

Match and standardize a GBR or USA address with confidence details. This consumes a paid lookup, and USA verification requires the optional USPS CASS dataset.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | No | USA city hint; use post_town for GBR. |
| `tags` | string | No | Tags to attach to the paid validation lookup for usage reporting. |
| `query` | string | Yes | Free-form address to match and standardize. |
| `state` | string | No | Two-letter USA state code hint. |
| `county` | string | No | GBR county hint. |
| `country` | string ("GBR" | "USA") | Yes | Validation dataset to use; USA requires the optional USPS CASS dataset. |
| `postcode` | string | No | GBR postcode hint; use zip_code for USA. |
| `zip_code` | string | No | USA ZIP Code hint; use postcode for GBR. |
| `post_town` | string | No | GBR post town hint; use city for USA. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Validate Contact

**Slug:** `IDEALPOSTCODES_VALIDATE_CONTACT`

Validate an email address or international phone number using an optional paid dataset enabled on the connected Ideal Postcodes API key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | string | No | Tags to attach to the paid validation lookup for usage reporting. |
| `value` | string | Yes | Email address or international phone number to validate; phone numbers must include a country code. |
| `contact_type` | string ("EMAIL" | "PHONE_NUMBER") | Yes | Kind of contact value to validate. |
| `include_current_carrier` | boolean | No | For phone validation only, request current carrier data. This may consume an additional lookup. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |