NAV Navbar
  • Introduction
  • Authentication
  • Meta
  • Activity
  • Errors
  • Introduction

    The Tali API is centered around a fairly basic REST interface with some simple business logic managed through the responses. Otherwise, it's basically a REST interface on top of our MongoDB models.

    At this point our API is not public, but we're working hard on creating developer access – so stay tuned!

    Authentication

    Example Request

    GET /api/v2/activity HTTP/1.1
    Host: www.telltali.com
    Accept: application/json
    Authorization: Bearer <access_token>
    

    Tali uses an OAuth access_token to authenticate requests, and expects to see it on every request header as:

    Authorization: Bearer <access_token>

    Meta

    Example Meta Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "meta": {
        "self": "https://www.telltali.com/api/v2/activity?page=2&per_page=10&status=complete",
        "next": "https://www.telltali.com/api/v2/activity?page=3&per_page=10&status=complete",
        "prev": "https://www.telltali.com/api/v2/activity?page=1&per_page=10&status=complete",
        "count": 10,
        "total": 35
        "pages": 4,
        "page": 2
      },
      "data": { ... }
    }
    

    Successful requests will return a top-level meta object containing many gifts and goodies. You can think of it as Tali's crude attempt at a HATEOAS type of system to assist in pagination and application state.

    Endpoints that return a list of resources will return the payload shown in the example. Single resources will only return self.

    Feel free to ignore it if you like, but if it helps... then cheers!

    Activity

    Overview

    Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "meta": { ... },
      "data": [
        {
          "id": "5a443db4d601ba00043de4ef",
          "self": "https://www.telltali.com/api/v2/activity/5a443db4d601ba00043de4ef",
          "status": "complete",
          "user": {
            "id": "59ca889fee749a000419c40a",
            "self": "https://www.telltali.com/api/v2/user/59ca889fee749a000419c40a",
            "firstName": "John",
            "lastName": "Smith"
          },
          "project": {
            "id": "59ca889fee749a000419c40a",
            "self": "https://www.telltali.com/api/v2/project/59ca889fee749a000419c40a",
            "label": "Smith Brothers Construction"
          },
          "description": "Reviewed existing court documents",
          "duration": 900,
          "custom_duration": 1800,
          "integration": {
            "name": "Clio",
            "synced": true
          },
          "records": [
            {
              "id": "5a443db4d601ba00043de4ef",
              "self": "https://www.telltali.com/api/v2/record/5a443db4d601ba00043de4ef",
              "type": "time",
              "status": "complete",
              "startTime": 1514417405403,
              "stopTime": 1514418125514,
            },
            ...
          ]
        },
        ...
      ]
    }
    

    An activity combines a user, project and one or more records to create a time entry with a description and duration. By default, the duration is a sum of the time logged per record, but can be manually defined using the custom_duration field.

    Attribute Description
    id Unique identifier for the object. (string)
    self API reference to the resource. (string)
    status State of the activity. (string) Values: pending, complete, trash Default: pending
    user The user this activity is for. (object)
    project The project this activity is for. (object)
    description Description of the work that was performed for the activity. (string)
    duration Seconds captured as a sum of all record start/stop times. (number)
    custom_duration User defined duration of seconds to be billed. (number)
    integration Name and synced status of an integration the user has connected. (object)
    records List of records for this activity. (array)

    Get Activities

    Example Request

    GET /api/v2/activity HTTP/1.1
    Host: www.telltali.com
    Accept: application/json
    Authorization: Bearer <access_token>
    

    GET /activity

    GET /activity/{activity.id}

    Parameter Default Description
    status complete (String) Activity status – values: pending, complete, or trash.
    page 1 (Number) Page number for pagination
    per_page 25 (Number) Activities per page
    order desc (String) Sort order – values: asc or desc
    sort created_at (String) Field to sort by – values: [see activity model]

    Create Activity

    Example Request

    POST /api/v2/activity HTTP/1.1
    Host: www.telltali.com
    Content-Type: application/json
    Authorization: Bearer <access_token>
    
    {
      "description": "Did a thing",
      "project": "Smith Construction",
      "duration": 900,
      "stop_time": 1514418125514
    }
    

    POST /activity

    Parameter Default Description
    description null Optional (String)
    project null Optional (String)
    duration null Optional (Number)
    stop_time null Optional (Date)

    Update Activity

    Example Request

    PUT /api/v2/activity/{activity.id} HTTP/1.1
    Host: www.telltali.com
    Content-Type: application/json
    Authorization: Bearer <access_token>
    
    {
      "description": "Did a thing",
      "project": "Smith Construction",
      "custom_duration": 1800
    }
    

    PUT /activity/{activity.id}

    Parameter Description
    description Optional (String)
    project Optional (String)
    custom_duration Optional (Number)

    Sync Activity

    Sync the activity with the integration the user has connected – for instance, Clio, TSheets, etc.

    Example Request

    POST /api/v2/activity/{activity.id}/sync HTTP/1.1
    Host: www.telltali.com
    Content-Type: application/json
    Authorization: Bearer <access_token>
    

    POST /activity/{activity.id}/sync

    Errors

    Example Error Response

    HTTP/1.1 403 Forbidden
    Content-Type: application/json
    
    {
      "error": "forbidden",
      "error_description": "User does not own this resource."
    }
    

    The Tali API uses this subset of HTTP status codes:

    Code Meaning
    200 OK - Life is good, and here's proof.
    201 Created - New resource created.
    204 No Content - Life is good, but there's no proof.
    304 Not Modified - You tried to update something that hasn't changed.
    400 Bad Request - Whoops. You probably made a syntax error.
    401 Unauthorized - Missing or expired access token.
    403 Forbidden - Valid access token, but for the wrong user.
    404 Not Found - Wrong endpoint bruh.
    500 Internal Server Error - Tali broke. You win. Contact us.