Apperio E-billing API
The e-billing endpoints provide access to the e-billing invoices in Apperio. They allow you to retrieve information about the invoices and the approval workflow, and also to approve and reject invoices.
OpenAPI Specification
openapi: 3.0.3
info:
title: Apperio API Documentation Analytics E-billing 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: E-billing
description: 'The e-billing endpoints provide access to the e-billing invoices in Apperio.
They allow you to retrieve information about the invoices and the
approval workflow, and also to approve and reject invoices.
'
paths:
/api/v1/ebilling/invoices/{invoice-id}/:
get:
summary: Get the invoice details
description: 'Capabilities: BUSINESS, LAW_FIRM
'
tags:
- E-billing
parameters:
- name: invoice-id
in: path
schema:
type: int
description: Invoice ID
example: 12345
responses:
'200':
description: 'Invoice details
'
content:
application/json:
schema:
type: object
description: 'An e-billing invoice that has been submitted to Apperio for processing.
'
required:
- name
properties:
id:
type: int
description: Apperio identifier for the e-billing invoice
example: 12345
readOnly: true
law_firm_id:
type: int
description: Apperio identifier for the law firm
example: 12345
readOnly: true
law_firm_reference:
type: string
description: The law firm's reference for the invoice. Also known as the invoice number.
example: LF-INV-12345
service_provider_type:
type: string
description: The type of service provider that submitted the invoice.
example: legal
enum:
- legal
- accountancy
status:
type: string
example: ebilled
description: 'Tracks the progress of an invoice in Apperio:
* `draft`: draft invoice that hasn''t yet been billed
* `queried`: Invoice that has been billed but queried by the business
* `ebilled`: Billed but not yet paid
* `in_review`: Business are reviewing the invoice
* `approved`: Business has approved
* `paid`: Business has paid
* `cancelled`: The invoice has been cancelled (AKA voided)
'
enum:
- draft
- queried
- ebilled
- in_review
- approved
- paid
- cancelled
status_changed_automatically:
type: boolean
description: 'Indicates whether the status was changed automatically by Apperio.
If `false`, the status was changed manually by a user.
Status can be changed automatically by Apperio when an invoice was queried
for a certain number of days and no action was taken. Apperio will then
automatically change the status to `cancelled`.
'
example: true
void_queried_at:
type: string
format: date-time
description: 'Capabilities: LAW_FIRM
The date and time the invoice will be voided after being queried
for a certain number of days.
'
example: '2021-01-01T00:00:00Z'
void_queried_in_days:
type: integer
nullable: true
description: 'Capabilities: LAW_FIRM
Number of days, counting from the current date, after which the invoice
will be voided automatically if it remains in the `queried` status.
It is a dynamic field, calculated as the difference between
`void_queried_at` and the current date.
Only populated if the invoice is in the `queried` status.
'
example: 30
has_been_ebilled:
type: boolean
description: 'Indicates whether the invoice has been e-billed.
This is `true` for all invoices that are not in the `draft` status.
'
example: true
has_breakdown:
type: boolean
description: 'Indicates whether the invoice has a breakdown of fees and disbursements.
This is `true` for invoices where the law firm has provided a breakdown
of fees and disbursements, either via a Data File Uploader or a LEDES file.
In case of the DFU, the data must also match the values entered for the invoice.
'
example: true
custom_upload_id:
type: int
description: 'The identifier for the custom upload that represents the LEDES file
used to create the invoice.
'
example: 12345
date:
type: string
format: date
description: 'The date the invoice was created in the service provider''s system.
'
example: '2021-01-01'
tax_date:
type: string
format: date
description: 'The date that should be used for tax purposes.
'
example: '2021-01-01'
tax_type:
type: string
description: 'The type of tax that should be applied to the invoice.
'
example: VAT
billing_start_date:
type: string
format: date
description: 'The start date of the billing period covered by the invoice.
'
example: '2021-01-01'
billing_end_date:
type: string
format: date
description: 'The end date of the billing period covered by the invoice.
'
example: '2021-01-31'
currency:
allOf:
- type: string
example: GBP
description: ISO 4217 Three letter currency code
minLength: 3
maxLength: 3
description: 'ISO 4217 Three letter currency code of the currency that the invoice is billed in.
'
net_fees:
type: string
format: decimal
description: 'The total amount of fees billed on the invoice, excluding tax.
'
example: '1000.00'
net_disbursements:
type: string
format: decimal
description: 'The total amount of disbursements billed on the invoice, excluding tax.
'
example: '100.00'
net_total:
type: string
format: decimal
description: 'The total amount billed (fees + disbursements) on the invoice, excluding tax.
'
example: '1100.00'
tax_total:
type: string
format: decimal
description: 'The total amount of tax billed on the invoice.
'
example: '220.00'
total:
type: string
format: decimal
description: 'The total amount billed on the invoice, including tax.
'
example: '1320.00'
matters:
type: array
items:
type: object
description: 'The invoice matter details
'
properties:
engagement_id:
type: int
description: 'The Apperio identifier of the matter that the invoice is associated with.
'
example: 12345
client_id:
type: int
description: 'The Apperio identifier of the client that the invoice is associated with.
'
example: 12345
law_firm_reference:
type: string
description: 'The law firm reference for the matter.
'
example: '12345'
name:
type: string
description: 'The name of the matter.
'
example: Land Aquisition
billing_entity:
type: string
description: 'The name of the entity that the invoice is billed to.
'
example: Acme Corporation
net_fees:
type: string
format: decimal
description: 'The total amount of fees billed on the invoice, excluding tax.
'
example: '1100.00'
net_disbursements:
type: string
format: decimal
description: 'The total amount of disbursements billed on the invoice, excluding tax.
'
example: '220.00'
description: 'Capabilities: LAW_FIRM
The matters that the invoice is associated with.
'
matter_ids:
type: array
items:
type: integer
description: 'The Apperio identifiers of the matters that the invoice is associated with.
'
example:
- 12345
- 67890
client_id:
type: int
description: 'The Apperio identifier of the client that the invoice is associated with.
'
example: 12345
billing_entity:
type: string
description: 'The name of the entity that the invoice is billed to.
'
example: Acme Corporation
document:
allOf:
- &id001
type: object
description: 'A `document` referenced from the invoice or credit note. Use the document management APIs to retrieve the full document details.
'
properties:
id:
type: string
format: uuid
description: 'The Apperio identifier of the document object.
'
example: 123e4567-e89b-12d3-a456-426614174000
version:
type: int
description: 'The `version` of the document.
'
example: 123
filename:
type: string
description: 'The name of the file.
'
example: Invoice.pdf
description: 'The PDF file attached to the invoice.
'
credit:
type: object
description: 'Credit notes associated with an invoice.
'
properties:
id:
type: int
description: 'The Apperio identifier of the credit note.
'
example: 12345
law_firm_id:
type: int
description: 'The Apperio identifier of the law firm that the credit note is associated with.
'
example: 12345
law_firm_reference:
type: string
description: 'The law firm reference for the credit note.
'
example: '12345'
invoice_id:
type: int
description: 'The Apperio identifier of the e-billing invoice that the credit note is associated with.
'
example: 12345
is_cancelled:
type: boolean
description: 'Whether the credit note has been cancelled.
'
example: false
date:
type: string
format: date
description: 'The date the credit note was created.
'
example: '2020-01-01'
refunded_fee:
type: string
format: decimal
description: 'The total amount of fees refunded on the credit note.
'
example: '1100.00'
refunded_disbursement:
type: string
format: decimal
description: 'The total amount of disbursements refunded on the credit note.
'
example: '220.00'
refunded_tax:
type: string
format: decimal
description: 'The total amount of tax refunded on the credit note.
'
example: '220.00'
has_been_ebilled:
type: boolean
description: 'Whether the credit note has been e-billed.
'
example: false
document:
allOf:
- *id001
description: 'The PDF file attached to the credit note.
'
source:
type: string
description: 'The source of the invoice.
'
enum:
- ledes
- pdf
example: ledes
approved_email_sent_at:
type: string
format: date-time
description: 'The date and time the email was sent to the business to notify them that
the invoice has been approved.
'
example: '2021-01-01T00:00:00Z'
approved_email_sent_to:
type: string
description: 'The email address the email was sent to.
'
example: john.smith@eample.com
is_manual:
type: boolean
description: 'Indicates whether the invoice was created by a "manual" law firm.
'
example: false
payable:
type: string
format: decimal
description: 'The total amount that is payable on the invoice.
'
example: '1320.00'
approval_query:
type: object
description: 'A record of status changes for an e-billing invoice.
'
properties:
created:
type: string
format: date-time
description: 'The date and time the status change was recorded.
'
example: '2021-01-01T00:00:00Z'
approver:
type: object
description: 'A user who can approve an invoice.
'
properties:
id:
type: int
description: 'The Apperio identifier of the approver.
'
example: 12345
first_name:
type: string
description: 'The first name of the approver.
'
example: John
last_name:
type: string
description: 'The last name of the approver.
'
example: Doe
email:
type: string
description: 'The email address of the approver.
'
example: john.doe@example.com
client_name:
type: string
description: 'The name of the client that the invoice was submitted to, as set on the invoice
at the time of the status change.
'
example: Acme Corporation
notes:
type: string
description: 'Any notes that were added to the status change.
'
example: Looks good to me!
permissions:
type: object
description: 'The permissions that the user has for the invoice.
'
properties:
can_edit_data:
type: boolean
description: 'Indicates whether the user can edit the data on the invoice.
'
example: true
can_edit_document:
type: boolean
description: 'Indicates whether the user can edit the document attached to the invoice.
'
example: false
example:
can_edit_data: true
can_edit_document: false
capabilities:
type: object
description: 'The optional features available for the invoice.
'
properties:
has_approval_workflow:
type: boolean
description: 'Indicates whether the invoice has an approval workflow.
'
example: true
example:
has_approval_workflow: true
withheld_fees:
type: string
format: decimal
description: 'The total amount of fees that have been withheld from the invoice.
Only present on invoices with an approval workflow.
*NOTE: This field is specific to Qatar''s withholding tax laws.*
'
example: '100.00'
withheld_user:
type: object
description: 'The user that entered the withheld fees.
Only present on invoices with an approval workflow.
*NOTE: This field is specific to Qatar''s withholding tax laws.*
'
properties:
id:
type: int
description: 'The Apperio identifier of the user.
'
example: 12345
first_name:
type: string
description: 'The first name of the user.
'
example: John
last_name:
type: string
description: 'The last name of the user.
'
example: Smith
email:
type: string
description: 'The email address of the user.
'
example: john.smith@example.com
withheld_date:
type: string
format: date
description: 'The date the withheld fees were entered.
Only present on invoices with an approval workflow.
*NOTE: This field is specific to Qatar''s withholding tax laws.*
'
example: '2021-01-01'
withheld_notes:
type: string
description: 'The notes entered when the withheld fees were entered.
Only present on invoices with an approval workflow.
*NOTE: This field is specific to Qatar''s withholding tax laws.*
'
example: Withheld for Qatar tax
attributes:
type: object
description: 'An object mapping attribute names to their values
'
example:
requester_name: Jane Doe
requester_email: jane.doe@example.com
'401':
description: 'Unauthenticated access - ensure to create a valid API token
'
'403':
description: 'Unauthorized access - Ensure your organisation owns this invoice and
the user has access to it
'
'404':
description: 'Invoice not found
'
/api/v1/ebilling/invoices/{invoice-id}/status/:
post:
summary: Change invoice status
description: 'Capabilities: BUSINESS, LAW_FIRM
'
tags:
- E-billing
parameters:
- name: invoice-id
in: path
schema:
type: int
description: Invoice ID
example: 12345
requestBody:
required: true
content:
application/json:
schema:
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apperio/refs/heads/main/openapi/apperio-e-billing-api-openapi.yml