to.co REST API
1.0.0

The to.co REST API provides developers programmatic access to the millions of companies who use to.co to publish their latest details to customers and business partners. You can find out more and get an API Key at https://to.co/developers.

This is the documentation for version 1.0.0 of the API. Last update on Feb 13, 2023.

Base URL 
https://api.to.co

Authentication

Api key (http_api_key)

Send an authentication token in the api_key query parameter to authenticate with the API.

Contacts

Add

POST /v1/contact

Creates a private contact

Body Required

  • first_name string

    The first name of the contact

  • last_name string

    The last name of the contact

  • full_name string

    The full name of the contact (first and last name). Submit either the Full Name or use the separate First and Last Name fields. to.co will split this field to update the First Name and Last Name.

  • email string

    A valid email address for the contact

  • email_opt_out string

    Set to true if the contact has opted out of email communication

  • org_name string

    The contact's Organization name

  • registration_number string

    The contact's official Organization registration or incorporation number

  • vat_registration_number string

    The contact's official Organization tax registration number e.g. VAT number or Employer Identification Number (EIS)

  • job_title string

    The contact's job title or role at the Organization

  • department string

    The Organization department where the contact works

  • country_code string

    ISO 3166 Country Code. 2 Characters. e.g. US for United States

  • avatar_url string

    URL to image of contact avatar

  • salutation string

    Mr, Mrs, Miss, Dr, etc

  • phone string

    Formatted phone number for the contact

  • phone_alt string

    Alternate formatted phone number

  • phone_local string

    Local phone number for contact

  • phone_mobile string

    Mobile number for contact

  • phone_free string

    Formatted toll-free phone number for contact

  • phone_tty string

    Formatted TTY contact phone number

  • website_url string

    Contact's or Organization's website URL

  • twitter_handle string

    The contact's Twitter page handle or full URL

  • instagram_handle string

    The contact's Instagram page handle or full URL

  • facebook_url string

    The contact's Facebook page URL

  • linkedin_url string

    The contact's LinkedIn page URL

  • youtube_url string

    The contact's YouTube page URL

  • vimeo_url string

    The contact's Vimeo page URL

  • tiktok_url string

    The contact's TikTok page URL

  • pinterest_url string

    The contact's Pinterest page URL

  • clubhouse_url string

    The contact's Clubhouse page URL

  • snapchat_url string

    The contact's Snapchat page URL

  • line1 string

    Line 1 of contact address

  • line2 string

    Line 2 of contact address

  • line3 string

    Line 3 of contact address

  • city string

    City of the contact address

  • sublocality string

    Sub-Locality. Typically defined as the region or area nearest the city or town

  • state string

    State name of contact address

  • state_code string

    Code for the State or County (Upper Case). 2 alpha-character ISO 3166 e.g. CA for California if country_code is US

  • zip string

    Address ZIP or Postal Code

Responses

  • • 200 object

    Success

    • contact object Required
      • created boolean

        Indicates if the Contact was created

      • id string

        The id of the Contact

    • request object Required
      • id string Required

        Unique request identifier

      • success boolean Required

        Did the request execute successfully?

      • period_start string Required

        The start date and time of the current subscription Data Credits plan

      • next_period_start string Required

        The start date and time of the next subscription Data Credits plan. Usually a calendar month after the period_start

      • requests_this_period integer

        The number of successfully executed API calls (requests) this period so far

        Default value is 0.

      • credit_available_this_period integer Required

        The total number of Data Credits available for use in this period. This is based upon the subscribed Data Credits Plan

      • credit_used_this_request integer Required

        The number of Data Credits used to process the current API request

      • credit_used_this_period integer Required

        The total number of Data Credits already used from period_start

      • credit_remaining_this_period string Required

        The total number of Data Credits still available this period

      • account_id string

        The internal to.co Account ID related to the Data Credits Plan

      • subscription_id string

        The internal to.co Subscription ID related to the Data Credits Plan

  • • 403 object

    Forbidden

  • • 404 object

    Not Found

