Api key (http_api_key)
Send an authentication token in the
api_key
query parameter
to authenticate with the API.
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.coAuthentication
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
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"
}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.
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"
}Path parameters
-
domain string Required
Domain name of the Org ending .to.co
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
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"
}Path parameters
-
domain string Required
Domain name of the location ending .to.co
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"
}