Developer

All tutorials

Swiftcomplete Validate API

intermediate
1Overview

The Validate API matches addresses against official address records, normalises formatting, and suggests corrections when the input contains meaningful errors.

Detects and validates what3words addresses. If invalid, returns the most likely candidate using proximity to the rest of the address, where available.

The response contains three top-level parts:

PartDescription
validationDescribes whether the input matched an underlying source record and at which resolution.
addressThe normalised address to use, provided as a single string and split into multiple lines.
associatedRecordsA list of any records associated with the returned address, such as apartments, suites, departments, or business names.
2Authentication

All requests require an API key passed in the X-API-Key header.

Get an API key here

X-API-Key: your_api_key_here
Copied
3Endpoint
POST https://api.swiftcomplete.com/v1/validate-address/
Content-Type: application/json
Copied

Request and response bodies are UTF-8 encoded JSON.

4Request

Each field is optional, but the request must contain at least one non-empty value in singleLine, companyName, line1, line2, line3, tertiaryLocality, secondaryLocality, primaryLocality, or postalCode.

state, stateCode, countryName, and countryCode do not satisfy this minimum-input requirement by themselves, but may be included with another qualifying field.

If your address data is unstructured, pass the whole address in singleLine.

If your address data is already structured, pass the components into their respective fields.

Do not combine singleLine with the structured address fields. When singleLine is provided, it takes precedence and the structured fields are ignored. You may still provide countryCode to restrict matching to one or more markets.

Providing one or more supported country codes restricts matching to those markets and improves accuracy. Separate multiple country codes with commas. It is strongly recommended whenever the relevant market is known.

FieldTypeDescription
singleLinestringFreeform, unstructured address string. Example: 10 downing st london sw1a2aa.
companyNamestringBusiness or organisation name associated with the address.
line1stringPrimary address line.
line2stringSecondary address line.
line3stringTertiary address line.
tertiaryLocalitystringSub-locality, neighbourhood, or village within a larger locality.
secondaryLocalitystringDistrict, borough, or suburb.
primaryLocalitystringCity or town.
statestringState, province, county, region, or other principal administrative area, where applicable.
stateCodestringState abbreviation, where applicable.
postalCodestringPostal or ZIP code.
countryNamestringCountry name.
countryCodestringOne or more supported ISO 3166-1 alpha-2 country codes. Separate multiple codes with commas, for example GB,DE.
what3wordsstringA what3words address, eg. ///filled.count.soap
5Response

A response contains validation, address, and associatedRecords.

FieldTypeDescription
validationobjectThe result of matching the input to the underlying source data.
addressobject or nullThe normalised address to use. Returned for match and suggestion; null for none.
associatedRecordsarray or nullRecords associated with the returned address. null when none exist.

validation

validation.result

validation.result is the core result of the operation. Read it first when deciding whether to accept the returned address, ask the user to confirm a suggestion, or ask the user to re-enter the address.

ResultDescription
matchThe input was successfully matched to an official record.
suggestionThe input matched the underlying source data but changes are large enough to justify seeking user confirmation.
noneThe input could not be matched to an address in the underlying source data. address and validation.resolution will be null.

validation.resolution

validation.resolution describes the highest address level matched against the underlying source data. See Input preservation for how this relates to values returned in address.

ResolutionDescriptionExample of matched source data
subPremiseThe input matched a specific unit, flat, suite, floor, department, organisation, or other source record within or associated with a building.HSBC Holdings plc, 8 Canada Square, London, E14 5HQ
premiseThe input matched a specific building or premise.10 Downing Street, London, SW1A 2AA
streetThe input matched a street or thoroughfare, but not a specific premise.Great Russell Street, London, WC1B 3DG
cityThe input matched only a city, town, or locality.London, United Kingdom
nullNo address level could be matched, or resolution is not applicable.Returned with validation.result: none.

address

address is the normalised address to use when validation.result is match or suggestion.

FieldTypeDescription
address.singleLinestringThe complete normalised address, formatted as a single display line.
address.multiLineobjectThe same address broken into structured components.