POST /v1/contact 
curl \
 -X POST https://api.to.co/v1/contact?api_key=api_token_value \
 -H "Content-Type: application/json" \
 -d '{"first_name":"Tom","last_name":"Jones","email":"tom@reallybigco.com","email_opt_out":false,"country_code":"US","avatar_url":"","org_name":"Really Big Co","department":"Sales Department, NY","job_title":"Retail Manager","registration_number":"","vat_registration_number":"","salutation":"Mr","phone":"","phone_alt":"","phone_local":"","phone_mobile":"","phone_free":"","phone_tty":"","website_url":"https://reallybigco.com","twitter_handle":"","instagram_handle":"","facebook_url":"","linkedin_url":"","youtube_url":"","vimeo_url":"","tiktok_url":"","pinterest_url":"","clubhouse_url":"","snapchat_url":"","line1":"350 Fifth Avenue","line2":"Midtown Manhattan","sublocality":"Manhattan","city":"New York City","state":"New York","state_code":"NY","zip":"10118"}'
Request example 
{
  "first_name": "Tom",
  "last_name": "Jones",
  "email": "tom@reallybigco.com",
  "email_opt_out": false,
  "country_code": "US",
  "avatar_url": "",
  "org_name": "Really Big Co",
  "department": "Sales Department, NY",
  "job_title": "Retail Manager",
  "registration_number": "",
  "vat_registration_number": "",
  "salutation": "Mr",
  "phone": "",
  "phone_alt": "",
  "phone_local": "",
  "phone_mobile": "",
  "phone_free": "",
  "phone_tty": "",
  "website_url": "https://reallybigco.com",
  "twitter_handle": "",
  "instagram_handle": "",
  "facebook_url": "",
  "linkedin_url": "",
  "youtube_url": "",
  "vimeo_url": "",
  "tiktok_url": "",
  "pinterest_url": "",
  "clubhouse_url": "",
  "snapchat_url": "",
  "line1": "350 Fifth Avenue",
  "line2": "Midtown Manhattan",
  "sublocality": "Manhattan",
  "city": "New York City",
  "state": "New York",
  "state_code": "NY",
  "zip": "10118"
}
Response example (200) 
{
  "contact": {
    "type": "object",
    "properties": {
      "created": {
        "type": "boolean",
        "description": "Indicates if the Contact was created"
      },
      "id": {
        "type": "string",
        "description": "The id of the Contact"
      }
    }
  },
  "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"
  }
}
Response example (403) 
{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}
Response example (404) 
{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}

Orgs

Get

GET /v1/org/{domain}

Returns a single organization

Path parameters

  • domain string Required

    This can either be a to.co Stable Domain Name e.g. m3t6dsk6.uk.to.co or to.co Public Domain Name like unilever.to.co. It must end in .to.co to be valid.

