Apperio Matter information API
A set of endpoints returning information about a specific matter.
OpenAPI Specification
openapi: 3.0.3
info:
title: Apperio API Documentation Analytics Matter information API
description: "# Introduction\n\nThe Apperio API allows law firms and businesses to enhance their internal\nbusiness intelligence capabilities. These APIs are designed to efficiently support\ninteractive reporting and are used to power the Apperio application.\n\n# API Versioning\n\nMajor versions will come with semantic versioning guarantees.\nThat is to say, there will be no breaking changes in minor version upgrades.\nIn particular the following changes will only be introduced in major versions of the API:\n\n * Changing the meaning of an entity or attribute\n * Renaming entities or attributes\n * Adding new required attributes in the request\n * Changing the URI of the endpoint\n * Removing a URI endpoint\n * Adding further choices to an enumeration\n * Removing choices from an enumeration in the request\n\nFurther endpoints and entity attributes can be added in minor versions. It's expected that\nclients should ignore any attributes that are returned in the response that they weren't\naware of. When a multiple option attribute isn't modelled with an explicit enumeration the\nintegrating clients should also ensure that they can handle unknown responses.\n\nEach previous version of the API will be supported for 6 months after the release of a new\nmajor version. A migration plan will be published for each major version to inform integrators\nof breaking changes.\n\n### What is likely to change in the next major version of the API?\n\n#### Service Versioning\n\nEach endpoint will include the version and service name. Endpoints will have the following format:\n\n`/api/v[MAJOR VERSION NUMBER]/[SERVICE_NAME]/[ENDPOINT NAME]`\n\nHence in version 2:\n\n* `/api/v1/filter/invoices/` will change to `/api/v2/filter/invoices/`\n* `/api/v1/analytics/` will change to `/api/v2/analytics/analytics/`\n\n#### Matter / Engagement\n\nThe terms matter and engagement are used interchangeably in the current version. This\nreflects historical usage in the product. References to `engagement` will be replaced\nwith `matter` in future versions.\n\n# Change Log for Version 1.5\n\n#### v1.5\n* Updated engagement and invoice filter endpoints parameters documentation\n* Added documentation for some ebilling endpoints\n\n#### v1.4\n* Added basic information about the matter header endpoint\n\n#### v1.3\n* Update rate limits\n* Fix analytics URL and auhorization header\n\n#### v1.2\n* Key Management\n* HTTP 429 response\n* Versioning moved from service to global API version\n* Glossary definitions\n\n#### v1.1\n* Matter Tag Set Discovery Endpoint\n\n#### v1.0\n* Versioning Strategy\n* Glossary\n\n#### v0.2\n\n* Invoice discovery endpoint.\n* Null choice filter.\n* Fair usage policy.\n* Capabilities for law firm and business users.\n\n#### v0.1\n\n* Filter resource discovery API.\n\n# Authentication\n\nAll endpoints require that you be authenticated. To become authenticated\nyou will need to create an API Key from the profile page in the application,\nand supply it within the Authentication header in the following format:\n\n```\ncurl -X GET \"https://sandbox.apperio.com/api/v1/data/analytics/\"\n-H \"Authorization: Token <TOKEN VALUE>\"\n```\n\nPlease contact Customer Success to enable API access on your account.\n\nAll requests that are made to the API will be made with the capabilities of\nthe user generating the token. It's important that you ensure that the access\ntoken is kept secret and not shared outside of your organisation. In particular\nbe mindful not to check it in to code or configuration files where it can be\nseen in plain text. We recommend cycling the API key at least every 12 months.\nIf you suspect that the key may been leaked then disable it immediately in the profile\nsection and inform Apperio. Apperio do not have access to these tokens; hence, you\nwill need to generate a new token if it's lost.\n\nYou should consider that this token grants access to anything that the associated\nuser can access on the website. This will allow you to take advantage of future\nendpoints without further configuration. With this in mind be careful to give this\naccount the minimum set of privileges required for your integration.\n\n# Pagination and Ordering\n\nPagination endpoints allow ordered data to be brought back in chunks. Pagination\nis usually limited to data discovery and information feed endpoints. If available\n`PAGINATION` will be listed in the *Capabilities* section of the endpoint. The response\ncan be ordered by setting the `ordering` query parameter. This takes a URL encoded\ncomma separated list of fields to order by. If a field is prepended by a `-` then\nthe ordering is reversed. For example if I wished to order by `last_worked_at_law_firm`\nwith the latest results first and then by `engagement_id` I would add the following\nto the query:\n\n```\nordering=-last_worked_at_law_firm%2Cengagement_id\n```\n\nThe number of results returned on a page is controlled by the `page-size` parameter.\nIt defaults to 50 across the API and will be capped to avoid large one-time data\nextractions that may be prone to fail.\n\n```\nordering=-last_worked_at_law_firm%2Cengagement_id&page-size=10\n```\n\nWhen there are more items to return than can be shown on one page then a pagination\nobject is returned in the response:\n\n```json\n\"pagination\": {\n \"next\": \"https://sandbox.apperio.com/api/v1/filter/engagements/?ordering=-last_worked_at_law_firm%2Cengagement_id&page=dj0yJnA9MiZnPWJiNTdmMDg2NzI2YzQxYWRhZmI4NmZjMjRlODI5ZTIz&page-size=10\",\n \"previous\":null\n \"nextPage\":\"dj0yJnA9MiZnPWJiNTdmMDg2NzI2YzQxYWRhZmI4NmZjMjRlODI5ZTIz\",\n \"previousPage\":null\n}\n```\n\nThe `nextPage` and `previousPage` provide a token that can be passed to the `page` parameter to\nnavigate to that page. `null` indicates that there is no further data in that direction. The `next` and\n`previous` attributes provide HATEOAS style links to navigate to the next and previous page.\n\n# Business and Law Firm Capabilities\n\nApperio is a double sided platform that allows law firms and businesses to collaborate. The Apperio API is available\nto both businesses and law firms; however some requests are only available to one side of the platform. The capabilities\nsection for each endpoint details which side can access each API call.\n\nThe access token serves to identify the organisation (law firm or business). Resources in each request will be restricted\nto those available to that organisation.\n\n# Acceptable usage policy\n\n* Please respect the usage limits. If you think you are likely to exceed them then please contact Customer Success.\n The standard usage limits are:\n - Requests from the same authorization token should be made in series; not in parallel\n - Maximum of 10000 requests in an hour\n* The API is designed to allow you to provide innovative services that incorporate data that's held in Apperio.\nThey should not be used as a means of duplicating that data.\n* If you're unsure about the most effective way to integrate with Apperio to support your business case then\nplease contact Customer Success so we can take you through different solutions.\n* Your application must be able to handle a `HTTP 429 Too Many Requests` response.\n* Apperio reserve the right to suspend API access if usage contravenes this policy. \n\n# Glossary\n\nThe following terminology is used throughout the API\n\n| Term | Description |\n| ------------- | ------------- |\n| Billable | The billable amount includes both entries that have been billed and the potential contribution from work that's in progress. |\n| Billed | The amount that has already been invoiced. |\n| Budget | The estimated budgeted amount for hourly matters. For fixed matters this represents the fixed cost. This also represents the cap for capped matters (see Fee Structure). |\n| Client | The client of the law firm. Multiple law firm clients can be associated with the one Apperio business. |\n| Disbursement | disbursements, hard cost and soft costs. |\n| Engagement | (see Matter) The term `engagement` is Apperio internal terminology for `matter` and will be replaced with `matter` in the next major version. |\n| Fee | The charge for work undertaken by the law firm. |\n| Fee Structure | How the matter will be billed. Apperio supports Hourly, Capped and Fixed Fee structures. |\n| Matter | A law firm case. |\n| Practice Group | The division in the law firm conducting the work. |\n| Wip | Work that has been carried out but not yet billed on the matter (Work in progress). |\n"
servers:
- url: https://sandbox.apperio.com/
- url: https://app.apperio.com/
tags:
- name: Matter information
description: 'A set of endpoints returning information about a specific matter.
'
paths:
/api/v1/matters/{matter-id}/header:
get:
summary: Matter header
description: 'Returns data displayed in the header of the matter page.
'
parameters:
- name: matter-id
in: path
required: true
schema:
type: integer
description: 'Inclusive date to gather data from
IMPORTANT: This parameter depends on the type of user.
For business users, it is the `project_id`.
For law firm users - `engagement_id`.
You can retrieve both from the `/api/v1/filter/engagements` endpoint.
'
example: 123
tags:
- Matter information
responses:
'200':
description: 'Matter header data
'
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The ID of the engagement
example: 123
budget_id:
type: integer
description: The ID of a budget associated with this engagement
example: 456
currency:
type: string
example: GBP
description: ISO 4217 Three letter currency code
minLength: 3
maxLength: 3
client_matter_reference:
type: string
description: A client's matter reference, if different than the law firm's one
example: M123-A4789/1
fee_structure:
type: string
example: hourly
description: "Fee Structure. How is the matter billed. Supported fee structures are:\n * `hourly` - Billed on a time and materials basis.\n * `fixed` - Fixed fee.\n * `capped` - Billed on time and materials up to a fixed cap.\n"
data_visible_up_to:
type: date
description: The last date the data is visible for. Equals to today's date minus the sharing window.
is_nonbillable:
type: boolean
description: Whether the matter is non-billable
law_firm:
type: object
description: Basic firm details
properties:
id:
type: integer
description: The ID of the firm
example: 123
name:
type: string
description: The name of the firm
example: Example Law Firm
service_provider_type:
type: string
description: The type of the service this firm provides
enum:
- legal
- accountancy
law_firm_created_at:
type: date
description: The date this matter was created in the law firm's PMS
law_firm_name:
type: string
description: The matter name, as provided by the law firm
billing_entity:
type: object
properties:
id:
type: integer
business_id:
type: integer
name:
type: string
number:
type: string
description: Matter number, as provided by the law firm
open_dates:
type: object
description: The date range of when the matter was "open"
properties:
start_date:
type: date
example: '2020-05-01'
end_date:
type: date
practice_group:
type: object
description: The matter's practice group
properties:
id:
type: integer
name:
type: string
status:
type: string
description: The matter status
enum:
- current
- closed
is_business_name_different:
type: boolean
client_contact_first_name:
type: string
client_contact_last_name:
type: string
client_contact_email:
type: string
standard_fee_structure:
type: object
description: The "standard" fee structure that the one prvovided by the law firm is mapped to
properties:
id:
type: integer
name:
type: string
active_fee_structure:
type: string
enum:
- capped
- fixed
- hourly
icon:
type: string
overrides:
type: array
client_name:
type: string
description: The name of the client
law_firm_closed_at:
type: date
description: The matter close date, as provided by the law firm
project:
type: object
description: The matter metadata provided by the business
properties:
id:
type: integer
name:
type: string
business_matter_type:
type: object
properties:
id:
type: integer
name:
type: string
folder:
type: object
properties:
id:
type: integer
name:
type: string
description: The folder name
full_folder_name:
type: string
description: The full path to the folder, including all is ancestors
pass_through:
type: boolean
description: Whether it is a pass-through matter
team:
type: object
properties:
id:
type: integer
name:
type: string
matter_owners:
type: array
items:
type: object
properties:
id:
type: integer
matter:
type: object
properties:
id:
type: integer
name:
type: string
user:
type: object
properties:
id:
type: integer
first_name:
type: string
last_name:
type: string
email:
type: string
assignment_start:
type: date
assignment_end:
type: date
confidential:
type: boolean
is_business_manual:
type: boolean
description: Whether the matter was created manually by the business
is_redacted:
type: boolean
description: Whether the data is redacted (because the matter is confidential and the user does not have access to confidential matters)