address.multiLine contains companyName, line1, line2, line3, tertiaryLocality, secondaryLocality, primaryLocality, state, stateCode, postalCode, countryName, countryCode, and what3words.

Each field contains the value returned by Swiftcomplete, or null where the component does not apply. When validation.result is none, address is null.

associatedRecords

associatedRecords provides a list of any address records associated with the returned address, such as companies, flats, suites, departments.

These records can be presented to the end user as optional refinements to the default address; they do not change the core validation result. When records are returned, show their picklistDisplay values to the user after the base address has been validated or accepted.

FieldTypeDescription
associatedRecords[].picklistDisplaystringConsumer-facing text to display in a pick list. Do not use this value directly as an address field.
associatedRecords[].overridesobjectThe replacement values to apply to the default address if this record is selected.
associatedRecords[].overrides.singleLinestringThe value that should replace address.singleLine if the integration uses the single-line format.
associatedRecords[].overrides.multiLineobjectA partial address object containing each structured field that should replace the corresponding field in address.multiLine. It can contain any multi-line address field.

Applying an associated record

Do not change the default address unless the user selects an associated record.

When a record is selected:

  1. If your integration uses address.singleLine, replace it with associatedRecords[n].overrides.singleLine.
  2. If your integration uses address.multiLine, replace each field present in associatedRecords[n].overrides.multiLine with the returned value.
  3. Leave every address field not included in overrides.multiLine unchanged.

When no associated records are available, associatedRecords is null.

6Input preservation

Swiftcomplete validates submitted address data against underlying source records. It may also preserve important input that is not present in the matched record but is still useful for delivery or recipient identification.

Examples include:

  • recipient or attention details, such as FAO Reception Desk;
  • department names;
  • informal or newly registered business names; and
  • delivery or entrance instructions, such as Use side entrance or Deliver to loading bay.

Swiftcomplete determines whether input should be preserved and where it should appear in the returned address. Integrations should use address.singleLine or address.multiLine as returned and should not attempt to identify or reposition preserved input.

Relationship with validation.resolution

validation.resolution describes the highest address level matched against the underlying source data. It does not describe the resolution of address.

Preserved input can therefore make the returned address more detailed than the matched source record. A populated field is not evidence that the field itself was validated.

Always use:

  • validation.resolution to assess match precision; and
  • address as the normalised address to display, store, or submit.

Worked example

The request and response below show Swiftcomplete matching the university at subPremise level while preserving an unvalidated department name:

{
  "singleLine": "Department of Geospatial Engineering, King's College London, Strand, London, WC2R 2LS, United Kingdom",
  "countryCode": "GB"
}
Copied
{
  "validation": {
    "result": "match",
    "resolution": "subPremise"
  },
  "address": {
    "singleLine": "Department Of Geospatial Engineering, Kings College London, Strand, London, WC2R 2LS, United Kingdom",
    "multiLine": {
      "companyName": "Kings College London",
      "line1": "Department Of Geospatial Engineering",
      "line2": "Strand",
      "line3": null,
      "tertiaryLocality": null,
      "secondaryLocality": null,
      "primaryLocality": "London",
      "state": "Greater London",
      "stateCode": null,
      "postalCode": "WC2R 2LS",
      "countryName": "United Kingdom",
      "countryCode": "GB"
    }
  },
  "associatedRecords": null
}
Copied
Kings College London is matched against the underlying source data and returned in companyName. Department Of Geospatial Engineering is not part of the matched source record, but is preserved in line1. The authoritative match level remains subPremise.
7Response handling guidance
ResultAssociated recordsRecommended handling
matchnullUse address as the normalised address, subject to your required validation.resolution.
matchArrayUse address as the default. Optionally show each picklistDisplay as a more specific choice and apply its overrides if selected.
suggestionnullPresent address as the corrected address and ask the user to confirm it before replacing their original address.
suggestionArrayPresent address as the corrected default. If accepted, optionally show associated records and apply an override only if selected.
nonenullAsk the user to review, edit, or re-enter the address.
8Markets

The Validate API currently supports the following markets:

MarketCountry code
United KingdomGB
GermanyDE
9Examples

match