Responses

  • • 200 object

    Success

    • org object Required
      • description string

        The description of the Org

      • domain string

        The to.co Stable Domain Name for the Org ending .{country_code}.to.co

      • emails object
      • industry object
        • sic_code string

          UK Standard Industrial Classification (SIC) 2007 Code

      • informal_name string

        The informal or trading name for the Org. Often this name will shed any suffixes required by the legal name

      • links object
      • locations object
        • count integer

          The total number of Locations associated with this Org

        • default object
          • address object
            • domain string

              to.co Stable Address Domain Name ending in .a.to.co

            • line1 string

              First line of the address

            • line2 string

              Second line of the address

            • line3 string

              Third line of the address

            • city string

              City or Town name

            • sublocality string

              Sub-Locality. Typically defined as the region or area nearest the city or town

            • state string

              State or County

            • state_code string

              Code for the State or County

            • zip string

              ZIP or Postal Code

            • country_code string

              County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

            • version_number integer

              Version number of the Address record

          • address_verified boolean

            Has the postal address been verified by the Location owner?

          • code string

            Optional code set by the owner to represent this Location

          • closed_date string

            The date the Location closed

          • default boolean

            Is this the default Location for the related Org?

          • description string

            The description of the Location

          • domain string

            The to.co Stable Domain Name for the Location ending .loc.to.co

          • emails object
          • established_year integer

            The year the Location was established

          • hours object
            • normal array[object]

              Normal opening hours

              • day integer

                Day of week where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday

              • open boolean

                Is the Location open or closed on this date?

              • open_time string

                If the Location is open, when does it open? Format: HH:MM

              • close_time string

                If the Location is open, when does it close? Format: HH:MM

            • message string

              Message to display next to normal opening hours

            • special array[object]

              Special opening hours which override the normal hours on given dates

              • date string

                Date on which the special hours are effective. Format YYYY-MM-DD

              • open boolean

                Is the Location open or closed on this date?

              • open_time string

                If the Location is open, when does it open? Format: HH:MM

              • close_time string

                If the Location is open, when does it close? Format: HH:MM

            • special_message string

              Message to display next to special opening hours

          • links object
          • name string

            The Location name

          • org_domain string

            The to.co Stable Domain Name for the Org ending .{country_code}.to.co

          • phones object
            • default string

              The default phone number

            • alt string

              The alternate phone number

            • local string

              The local phone number

            • fax string

              The facsimile (fax) phone number

            • mobile string

              The mobile phone number

            • free string

              The free phone number

            • tty string

              The TTY (Teletypewriter) phone number

          • public_domain string

            The public to.co Stable Domain Name or Public Location Domain ending in .loc.to.co which shows the to.co Page for the Location

          • updated string

            The time the Location was last updated in Coordinated Universal Time (UTC)

          • version_number integer

            Version number of the Location record

      • logo_url string

        The URL of the logo for the Org

      • name string

        The official or legal name of the Org

      • phones object
        • default string

          The default phone number

        • alt string

          The alternate phone number

        • local string

          The local phone number

        • fax string

          The facsimile (fax) phone number

        • mobile string

          The mobile phone number

        • free string

          The free phone number

        • tty string

          The TTY (Teletypewriter) phone number

      • public_domain string

        The public to.co Legal Name Domain or Go Business Domain ending in .to.co which shows the to.co Page for the Org

      • registration object
        • country_code string

          County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

        • date string

          The date the Org was registered

        • number string

          The official registration number issued by the Company Registrar

        • state_code string

          State Abbreviation Code (Upper Case) e.g AL for Alabama. 2 alpha-character

        • address object
          • domain string

            to.co Stable Address Domain Name ending in .a.to.co

          • line1 string

            First line of the address

          • line2 string

            Second line of the address

          • line3 string

            Third line of the address

          • city string

            City or Town name

          • sublocality string

            Sub-Locality. Typically defined as the region or area nearest the city or town

          • state string

            State or County

          • state_code string

            Code for the State or County

          • zip string

            ZIP or Postal Code

          • country_code string

            County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

          • version_number integer

            Version number of the Address record

      • updated string

        The time the Org was last updated in Coordinated Universal Time (UTC)

      • vat_registration object
        • number string

          VAT Registration Number issued to the Org e.g. GB111222233

      • version_number integer

        Version number of the Org record

    • request object Required
      • id string Required

        Unique request identifier

      • success boolean Required

        Did the request execute successfully?

      • period_start string Required

        The start date and time of the current subscription Data Credits plan

      • next_period_start string Required

        The start date and time of the next subscription Data Credits plan. Usually a calendar month after the period_start

      • requests_this_period integer

        The number of successfully executed API calls (requests) this period so far

        Default value is 0.

      • credit_available_this_period integer Required

        The total number of Data Credits available for use in this period. This is based upon the subscribed Data Credits Plan

      • credit_used_this_request integer Required

        The number of Data Credits used to process the current API request

      • credit_used_this_period integer Required

        The total number of Data Credits already used from period_start

      • credit_remaining_this_period string Required

        The total number of Data Credits still available this period

      • account_id string

        The internal to.co Account ID related to the Data Credits Plan

      • subscription_id string

        The internal to.co Subscription ID related to the Data Credits Plan

  • • 403 object

    Forbidden

  • • 404 object

    Not Found

GET /v1/org/{domain} 
curl \
 -X GET https://api.to.co/v1/org/unilever.to.co?api_key=api_token_value
Response example (200) 
{
  "org": {
    "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"
  }
}
Response example (403) 
{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}
Response example (404) 
{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}

GetLocations

GET /v1/org/{domain}/locations

Returns the locations associated with an organization

Path parameters

  • domain string Required

    Domain name of the Org ending .to.co

