API - Overview

API v1

The TidyClub API allows you to include the power of TidyClub directly into your app. The API provides methods to read and write from TidyClub securely, so your users can bring all their important information with them to your app. Any changes they make will be updated in realtime to all of their computers, tablets and mobile phones. You'll also have access to powerful features such as contacts, events, memberships, finances, tasks and more.

Why TidyClub?

The API is the easiest and most robust way to keep all aspects of your club up to date across all devices and all of your committee. By using our API, not only will you make your app more powerful and easy to use, but you'll be broadening your audience to the people who are already using TidyClub. We're constantly improving the API and will be looking to add native development kits for the most popular mobile and web platforms to make integrating simple.

What next?

For questions about how TidyClub would work with your app, feel free to contact us.

Public and Private Data

In order to read or write private data using the TidyClub API, you will need to supply additional user-authentication tokens. This extra information lets TidyClub know who should be authorized to access private data during the request.

Whenever you provide additional user access tokens, both public and private data will be available.

For an API Method calls which is designed exclusively for private data access. and doesn't have an associated user access token the request will be rejected when trying to match user credentials.

Registration

Start by creation your application to obtain its TidyClub API credentials. That can be done by going to Settings -> Applications. Your application will be assigned a Client ID and a Client Secret. Be sure to use an account with a secure password to own these credentials. The Client Secret should not be shared.

Schema

All TidyClub API requests start with https://{domain_prefix}.tidyclub.com/api/v1/. All data is sent and received as JSON.

GET request. Access token sent as a parameter
$ curl -i https://default.tidyclub.com/api/v1/contacts?access_token=1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 5
Connection: keep-alive
Server: Apache/2.2.14

[
  {
    "id": 1,
    "first_name": "First",
    "last_name": "Last",
    ...
    "created_at": "2012-12-16T21:01:22Z"
  }
]
POST request. Access token sent in a header
$ cat contact.json

{
  "first_name": "First",
  "last_name": "Last"
}
$ curl -i -X POST -H "Authorization: Bearer 1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa" -H "Content-Type: application/json" -d @contact.json https://default.tidyclub.com/api/v1/contacts

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 5
Connection: keep-alive
Server: Apache/2.2.14

{
  "id": 1,
  "first_name": "First",
  "last_name": "Last",
  ...
  "created_at": "2012-12-16T21:01:22Z"
}

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ
Authentication

Applications connect with TidyClub via OAuth 2.0. Read more

access token sent in a header
$ curl -H "Authorization: Bearer TOKEN" https://default.tidyclub.com/api/v1/contacts
access token sent as a parameter
$ curl https://default.tidyclub.com/api/v1/contacts?access_token=TOKEN
Response Codes

200 OK Success

201 Created Success

400 Bad Request Unable to parse parameters

401 Unauthorized Access token was missing or incorrect.

403 Forbidden Accessing restricted area without appropriate user privileges

404 Not Found The URI requested is invalid or the resource requested, such as a contact, does not exists.

406 Not Acceptable Returned when an invalid format is specified in the request.

422 Unprocessable Entity Sending invalid fields will result in an unprocessable entity response.

500 Internal Server Error Something is broken. Please contact us so the TidyClub team can investigate.