Skip to main content

Clarra API Guide

Keao
  • Updated

Introduction

Welcome to the Clarra API Guide. This document provides all the necessary information to interact with our API, including authentication, available endpoints, and examples.

What is a REST API?

A REST (Representational State Transfer) API is a set of web service endpoints that allow communication between different software applications over the internet. REST APIs use standard HTTP methods such as GET, POST, PUT, DELETE, etc., to perform operations on resources identified by URLs. REST is an architectural style that leverages the HTTP protocol, making it widely used for web-based APIs due to its simplicity and scalability.

Basic Usage Scenarios

The Clarra API allows you to automate and integrate various functionalities of the Clarra application into your own systems. Here are some common scenarios where you might use the Clarra API:

  1. Automating Contact Management: You can create, update, and retrieve contact information, ensuring that your application’s contact database is always in sync with Clarra.

  2. Managing Events and Appointments: Schedule, update, and track events, deadlines, and tasks by integrating with Clarra’s event management system.

  3. Handling Legal Matters: Create and oversee legal matters, track their progress, and manage associated documents, ensuring a streamlined workflow.

  4. Timekeeping and Billing: Record and update time entries for different matters, enabling accurate billing and resource tracking.

  5. Document Management: Upload, retrieve, and manage documents within Clarra, ensuring that all your case-related documents are organized and easily accessible.

How to Use the Clarra API

  1. Authentication: Obtain an API key from your Clarra account settings and include it in the Authorization header of each request. Alternatively, you can use OAuth2 for authentication. Each API key can be customized for a specific application by limiting the functions the API is authorized to execute.

  2. Making Requests: Use standard HTTP methods to interact with the API endpoints. For example, use GET to retrieve data, POST to create new resources, PUT to update existing resources, and DELETE to remove resources.

  3. Handling Responses: The API returns responses in JSON format. Each response includes a status code indicating the success or failure of the request. Handle these responses in your application to ensure proper error handling and data processing.

  4. Rate Limiting: Be aware of the rate limits imposed by the API to avoid being throttled. The default rate limit is 1000 requests per hour.

Example Workflow

Here’s a step-by-step example of how you might use the Clarra API to manage contacts:

  1. Authenticate: Obtain your API key from the Clarra application and include it in the header of your requests.

    https
    Authorization: Bearer YOUR_API_KEY

  2. Create a New Contact: Use the POST /Contacts/Create endpoint to create a new contact.

    json 
    {
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "123-456-7890"
}

  3. Retrieve Contact Information: Use the GET /Contacts/GetContacts endpoint to retrieve information about existing contacts.

    http 
    GET /Contacts/GetContacts

  4. Update a Contact: Use the PUT /Contacts/Update endpoint to update the details of an existing contact.

    json 
    {
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@newexample.com"
}

  5. Delete a Contact: Use the DELETE /Contacts/Delete endpoint to remove a contact from the system.

    https
    DELETE /Contacts/Delete?id=123

By following these steps, you can effectively manage your contacts within the Clarra application using the API. 

Try the Clarra API

You can try the API on docs.clarra.com. Authorize with your API key or 0auth to use the Try Out feature.

 

Base URL

The base URL for all API requests is:

https://api.clarra.com/

 

API Version

Version: 1.0.0

Authentication

API Key

To access the Clarra API, an API Key is required. The API Key can be generated from the Clarra application by navigating to Account Settings > Integrations > Public API.

  • Security Scheme Type: API Key
  • Header parameter name: ApiKey

OAuth2

Clarra API also supports OAuth2 for authentication.

  • Security Scheme Type: OAuth2
  • Implicit OAuth Flow
    • Authorization URL: https://clarra-qa.us.auth0.com/authorize?audience=https://clarraqa/external/api
    • Scopes:
      • openid
      • profile
      • email

Endpoints

Contacts

Contact API is used to create, manage, and track all contacts, associating them with matters, events, deadlines, documents, mail, and more.

Get New Company Contact

  • URL: /Contacts/GetNewCompanyContact
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Response:
    json 
    {
  "status": "Success",
  "data": "New company contact details"
}

Get New Individual Contact

  • URL: /Contacts/GetNewIndividualContact
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Response:
    json 
    {
  "status": "Success",
  "data": "New individual contact details"
}

Create Individual/Company Contact

  • URL: /Contacts/Create
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "externalID": "string",
  "data": "string",
  "id": 0,
  "firstName": "string",
  "lastName": "string",
  "middleName": "string",
  "type": 0,
  "companyName": "string",
  "webSite": "string",
  "title": "string",
  "contactAddress": [{}],
  "contactPhones": [{}],
  "contactEmails": [{}],
  "contactTypes": [{}],
  "contactTags": [{}],
  "contactLinkedCompanies": [{}],
  "linkedMatter": [{}],
  "contactCustomFields": [{}],
  "contactNotes": [{}]
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Contact created successfully"
}

Update Individual/Company Contact

  • URL: /Contacts/UpdateContactZap
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "externalID": "string",
  "data": "string",
  "id": 0,
  "firstName": "string",
  "lastName": "string",
  "middleName": "string",
  "type": 0,
  "companyName": "string",
  "webSite": "string",
  "title": "string",
  "contactAddress": [{}],
  "contactPhones": [{}],
  "contactEmails": [{}],
  "contactTypes": [{}],
  "contactTags": [{}],
  "contactLinkedCompanies": [{}],
  "linkedMatter": [{}],
  "contactCustomFields": [{}],
  "contactNotes": [{}]
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Contact updated successfully"
}

Events

Event API is used for managing tasks, deadlines, and appointments, which can be customized and tracked.

Get New Event

  • URL: /Events/GetNewEvent
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Response:
    json 
    {
  "status": "Success",
  "data": "New event details"
}

