We recommend having a look at it first to see if it suits your needs before falling back to API v1.
Click here to read the docs.
Overview
API v1
This is a legacy version of our API. Have a look at API v2 first before continuing to read this.
The TidyHQ API allows you to include the power of TidyHQ directly into your app. The API provides methods to read and write from TidyHQ 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 TidyHQ?
The API is the easiest and most robust way to keep all aspects of your organisation 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 TidyHQ. 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 TidyHQ would work with your app, feel free to contact us.
Public and Private Data
In order to read or write private data using the TidyHQ API, you will need to supply additional user-authentication tokens. This extra information lets TidyHQ 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.
Start by creation your application to obtain its TidyHQ API credentials. That can be done by going to 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.
All TidyHQ API requests start with https://api.tidyhq.com/v1/
. All data is sent and received as JSON.
GET request. Access token sent as a parameter
$ curl -i https://api.tidyhq.com/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://api.tidyhq.com/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
Applications connect with TidyHQ via OAuth 2.0.
access token sent in a header
$ curl -H "Authorization: Bearer TOKEN" https://api.tidyhq.com/v1/contacts
access token sent as a parameter
$ curl https://api.tidyhq.com/v1/contacts?access_token=TOKEN
Requests that return collections of resources can be paginated. Set the
limit
or
per_page
parameter. Use the
offset
or
page
parameter to browse through the pages.
Pagination information will be returned in the response header.
X-Pagination-Per-Page: 25 X-Pagination-Current-Page: 2 X-Pagination-Total-Pages: 10 X-Pagination-Total-Entries: 247
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 TidyHQ team can investigate.
Authentication
Applications connect with TidyHQ via OAuth 2.0. This is the way used by most major API providers. All OAuth2 requests must use the SSL and require authentication. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely.
Authorization code is probably the most used flow. It basically consists in a exchange of a authorization token for an access token.
1. Redirect users to request TidyHQ access
GET https://accounts.tidyhq.com/oauth/authorize
Parameters
- client_id
- Required - The client ID you received from TidyHQ when you registered.
- redirect_uri
- Required - URL in your application where users will be sent after authorization.
- response_type
-
Required
-
code
https://accounts.tidyhq.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code
2. TidyHQ redirects back to your site
If the user accepts the request, TidyHQ redirects back to REDIRECT_URI as a GET with a temporary code in a code
parameter.
http://REDIRECT_URI?code=RETURNED_CODE
To request the access token, you should use the returned code and exchange it for a access token by doing POST request to the /oauth/token
endpoint.
POST https://accounts.tidyhq.com/oauth/token
Parameters
- client_id
- Required - The client ID you received from TidyHQ when you registered.
- client_secret
- Required - The client secret you received from TidyHQ when you registered.
- redirect_uri
- Required - Application Redirect URL
- code
- Required - The code you received as a response to previous step.
- grant_type
-
Required
-
authorization_code
$ curl -i -X POST -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI" https://accounts.tidyhq.com/oauth/token HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-store Pragma: no-cache Content-Length: 296 Connection: keep-alive Server: Apache/2.2.14 { "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54", "token_type": "bearer", "expires_in": null, "refresh_token": null }
3. Use the access token to access the API
GET https://api.tidyhq.com/v1/{resources}?access_token=TOKEN
1. Redirect users to request TidyHQ access
GET https://accounts.tidyhq.com/oauth/authorize
Parameters
- client_id
- Required - The client ID you received from TidyHQ when you registered.
- redirect_uri
- Required - URL in your application where users will be sent after authorization.
- response_type
-
Required
-
token
https://accounts.tidyhq.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=token
2. TidyHQ redirects back to your site
If the user accepts the request, TidyHQ redirects back to REDIRECT_URI as a GET. Then access_token will be added to the hash fragment portion of the return URL.
http://{REDIRECT_URI}#access_token=6c91d4ca80b2ffff904fd4ccf1b0c32ee38fb04e96fee4b6ce41d45ee17fdf38&token_type=bearer
3. Use the access token to access the API
GET https://api.tidyhq.com/v1/{resources}?access_token=TOKEN
In this flow, a token is requested in exchange for the resource owner credentials (username and password).
POST https://accounts.tidyhq.com/oauth/token
Parameters
- domain_prefix
- Required - Organisation domain prefix.
- client_id
- Required - The client ID you received from TidyHQ when you registered.
- client_secret
- Required - The client secret you received from TidyHQ when you registered.
- username
- Required - TidyHQ user's email
- password
- Required - TidyHQ user's password
- grant_type
-
Required
-
password
$ curl -i -X POST -d "domain_prefix=default&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&username=USERNAME&password=PASSWORD&grant_type=password" https://accounts.tidyhq.com/oauth/token HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Cache-Control: no-store Pragma: no-cache Content-Length: 296 Connection: keep-alive Server: Apache/2.2.14 { "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54", "token_type": "bearer", "expires_in": null, "refresh_token": null }
access token sent in a header
$ curl -H "Authorization: Bearer TOKEN" https://api.tidyhq.com/v1/contacts
access token sent as a parameter
$ curl https://api.tidyhq.com/v1/contacts?access_token=TOKEN
Organization
Authentication token is required.
GET /organization
Response
Status: 200 OK
{ "name": "Default Club", "domain_prefix": "default", "location": null, "address": "Street 1", "city": "Perth", "state": "Western Australia", "postcode": "4242", "country": "Australia", "phone": "0123456789", "website": "http://website.com", "twitter": "default_club", "facebook": "default_club", "currency": "AUD", "time_zone": "Australia/Perth", "public_contacts": [], "logo_url": "https://assets.tidyhq.com/assets/clubs/logos/medjpg/club_logo_2.png", "plan": { "name":"Basic", "quota":{ "emails":{ "limit":10000, "count":20 }, "contacts":{ "limit":100, "count":10 } } }, "parent_organizations": [ { "id": "932df4a6633f", "name": "CycleSport" } ], "child_organizations": [ { "id": "49d7b957fccd", "name": "Really Good Football Club" } ] }
Association
Authentication token is required.
GET /association/organizations
Response
Status: 200 OK
[{ "id": "3abe3d9499cb", "name": "Child Organisation", "domain_prefix": "child", "location": null, "address": "Street 1", "city": "Perth", "state": "Western Australia", "postcode": "4242", "country": "Australia", "phone": "0123456789", "website": "http://website.com", "twitter": "child_club", "facebook": "child_club", "currency": "AUD", "time_zone": "Australia/Perth", "public_contacts": [], "logo_url": "https://assets.tidyhq.com/assets/clubs/logos/medjpg/club_logo_2.png", "plan": { "name":"Basic", "quota":{ "emails":{ "limit":10000, "count":20 }, "contacts":{ "limit":100, "count":10 } } } }]
GET /association/organizations/:id
GET /association/organizations/:organization_id/contacts
GET /association/organizations/:organization_id/events
GET /association/organizations/:organization_id/events/:id
GET /association/organizations/:organization_id/meetings
GET /association/organizations/:organization_id/meetings/:id
Contacts
TidyHQ contains a simple contract relationship management (CRM) system, it allows for simple managing a clubs interactions with current and future members, supporters, sponsors and other stakeholders. This method returns a list of contacts.
Authentication token is required.
GET /contacts
GET /groups/:group_id/contacts
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- search_terms
- Optional string
- show_all
-
Optional
boolean
true
false
- include deleted contacts - updated_since
-
Optional
datetime
Example: 2021-06-01 00:00:00 - `ids[]`
-
Optional
list of alphanumeric or numeric contact ids.
Example: `ids[]=123&ids[]=2` - filter
-
Optional
array
filter[]custom_field_id=5f1c674336f2 filter[]custom_field_value=1 ## In an encoded URL: https://api.tidyhq.com/v1/contacts?per_page=10&access_token=
&filter%5B%5Dcustom_field_id=5f1c674336f2&filter%5B%5Dcustom_field_value=1
Response
Status: 200 OK
[{ "id": 1, "first_name": "First", "last_name": "Last", ... "status":"active", "member_since": "2019-01-07", "contact_id": 1, "contact_id_number": "BB123456", "created_at": "2012-12-16T21:01:22Z", "custom_fields": [ { "id":"5b8ff85455e9", "title":"Custom checkbox field", "type":"boolean", "value":true }, { "id":"280ada4c1dea", "title":"Custom dropdown field", "type":"dropdown", "value": { "id":"2fbd15a7ff31","title":"Option 3" } }, { "id":"91288961b8d7", "title":"Custom date field", "type":"date", "value":"2012-01-01" } ], "contact_links": [ { "contact_id": 12345, "relationship_type": "Adult" }, { "contact_id": 23456, "relationship_type": "Child" }, ] }]
GET /contacts/me
GET /contacts/:id
Response
Status: 200 OK
{ "id": 1, "first_name": "First", "last_name": "Last", ... "status":"inactive", "member_since": "2019-01-07", "contact_id_number": "BB123456", "created_at": "2012-12-16T21:01:22Z" }
POST /contacts
Parameters
- first_name
- Required string
- last_name
- Optional string
- email_address
- Optional string
- phone_number
- Optional string
- address1
- Optional string
- city
- Optional string
- state
- Optional string
- country
- Optional string
- postcode
- Optional string
- gender
-
Optional
string
- Either
female
ormale
ornon_binary
orundisclosed
- birthday
- Optional date
- Optional string - Facebook account name
- Optional string - X account name
- details
- Optional text - A brief description of contact
- custom_fields
-
Optional
object
– A struct of
custom field
IDs as keys and values.
{ custom_field_id: value, custom_dropdown_field_id: custom_dropdown_field_choice_id }
{ "5b8ff85455e9": true, "91288961b8d7": "2012-01-01", "280ada4c1dea": "2fbd15a7ff31" // Dropdown field id as a key, dropdown field choice id as a value. Use blank value to empty the field }
Response
Status: 201 Created
{ "id": 1, "first_name": "First", "last_name": "Last", ... "status":"active", "created_at": "2012-12-16T21:01:22Z" }
PUT /contacts/:id
Parameters
See Create a contact section. All parameters are optional.
Response
Status: 200 OK
{ "id": 2, "first_name": "First", "last_name": "Last", ... "status":"active", "created_at": "2012-12-16T21:01:22Z" }
DELETE /contacts/:id
Response
Status: 200 OK
{ "message": "Successful" }
Custom Fields
Authentication token is required.
GET /custom_fields
Response
Status: 200 OK
[ { "id":"76fc0695956c", "title":"Custom single-line text field", "type":"string", "created_at":"2015-03-26T16:12:00+08:00" }, { "id":"331e2e7ef369", "title":"Custom text type field", "type":"text", "created_at":"2015-03-26T16:12:00+08:00" }, { "id":"5b8ff85455e9", "title":"Custom checkbox field", "type":"boolean", "created_at":"2015-03-26T16:12:00+08:00" }, { "id":"280ada4c1dea", "title":"Custom dropdown field", "type":"dropdown", "created_at":"2015-03-26T16:12:00+08:00", "choices": [ { "id":"2ec44e02f756", "title":"Option 1", "created_at":"2015-03-26T16:12:00+08:00" }, { "id":"5259f806909c", "title":"Option 2", "created_at":"2015-03-26T16:33:21+08:00" } ] }, { "id":"91288961b8d7", "title":"Custom date field", "type":"date", "created_at":"2015-03-26T16:12:00+08:00" } ]
GET /custom_fields/:id
Response
Status: 200 OK
{ "id":"5b8ff85455e9", "title":"Custom checkbox field", "type":"boolean", "created_at":"2015-03-26T16:12:00+08:00" }
POST /custom_fields
Parameters
- title
- Required string
- type
-
Required
string
string
text
dropdown
boolean
date
Response
Status: 201 Created
{ "id":"91288961b8d7", "title":"Custom date field", "type":"date", "created_at":"2015-03-26T16:12:00+08:00" }
PUT /custom_fields/:id
Parameters
See Create a custom field section. All parameters are optional.
Response
Status: 200 OK
{ "id":"76fc0695956c", "title":"Custom single-line text field", "type":"string", "created_at":"2015-03-26T16:12:00+08:00" }
DELETE /custom_fields/:id
Response
Status: 200 OK
{ "message": "Successful" }
Custom Dropdown Field Choices
GET /custom_fields/:custom_field_id/choices
Response
Status: 200 OK
[ { "id":"2ec44e02f756", "title":"Option 1", "created_at":"2015-03-26T16:12:00+08:00" }, { "id":"5259f806909c", "title":"Option 2", "created_at":"2015-03-26T16:33:21+08:00" } ]
GET /custom_fields/:custom_field_id/choice/:id
Response
Status: 200 OK
{ "id":"2ec44e02f756", "title":"Option 1", "created_at":"2015-03-26T16:12:00+08:00" }
POST /custom_fields/:custom_field_id/choices
Parameters
- title
- Required string
Response
Status: 201 Created
{ "id":"2ec44e02f756", "title":"Option 1", "created_at":"2015-03-26T16:12:00+08:00" }
PUT /custom_fields/:custom_field_id/choices/:id
Parameters
See Create a custom dropdown field choice section. All parameters are optional.
Response
Status: 200 OK
{ "id":"2ec44e02f756", "title":"Option 1", "created_at":"2015-03-26T16:12:00+08:00" }
DELETE /custom_fields/:custom_field_id/choices/:id
Response
Status: 200 OK
{ "message": "Successful" }
Groups
TidyHQ allows for grouping of contacts. This is to makes communication, invoicing, and sending invitations to a custom collection of contacts easy. This method returns Group ID information.
Authentication token is required.
GET /groups
GET /contacts/:contact_id/groups
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- search_terms
- Optional string
Response
Status: 200 OK
[ { "id": 1, "label": "Group", "description": "Some text", ... "created_at": "2012-12-16T21:01:22Z" } ]
GET /groups/:id
Response
Status: 200 OK
{ "id": 1, "label": "Group", "description": "Some text", ... "created_at": "2012-12-16T21:01:22Z" }
POST /groups
Parameters
- label
- Required string
- description
- Optional string
Response
Status: 201 Created
{ "id": 1, "label": "Group", "description": "Some text", ... "created_at": "2012-12-16T21:01:22Z" }
PUT /groups/:id
Parameters
See Create a group section. All parameters are optional.
Response
Status: 200 OK
{ "id": 1, "label": "Group", "description": "Some text", ... "created_at": "2012-12-16T21:01:22Z" }
DELETE /groups/:id
Response
Status: 200 OK
{ "message": "Successful" }
PUT /groups/:group_id/contacts/:contact_id
Response
Status: 204 No Content
DELETE /groups/:group_id/contacts/:contact_id
Response
Status: 204 No Content
Membership Levels
Authentication token is required.
GET /membership_levels
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": 1, "name": "Individual (rolling 3 months)", "description": "", "duration": 3, "unit_period": "month", "fixed": false, "start_at": null, "enabled": false, "active_since": null, "amount": "2.0", "bundle": false, "deleted": false, "plan_type": "rolling", "auto_renew": true, "created_at": "2015-07-15T18:11:00+08:00" } ]
GET /membership_levels/:id
Response
Status: 200 OK
{ "id": 2, "name": "Family (rolling 1 year)", "description": "", "duration": 1, "unit_period": "year", "fixed": false, "start_at": null, "enabled": true, "active_since": "2015-07-14", "amount": "0.0", "bundle": true, "bundle_amounts": [{ "amount": "0.0", "subsequent": false, "type": "adult" }, { "amount": "5.0", "subsequent": false, "type": "adult" }, { "amount": "20.0", "subsequent": false, "type": "child" }, { "amount": "10.0", "subsequent": true, "type": "child" }], "deleted": false, "plan_type": "rolling", "auto_renew": true, "created_at": "2015-07-15T18:53:01+08:00" }
Memberships
Authentication token is required.
GET /memberships
GET /contacts/:contact_id/memberships
GET /membership_levels/:membership_level_id/memberships
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- active
-
Optional
boolean
true
false
- updated_since
-
Optional
datetime
Example: 2021-06-01 00:00:00
Response
Status: 200 OK
[ { "id": 1, "start_date": "2012-12-16T21:01:22Z", "end_date": "2013-12-16T21:01:22Z", "contact_id": 1, "membership_level_id": 1, "state": "activated", "membership_id_reference": 2197, "membership_id": "c7324cf9bd5c" "membership_level": { "id": 197, "name": "Coaches", "plan_type": "rolling", "auto_renew": true }, "subscriptions": [ { "id": 3329, "start_date": "2018-12-21", "end_date": "2019-01-20", "status": "Expired", "variations": [ { "question": "State", "answer": "CycleSport", "price": "1.8", "destination": { "id": "932df4a6633f", "type": "Organisation", "name": "CycleSport" }, "autofill_group": { "id": 1481, "name": "CycleSport" } }, { "question": "Club", "answer": "Albany CC", "price": "0.69", "destination": { "id": "3ffaa3ca3577", "type": "Organisation", "name": "Awesome Sport" }, "autofill_group": { "id": 1493, "name": "Awesome Sport" } } ] } ], "created_at": "2012-12-16T21:01:22Z" } ]
GET /memberships/:id
Response
Status: 200 OK
{ "id": 1, "start_date": "2012-12-16T21:01:22Z", "end_date": "2013-12-16T21:01:22Z", "contact_id": 1, "membership_level_id": 1, "state": "expired", "created_at": "2012-12-16T21:01:22Z" }
Emails
You can create and send emails from TidyHQ. This allows the organisation to keep a record of the communication that has been sent and by who. This method allows the drafting of a new email and displaying of a sent email.
Authentication token is required.
GET /emails
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- created_since
- Optional datetime
- way
-
Optional
string
inbound
outbound
- type
-
Optional
string
email
group_email
- read
-
Optional
boolean
true
false
- archived
-
Optional
boolean
true
false
- deleted
-
Optional
boolean
true
false
- junk
-
Optional
boolean
true
false
Response
Status: 200 OK
[ { "id": "76fc0695956c", "sender_id": 23, "recipient_ids": [42, 74], "way": "inbound", "type": "email", "subject": "Subject", "body": "Body text", "scheduled_at": null, "read": false, "archived": false, "deleted": false, "junk": false, "attachments": [], "created_at": "2012-12-16T21:01:22Z" } ]
GET /emails/:id
Response
Status: 200 OK
{ "id": "76fc0695956c", "sender_id": 23, "recipient_ids": [42, 74], "way": "outbound", "type": "group_email", "subject": "Subject", "body": "Body text", "scheduled_at": null, "read": false, "archived": false, "deleted": false, "junk": false, "attachments": [], "created_at": "2012-12-16T21:01:22Z" }
POST /emails
Parameters
- subject
- Required string
- body
- Required string
- contacts
-
Required
array
An array of contact ids
[1, 2, 3]
Response
Status: 201 Created
Meetings
TidyHQ keeps a track of all of your meetings, including who attended, who was an apology, what topics were discussed.
Authentication token is required.
GET /meetings
GET /association/organizations/:organization_id/meetings
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id":1, "name":"Meeting", "body":"Body text", "date":"2013-01-31T00:00:00Z", "location":"Perth", "topics":[ { "owner_id":7, "title":"Topic 1", "date":"2013-01-31", "category":"TODO", "task": { "id":1, "title":"Task", "description":null, "due_date":"2013-01-30T22:00:00Z", "created_at":"2013-01-04T02:16:17Z" } }, { "owner_id":7, "title":"Topic 2", "date":"2013-01-31", "category":"DECISION", "task":null } ], "attendees":[7], "apologies":[7], "minute_takers":[7] "public":false, "created_at":"2013-01-03T13:53:57Z", } ]
GET /meetings/:id
GET /association/organizations/:organization_id/meetings/:id
Events
Running an event gets even better with TidyHQ as we sync all event information across our CRM, communication archive and also keep a track of payments from your attendees. Through the TidyHQ API you can view, create, update or delete an event so you can sync it in even more places.
These methods returns the identified event resource along with location, start time and end time objects.
Authentication token is required.
GET /events
GET /association/organizations/:organization_id/events
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- start_at
- Optional timestamp in ISO 8601 format
- end_at
- Optional timestamp in ISO 8601 format
- public
-
Optional
boolean
true
false
Response
Status: 200 OK
[ { "id": 1, "name": "Event", "location": "Perth", ... "created_at": "2012-12-16T21:01:22Z" } ]
GET /events/:id
GET /association/organizations/:organization_id/events/:id
Response
Status: 200 OK
{ "id": 1, "name": "Event", "location": "Perth", ... "created_at": "2012-12-16T21:01:22Z" }
POST /events
Parameters
- name
- Required string
- location
- Optional string
- start_at
- Required datetime
- end_at
- Optional datetime
- body
- Optional text - A brief description of event
- archived
- Optional boolean - Archiving your event means that it will no longer show on the public facing events page
- hidden
- Optional boolean - Hidden events aren't shown on the public facing events page and Admin Dashboard. You are still able to by tickets from hidden event using the API. When buying a ticket from hidden event email with certificates and receipts will not be sent.
- category_id
-
Optional
integer
- The default is
tickets
category.
Response
Status: 201 Created
{ "id": 1, "name": "Event", "location": "Perth", ... "created_at": "2012-12-16T21:01:22Z" }
PUT /events/:id
Parameters
See Create an event section. All parameters are optional.
Response
Status: 200 OK
{ "id": 1, "name": "Event", "location": "Perth", ... "created_at": "2012-12-16T21:01:22Z" }
DELETE /events/:id
Response
Status: 200 OK
{ "message": "Successful" }
Sessions
TidyHQ has a powerful Session function that makes sure everyone in the organization happy. TidyHQ allows viewing, posting, updating and deleting of a Session.
Returns Title, Description, Location, Start Date, End Date.
Authentication token is required.
GET /sessions.json
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": "SVXD128723BS", "title": "Session title", "description": "Session description", "location": "Session location", "date_start": "2016-04-28T14:00:00+0800", "date_end": "2016-04-28T15:00:00+0800", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-05-04T16:08:46+0800", "remind": true, "remind_lead": 1, "recurrence": { "kind": "daily", "every": 2, "end_date": "2016-09-01", "week_day_numbers": [], "day_of_month": null, "month": null } "members": [ { "id": 34, "member_id": 13, "date_on": null, "kind": "unknown", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-04-27T16:25:45+0800" }, { "id": 37, "member_id": 105, "date_on": "2016-04-30", "kind": "attendee", "created_at": "2016-04-27T16:52:56+0800", "updated_at": "2016-04-27T16:52:56+0800" }, { "id": 38, "member_id": 105, "date_on": "2016-05-02", "kind": "maybe", "created_at": "2016-04-27T17:43:18+0800", "updated_at": "2016-04-29T10:09:54+0800" } ... { "id": 41, "member_id": 105, "date_on": "2016-05-04", "kind": "apology", "created_at": "2016-04-29T10:25:10+0800", "updated_at": "2016-05-04T18:17:49+0800" } } ... ]
GET /sessions/:id.json
Response
Status: 200 OK
{ "id": "SVXD128723BS", "title": "Session title", "description": "Session description", "location": "Session location", "date_start": "2016-04-28T14:00:00+0800", "date_end": "2016-04-28T15:00:00+0800", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-05-04T16:08:46+0800", "remind": true, "remind_lead": 1, "recurrence": { "kind": "daily", "every": 2, "end_date": "2016-09-01", "week_day_numbers": [], "day_of_month": null, "month": null }, "members": [ { "id": 34, "member_id": 13, "date_on": null, "kind": "unknown", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-04-27T16:25:45+0800" }, { "id": 37, "member_id": 105, "date_on": "2016-04-30", "kind": "attendee", "created_at": "2016-04-27T16:52:56+0800", "updated_at": "2016-04-27T16:52:56+0800" }, { "id": 38, "member_id": 105, "date_on": "2016-05-02", "kind": "maybe", "created_at": "2016-04-27T17:43:18+0800", "updated_at": "2016-04-29T10:09:54+0800" } ... { "id": 41, "member_id": 105, "date_on": "2016-05-04", "kind": "apology", "created_at": "2016-04-29T10:25:10+0800", "updated_at": "2016-05-04T18:17:49+0800" } ] } }
POST /sessions.json
Parameters
- title
- Required string
- description
- Optional text
- location
- Optional string
- date_start
- Required datetime
- date_end
- Optional datetime
- remind
- Optional boolean Remind members or not
- remind_lead
- Optional integer 1..6 days before the Session
- members
- Optional string Member ids separated by commas ex. '4216, 1025, 2931'
- recurrence_kind
- Optional string Kind of Session recurrence, one of the list [daily, weekly, monthly, yearly]
- recurrence_every
- Optional string Loop for every day (week, month, year)
- recurrence_end_date
- Optional datetime DateTime when the Session ends in YYYY-MM-DD HH:MM format
- recurrence_day_of_month
- Optional datetime Loop for monthly and yearly repeat in [1..31] limits
- recurrence_month
- Optional integer Loop for yearly repeat in [1..12] limits
Response
Status: 201 Created
{ "id": "0v9EAyM", "title": "Session Title", "description": "Session Description", "location": "Bangkok", "date_start": "2016-05-06T09:00:00+0800", "date_end": "2016-05-06T10:00:00+0800", "created_at": "2016-05-05T22:39:25+0800", "updated_at": "2016-05-05T22:39:25+0800", "remind": null, "remind_lead": null, "recurrence": { "kind": "weekly", "every": 1, "end_date": null, "week_day_numbers": [ 0, 2, 4 ], "day_of_month": null, "month": null }, "members": [ { "id": 66, "member_id": 16, "date_on": null, "kind": "unknown", "created_at": "2016-05-05T22:39:25+0800", "updated_at": "2016-05-05T22:39:25+0800" }, { "id": 67, "member_id": 105, "date_on": null, "kind": "unknown", "created_at": "2016-05-05T22:39:25+0800", "updated_at": "2016-05-05T22:39:25+0800" } ] }
PUT /sessions/:id.json
Parameters
See Create a Session section.
Response
Status: 200 OK
{ "id": "SVXD128723BS", "title": "Session title", "description": "Session description", "location": "Session location", "date_start": "2016-04-28T14:00:00+0800", "date_end": "2016-04-28T15:00:00+0800", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-05-04T16:08:46+0800", "remind": true, "remind_lead": 1, "recurrence": { "kind": "daily", "every": 2, "end_date": "2016-09-01", "week_day_numbers": [], "day_of_month": null, "month": null }, "members": [ { "id": 34, "member_id": 13, "date_on": null, "kind": "unknown", "created_at": "2016-04-27T16:25:45+0800", "updated_at": "2016-04-27T16:25:45+0800" }, { "id": 37, "member_id": 105, "date_on": "2016-04-30", "kind": "attendee", "created_at": "2016-04-27T16:52:56+0800", "updated_at": "2016-04-27T16:52:56+0800" }, { "id": 38, "member_id": 105, "date_on": "2016-05-02", "kind": "maybe", "created_at": "2016-04-27T17:43:18+0800", "updated_at": "2016-04-29T10:09:54+0800" } ... { "id": 41, "member_id": 105, "date_on": "2016-05-04", "kind": "apology", "created_at": "2016-04-29T10:25:10+0800", "updated_at": "2016-05-04T18:17:49+0800" } ] } }
DELETE /sessions/:id.json
Response
Status: 200 OK
{ "message": "Successful" }
POST /sessions/:id/decisions.json
Parameters
- decision
- Required string One of the decisions (attendee, apology, maybe)
- date
- Optional datetime On what date user decides or whole Session if empty (format YYYY-MM-DD)
Response
Status: 200 OK
{ "message": "Successful" }
Tickets
Event Tickets are purchased by an organisation supporter who plans on attending an event. This method creates new ticket types for an event, returning the ID of the newly created ticket type. When a ticket is purchased a new attendee record is made.
Authentication token is not required.
GET /events/:event_id/tickets
Response
Status: 200 OK
[ { "id": "c17a437d2a71", "name": "For Members", "amount": "10.0", ... "created_at": "2012-12-16T21:01:22Z" } ]
GET /events/:event_id/tickets/sold
Response
Status: 200 OK
[ { "contact_id": 1, "ticket_id": "c17a437d2a71", "created_at": "2012-12-16T21:01:22Z", "code": "a07da838e43da438634e5c09" } ]
GET /events/:event_id/tickets
Response
Status: 200 OK
{ "id": "c17a437d2a71", "name": "For Members", "amount": "10.0", ... "created_at": "2012-12-16T21:01:22Z" }
POST /events/:event_id/tickets
Parameters
- name
- Required string
- amount
-
Optional
decimal
- The default is
0.0
, so leaving this out or setting it to zero would mean free ticket type. - initial_quantity
-
Optional
numerical
- The default is
null
which means unlimited tickets count. Must be greater than or equal to 1. - maximum_purchase
-
Optional
numerical
- The default is
5
. Must be greater than or equal to 1. - sales_end
- Optional datetime
Response
Status: 201 Created
{ "id": "c17a437d2a71", "name": "For Members", "amount": "10.0", ... "created_at": "2012-12-16T21:01:22Z" }
PUT /events/:event_id/tickets/:id
Parameters
See Create a ticket section. All parameters are optional.
Response
Status: 200 OK
{ "id": "c17a437d2a71", "name": "For Members", "amount": "10.0", ... "created_at": "2012-12-16T21:01:22Z" }
DELETE /events/:event_id/tickets/:id
Response
Status: 200 OK
{ "message": "Successful" }
Categories
Authentication token is required.
TidyHQ allows for categories for payments. For example when a payment is made for a bag of apples this payment can be placed in the Category 'Food'. This allows the User to better track total expenditure of certain types over the course of a year. This method returns the name of the Category and Current Balance of the entire Category.
GET /categories
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id":1, "name":"Administration", "description":"Category description text here", "balance":{"AUD":-20.0,"USD":42.0}, "created_at":"2013-01-03T13:53:57Z", } ]
Tasks
TidyHQ has a powerful Tasks function that makes sure everyone in the organisation is doing their bit, and those on the committee can keep track of what is outstanding. TidyHQ allows viewing, posting, updating and deleting of a Task.
Returns Title, Description, Due Date and which Contact the Task has been assigned to.
Authentication token is required.
GET /tasks
GET /contacts/:contact_id/tasks
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- completed
-
Optional
boolean
true
false
Response
Status: 200 OK
[ { "id": 1, "title": "Task title", "description": "Task description text", "contact_id": 1, "due_date": "2013-12-16" "created_at": "2012-12-16T21:01:22Z" } ]
GET /tasks/:id
Response
Status: 200 OK
{ "id": 1, "title": "Task title", "description": "Task description text", "contact_id": 1, "due_date": "2013-12-16" "created_at": "2012-12-16T21:01:22Z" }
POST /tasks
Parameters
- title
- Required string
- description
- Optional string
- due_date
- Required date
- contact_id
- Required integer id of contact the task will be assigned to
- Required integer
Response
Status: 201 Created
{ "id": 1, "title": "Task title", "description": "Task description text", "contact_id": 1, "due_date": "2013-12-16" "created_at": "2012-12-16T21:01:22Z" }
PUT /tasks/:id
Parameters
See Create a task section.
Response
Status: 200 OK
{ "id": 1, "title": "Task title", "description": "Task description text", "contact_id": 1, "due_date": "2013-12-16" "created_at": "2012-12-16T21:01:22Z" }
DELETE /tasks/:id
Response
Status: 200 OK
{ "message": "Successful" }
Invoices
TidyHQ allows a Authenticated User to send an Invoice to a Contact for future payment. Invoice details include Invoice Name, Invoice Pre Tax Amount, Invoice Included Tax Total, Date of the invoice, Due Date of the Invoice, and which Contact the Invoice is being sent to.
Authentication token is required.
GET /invoices
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- status
- Optional string
-
activated
default -
cancelled
-
activated,cancelled
- updated_since
- Optional string
Response
Status: 200 OK
[ { "id": "4eeb3ac8ede1", "ref_no": "42", "contact_id": 227, "type": "invoice", "name": "Invoice Ref.No 42", "description": null, "due_date": "2014-08-01", "category_id":9, "amount": 409.14, "amount_paid": 0.0, "amount_due": 409.14, "paid": false, "metadata":null, "status":"cancelled", "payments": [] }, { "id": "91892af259e9", "ref_no": "43", "contact_id": 206, "type": "invoice", "name": "Invoice Ref.No 43", "description": null, "due_date": "2014-07-19", "category_id":9, "amount": 721.65, "amount_paid": 700.0, "amount_due": 21.65, "paid": false, "metadata":"819178d98ef2", "status":"activated", "payments": [ { "id":"5b1cc25e95d6", "amount":340.0, "type":"other", "paid_at":"2015-07-05T14:35:00Z", "status":"paid" }, { "id":"7a0d54702ce9", "amount":360.0, "type":"cash", "paid_at":"2015-07-06T14:35:00Z", "status":"paid" } { "id":"8d1m33913kl0", "amount":60.0, "type":"cash", "paid_at":"2015-07-06T14:35:00Z", "status":"cancelled" } ] }, { "id": "001c1ca97c04", "ref_no": "44", "contact_id": 207, "type": "invoice", "name": "Invoice Ref.No 44", "description": null, "due_date": "2014-08-19", "category_id":9, "amount": 359.17, "amount_paid": 359.17, "amount_due": 0.0, "paid": true, "metadata":"", "status":"activated", "payments": [ { "id":"5de94837d348", "amount":359.17, "type":"cheque", "paid_at":"2015-07-05T14:35:00Z" } ] } ]
GET /invoices/:id
Response
Status: 200 OK
{ "id": "001c1ca97c04", "ref_no": "44", "contact_id": 207, "type": "invoice", "name": "Invoice Ref.No 44", "description": null, "due_date": "2014-08-19", "category_id":9, "amount": 359.17, "amount_paid": 359.17, "amount_due": 0.0, "paid": true, "metadata":null, "status":"activated", "payments": [ { "id":"5de94837d348", "amount":359.17, "type":"cheque", "paid_at":"2015-07-05T14:35:00Z", "status":"paid" } ] }
POST /invoices
Parameters
- reference
- Required string
- description
- Optional string
- amount
- Required decimal
- included_tax_total
- Required decimal
- pre_tax_amount
- Required decimal
- due_date
- Required datetime
- category_id
- Required integer
- contact_id
- Required integer
- metadata
- Optional string
Response
Status: 201 Created
POST /invoices/:id/payments
Parameters
- amount
- Optional decimal
- payment_type
-
Optional
string
cash
card
cheque
bank
other
- date
- Optional datetime
Response
Status: 201 Created
DELETE /invoices/:id
Response
Status: 200 OK
{ "message": "Successful" }
Deposits
TidyHQ allows a Authenticated User to record a Deposit next to a Contact for payment. Deposit details include Deposit Name, Description, Deposit Amount, Date the Deposit was paid, Category, and which Contact the Deposit was made by.
Authentication token is required.
GET /deposits
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- status
- Optional string
-
activated
default -
cancelled
-
activated,cancelled
- updated_since
- Optional string
Response
Status: 200 OK
[ { "id":"0fe0bc5db4dd", "ref_no":"736", "contact_id":10789, "type":"deposit", "name":"Deposit of $10", "description": null, "category_id":9, "currency":"AUD", "amount": 10.0, "metadata":null, "status":"activated", "payments":[ { "id":"909612847079", "amount":10.0, "type":"cheque", "paid_at":"2015-05-20T18:44:13Z", "status":"paid" } ] } ]
GET /deposits/:id
Response
Status: 200 OK
{ "id":"0fe0bc5db4dd", "ref_no":"736", "contact_id":10789, "type":"deposit", "name":"Deposit of $10", "description": null, "category_id":9, "currency":"AUD", "amount": 10.0, "metadata":null, "status":"activated", "payments":[ { "id":"909612847079", "amount":10.0, "type":"cheque", "paid_at":"2015-05-20T18:44:13Z", "status":"paid" } ] }
POST /deposits
Parameters
- name
- Required string
- description
- Optional string
- amount
- Required decimal
- paid_date
- Optional datetime
- payment_type
-
Optional
string
cash
card
cheque
bank
other
- category_id
- Required integer
- contact_id
- Required integer
- metadata
- Optional string
Response
Status: 201 Created
Expenses
TidyHQ allows a Authenticated User to record an Expense next to a Contact for payment that has been from the organisation. Expense details include Expense Name, Description, Expense Amount, Date the Expense is due, Category, and which Contact the Expense came from.
Authentication token is required.
GET /expenses
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
- status
- Optional string
-
activated
default -
cancelled
-
activated,cancelled
- updated_since
- Optional string
Response
Status: 200 OK
[ { "id": "4eeb3ac8ede1", "ref_no": "42", "contact_id": 227, "type": "expense", "name": "Expense Ref.No 42", "description": null, "due_date": "2014-08-01", "category_id":9, "amount": 409.14, "amount_paid": 0.0, "amount_due": 409.14, "paid": false, "metadata":null, "status":"cancelled", "payments": [] }, { "id": "91892af259e9", "ref_no": "43", "contact_id": 206, "type": "expense", "name": "Expense Ref.No 43", "description": null, "due_date": "2014-07-19", "category_id":9, "amount": 721.65, "amount_paid": 700.0, "amount_due": 21.65, "paid": false, "metadata":null, "status":"activated", "payments": [ { "id":"5b1cc25e95d6", "amount":340.0, "type":"other", "paid_at":"2015-07-05T14:35:00Z", "status":"paid" }, { "id":"7a0d54702ce9", "amount":360.0, "type":"cash", "paid_at":"2015-07-06T14:35:00Z", "status":"paid" } ] }, { "id": "001c1ca97c04", "ref_no": "44", "contact_id": 207, "type": "expense", "name": "Expense Ref.No 44", "description": null, "due_date": "2014-08-19", "category_id":9, "amount": 359.17, "amount_paid": 359.17, "amount_due": 0.0, "paid": true, "metadata":null, "status":"activated", "payments": [ { "id":"5de94837d348", "amount":359.17, "type":"cheque", "paid_at":"2015-07-05T14:35:00Z", "status":"paid" } ] } ]
GET /expenses/:id
Response
Status: 200 OK
{ "id": "001c1ca97c04", "ref_no": "44", "contact_id": 207, "type": "expense", "name": "Expense Ref.No 44", "description": null, "due_date": "2014-08-19", "category_id":9, "amount": 359.17, "amount_paid": 359.17, "amount_due": 0.0, "paid": true, "metadata":null, "status":"activated", "payments": [ { "id":"5de94837d348", "amount":359.17, "type":"cheque", "paid_at":"2015-07-05T14:35:00Z", "status":"paid" } ] }
POST /expenses
Parameters
- name
- Required string
- description
- Optional string
- amount
- Required decimal
- due_date
- Required datetime
- category_id
- Required integer
- contact_id
- Required integer
- metadata
- Optional string
Response
Status: 201 Created
POST /expenses/:id/payments
Parameters
- amount
- Optional decimal
- payment_type
-
Optional
string
cash
card
cheque
bank
other
- date
- Optional datetime
Response
Status: 201 Created
DELETE /expenses/:id
Response
Status: 200 OK
{ "message": "Successful" }
Transactions
GET /transactions
Parameters
- start_date
- Optional datetime
- end_date
- Optional datetime
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": "bd2398135231", "category_id": 9, "category_name": "Event", "currency": "AUD", "paid_at": "2015-07-21T05:47:00Z", "contact_id": 1, "contact_name": "Cathrine Funk", "payment_type": "other", "surcharge": false, "amount": 10.0, "total": 10.0, "fee": 0.0, "status":"cancelled" }, { "id": "159ef582313c", "category_id": 10, "category_name": "Food", "currency": "AUD", "paid_at": "2015-07-20T18:44:13Z", "contact_id": 1, "contact_name": "Cathrine Funk", "payment_type": "stripe", "surcharge": false, "amount": 108.05, "total": 110.0, "fee": 1.95, "status":"refunded" }, { "id": "7d104d1cc1c3", "category_id": 9, "category_name": "Event", "currency": "USD", "paid_at": "2015-07-20T18:44:13Z", "contact_id": 1, "contact_name": "Cathrine Funk", "payment_type": "stripe", "surcharge": true, "amount": 260.0, "total": 264.2, "fee": 4.2, "status":"paid" } ]
GET /transactions/:id
Response
Status: 200 OK
{ "id": "159ef582313c", "category_id": 10, "category_name": "Food", "currency": "AUD", "paid_at": "2015-07-20T18:44:13Z", "contact_id": 1, "contact_name": "Cathrine Funk", "payment_type": "stripe", "surcharge": false, "amount": 108.05, "total": 110.0, "fee": 1.95, "status":"paid" }
Shop
GET /shop/products
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": "bd2398135231", "name": "Tidy Tee", "description": "Blue TidyHQ t-shirt. 100% cotton. Sizes S/M/L. Available in Blue only", "permalink": "tidy-tee", "sell_price": 20, "cost_price": 15, "sell_category_id": 10, "cost_category_id": 20, "quantity": 29, "visible_to": "public", "created_at": "2017-09-25T18:10:24Z", "images": ["link/to/img1.jpg", "link/to/img1.jpg"], "variants": [ { "id": "9fe1c4cae709", "name": "Small", "quantity": 5, "created_at": "2017-09-25T18:10:24Z" }, { "id": "6d21c81e88e4", "name": "Medium", "quantity": 10, "created_at": "2017-09-25T18:10:24Z" } ] } ]
GET /shop/products/:id
Response
Status: 200 OK
{ "id": "bd2398135231", "name": "Tidy Tee", "description": "Blue TidyHQ t-shirt. 100% cotton. Sizes S/M/L. Available in Blue only", "permalink": "tidy-tee", "sell_price": 20, "cost_price": 15, "sell_category_id": 10, "cost_category_id": 20, "quantity": 15, "visible_to": "public", "created_at": "2017-09-25T18:10:24Z", "images": ["link/to/img1.jpg", "link/to/img1.jpg"], "variants": [ { "id": "9fe1c4cae709", "name": "Small", "quantity": 5, "created_at": "2017-09-25T18:10:24Z" }, { "id": "6d21c81e88e4", "name": "Medium", "quantity": 10, "created_at": "2017-09-25T18:10:24Z" } ] }
GET /shop/shipping_options
Parameters
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": "fcf3c4caddb2", "name": "Example Shipping: Pick up from club house", "description": "Pick up on training nights. Club address: 1 Football St, Melbourne, Victoria.", "price": 0.0, "category_id": 12, "address_not_required": true, "created_at": "2017-09-25T18:10:24Z", "country_codes": ["AU"] } ]
GET /shop/shipping_options/:id
Response
Status: 200 OK
{ "id": "fcf3c4caddb2", "name": "Example Shipping: Pick up from club house", "description": "Pick up on training nights. Club address: 1 Football St, Melbourne, Victoria.", "price": 0.0, "category_id": 12, "address_not_required": true, "created_at": "2017-09-25T18:10:24Z", "country_codes": ["AU"] }
GET /shop/orders
Parameters
- status
- Optional string
-
all
default -
pending
-
completed
-
cancelled
- created_since
- Optional datetime
- limit
- Optional numerical
- offset
- Optional numerical
Response
Status: 200 OK
[ { "id": "b95cc4ca4694", "contact_id": 1001, "number": "27662080051", "status": "pending", "created_at": "2017-09-25T18:10:24Z", "shipping_option_id": "fcf3c4caddb2", "products": [ { "product_id":"a592c4ca299f", "variant_id":"4687eccb0046", "quantity":2 }, { "product_id":"d80fc81e5cd7", "variant_id":"7ce616790496", "quantity":1 } ] } ]
GET /shop/orders/:id
Response
Status: 200 OK
{ "id": "b95cc4ca4694", "contact_id": 1001, "number": "27662080051", "status": "pending", "created_at": "2017-09-25T18:10:24Z", "shipping_option_id": "fcf3c4caddb2", "products": [ { "product_id":"a592c4ca299f", "variant_id":"4687eccb0046", "quantity":2 }, { "product_id":"d80fc81e5cd7", "variant_id":"7ce616790496", "quantity":1 } ] }
Pricing Variations
Authentication token is required.
GET /membership_levels/:membership_level_id/pricing_variations
Response
Status: 200 OK
[ { "State": [ { "name": "CycleSport", "amount": "121.66", "destination": { "id": "932df4a6633f", "type": "Organisation", "name": "CycleSport" }, "autofill_group": { "id": 1481, "name": "CycleSport" }, "Club": [ { "name": "225 Racing CC", "amount": "25.46", "destination": { "id": "441867444512", "type": "Organisation", "name": "225 Racing CC" }, "autofill_group": { "id": 1489, "name": "225 Racing CC" } }, ] } ] } ]