Search

Submit Contract Request API

Overview

The Submit Contract Request via API feature allows you to create Contract Requests programmatically from your own enterprise systems, eliminating the need to manually enter information through the Pramata Platform for each submission.

This guide covers both Version 2 (current) and Version 1 (deprecated) of the API, and walks you through:

  • Submitting a contract request with required fields and optionally including attachments.
  • Adding custom fields to capture additional information.
  • Understanding differences between V1 and V2 to support migration.

With minimal setup, you can automate your contract workflow and seamlessly integrate contract requests into your existing business processes, saving valuable time and reducing manual data entry.

Version Comparison

Note: Version 2 is the current API version. Version 1 is deprecated and no longer supported. Existing Version 1 users should migrate to Version 2.

Feature Version 2 Version 1
Status Current Version Deprecated - no longer available
File Attachments Included directly in the request (up to 5 files) Requires a separate upload step before submitting the request
Submitter Identification Submitter email address is a required field and available in the request Submitter ID is defaulted to a common API user
Minimum Required Fields Contract Request Type and account name Contract Type, account name, needed-by date, priority, and description
Error Messages Detailed error messages that describe exactly what failed and how to fix it Basic error responses with limited detail

Prerequisites

To use this API, ensure you have the following:

  • Access to a Pramata instance (UAT or Production) with Legal Admin permission to retrieve the API names for form fields.
  • Submit Contract Request API enabled for your instance. If you're unsure whether this is enabled, reach out to your Customer Success Manager
  • Access to Pramata API Developer Portal (API client credentials are shared in the API portal). To get access, reach out to your Customer Success Manager.

Finding API Field Names on Pramata Platform

Before you can use custom fields in your API requests, you need to find their API field names:

  1. Login to your Pramata Platform as Legal Admin and navigate to Contract Requests > Settings > Request Forms tab.
  2. Locate your form: You'll see the Contract Request form (the Primary form) on this page. This form contains all the fields available for contract requests.
    Note: If you need to customize this form first, you can do so by dragging and dropping components. After customization, remember to click the Save Form button. To know more about the Form Components, refer here.
  3. Get API field names: For each field you want to include in your API requests:
    1. Hover on the field name and click the Edit icon to open the settings window.
    2. Select the API tab.
    3. Locate the Property Name value (this is your API field name)
    4. Copy and save this value for later use in your API requests
  4. Create a reference document: We recommend creating a simple spreadsheet or document that maps your form fields to their corresponding API Property Names for easy reference when building your API requests.
    Important: Each Property Name is automatically generated in camelCase format based on the field's label. These names must remain unique across the entire form. For example: If you have a field labeled "Contract Start Date", the API Property Name would be automatically generated as "contractStartDate".

submit CR API.gif

Version 2

Version 2 is the current, recommended version. It simplifies file attachment handling by accepting files inline as multipart form parameters.

Step 1: Creating a Contract Request with Required Fields

When creating any contract request, there are certain required fields that must always be included:

Required Fields

The following top-level parameters are always required:

Parameter Type Required Description
submitter_email_id string Yes Email address of the user submitting the request. Must be a valid user in the Pramata platform.
data JSON string Yes All contract request fields serialised as a JSON string. See field types below.

Required fields inside data

Field Required Example
contract_request_type Yes "NDA", "Service Agreement"
account Yes "Amazon.com Services"
Other fields (e.g. needed_by_date, priority, description) Varies Depends on your form configuration

Important: Required fields within data vary based on your form configuration in the Pramata Platform. Verify current requirements with your Legal Admin before implementing your integration.

Optional Fields

Up to 5 file attachments can be included using file1 through file5 as top-level multipart parameters. Do not include a file field inside data — file attachments are handled automatically by the API.

A file upload field must be configured in your Pramata form for attachments to be accepted. If files are provided but no file field is configured, the request will be rejected with a 422 error.

Supported Field Types in data

All fields within data must match the field definitions in your form configuration.

Field Type Example Value Notes
text "Test Request" Plain string
textArea "Test Request" or "{\"key\":\"value\"}" String or stringified JSON
select "Medium" Must match a configured option
selectBoxes {"option1": true, "option2": false} Key-value map of options
radio "abc" Must match a configured option
checkbox true Boolean
number 32 Numeric
currency 32 Numeric
email "test@pramata.com" Valid email format
phoneNumber "1234567890" String
dateTime "2026-03-03T00:00:00+05:30" ISO 8601 with timezone
date "2025-07-15" ISO 8601 date
account "Amazon.com Services" Account name string
file Use file1–file5 params Do not include in data — use top-level file params