Responses

  • • 200 object

    Success

    • locations object Required
      • total integer

        The total number of Location records available. This could be greater than the number returned in the results if pagination is in use

      • results array[object]

        The list of Locations

        • address object
          • domain string

            to.co Stable Address Domain Name ending in .a.to.co

          • line1 string

            First line of the address

          • line2 string

            Second line of the address

          • line3 string

            Third line of the address

          • city string

            City or Town name

          • sublocality string

            Sub-Locality. Typically defined as the region or area nearest the city or town

          • state string

            State or County

          • state_code string

            Code for the State or County

          • zip string

            ZIP or Postal Code

          • country_code string

            County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

          • version_number integer

            Version number of the Address record

        • address_verified boolean

          Has the postal address been verified by the Location owner?

        • code string

          Optional code set by the owner to represent this Location

        • closed_date string

          The date the Location closed

        • default boolean

          Is this the default Location for the related Org?

        • description string

          The description of the Location

        • domain string

          The to.co Stable Domain Name for the Location ending .loc.to.co

        • emails object
        • established_year integer

          The year the Location was established

        • hours object
          • normal array[object]

            Normal opening hours

            • day integer

              Day of week where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday

            • open boolean

              Is the Location open or closed on this date?

            • open_time string

              If the Location is open, when does it open? Format: HH:MM

            • close_time string

              If the Location is open, when does it close? Format: HH:MM

          • message string

            Message to display next to normal opening hours

          • special array[object]

            Special opening hours which override the normal hours on given dates

            • date string

              Date on which the special hours are effective. Format YYYY-MM-DD

            • open boolean

              Is the Location open or closed on this date?

            • open_time string

              If the Location is open, when does it open? Format: HH:MM

            • close_time string

              If the Location is open, when does it close? Format: HH:MM

          • special_message string

            Message to display next to special opening hours

        • links object
        • name string

          The Location name

        • org_domain string

          The to.co Stable Domain Name for the Org ending .{country_code}.to.co

        • phones object
          • default string

            The default phone number

          • alt string

            The alternate phone number

          • local string

            The local phone number

          • fax string

            The facsimile (fax) phone number

          • mobile string

            The mobile phone number

          • free string

            The free phone number

          • tty string

            The TTY (Teletypewriter) phone number

        • public_domain string

          The public to.co Stable Domain Name or Public Location Domain ending in .loc.to.co which shows the to.co Page for the Location

        • updated string

          The time the Location was last updated in Coordinated Universal Time (UTC)

        • version_number integer

          Version number of the Location record

    • request object Required
      • id string Required

        Unique request identifier

      • success boolean Required

        Did the request execute successfully?

      • period_start string Required

        The start date and time of the current subscription Data Credits plan

      • next_period_start string Required

        The start date and time of the next subscription Data Credits plan. Usually a calendar month after the period_start

      • requests_this_period integer

        The number of successfully executed API calls (requests) this period so far

        Default value is 0.

      • credit_available_this_period integer Required

        The total number of Data Credits available for use in this period. This is based upon the subscribed Data Credits Plan

      • credit_used_this_request integer Required

        The number of Data Credits used to process the current API request

      • credit_used_this_period integer Required

        The total number of Data Credits already used from period_start

      • credit_remaining_this_period string Required

        The total number of Data Credits still available this period

      • account_id string

        The internal to.co Account ID related to the Data Credits Plan

      • subscription_id string

        The internal to.co Subscription ID related to the Data Credits Plan

  • • 403 object

    Forbidden

  • • 404 object

    Not Found

GET /v1/org/{domain}/locations 
curl \
 -X GET https://api.to.co/v1/org/unilever.to.co/locations?api_key=api_token_value
Response example (200) 
{
  "locations": {
    "total": 1,
    "results": [
      {
        "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"
        }
      }
    ]
  },
  "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"
  }
}
Response example (403) 
{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}
Response example (404) 
{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}

Search

GET /v1/org/search

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.

Query parameters

  • q string Required

    Search term

