API Home

Requests

Contacts

 /v1/contact POST

Orgs

 /v1/org/{domain} GET
 /v1/org/{domain}/locations GET
 /v1/org/search GET

Locations

 /v1/org/{domain}/locations GET
 /v1/location/{domain} GET

Schemas

/v1/org/search GET

Returns a collection of organizations whose name contains the given search term (submitted as q in the parameters) or is an exact match on the to.co org domain. The search is case-insensitive. The companies are returned in alphabetic order by default but you can change this using the sort parameter. The response is paginated (see pagination). The organization response returns an address if present. The registered address for registered organizations or the default address for non-registered organizations.

Orgs

Request URL

https://api.to.co/v1/org/search?q=john%20lewis&api_key={your_api_key}

Request Parameters

Key Type Required Description Example
q string Required Search term
"john lewis"

Responses

Success (200)

Schema: OrgSearchResponse

{
  "orgs": {
    "total": 1,
    "results": [
      {
        "description": "Shop new season trends in homeware, furniture and fashion at John Lewis & Partners.",
        "domain": "yxpx6pdx.uk.to.co",
        "informal_name": "John Lewis",
        "locations": {
          "count": 3,
          "default": {
            "address_verified": true,
            "name": "John Lewis & Partners",
            "hours": {
              "normal": [
                {
                  "day": 0,
                  "open": false,
                  "open_time": "00:00",
                  "close_time": "00:00"
                },
                {
                  "day": 1,
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "17:00"
                },
                {
                  "day": 2,
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "17:00"
                },
                {
                  "day": 3,
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "17:00"
                },
                {
                  "day": 4,
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "17:00"
                },
                {
                  "day": 5,
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "17:00"
                },
                {
                  "day": 6,
                  "open": false,
                  "open_time": "00:00",
                  "close_time": "00:00"
                }
              ],
              "special": [
                {
                  "date": "2025-12-24",
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "16:00"
                },
                {
                  "date": "2025-12-26",
                  "open": true,
                  "open_time": "09:00",
                  "close_time": "16:00"
                }
              ]
            },
            "domain": "2hqh3aw8.loc.uk.to.co",
            "address": {
              "domain": "yyb7e4pd.a.uk.to.co",
              "line1": "171 Victoria Street",
              "line2": "London",
              "zip": "SW1E 5NN",
              "country_code": "GB"
            },
            "links": {
              "facebook_url": "https://www.facebook.com/johnlewisretail",
              "instagram_url": "https://instagram.com/johnlewis",
              "linkedin_url": "https://www.linkedin.com/company/johnlewisandpartners/",
              "tiktok_url": "https://www.tiktok.com/@johnlewis",
              "twitter_url": "https://twitter.com/JohnLewisRetail",
              "website_url": "https://www.johnlewis.com/",
              "youtube_url": "https://www.youtube.com/c/johnlewisandpartners"
            }
          }
        },
        "logo_url": "https://media.to.co/yxpx6pdx.uk.to.co/20220121T15065-7w0qIqaBp3SxY0Y3hqJb.jpg",
        "name": "John Lewis plc",
        "public_domain": "johnlewis.to.co",
        "registration": {
          "date": "1928-09-20",
          "country_code": "GB",
          "number": "00233462",
          "address": {
            "domain": "pmyn68c5.a.uk.to.co",
            "line1": "171 Victoria Street",
            "line2": "London",
            "zip": "SW1E 5NN",
            "country_code": "GB"
          }
        },
        "updated": "2022-01-27T15:50:28.000Z",
        "version_number": 1
      }
    ]
  },
  "request": {
    "id": "caedc1bd-a4d4-4e18-a904-bac04c31fe85",
    "success": true,
    "period_start": "2025-02-03T14:49:40.000Z",
    "next_period_start": "2025-03-03T14:49:40.000Z",
    "requests_this_period": 2000,
    "credit_available_this_period": 10000,
    "credit_used_this_request": 1,
    "credit_used_this_period": 2500,
    "credit_remaining_this_period": 7500,
    "account_id": "fddb84zz.acct.to.co",
    "subscription_id": "Az9g3fSwOBwtj2El"
  }
}

Forbidden (403)

Schema: ForbiddenError

{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}

Not Found (404)

Schema: NotFoundError

{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}