Important: Field names and values are case-sensitive and must match your form configuration exactly. Fields not defined in your form will be rejected with a 422 error.

API Details

  • Method: POST
  • Content-Type: multipart/form-data
  • API Endpoint: https://[tenantname]-api-[env].pramata.com/services/data/v2/contract_requests
  • Production Example: https://demos-api.pramata.com/services/data/v2/contract_requests
  • UAT Example: https://demos-api-uat.pramata.com/services/data/v2/contract_requests

Examples 

Request (Required Fields Only)
POST https://demos-api-uat.pramata.com/services/data/v2/contract_requests
Content-Type: multipart/form-data

submitter_email_id: john.doe@acme.com
data: {"contract_request_type":"NDA","account":"Amazon.com Services",
      "needed_by_date":"2025-07-15","priority":"Medium","description":"Test Request"}
With File Attachments
POST https://demos-api-uat.pramata.com/services/data/v2/contract_requests
Content-Type: multipart/form-data

submitter_email_id: john.doe@acme.com
data: {"contract_request_type":"NDA","account":"Amazon.com Services",
      "needed_by_date":"2025-07-15","priority":"Medium","description":"Test Request"}
file1: <binary file content>
file2: <binary file content>
All Common Field Types
{
  "contract_request_type": "NDA",
  "account":               "Amazon.com Services",
  "needed_by_date":        "2025-07-15T00:00:00+00:00",
  "priority":              "Medium",
  "description":           "Test Request",
  "isRenewalAutomatic":    true,
  "expectedRevenue":       50000,
  "requestedBy":           "John Doe"
}

Responses

Success — 200 OK
{
  "data": {
    "contract_request_id": 10005,
    "is_auto_generated":   false
  }
}
Error Responses

All errors follow this envelope format:

{
  "errors": [{
    "status": "<http-status-code>",
    "title":  "<error title>",
    "detail": "<description of what went wrong>"
  }]
}

Tip: Always check the detail field — messages are descriptive and actionable, telling you exactly what to fix before retrying.

401 Unauthorized — submitter not found

Returned when submitter_email_id does not match any user in the Pramata platform.

{
  "errors": [{
    "status": "401",
    "title":  "Unauthorized",
    "detail": "User with email_id john.doe@acme.com is not valid or does not exist"
  }]
}
400 Bad Request — file too large

Returned when a file attachment exceeds the allowed size limit.

{
  "errors": [{
    "status": "400",
    "title":  "Bad Request",
    "detail": "Rejected large file, Filename - contract.pdf, Filesize - 50.1MB"
  }]
}
422 Unprocessable Entity — validation failure

Returned when validation fails. Common causes:

Missing top-level fields:

{
  "errors": [{
    "status": "422",
    "title":  "Unprocessable Entity",
    "detail": "Following fields are required: submitter_email_id, data"
  }]
}

Missing required fields in data:

{
  "errors": [{
    "status": "422",
    "title":  "Unprocessable Entity",
    "detail": "Following fields are required: contract_request_type, account"
  }]
}

Invalid field in data (not defined in form):

{
  "errors": [{
    "status": "422",
    "title":  "Unprocessable Entity",
    "detail": "Invalid field(s): priority23. These fields are not defined in the form definition."
  }]
}

Too many files:

{
  "errors": [{
    "status": "422",
    "title":  "Unprocessable Entity",
    "detail": "Too many files. Maximum allowed is 5 files."
  }]
}

File upload not supported in this form:

{
  "errors": [{
    "status": "422",
    "title":  "Unprocessable Entity",
    "detail": "No file upload field is configured in this form. Add a file field before uploading attachments."
  }]
}
502 Bad Gateway — upstream service error

Returned when an upstream service returns an unexpected error.

{
  "errors": [{
    "status": "502",
    "title":  "Bad Gateway",
    "detail": "Failed to connect to file upload service"
  }]
}
504 Gateway Timeout

Returned when a service does not respond in time.

{
  "errors": [{
    "status": "504",
    "title":  "Gateway Timeout",
    "detail": "File upload timed out"
  }]
}

 

Step 2: Adding Your Custom Fields

Now let's say you want to capture additional information beyond the required fields. For example, you might want to collect:

  • The other party's address
  • Expected contract value
  • Contract duration

Here's how you add custom fields to your request:

Example Request (Required Fields + Custom Fields)

