Last date modified: 2025 18 Aug

Custom connectors

You can integrate into the Contracts Analysis pipeline through custom connectors. A custom connector is a framework that customers can use to wrap around their existing machine learning (ML) and artificial intelligence (AI) pipelines, applications, or third-party services, allowing seamless integration to the Contracts Analysis pipeline. You can use custom connectors to integrate an internal entity extraction application without having to manually export/import data from Relativity, connect to a third-party contract analytics tool you are currently using, and more.

Contracts custom connectors support the following functionality:

  • Document classification
  • Segmentation
  • Annotations
  • Field Population

Configuring a custom connector

To configure a custom connector:

  1. Create a New Contracts Model.
  2. For Model Type select External Analysis.
  3. Enter your API's endpoint URL for External API Endpoint.
  4. Click Check to verify connection.
    This verification is performed from your Relativity web server. Depending on your Relativity infrastructure setup, connectivity may be different from your agent servers compared to your web servers. Check with your Relativity IT administrator if you experience problems.
    • Use the @ character to trigger a list of Relativity fields to select and map to a JSON property.
    • To send the document’s native file, use the Contracts Native field. This provides a base64 encoded version of the Relativity document in the request body.
  5. Click Edit Body to enter your API's JSON request body.
    • Use the @ character to trigger a list of Relativity fields to select and map to a JSON property.
    • To send the document’s native file, use the Contracts Native field. This provides a base64 encoded version of the Relativity document in the request body.
  6. Click Save once all mapping is complete.
    Validation will occur to verify the input API Body is valid JSON. If not, a message will appear.
  7. Select a Relativity Object to populate from your API’s response.

Field mapping is done after saving the Model first and then going back to edit it.

Token mapping

To set up token mapping:

  1. After saving the model, you'll see three new sections appear:
    • Object Mapping
    • Document Mapping
    • Authentication Headers.
  2. Click the Edit button on the Object Mapping card to view a mapping interface with the Relativity Object Fields on the left and Response Properties on the right.
  3. Select the Relativity object fields from the list on the left.
  4. Click the Paste Response button on the right, then paste in a sample response from your API.
  5. Click the Generate Properties button at the bottom. Contracts's custom connector framework will parse the sample, extract the properties and display them to map to the Relativity object fields.
    If your sample response does not contain all properties you can use the Add Tokens field at the top of the list to add any additional tokens needed for mapping.
  6. Once you have all fields mapped, click Save.
  7. The page will refresh and display the new token mappings at the bottom.
  8. For Authentication Headers, click New and add a Parameter Name, Parameter Value, and Parameter Location, header or URL.
  9. When the request is sent, we will append the headers so that each request or document includes the headers, allowing you to send custom headers for each request to support authentication requirements of third party services.

Custom connector developer documentation

This section provides an overview of custom connectors for developers.

Authentication

Custom connectors support the use of one of the following standard authentication methods: API Key.

Request

We provide you with a simple configuration interface to map Relativity fields to the properties in your API's request schema.

Requirements

  • All HTTP requests will be sent using the POST method.
  • HTTP version 1.1 is required. 2.0 is currently not supported.
  • Requests may be sent using HTTP or HTTPS. However, HTTPS is recommended.

Examples

Below are examples of API calls.

Extracted text example

In the following example, let’s say your API requires two fields to be sent for a request.

NameDescription
idThe document ID
textThe extracted text of the document

An example JSON request body would look like the following:

An image showing an example JSON request body.

Native document example

In this example we show how you would send the native document API requires two fields to be sent for a request:

NameDescription
idThe document ID
fileTypeThe native file type
fileDataThe base64 encoded native Document data

An example JSON request body would look like the following:

An image showing an example JSON request body.

Response

To take advantage of Contracts’ rich document viewer functionality in Relativity, Custom Connectors accepts the following fields in your API’s JSON response payload.

NameTypeUse caseDescriptionRelativity field
documentIdnumberALLThe Relativity ArtifactID of the document used to match the response of your API back to the document. Artifact ID (read only)
categorystringClassificationThe category of the contractContract Type
probabilitydecimalClassificationThe confidence score for the categorization of the contract Contract Type Confidence Score
titlestringALLThe title of the contractContract Title
sectionsarraySegmentationAn array of sectionsSection
annotationsarrayAnnotationAn array of AnnotationsAnnotation
fieldsarrayRelativity Field PopulationAn array of FieldsField

Section (Relativity document)

The following table provides descriptions and use cases for Section fields.

NameTypeUse caseDescriptionRelativity field
textstringSegmentation (required)The text of the sectionContracts Extracted Text
headingstringSegmentation (optional)The heading of the sectionSection Heading
startintegerSegmentation (required)The start offset of the Section in relation to the original Relativity Document Contracts Extracted Text Contracts Section Start
endintegerSegmentation (required)The end offset of the Section in relation to the original Relativity Document Contracts Extracted Text Contracts Section End
categorystringSegmentation (optional)The category of the sectionSection Type
probabilitydecimalSegmentation (optional)The confidence score for the categorization of the sectionSection Type Confidence Score

Annotation (RDO)

The following table provides descriptions and use cases for Annotation (RDO) fields.

NameTypeUse caseDescriptionRDO field
textstringAnnotation (required)The text of the annotationText
categorystringAnnotation (required)The category or type of the annotationCategory
offsetintegerAnnotation (required)The start offset of the Annotation in relation to the original Relativity Document Contracts Extracted Text Length
lengthintegerAnnotation (required)The length of the Annotation string Offset

Field (Contracts internal)

The following table provides descriptions and use cases for fields.

NameTypeUse caseDescriptionRDO field
fieldstringRelativity Field Population (required)The unique name of the fieldContracts Internal Field
valuestringRelativity Field Population (required)The value of the fieldContracts Internal Field
locationsarrayRelativity Field Population (required)An array of locations for boundary boxes for the field Location

Location (Contracts internal)

The following table provides descriptions and use cases for Location fields.

NameTypeUse caseDescriptionRDO field
page numberintegerRelativity Field Population (required)The page number of the boundary box of the field in the document Contracts Internal Field
leftdecimalRelativity Field Population (required)The left coordinate of the bounding box as a ratio of the overall document page width Contracts Internal Field
topdecimalRelativity Field Population (required)The top coordinate of the bounding box as a ratio of the overall document page height Contracts Internal Field
heightdecimalRelativity Field Population (required)The height of the bounding box as a ratio of the overall document page height Contracts Internal Field
widthdecimal Relativity Field Population (required)The width of the bounding box as a ratio of the overall document page width Contracts Internal Field

Examples

Following are examples of API calls.

Annotation, segmentation, and classification

The following are example responses your API would return to support the use cases of annotations, segmentation, and classification.

Annotations

This example will save an Organization annotation on document 12345 with the text of “Acme & Sons Bank”. This annotation will be visible to users when viewing the document with the Contracts Viewer.

An image of an example API response.

Segmentation

This example will create two sections on document 12345. These sections will be visible to users when viewing the document with the Contracts Viewer.

An image of an example API response.

Classification

This example will classify document 12345 as a Loan Agreement and save that classification to the Contract Type Relativity field.

An image of an example API response.

Relativity field population

The following is an example response your API would return to support the Relativity Field Population use case.

This example identifies in document 12345 the fields Invoice ID and Invoice Amount which can be setup to map to a Relativity Object when running Contracts Analysis.

An image of an example API response.

 

Return to top of the page
Feedback