Registration

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.

Schema

All TidyHQ API requests start with https://api.tidyhq.com/v2/. All data is sent and received as JSON.

GET request. Access token sent as a parameter

$ curl -i https://api.tidyhq.com/v2/contacts/me?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": "4g4cef34g,  
  "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/v2/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": "g33h4gf33",  
  "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

Pagination

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

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 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.

access token sent in a header

$ curl -H "Authorization: Bearer TOKEN" https://api.tidyhq.com/v2/contacts/me

access token sent as a parameter

$ curl https://api.tidyhq.com/v2/contacts/me?access_token=TOKEN

Authorization Code Flow

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/v2/{resources}?access_token=TOKEN

Implicit Grant

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/v2/{resources}?access_token=TOKEN

Resource Owner Password Credentials

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  
}

Use the access token to access the API

access token sent in a header

$ curl -H "Authorization: Bearer TOKEN" https://api.tidyhq.com/v2/contacts/me

access token sent as a parameter

$ curl https://api.tidyhq.com/v2/contacts/me?access_token=TOKEN