{
"data": {
"contract_request_type": "New",
"account": "Sample Company",
"needed_by_date": "2025-08-01",
"priority": "Medium",
"description": "Contract request for new service agreement",
"requested_by": "John Doe",
"WhatIsTheAddressOfTheParty": "123 Main Street",
"expectedRevenue": 50000,
"contractTerm": 12,
"isRenewalAutomatic": true
}}

Note: The custom field names (like whatIsTheAddressOfTheOtherParty, expectedRevenue, etc.) must match the API Property Names you found in the Finding API Field Names section.

Version 1

IMPORTANT: Version 1 of the Submit Contract Request API is no longer supported. Please migrate to Version 2. Existing Version 1 users should refer to the Version Comparison table above and the Version 2 section for migration guidance.

Step 1: Creating a Basic Contract Request with Required Fields

When creating any contract request, there are certain required fields that must always be included:

Required Fields

The following fields are typically required for most contract requests:

  • contract_request_type - The type of contract (e.g., "NDA", "Service Agreement", "New")
  • account - The company/account name
  • needed_by_date- When the contract is needed (date format)
  • priority - Priority level (e.g., "Low", "Medium", "High")
  • description - Brief description of the request

Important Note: Required fields may vary based on your form configuration in the Pramata Platform. Verify current requirements with your Legal Admin before implementing your API integration.

API Details

Example Request (Required Fields Only)

{
"data": {
"contract_request_type": "NDA",
"account": "Amazon.com Services ",
"needed_by_date": "2025-07-15",
"priority": "Medium",
"description": "Test Request2",
}
}

API Response

{
"data": {
"contract_request_id": 10005,
"is_auto_generated": false
}
}

 

Step 2: Adding Your Custom Fields

Now let's say you want to capture additional information beyond the required fields. For example, you might want to collect:

  • The other party's address
  • Expected contract value
  • Contract duration

Here's how you add custom fields to your request:

Example Request (Required Fields + Custom Fields)

{
"data": {
"contract_request_type": "New",
"account": "Sample Company",
"needed_by_date": "2025-08-01",
"priority": "Medium",
"description": "Contract request for new service agreement",
"requested_by": "John Doe",
"WhatIsTheAddressOfTheParty": "123 Main Street",
"expectedRevenue": 50000,
"contractTerm": 12,
"isRenewalAutomatic": true
}

Note: The custom field names (like whatIsTheAddressOfTheOtherParty, expectedRevenue, etc.) must match the API Property Names you found in the Finding API Field Names section.

 

Step 3: Working with Attachments

Finally, let's say you want to include supporting documents with your contract request (such as a draft contract, specifications, or reference materials). Here's how you handle attachments:

Step 3a: First, Upload Your Attachment

API Details

Attachment Upload Response

{
"key": "contract_request_uploads_tmp/1748494066-file-example.pdf",
"originalName": "file-sample_150kB.pdf"
}

 

Step 3b: Include Attachment Information in Your Contract Request

Use the response from the upload to reference the attachment in your contract request:

Example Request (With Attachment)

{
    "data": {
        "contract_request_type": "New",
        "account": "Sample Company",
        "needed_by_date": "2025-09-15",
        "priority": "Medium",
        "description": "Contract request for new service agreement",
        "requested_by": "John Doe",
        "WhatIsTheAddressOfTheParty": "123 Main Street",
        "expectedRevenue": 50000,
        "contractTerm": 12,
        "isRenewalAutomatic": true,
        "file": [
            {
                "storage": "url",
                "data": {
                    "key": "contract_request_uploads_tmp/1748494066-file-example.pdf",
                    "originalName": "file-sample_150kB.pdf"
                }
            }
        ]
     }
 }

 

Complete Example with All Components

Here's a complete example showing a contract request with required fields, custom fields, and attachments:

{
"data": {
"contract_request_type": "Service Agreement",
"account": "Global Tech Solutions LLC",
"needed_by_date": "2025-12-01",
"priority": "High",
"description": "Multi-year service agreement for cloud infrastructure support",
"requested_by": "John Smith",
"whatIsTheAddressOfTheOtherParty": "456 Technology Boulevard, Austin, TX 78701",
"expectedRevenue": 150000,
"contractTerm": 24,
"isRenewalAutomatic": false,
"specialRequirements": "Must include SLA guarantees and data security clauses",
"file": [
{
"storage": "url",
"data": {
"key": "contract_request_uploads_tmp/1748494066-requirements-doc.pdf",
"originalName": "technical-requirements.pdf"
}
},
{
"storage": "url",
"data": {
"key": "contract_request_uploads_tmp/1748494067-sla-template.pdf",
"originalName": "sla-template.pdf"
}
}
]
}
}