Responses

  • • 200 object

    Success

    • orgs object Required
      • total integer

        The total number of Org records available. This could be greater than the number returned in the results if pagination is in use

      • results array[object]

        The list of Orgs

        • description string

          The description of the Org

        • domain string

          The to.co Stable Domain Name for the Org ending .{country_code}.to.co

        • emails object
        • industry object
          • sic_code string

            UK Standard Industrial Classification (SIC) 2007 Code

        • informal_name string

          The informal or trading name for the Org. Often this name will shed any suffixes required by the legal name

        • links object
        • locations object
          • count integer

            The total number of Locations associated with this Org

          • default object
            • address object
              • domain string

                to.co Stable Address Domain Name ending in .a.to.co

              • line1 string

                First line of the address

              • line2 string

                Second line of the address

              • line3 string

                Third line of the address

              • city string

                City or Town name

              • sublocality string

                Sub-Locality. Typically defined as the region or area nearest the city or town

              • state string

                State or County

              • state_code string

                Code for the State or County

              • zip string

                ZIP or Postal Code

              • country_code string

                County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

              • version_number integer

                Version number of the Address record

            • address_verified boolean

              Has the postal address been verified by the Location owner?

            • code string

              Optional code set by the owner to represent this Location

            • closed_date string

              The date the Location closed

            • default boolean

              Is this the default Location for the related Org?

            • description string

              The description of the Location

            • domain string

              The to.co Stable Domain Name for the Location ending .loc.to.co

            • emails object
            • established_year integer

              The year the Location was established

            • hours object
              • normal array[object]

                Normal opening hours

                • day integer

                  Day of week where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday

                • open boolean

                  Is the Location open or closed on this date?

                • open_time string

                  If the Location is open, when does it open? Format: HH:MM

                • close_time string

                  If the Location is open, when does it close? Format: HH:MM

              • message string

                Message to display next to normal opening hours

              • special array[object]

                Special opening hours which override the normal hours on given dates

                • date string

                  Date on which the special hours are effective. Format YYYY-MM-DD

                • open boolean

                  Is the Location open or closed on this date?

                • open_time string

                  If the Location is open, when does it open? Format: HH:MM

                • close_time string

                  If the Location is open, when does it close? Format: HH:MM

              • special_message string

                Message to display next to special opening hours

            • links object
            • name string

              The Location name

            • org_domain string

              The to.co Stable Domain Name for the Org ending .{country_code}.to.co

            • phones object
              • default string

                The default phone number

              • alt string

                The alternate phone number

              • local string

                The local phone number

              • fax string

                The facsimile (fax) phone number

              • mobile string

                The mobile phone number

              • free string

                The free phone number

              • tty string

                The TTY (Teletypewriter) phone number

            • public_domain string

              The public to.co Stable Domain Name or Public Location Domain ending in .loc.to.co which shows the to.co Page for the Location

            • updated string

              The time the Location was last updated in Coordinated Universal Time (UTC)

            • version_number integer

              Version number of the Location record

        • logo_url string

          The URL of the logo for the Org

        • name string

          The official or legal name of the Org

        • phones object
          • default string

            The default phone number

          • alt string

            The alternate phone number

          • local string

            The local phone number

          • fax string

            The facsimile (fax) phone number

          • mobile string

            The mobile phone number

          • free string

            The free phone number

          • tty string

            The TTY (Teletypewriter) phone number

        • public_domain string

          The public to.co Legal Name Domain or Go Business Domain ending in .to.co which shows the to.co Page for the Org

        • registration object
          • country_code string

            County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

          • date string

            The date the Org was registered

          • number string

            The official registration number issued by the Company Registrar

          • state_code string

            State Abbreviation Code (Upper Case) e.g AL for Alabama. 2 alpha-character

          • address object
            • domain string

              to.co Stable Address Domain Name ending in .a.to.co

            • line1 string

              First line of the address

            • line2 string

              Second line of the address

            • line3 string

              Third line of the address

            • city string

              City or Town name

            • sublocality string

              Sub-Locality. Typically defined as the region or area nearest the city or town

            • state string

              State or County

            • state_code string

              Code for the State or County

            • zip string

              ZIP or Postal Code

            • country_code string

              County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

            • version_number integer

              Version number of the Address record

        • updated string

          The time the Org was last updated in Coordinated Universal Time (UTC)

        • vat_registration object
          • number string

            VAT Registration Number issued to the Org e.g. GB111222233

        • version_number integer

          Version number of the Org record

    • request object Required
      • id string Required

        Unique request identifier

      • success boolean Required

        Did the request execute successfully?

      • period_start string Required

        The start date and time of the current subscription Data Credits plan

      • next_period_start string Required

        The start date and time of the next subscription Data Credits plan. Usually a calendar month after the period_start

      • requests_this_period integer

        The number of successfully executed API calls (requests) this period so far

        Default value is 0.

      • credit_available_this_period integer Required

        The total number of Data Credits available for use in this period. This is based upon the subscribed Data Credits Plan

      • credit_used_this_request integer Required

        The number of Data Credits used to process the current API request

      • credit_used_this_period integer Required

        The total number of Data Credits already used from period_start

      • credit_remaining_this_period string Required

        The total number of Data Credits still available this period

      • account_id string

        The internal to.co Account ID related to the Data Credits Plan

      • subscription_id string

        The internal to.co Subscription ID related to the Data Credits Plan

  • • 403 object

    Forbidden

  • • 404 object

    Not Found