Create Event

  • URL: /Events/CreateNewEvent
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "externalID": "string",
  "data": "string",
  "id": 0,
  "eventType": "string",
  "isMilestone": true,
  "eventCode": "string",
  "date": "2019-08-24T14:15:22Z",
  "time": "string",
  "duration": "string",
  "location": "string",
  "isException": true,
  "timezone": "string",
  "recurringEvent": true,
  "description": "string",
  "reminders": "string",
  "matter": "string",
  "matterNumber": "string",
  "matterID": 0,
  "assignees": [{}],
  "followers": [{}],
  "status": "string",
  "notes": [{}],
  "createdBy": {
    "id": "string",
    "firstName": "string",
    "email": "string",
    "lastName": "string",
    "initials": "string",
    "assignee": "string"
  },
  "createdOn": "2019-08-24T14:15:22Z"
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Event created successfully"
}

Matter

Matter API enables users to create and manage matters, streamlining operations with customizable workflows.

Get New Matter

  • URL: /Matter/GetNewMatter
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Response:
    json 
    {
  "status": "Success",
  "data": "New matter details"
}

Create Matter

  • URL: /Matter/CreateMatterWithZap1
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "externalID": "string",
  "data": "string",
  "id": 0,
  "matter": "string",
  "number": "string",
  "openDate": "2019-08-24T14:15:22Z",
  "closedDate": "2019-08-24T14:15:22Z",
  "complex": "string",
  "matterType": "string",
  "primaryOfficeHandling": "string",
  "caseSummary": "string",
  "court": "string",
  "courtCaseNumber": "string",
  "tenantId": 0,
  "notes": [{}],
  "adminNotes": [{}],
  "customFields": [{}],
  "mailDocsDirectory": "string",
  "docsFolder": "string",
  "leadAttorneyList": [{}],
  "otherAttorneyList": [{}],
  "paraLegalList": [{}],
  "docketingUsers": [{}],
  "linkedCases": [{}],
  "contactCases": [{}]
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Matter created successfully"
}

TimeSlip

TimeSlip API records time, billing rates, and resources associated with each matter.

Get New TimeSlip

  • URL: /TimeSlip/GetNewTimeSlip
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Response:
    json 
    {
  "status": "Success",
  "data": "New timeslip details"
}

Create TimeSlip

  • URL: /TimeSlip/CreateNewTimeSlipZap
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "externalID": "string",
  "data": "string",
  "id": 0,
  "tenantId": 0,
  "date": "2019-08-24T14:15:22Z",
  "duration": "string",
  "timekeeper": "string",
  "matter": "string",
  "type": "string",
  "project": "string",
  "description": "string",
  "notes": "string"
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Timeslip created successfully"
}

ClarraDocs

ClarraDocs API manages document-related operations.

Get New ClarraDocs Item

  • URL: /ClarraDocs/GetNewClarraDocsItem
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Query Parameters:
    • startDate (string <date-time>)
    • endDate (string <date-time>)
    • matterNumber (string)
    • mailType (string)
  • Response:
    json 
    {
  "status": "Success",
  "data": "New ClarraDocs item details"
}

Create ClarraDocs Item

  • URL: /ClarraDocs/Create
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "Id": 0,
  "Description": "string",
  "Note": "string",
  "MatterNumber": "string",
  "MailType": "string",
  "Date": "2019-08-24T14:15:22Z",
  "Status": "string",
  "Tags": ["string"],
  "Files": ["string"],
  "FileLinks": ["string"],
  "ExternalID": "string",
  "data": "string"
}
  • Response:
    json
    { "status": "Success", "message": "ClarraDocs item created successfully" }

Properties

Properties API is used to manage various properties in the system.

Get Properties

  • URL: /Properties/GetProperties
  • Method: GET
  • Authorization: ApiKey, oauth2
  • Query Parameters:
    • sectionId (integer <int32>)
  • Response:
    json 
    {
  "status": "Success",
  "data": "Properties details"
}

Create Property

  • URL: /Properties/CreateProperty
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "id": 0,
  "section": 0,
  "systemName": "string",
  "fieldName": "string",
  "fieldType": 0,
  "tableName": "string",
  "sortType": 0,
  "displayOnPage": 0,
  "isActive": true,
  "isRequired": true,
  "customFields": [{}],
  "customRules": [{}]
}
  • Response:
    json 
    {
  "status": "Success",
  "message": "Property created successfully"
}

Search

Search API allows you to search for various entities within the Clarra system.

Search Matters

  • URL: /Matters
  • Method: POST
  • Authorization: ApiKey, oauth2
  • Request Body:
    json 
    {
  "filter": "string",
  "matterID": 0,
  "externalID": "string",
  "matterName": "string",
  "matterNumber": "string",
  "matterType": "string",
  "openDate": "2019-08-24T14:15:22Z",
  "dateClosed": "2019-08-24T14:15:22Z"
}
  • Response:
    json 
    {
  "status": "Success",
  "data": "Search results"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Here are some common status codes:

  • 200 OK: The request was successful.
  • 201 Created: The resource was created successfully.
  • 400 Bad Request: The request was invalid or cannot be served.
  • 401 Unauthorized: Authentication failed or user does not have permissions.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: An error occurred on the server.

Example Error Response

json 
{
  "error": true,
  "message": "Invalid API key"
}

Rate Limiting

To ensure fair usage, the API imposes rate limits. The default limit is 1000 requests per hour. If you exceed this limit, you will receive a 429 Too Many Requests response.

Contact and Support

If you have any questions or need support, please contact our support team at support@clarra.com.

Related articles

Comments

0 comments

Please sign in to leave a comment.