Our new REST API opens to.co to the world
A RESTful API is an interface that enables the exchange of data between computers via HTTP requests. The API specifies a web URL structure which can be used to locate specific resources, also known as the request endpoint.
Using HTTP methods, the server knows what it needs to do with a specific resource.
- GET: Requests a resource identified by a specific URL
- POST: Creates a resource, the request body contains all the information required
- PUT: Updates an existing resource, the request body contains the updated data
- DELETE: Deletes an existing resource, identified by the URL
to.co REST API
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. To get started using the to.co REST API, check out the Developers page.
API Keys and Data Credits
Using the to.co REST API requires an API Key, your unique authentication token used to get access to the to.co REST API. You get your own API Key FREE when you register at https://auth.to.co/register so you can start using the REST API with no credit card required.
An API Key should be included as a URL parameter for every REST API request ?api_key={YOUR_API_KEY}
The API usage is limited by the use of Data Credits, additional data credits can be purchased by upgrading to a Data Credits plan.
Using the to.co REST API will cost you 1 Data Credit per request. Each request will feedback a summary of your Data Credits usage and remaining within a sub-object "request" like so:
{
"request":{
"id":"1d2f4583-d435-d153-d253-25f03650215d",
"success":true,
"period_start":"2022-05-02T23:00:00.000Z",
"next_period_start":"2022-06-02T22:59:59.000Z",
"requests_this_period":3,
"credit_available_this_period":10,
"credit_used_this_request":3,
"credit_used_this_period":3,
"credit_remaining_this_period":7,
"alias":"Default",
"user_id":"5s653h52j.user.to.co",
"account_id":"2f52633f.acct.to.co",
"subscription_id":"2f533ax1h2y3fkl2"
},
"orgs": {
"total":5,
"results":[
...
]
}
}
Request Endpoints
| Request | URL | Method | Description |
|---|---|---|---|
| Search Orgs | https://api.to.co/v1/org/search?q={name} | GET | Returns a list of organizations searched by the search query parameter (q) |
| Get Org | https://api.to.co/v1/org/{domain} | GET | Get the details of a to.co organization |
| Get Org Locations | https://api.to.co/v1/org/{domain}/locations | GET | Get a list of locations that are associated with a to.co organization |
| Get Location | https://api.to.co/v1/location/{domain} | GET | Returns the details about a specific to.co location |
| Add Contact | https://api.to.co/v1/contact | POST | Create a new contact by passing across the details of someone you do business with. |
For example, if we request this URL (using our API Key), we can request the details about the bpplc.to.co organization.
HTTP
https://api.to.co/v1/org/bpplc.to.co?api_key={YOUR_API_KEY}
Curl
$ curl --get https://api.to.co/v1/org/bpplc.to.co -d api_key={YOUR_API_KEY}
We get this response:
{
"request": {
"id": "1d2f4583-d435-d153-d253-25f03650215d",
"success": true,
"period_start": "2022-05-02T23:00:00.000Z",
"next_period_start": "2022-06-02T22:59:59.000Z",
"requests_this_period": 3,
"credit_available_this_period": 10,
"credit_used_this_request": 3,
"credit_used_this_period": 3,
"credit_remaining_this_period": 7,
"alias": "Default",
"user_id": "5s653h52j.user.to.co",
"account_id": "2f52633f.acct.to.co",
"subscription_id": "2f533ax1h2y3fkl2"
},
"org": {
"description": "We want to be an energy company with purpose; one that is trusted by society, valued by shareholders and motivating for everyone who works at bp.",
"domain": "mzgxkym9.uk.to.co",
"emails": {
"default": "info@bp.com"
},
"informal_name": "BP",
"links": {
"twitter_url": "https://twitter.com/toco",
"website_url": "https://bp.com",
"youtube_url": "https://youtube.com/toco"
},
"locations": {
"count": 1,
"default": {
"address_verified": false,
"name": "bp",
"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:30"
},
{
"day": 4,
"open": true,
"open_time": "09:00",
"close_time": "17:35"
},
{
"day": 5,
"open": true,
"open_time": "09:00",
"close_time": "17:30"
},
{
"day": 6,
"open": false,
"open_time": "00:00",
"close_time": "00:00"
}
]
},
"domain": "kr8tngmx.loc.uk.to.co",
"address": {
"domain": "2ys6hze8.a.uk.to.co",
"line1": "1 St James's Square",
"city": "London",
"zip": "SW1Y 4PD",
"country_code": "GB"
},
"links": {
"website_url": "https://www.bp.com/"
}
}
},
"logo_url": "https://media.to.co/mzgxkym9.uk.to.co/20220117T17251-gr6x54vqkFftZlUtIHT3.jpg",
"name": "Bp p.l.c.",
"public_domain": "bpplc.to.co",
"registration": {
"date": "1909-04-14",
"country_code": "GB",
"number": "00102498",
"address": {
"domain": "s6dpgtph.a.uk.to.co",
"line1": "1 St James's Square",
"city": "London",
"zip": "SW1Y 4PD",
"country_code": "GB"
}
},
"updated": "2022-05-06T05:33:29.000Z",
"version_number": 1
}
}
Automation with Webhooks
In addition to the to.co REST API, you can use Webhooks to get the notified about data changes in organizations you watch. Check out this article about Webhooks or our Webhooks docs
Get started with the REST API
If you are interest in getting started using our REST API, you can check out our support for the REST API.
If you need any help do get in touch.
Luke Geaves