GET /v1/org/search 
curl \
 -X GET https://api.to.co/v1/org/search?q=john+lewis&api_key=api_token_value
Response example (200) 
{
  "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"
  }
}
Response example (403) 
{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}
Response example (404) 
{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}

Locations

GetLocation

GET /v1/location/{domain}

Returns a single location

Path parameters

  • domain string Required

    Domain name of the location ending .to.co

Responses

  • • 200 object

    Success

    • location object Required
      • address object
        • domain string

          to.co Stable Address Domain Name ending in .a.to.co

        • line1 string

          First line of the address

        • line2 string

          Second line of the address

        • line3 string

          Third line of the address

        • city string

          City or Town name

        • sublocality string

          Sub-Locality. Typically defined as the region or area nearest the city or town

        • state string

          State or County

        • state_code string

          Code for the State or County

        • zip string

          ZIP or Postal Code

        • country_code string

          County Code (Upper Case) e.g US. 2 alpha-character ISO 3166

        • version_number integer

          Version number of the Address record

      • address_verified boolean

        Has the postal address been verified by the Location owner?

      • code string

        Optional code set by the owner to represent this Location

      • closed_date string

        The date the Location closed

      • default boolean

        Is this the default Location for the related Org?

      • description string

        The description of the Location

      • domain string

        The to.co Stable Domain Name for the Location ending .loc.to.co

      • emails object
      • established_year integer

        The year the Location was established

      • hours object
        • normal array[object]

          Normal opening hours

          • day integer

            Day of week where 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday

          • open boolean

            Is the Location open or closed on this date?

          • open_time string

            If the Location is open, when does it open? Format: HH:MM

          • close_time string

            If the Location is open, when does it close? Format: HH:MM

        • message string

          Message to display next to normal opening hours

        • special array[object]

          Special opening hours which override the normal hours on given dates

          • date string

            Date on which the special hours are effective. Format YYYY-MM-DD

          • open boolean

            Is the Location open or closed on this date?

          • open_time string

            If the Location is open, when does it open? Format: HH:MM

          • close_time string

            If the Location is open, when does it close? Format: HH:MM

        • special_message string

          Message to display next to special opening hours

      • links object
      • name string

        The Location name

      • org_domain string

        The to.co Stable Domain Name for the Org ending .{country_code}.to.co

      • phones object
        • default string

          The default phone number

        • alt string

          The alternate phone number

        • local string

          The local phone number

        • fax string

          The facsimile (fax) phone number

        • mobile string

          The mobile phone number

        • free string

          The free phone number

        • tty string

          The TTY (Teletypewriter) phone number

      • public_domain string

        The public to.co Stable Domain Name or Public Location Domain ending in .loc.to.co which shows the to.co Page for the Location

      • updated string

        The time the Location was last updated in Coordinated Universal Time (UTC)

      • version_number integer

        Version number of the Location record

    • request object Required
      • id string Required

        Unique request identifier

      • success boolean Required

        Did the request execute successfully?

      • period_start string Required

        The start date and time of the current subscription Data Credits plan

      • next_period_start string Required

        The start date and time of the next subscription Data Credits plan. Usually a calendar month after the period_start

      • requests_this_period integer

        The number of successfully executed API calls (requests) this period so far

        Default value is 0.

      • credit_available_this_period integer Required

        The total number of Data Credits available for use in this period. This is based upon the subscribed Data Credits Plan

      • credit_used_this_request integer Required

        The number of Data Credits used to process the current API request

      • credit_used_this_period integer Required

        The total number of Data Credits already used from period_start

      • credit_remaining_this_period string Required

        The total number of Data Credits still available this period

      • account_id string

        The internal to.co Account ID related to the Data Credits Plan

      • subscription_id string

        The internal to.co Subscription ID related to the Data Credits Plan

  • • 403 object

    Forbidden

  • • 404 object

    Not Found

GET /v1/location/{domain} 
curl \
 -X GET https://api.to.co/v1/location/xyz1234.loc.us.to.co?api_key=api_token_value
Response example (200) 
{
  "location": {
    "address_verified": true,
    "name": "John Lewis & Partners",
    "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"
    }
  },
  "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"
  }
}
Response example (403) 
{
  "code": 403,
  "message": "Forbidden: Invalid api_key parameter value"
}
Response example (404) 
{
  "code": 404,
  "message": "Not Found: No Org exists for this domain"
}