{
  "singleLine": "40 Sisters Avenue, London, SW11 5SQ, United Kingdom",
  "countryCode": "GB"
}
Copied
{
  "validation": {
    "result": "match",
    "resolution": "premise"
  },
  "address": {
    "singleLine": "40 Sisters Avenue, London, SW11 5SQ, United Kingdom",
    "multiLine": {
      "companyName": null,
      "line1": "40 Sisters Avenue",
      "line2": null,
      "line3": null,
      "tertiaryLocality": null,
      "secondaryLocality": null,
      "primaryLocality": "London",
      "state": "Greater London",
      "stateCode": null,
      "postalCode": "SW11 5SQ",
      "countryName": "United Kingdom",
      "countryCode": "GB"
    }
  },
  "associatedRecords": null
}
Copied

match with associatedRecords

{
  "singleLine": "242 acklam road w105jj",
  "countryCode": "GB"
}
Copied
{
  "validation": {
    "result": "match",
    "resolution": "premise"
  },
  "address": {
    "singleLine": "242 Acklam Road, London, W10 5JJ, United Kingdom",
    "multiLine": {
      "companyName": null,
      "line1": "242 Acklam Road",
      "line2": null,
      "line3": null,
      "tertiaryLocality": null,
      "secondaryLocality": null,
      "primaryLocality": "London",
      "state": "Greater London",
      "stateCode": null,
      "postalCode": "W10 5JJ",
      "countryName": "United Kingdom",
      "countryCode": "GB"
    }
  },
  "associatedRecords": [
    {
      "picklistDisplay": "A P D A London Ltd",
      "overrides": {
        "singleLine": "A P D A London Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "A P D A London Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Barton Engineers",
      "overrides": {
        "singleLine": "Barton Engineers, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Barton Engineers"
        }
      }
    },
    {
      "picklistDisplay": "Bloobloom",
      "overrides": {
        "singleLine": "Bloobloom, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Bloobloom"
        }
      }
    },
    {
      "picklistDisplay": "Buchanan Advertising (UK) Ltd",
      "overrides": {
        "singleLine": "Buchanan Advertising (UK) Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Buchanan Advertising (UK) Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Frescobol",
      "overrides": {
        "singleLine": "Frescobol, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Frescobol"
        }
      }
    },
    {
      "picklistDisplay": "Fusion One International Ltd",
      "overrides": {
        "singleLine": "Fusion One International Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Fusion One International Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Goodwood Contractors Ltd",
      "overrides": {
        "singleLine": "Goodwood Contractors Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Goodwood Contractors Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Indie Bay Snacks",
      "overrides": {
        "singleLine": "Indie Bay Snacks, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Indie Bay Snacks"
        }
      }
    },
    {
      "picklistDisplay": "Intelligent Imaging Innovations Ltd",
      "overrides": {
        "singleLine": "Intelligent Imaging Innovations Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Intelligent Imaging Innovations Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Ottoman Hands Ltd",
      "overrides": {
        "singleLine": "Ottoman Hands Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Ottoman Hands Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Paymentsense",
      "overrides": {
        "singleLine": "Paymentsense, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Paymentsense"
        }
      }
    },
    {
      "picklistDisplay": "Perfect Storm Media Ltd",
      "overrides": {
        "singleLine": "Perfect Storm Media Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Perfect Storm Media Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Phycobloom Ltd",
      "overrides": {
        "singleLine": "Phycobloom Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Phycobloom Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Powder Bowl Trading Ltd",
      "overrides": {
        "singleLine": "Powder Bowl Trading Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Powder Bowl Trading Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Rachel Nevin Communications",
      "overrides": {
        "singleLine": "Rachel Nevin Communications, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Rachel Nevin Communications"
        }
      }
    },
    {
      "picklistDisplay": "Rigby & Marchant Ltd",
      "overrides": {
        "singleLine": "Rigby & Marchant Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Rigby & Marchant Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Sophie Harley London",
      "overrides": {
        "singleLine": "Sophie Harley London, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Sophie Harley London"
        }
      }
    },
    {
      "picklistDisplay": "Twotwentyseven",
      "overrides": {
        "singleLine": "Twotwentyseven, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Twotwentyseven"
        }
      }
    },
    {
      "picklistDisplay": "V M V Studio",
      "overrides": {
        "singleLine": "V M V Studio, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "V M V Studio"
        }
      }
    },
    {
      "picklistDisplay": "Westbourne Studios",
      "overrides": {
        "singleLine": "Westbourne Studios, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Westbourne Studios"
        }
      }
    },
    {
      "picklistDisplay": "Workspace Management",
      "overrides": {
        "singleLine": "Workspace Management, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Workspace Management"
        }
      }
    },
    {
      "picklistDisplay": "Yousoft Ltd",
      "overrides": {
        "singleLine": "Yousoft Ltd, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Yousoft Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Zalacain Wayfinding",
      "overrides": {
        "singleLine": "Zalacain Wayfinding, 242 Acklam Road, London, W10 5JJ, United Kingdom",
        "multiLine": {
          "companyName": "Zalacain Wayfinding"
        }
      }
    }
  ]
}
Copied

