API

Introduction

Paydirt's API is a versioned, RESTful, JSON based API.

If you're planning on using the Paydirt API, or you need any help integrating with it, please get in touch with our lead developer, nicholas@paydirtapp.com.

Root URL

Paydirt's API is accessible at https://app.paydirtapp.com/api/{VERSION}/ . The current API version is v1.

Authentication

Each request must be authenticated with a user's API key. You can find your API key in your Password Settings page.

Currently, the only authentication method that is supported is parameter based authentication. Each request must include the user's API key in the api_key parameter.

Examples:

GET /api/v1/clients?api_key={YOUR_API_KEY}
GET /api/v1/jobs/148?api_key={YOUR_API_KEY}
POST /api/v1/time?api_key={YOUR_API_KEY}&duration=3600&job_id=148...

Requests that are made without an api_key parameter, or with an invalid API key, will return a status code of 401 Unauthorized.

API requests that are made by a user with limited permissions (configured from your Team Settings page) will return a status code of 403 Forbidden. Users need full permissions to be able to access the Paydirt API, as the API allows them to view all information under the account and create clients, projects and jobs.

API Responses

Each valid API request will receive a JSON response with the status code 200 Ok. For single resources and collections the response includes a root object.

Examples:

# Request for a collection
GET /api/v1/clients?api_key={YOUR_API_KEY}

# Response body
{
  clients:
    [
      { id: 123, business_name: 'Widgets Inc' ... }
      ...
    ]
}

# Request for a single resource
GET /api/v1/clients/123?api_key={YOUR_API_KEY}

# Response body
{
  client: { id: 123, business_name: 'Widgets Inc' ... }
}

Invalid Requests

When an invalid API request is made (for example, for a client that doesn't belong to the authenticating user, or with invalid parameters for creating a time log), the API will return a status code of 422 Unprocessable Entity, and the following JSON body:

{
  errors: [ ... ]
}

The errors array should help you determine why the API call was invalid.