Lookups

Help for your own forms: check a phone number as the customer types it, and find the addresses at a UK postcode. Browser and server-only applications can both call these.

Check a phone number

GET https://subcontext.com/api/v1/customers/validate_phone Try it

Token scopes: read or write

Checks a phone number, for live feedback as the customer types it. A quick format check runs first. Numbers that pass it are checked with a phone validation service (UK numbers without a country code are taken as UK).

If the validation service can't be reached, the number is treated as valid (reason is lookup_unavailable), so an outage doesn't stop a customer.

Pass application_id when you have one. The check then uses the application's presentation settings (for example, whether a mobile that's switched off counts as invalid).

Parameters

Name	In	Type	Description
phone required	query	string	The number as typed.
application_id	query	string (uuid)	The application the number is for, if there is one yet. An unknown id is ignored, and so is one a browser application sends without the application's `share_token` in `X-Share-Token`.
X-Share-Token	header	string	The application's `share_token`, from the answer that started it. A browser application sends it with every request about an application that already exists, a replay of the request that started it included. Without it, or with another application's, the answer is `404 not_found` (`409 idempotency_replay_unproven` on a replay). A server-only application doesn't need it.

Responses

200 Whether the number is valid.

Field	Type	Description
data required	object
data.valid required	boolean	Whether to accept the number.
data.normalised	string	The number tidied up, when it's valid.
data.reason	string	Why it's invalid, or why it was accepted without a full check. One of: `"blank"`, `"format_invalid"`, `"too_short"`, `"too_long"`, `"invalid_number"`, `"lookup_unavailable"`, `"drama_number"`

Example

{
  "data": {
    "valid": true,
    "normalised": "+447700900123"
  }
}

401 No token was sent, or it isn't valid because it has expired, was revoked (for example because the application's secret was rotated), or was cut short. Get a new token and try once more.

Field	Type	Description
error required	object
error.code required	string	A short code for the kind of error, such as `invalid_token`, `forbidden`, `not_found` or `validation_failed`. Each code means one thing wherever it appears.
error.message required	string	What went wrong and what to do about it, in plain English.
error.fields	object	When the error is about particular inputs, which ones and why, by name: a nested one with a dot (`customer.email`), one in a list with its place (`components[0].term_years`). Left out when the error isn't about particular inputs.

Example

{
  "error": {
    "code": "invalid_token",
    "message": "The access token has expired. Ask for a new one."
  }
}

403 The token can't be used here. It's missing a scope, it was used from the wrong place (a server-only application's token in a browser, or a browser application's token from a server, another website or a request only server-only applications may make), or it wasn't asked for with `resource=https://subcontext.com/api/v1`.

Field	Type	Description
error required	object
error.code required	string	A short code for the kind of error, such as `invalid_token`, `forbidden`, `not_found` or `validation_failed`. Each code means one thing wherever it appears.
error.message required	string	What went wrong and what to do about it, in plain English.
error.fields	object	When the error is about particular inputs, which ones and why, by name: a nested one with a dot (`customer.email`), one in a list with its place (`components[0].term_years`). Left out when the error isn't about particular inputs.

Example

{
  "error": {
    "code": "forbidden",
    "message": "origin 'https://www.example.com' is not allowlisted for this OAuth application"
  }
}

Find addresses at a postcode

GET https://subcontext.com/api/v1/addresses/lookup Try it

Token scopes: read or write

The addresses at a UK postcode, for an address picker. valid is true when the postcode found at least one address, and town is its post town. An unknown postcode (or a lookup that couldn't be made) gives no addresses.

Parameters

Name	In	Type	Description
postcode required	query	string	The postcode, with or without its space.
application_id	query	string (uuid)	The application the address is for, if there is one yet. An unknown id is ignored, and so is one a browser application sends without the application's `share_token` in `X-Share-Token`.
X-Share-Token	header	string	The application's `share_token`, from the answer that started it. A browser application sends it with every request about an application that already exists, a replay of the request that started it included. Without it, or with another application's, the answer is `404 not_found` (`409 idempotency_replay_unproven` on a replay). A server-only application doesn't need it.

Responses

200 The addresses found.

Field	Type	Description
data required	object
data.addresses required	array of object	The addresses, ready to fill in a customer's address.
data.addresses[].address_line1 required	string
data.addresses[].address_line2 required	string	Further lines, joined with commas. Empty when there are none.
data.addresses[].city required	string	The post town.
data.addresses[].postal_code required	string	The postcode, formatted with its space.
data.addresses[].country required	string
data.valid required	boolean	Whether the postcode found any addresses.
data.town required	string or null	The post town, or `null` when nothing was found.

Example

{
  "data": {
    "addresses": [
      {
        "address_line1": "10 Example Street",
        "address_line2": "",
        "city": "London",
        "postal_code": "SW1A 2AA",
        "country": "United Kingdom"
      },
      {
        "address_line1": "Flat 2",
        "address_line2": "12 Example Street",
        "city": "London",
        "postal_code": "SW1A 2AA",
        "country": "United Kingdom"
      }
    ],
    "valid": true,
    "town": "London"
  }
}

401 No token was sent, or it isn't valid because it has expired, was revoked (for example because the application's secret was rotated), or was cut short. Get a new token and try once more.

Field	Type	Description
error required	object
error.code required	string	A short code for the kind of error, such as `invalid_token`, `forbidden`, `not_found` or `validation_failed`. Each code means one thing wherever it appears.
error.message required	string	What went wrong and what to do about it, in plain English.
error.fields	object	When the error is about particular inputs, which ones and why, by name: a nested one with a dot (`customer.email`), one in a list with its place (`components[0].term_years`). Left out when the error isn't about particular inputs.

Example

{
  "error": {
    "code": "invalid_token",
    "message": "The access token has expired. Ask for a new one."
  }
}

Field	Type	Description
error required	object
error.code required	string	A short code for the kind of error, such as `invalid_token`, `forbidden`, `not_found` or `validation_failed`. Each code means one thing wherever it appears.
error.message required	string	What went wrong and what to do about it, in plain English.
error.fields	object	When the error is about particular inputs, which ones and why, by name: a nested one with a dot (`customer.email`), one in a list with its place (`components[0].term_years`). Left out when the error isn't about particular inputs.

Example

{
  "error": {
    "code": "forbidden",
    "message": "origin 'https://www.example.com' is not allowlisted for this OAuth application"
  }
}

Stuck, or something missing?

Get in touch and a person on the team will help.