openapi: 3.0.1
info:
title: termscout-data
description: "TermScout API \n\nAll requests require both authentication and an API key.\n\nOath and\
\ Basic auth are supported.\n\nAll query params are `kebob-case`, all responses are `snake_case`"
version: '2022-07-19T16:30:18Z'
servers:
- url: https://api.termscout.com
paths:
/contract-positions:
get:
summary: Market data across contract positions
description: "Frequency counts based on TermScout's market data across contract positons. Without\
\ any query parameters, will return total contract counts for each contract position, defaulting\
\ to the IT template.\n\n To filter on a specific template or label, include a `template-id`,\
\ `label-id` and `selected`. Set `selected` to `1` for frequency counts where the given label\
\ is true. Set `selected` to `0` for frequency counts where the label is not true.\n\n To construct\
\ frequency percentages for a given label, first call the endpoint with no `label-id` to get the\
\ denominator. Then call the endpoint with `label-id` and `selected` included to get the numerator.\
\ Then you can divide the numerator by the denominator for each contract position returned."
parameters:
- name: template-id
in: query
description: ID of template to fetch counts for
required: true
schema:
type: string
- name: label-id
in: query
description: ID of label to fetch counts for
schema:
type: string
- name: selected
in: query
description: Set to `1` for counts where label is true, `0` for counts where label is false
schema:
type: string
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ContractPositions'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:contract-positions:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Origin: '''*'''
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts:
get:
summary: Customer contracts
description: List of contracts available to the authorized customer
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ContractList'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:contracts-list:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Origin: '''*'''
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
post:
summary: Upload a contract
description: "Endpoint to upload a contract. Currently supports .pdf, .docx and .txt. \n\nA base64\
\ encoded byte string for the document data is required as the POST body.\n\nTo upload multiple\
\ documents, POST with the primary document, retrieve the returned `contract-id` then repeat the\
\ same step for each new document, including the `contract_id` in the subsequent requests to associate\
\ multiple documents with the same contract.\n\nIf submitted without a `contract-id`, will create\
\ a new contract and return a new `contract-id` and a `document-id`. \n\nIf submitted with a `document-id`,\
\ will replace that document with the new document"
parameters:
- name: document-name
in: query
description: Name of submitted document
required: true
schema:
type: string
- name: template-id
in: query
description: ID of template
required: true
schema:
type: string
- name: defined-term
in: query
description: Defined term
schema:
type: string
- name: url
in: query
description: URL of hosted public contract
schema:
type: string
- name: contract-id
in: query
description: ID of contract. If supplied, will update existing contract with new document
schema:
type: string
- name: party-b-defined-term
in: query
description: Name of the party B entity (customer, receiver, investing entity)
schema:
type: string
- name: document-id
in: query
description: ID of document. Include if replacing document
schema:
type: string
- name: party-a-defined-term
in: query
description: Name of the party A entity (vendor, discloser, issuing entity)
schema:
type: string
- name: contract-position-id
in: query
description: 'Party that drafted the contract: Use ''1'' for vendor form and ''2'' for customer
form'
schema:
type: string
- name: review-level
in: query
description: 'Review level of the contract review: Use ''verified'' for human-in-the-loop and
''predicted'' for AI only'
schema:
type: string
- name: is-public
in: query
description: Use '1' for public contracts and '0' for private contracts
schema:
type: string
responses:
'200':
description: 200 response
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ContractUpload'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:contract-upload:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
responseParameters:
method.response.header.Access-Control-Allow-Origin: '''*'''
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/citations:
get:
summary: Citations and source language
description: "Citations and source language on a given contract. Without any query parameters, will\
\ return all citations for a given contract. \n\n To filter on a specific question or label, include\
\ *one* of either a `label-id` a `question-id`, or a `topic-id`"
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
- name: question-id
in: query
description: ID of question to fetch citation for
schema:
type: string
- name: label-id
in: query
description: ID of label to fetch citation for
schema:
type: string
- name: topic-id
in: query
description: ID of topic to fetch citation for
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/Citations'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:citations-sl:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/extracted-fields:
get:
summary: Key data points for a contract
description: Key data points for a contract
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractedFields'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:extracted-fields:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/overview:
get:
summary: General overview and metadata for a given contract
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/ContractOverview'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:overview:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/playbook-detail:
get:
summary: Playbook results
description: Fetch details of playbook results applied to the given contract
parameters:
- name: filter-id
in: query
description: ID of filter
schema:
type: string
- name: contract-id
in: path
description: Contract id
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/PlaybookDetail'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:playbook-detail:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/prediction-detail:
get:
summary: Predicted labels
description: Fetch predicted labels and associated details for the given contract by topic
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionDetail'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:prediction-detail:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/prediction-flags:
get:
summary: Predicted red flags
description: Fetch details of playbook results applied to the given contract
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionFlags'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:prediction-flags:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/prediction-summary:
get:
summary: Prediction summary
description: Fetch topic level summary of predicted labels
parameters:
- name: topic-id
in: query
description: ID of topic
required: true
schema:
type: string
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/PredictionSummary'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:prediction-summary:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
/contracts/{contract-id}/status:
get:
summary: Status of a contract
description: 'Status of a contract in our review pipeline. Will either be: `In Progress` or `Completed`'
parameters:
- name: contract-id
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/ContractStatus'
security:
- lambda-api-authorizer: []
- api_key: []
x-amazon-apigateway-integration:
uri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:contract-status:${stageVariables.lambdaAlias}/invocations
httpMethod: POST
responses:
default:
statusCode: '200'
passthroughBehavior: when_no_match
responseTransferMode: BUFFERED
contentHandling: CONVERT_TO_TEXT
type: aws_proxy
components:
schemas:
PredictionDetailLabel:
type: object
properties:
label_id:
type: number
description: ID of the label
label_display:
type: string
description: Display name of the label
confidence:
type: number
description: Prediction confidence
defined_term:
type: string
description: Defined term of the document where the prediction was found
citation:
type: string
description: Section identifier where the prediction was found
source_language:
type: string
description: Source language where the prediction was found
selected:
type: number
description: 'Whether or not the label was selected in the affirmative or not: 1 for selected
and 0 for unselected'
description: Details for a given predicted label
ContractList:
type: array
description: Item for ContractList, contains contract status and basic information
items:
type: object
properties:
contract_id:
type: string
description: ID of the ontract
status:
type: string
description: Status of the contract
template_id:
type: number
description: Template id of the contract
primary_agreement:
type: string
description: Primary agreement name of the contract
PredictionFlag:
type: object
properties:
label_id:
type: number
description: ID of the label
label_display:
type: string
description: Display name of the label
confidence:
type: number
description: Prediction confidence
defined_term:
type: string
description: Defined term of the document where the prediction was found
citation:
type: string
description: Section identifier where the prediction was found
source_language:
type: string
description: Source language where the prediction was found
selected:
type: number
description: 'Whether or not the label was selected in the affirmative or not: 1 for selected
and 0 for unselected'
description: Details for a given red flag
PredictionDetailTopic:
type: object
properties:
topic_id:
type: number
description: ID of the topic
topic_name:
type: string
description: Name of the topic
predictions:
type: array
items:
$ref: '#/components/schemas/PredictionDetailLabel'
description: Topic metadata and label predictions for the given topic
ContractStatus:
type: object
properties:
contract_id:
type: string
description: ID of given contract
status:
type: string
description: 'Status of given contract. Will be either: `In Progress` or `Completed`'
enum:
- In Progress
- Completed
- Failed
PredictionFlags:
type: object
properties:
contract_id:
type: string
description: ID of the contract
details:
type: array
items:
$ref: '#/components/schemas/PredictionFlagsDetail'
description: Predicted red flags for the given contract
ExtractedFields:
type: array
items:
$ref: '#/components/schemas/ExtractedField'
PredictionSummary:
type: object
properties:
contract_id:
type: string
description: ID of the contract
topic_id:
type: number
description: ID of the topic
summary:
type: string
description: Summary of predicted labels for the given topic
description: Summary of predicted labels for a given contract and topic
ContractPosition:
type: object
properties:
id:
type: number
description: ID of the given contract position
format: integer
name:
type: string
description: Name of the given contract position
quantity:
type: string
description: Number of contracts that meet that meet the criteria defined by the input query
parameters
description: Frequency count for the given contract position
ContractOverview:
type: object
properties:
party_a:
type: string
description: One of the parties in the contract
party_b:
type: string
description: The other party in the contract
template_id:
type: number
description: ID of the template this contract belongs to
template_name:
type: string
description: Name of the template this contract belongs to, e.g., 'IT' or 'Business Intelligence
Software'
parent_template_id:
type: number
description: ID of the parent template
is_public:
type: number
description: Visibility of contract. `1` if public, `0` if private
contract_position_id:
type: number
description: Contract position id of contract
rating_display:
type: string
description: User friendly display of contract rating
product_suite_id:
type: number
description: ID of product suite, or company, that contract belongs to
product_suite_name:
type: string
description: Name of product suite, or company, that contract belongs to
product_suite_url:
type: string
description: DEPRECATED
deprecated: true
max_score:
type: number
description: Max score
format: double
deprecated: true
overall_score:
type: number
description: Numeric representation of the overall score
format: double
deprecated: true
rating_percentile:
type: number
description: Number value of contract rating. On a scale of 0-10, 0 is Vendor Favorable, 5 is
Balanced and 10 is Customer Favorable
format: double
rating:
type: string
description: Display friendly rating of contract. Will be one of `Customer Favorable`, `Vendor
Favorable` or `Balanced`
raw_rating:
type: string
description: Raw rating number of contract
deprecated: true
primary_agreement:
type: string
description: Primary agreement name for the contract
primary_agreement_url:
type: string
description: Source URL for the contract, where it originated from online
format: uri
last_updated:
type: string
description: Date and time contract was last reviewed
format: datetime
overall_clarity:
type: string
description: Clarity of given contract
contract_position:
type: string
description: Position of contract
logo_url:
type: string
description: Location of image for contract or product suite
format: uri
badge_url:
type: string
description: Location of badge
format: uri
legal_entity:
type: string
description: Name of legal entity the contract belongs to
secondary_categories:
type: array
description: Secondary categories of contract
items:
type: string
primary_agreement_defined_term:
type: string
description: Primary agreement defined term, or short name of primary agreement
notes_to_customer:
type: string
description: Notes to customer
primary_category_id:
type: number
description: Category id of contract
category:
type: string
description: Display friendly category name
category_url:
type: string
description: DEPRECATED
deprecated: true
description: Contract overview and general metadata
PlaybookPassFailDetail:
type: object
properties:
selection:
type: string
description: 'Description of how the label should appear in the contract. Will be one of the
following: `required`, `acceptable` or `unacceptable`'
reason:
type: string
description: 'Reason why the label passed or failed. Will be one of the following: `required_and_found`,
`required_not_found`, `acceptable_and_found`, `acceptable_not_found`, `unacceptable_and_found`,
`unacceptable_not_found`'
is_fail:
type: number
description: Result if label passed or failed
label_id:
type: string
description: ID of the label
description: Detailed list of labels that passed or failed and why
PredictionFlagsDetail:
type: object
properties:
name:
type: string
description: Perspective name, eg. Customer, Vendor
flag_count:
type: number
description: Number of red flags identified for the given perspective
flags:
type: array
items:
$ref: '#/components/schemas/PredictionFlag'
description: List of perspectives containing red flag count and details
Empty:
title: Empty Schema
type: object
ContractPositions:
type: array
description: Frequency counts for all relevant contract positions
items:
$ref: '#/components/schemas/ContractPosition'
ContractUpload:
type: object
properties:
contract_id:
type: string
description: ID of newly created contract
document_id:
type: string
description: ID of document created
testUpload:
type: object
properties:
contract_id:
type: string
description: ID of newly created contract
document_id:
type: string
description: ID of document created
Citation:
title: Citation
type: object
properties:
citations:
type: string
description: Citation
source_langauge:
type: string
description: Source language of the citation
ExtractedField:
type: object
properties:
extracted_field_id:
type: number
description: ID of extracted field
format: integer
contract_id:
type: string
description: ID of given contract
extracted_field_measurement_id:
type: number
description: ID of measurement
format: integer
extracted_field_data_type_id:
type: number
description: ID of extracted field data type
format: integer
source_id:
type: number
description: ID of the source/citation that references the extracted field value
format: integer
value:
type: string
description: Value of the extracted field
extracted_field_name:
type: string
description: Name of the extracted field
measurement_name:
type: string
description: Name of the measurement type. Used for adding context to the value. Examples include
some common units of measurements for time and currencies, e.g., `USD` or `Days`
type_name:
type: string
description: Name of data type of the given value
source_language:
type: string
description: Source language of contract that references the extracted field value
citation:
type: string
description: 'Name of the citation in the contract that references the extracted field value '
description: Key data point extracted from the contract
Citations:
type: array
items:
$ref: '#/components/schemas/Citation'
PlaybookDetail:
type: object
properties:
tier:
type: number
description: Tier level of the question. Lower number tiers have a greater influence on score.
issue_number:
type: string
description: Numerical ordering of clauses, grouped by tiers
filter_question_id:
type: number
description: ID of the filter question
question_id:
type: number
description: ID of the question
display_name:
type: string
description: Display name of the filter question
answer_display:
type: string
description: Short answer if question was addressed in contract. Can be `Yes`, `No`, `N\A` or
`Null`
filter_passed:
type: boolean
description: Result if the contract passed the filter question
footnote:
type: string
description: Footnotes to the customer
rank:
type: number
description: Rank
citation:
type: string
description: Citation to the contract contract that refers to this question
selected_label_ids:
type: array
description: DEPRECATED
items:
type: number
deprecated: true
unselected_label_ids:
type: array
description: DEPRECATED
items:
type: number
deprecated: true
required_label_ids:
type: array
description: DEPRECATED
items:
type: number
deprecated: true
acceptable_label_ids:
type: array
description: DEPRECATED
items:
type: number
deprecated: true
unacceptable_label_ids:
type: array
description: DEPRECATED
items:
type: number
deprecated: true
details:
type: array
items:
$ref: '#/components/schemas/PlaybookPassFailDetail'
description: Detailed reasons why a playbook question failed
PredictionDetail:
type: object
properties:
contract_id:
type: string
description: ID of the contract
details:
type: array
items:
$ref: '#/components/schemas/PredictionDetailTopic'
description: Fetch predicted labels and associated details for the given contract by topic
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
lambda-api-authorizer:
type: apiKey
name: Authorization
in: header
x-amazon-apigateway-authtype: custom
x-amazon-apigateway-authorizer:
authorizerUri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:747513234329:function:api-authorizer/invocations
authorizerResultTtlInSeconds: 0
type: token
x-amazon-apigateway-documentation:
version: '22'
createdDate: '2023-03-27T17:24:54Z'
documentationParts:
- location:
type: API
properties:
info:
description: "TermScout API \n\nAll requests require both authentication and an API key.\n\nOath\
\ and Basic auth are supported.\n\nAll query params are `kebob-case`, all responses are `snake_case`"
- location:
type: METHOD
path: /certify/{certified-name}
method: GET
properties:
summary: Certified contracts
- location:
type: METHOD
path: /certify
method: GET
properties:
summary: List of certified contracts
- location:
type: METHOD
path: /contract-positions
method: GET
properties:
summary: Market data across contract positions
description: "Frequency counts based on TermScout's market data across contract positons. Without\
\ any query parameters, will return total contract counts for each contract position, defaulting\
\ to the IT templ
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/termscout/refs/heads/main/openapi/termscout-data-openapi.yml