suggestion with associatedRecords and an attention line

The attention line is preserved in line1. Each associated-record override adds the selected company while leaving the attention line in place.

{
  "singleLine": "FAO Accounts Payable, 65 Alfred Rod, London, W2 5EU, United Kingdom",
  "countryCode": "GB"
}
Copied
{
  "validation": {
    "result": "suggestion",
    "resolution": "premise"
  },
  "address": {
    "singleLine": "FAO Accounts Payable, 65 Alfred Road, London, W2 5EU, United Kingdom",
    "multiLine": {
      "companyName": null,
      "line1": "FAO Accounts Payable",
      "line2": "65 Alfred Road",
      "line3": null,
      "tertiaryLocality": null,
      "secondaryLocality": null,
      "primaryLocality": "London",
      "state": "Greater London",
      "stateCode": null,
      "postalCode": "W2 5EU",
      "countryName": "United Kingdom",
      "countryCode": "GB"
    }
  },
  "associatedRecords": [
    {
      "picklistDisplay": "Blaiz Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Blaiz Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Blaiz Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Carnot Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Carnot Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Carnot Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Craster Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Craster Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Craster Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Daisy Global Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Daisy Global Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Daisy Global Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Davina Combe Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Davina Combe Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Davina Combe Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Great Western Studios",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Great Western Studios, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Great Western Studios"
        }
      }
    },
    {
      "picklistDisplay": "Italspirits Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Italspirits Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Italspirits Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Moxon Architects Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Moxon Architects Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Moxon Architects Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Nishura Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Nishura Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Nishura Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Obatan Llc",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Obatan Llc, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Obatan Llc"
        }
      }
    },
    {
      "picklistDisplay": "R F Gill & Associates",
      "overrides": {
        "singleLine": "FAO Accounts Payable, R F Gill & Associates, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "R F Gill & Associates"
        }
      }
    },
    {
      "picklistDisplay": "Run For The Hills",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Run For The Hills, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Run For The Hills"
        }
      }
    },
    {
      "picklistDisplay": "Solid Floor Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Solid Floor Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Solid Floor Ltd"
        }
      }
    },
    {
      "picklistDisplay": "Stephen Fletcher Architects",
      "overrides": {
        "singleLine": "FAO Accounts Payable, Stephen Fletcher Architects, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "Stephen Fletcher Architects"
        }
      }
    },
    {
      "picklistDisplay": "What3words Ltd",
      "overrides": {
        "singleLine": "FAO Accounts Payable, What3words Ltd, 65 Alfred Road, London, W2 5EU, United Kingdom",
        "multiLine": {
          "companyName": "What3words Ltd"
        }
      }
    }
  ]
}
Copied

none

{
  "singleLine": "This is not a real address",
  "countryCode": "GB"
}
Copied
{
  "validation": {
    "result": "none",
    "resolution": null
  },
  "address": null,
  "associatedRecords": null
}
Copied
10Errors
HTTP codeMeaningWhat to do
400The request contains malformed JSON or fails request validation, such as when no non-empty address component is provided.Correct the request. Do not retry it unchanged.
401The X-API-Key header is missing or contains an invalid key.Check the key and header name.
429Too many requests.Back off and retry after the period indicated in Retry-After.
500An unexpected error occurred on the server.Retry with backoff. If the problem persists, contact support.