Skip to main content

Finalize API Sample Use Cases

  • Updated

Overview

The sections below outline sample use cases of the LinkSquares Finalize API and demonstrate how you can leverage the available Finalize API endpoints to achieve the desired functionality. Where applicable, sample request and/or response body code is provided. 

Note: This is not an exhaustive list of use cases or workflows. 

To learn more about the Finalize API, reference our article on Finalize API Technical Overview. 

Process

Creating Agreements and Request Forms

To create Finalize agreements, you must retrieve the Finalize template information and submit the necessary data values to create an agreement from that template. 

Finding the Relevant Template

Find the template you want to leverage to draft an agreement. 

  • Endpoint Reference: GET /finalize/v2/templates
  • Collection Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/templates
  • Retrieve a list of all available templates and record the ID of the template you would like to use to create the agreement.
  • Optionally, enter parameters to filter the pages that are shown and how many templates per page. 
    • Page integer: Enter an integer to return a specific page of templates. 
    • Per_page: Enter an integer to return the amount of templates returned per page.  
  • Optionally, filter templates by a specific attribute.
    • Created before: Returns only templates created before the specified date. The date must be in ISO8601 format.
      • GET /finalize/v2/templates/?filter[[created_at][before]=2022-08-01T15:00:00
    • Created after: Returns only templates created after the specified date. The date must be in ISO8601 format.
      • GET /finalize/v2/templates/?filter[[created_at][after]=2022-08-01T15:00:00
    • Name: Returns only templates with the specified name attribute. This can query template names with partial matches.
      • GET /finalize/v2/templates/?filter[name]={name}
    • Type: Returns only templates of the specified type (kind) attribute (intake, draft, or request_form). 
      • GET /finalize/v2/templates/?filter[kind]={kind}

Note:

  • The Finalize API does not support Signature-only templates.
  • Only Published templates will be returned
  • Templates with tables, sign-only templates, or templates with conditional (nested) questions are not supported

 

Request Body

curl
-X 'GET' \ 
'https://api.linksquares.com/api/finalize/v2/templatesfilter[kind][]=intake' \
-H 'accept: application/json'

Response 

{
    "data": [
        {
            "id": "99fd96ed-2c61-4066-b800-c34850146ea9",
            "name": "Security Addendum",
            "description": "Security terms for vendors",
            "kind": "draft",
            "created_at": "2023-08-24T18:09:30.768Z",
            "updated_at": "2023-08-24T18:09:30.768Z"
        }
    ],
    "total_count": 1,
    "_links": {
        "next": {
            "href": "https://api.linksquares.com/api/finalize/v2/templates?page=3&per_page=1"
        },
        "prev": {
            "href": "https://api.linksquares.com/api/finalize/v2/templates?page=1&per_page=1"
        }
    }
}

Retrieving Template Information

Get detailed information about the selected template.

  • Endpoint Reference: GET /finalize/v2/templates/{template_id}
  • Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/templates/{template_id}
  • Pass in the ?include=embedded query parameter to get details about the template such as agreement detail field and token information. 
    • https://api.linksquares.com/api/finalize/v2/templates/{template_id}?include=embedded
  • If the template contains file-type agreement detail fields, the response will contain question IDs for each file-type agreement detail field and attachment IDs for any associated file(s). Every question with a file attachment will have a unique question ID and attachment ID(s). 
    • To download and preview a file associated with an agreement detail field, call the following endpoint: GET /finalize/v2/templates/{template_id}/questions/{question_id}/attachments/{attachment_id}/file

Request Body

curl
-X 'GET' \ 
'https://api.linksquares.com/api/finalize/v2/templates/{template_id}?include=embedded' \
-H 'accept: application/json'

Response 

{
    "data": {
        "id": "99fd96ed-2c61-4066-b800-c34850146ea9",
        "name": "Security Addendum",
        "description": "Security terms for vendors",
        "kind": "draft",
        "instructions": "sample text",
        "created_at": "2023-08-24T18:18:00.345Z",
        "updated_at": "2023-08-24T18:18:00.345Z",
        "token_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
        "question_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
    },
    "_embedded": {
        "tokens": [{
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "kind": "single_selection",
            "question": "What is Single Choice Token?",
            "required": true,
            "clause_category_id": "string",
            "clause_category_name": "string",
            "options": [{
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "value": "string"
            }]
        }],
        "questions": [{
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "description": "What is Token One?",
            "required": true,
            "answer_type": "single_selection",
            "answer_options": [{
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "description": "Yes"
            }{
                “id”: “ca1fa90e-a22c-4df4-b488-0d9d1680de31",
                “description”: “Add additional document”,
                “required”: true,
                “answer_type”: “file”,
                “attachment_ids”: []
            }]
        }]
    }
}

Creating the Agreement

There are two workflows for creating an agreement. 

  • Creating a Request Form or Draft (Our Paper) Agreement
  • Creating an Agreement With an Intake Workflow (3rd Party Paper)

Creating a Request Form or Draft (Our Paper) Agreement

Step 1: Creating the Agreement 

  • Endpoint Reference: POST /finalize/v2/agreements
  • Full Endpoint URL: POST https://api.linksquares.com/api/finalize/v2/agreements
  • Set the template type to “Draft” or “Request” based on whether you are creating a Request form or drafting an agreement directly.
  • If the template contains file-type agreement detail fields, you must include the name of the file(s) that you intend to upload within the request body. 
  • If this process is successful, the response body returns the created agreement object.

Request Body 

curl
-X 'POST' \  'https://api.linksquares.com/api/finalize/v2/agreements' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "data": {
        "name": "LinkSquares Contract",
        "kind": "draft",
        "template_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agreement_file": {
            "name": "LinkSquares_NDA.docx"
        },
        "tokens": [{
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "value": "Token 1 value"
        },
        {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "selected": [{
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            }]
        }],
        "answers": [{
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "value": "Answer to question one"
        },
        {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "selected": [{
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            }]
        }]
    }
}'

Response 

{
    "data": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "LinkSquares Contract",
        "created_at": "2023-08-24T18:43:42.446Z",
        "status_updated_at": "2023-08-24T18:43:42.446Z",
        "kind": "draft",
        "template_id": "a25771d9-f44b-4284-82a7-a9e822ae6c18",
        "author_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "owner_id": "b25771d9-f44b-4284-82a7-a9e822ae6c18",
        "collaborator_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
        "status_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "question_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
        "token_value_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
    },
    "_links": {
        "agreement_file_upload": {
            "href": "https://s3.amazonaws.com/linksquares-finalize-bucket/store/agreementversion/d0441f5b-3f7a-43de-84ef-37758b9929dd/file/ffd9b8871fb6250a4a98a53011e17527/basic_agreement.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<Amz-Credential-Value>&X-Amz-Date=20230402T134848Z&X-Amz-Expires=900&X-Amz-Security-Token=<Amz-Security-Token-Value>&X-Amz-SignedHeaders=host&X-Amz-Signature=<Amz-Signature-Value>",
            "operation": "put",
            "file": "basic_agreement.docx"
        },
        "agreement_uploads_complete": {
            "href": "https://api.linksquares.com/api/finalize/v2/agreements/eb05deb4-05c5-45d0-ae74-9ec2f3e2ad86",
            "operation": "patch",
            "body": {
                "data": {
                    "upload_complete": true
                }
            }
        }
    }
}

Step 2: Uploading the Agreement to the Presigned URL

  • Endpoint Reference: PUT agreement_file_upload and PUT answer_file_uploads
  • If you have provided file data within the request body, the response body will return the presigned URL to which the agreement file should be uploaded (agreement_file_upload) and the presigned URL(s) to which the file(s) for file-type agreement detail fields should be uploaded (answer_file_uploads). 
  • If there are multiple presigned URLs for file-type agreement detail fields, make a separate PUT request to each URL with the file you intend to upload in response to the respective agreement detail field. 

Step 3: Completing the Agreement 

  • Endpoint Reference: PATCH agreement_uploads_complete
  • Once the agreement has been created, you can call the following endpoint to download a file that was uploaded in response to file-type agreement detail fields. 
    • GET /finalize/v2/agreements/{agreement_id}/answers/{answer_id}/attachments/{attachment_id}/file 

Creating an Agreement With an Intake (3rd Party Paper) Workflow

Step 1: Creating the Agreement 

  • Endpoint Reference: POST /finalize/v2/agreements
  • Full Endpoint URL: POST https://api.linksquares.com/api/finalize/v2/agreements
  • You must pass the name of the agreement file within the request body.
  • If the template used to create the agreement contains file-type agreement detail fields, you must include the name of the file(s) that you intend to upload in response to the agreement detail fields within the request body.
  • If this process is successful, the response body returns the created agreement object.

Request Body 

{
    “data”: {
        “name”: “LinkSquares NDA”,
        “kind”: “intake”,
        “template_id”: “45629028-d4b5-4f77-ae85-efaab84330f6”,
        “agreement_file”: {
            “name”: “Master Vendor_Agreement_2023.pdf”
        },
        “answers”: [{
            “id”: “ae218e16-2a31-4c41-9883-3d88dafdcf94”,
            “value”: “answer”
        },
        {
            “id”: “d91c99a6-4e23-433f-b43f-e4fa8294ba4d”,
            “value”: “answer”
        },
        {
            “id”: “f5c47e8d-598d-439b-be4e-5f0cb59b481b”,
            “value”: “answer”
        },
        {
            “id”: “fe0f533a-b6f3-487f-b544-ff10b2bc2508”,
            “value”: “answer”
        },
        {
            “id”: “d3852ca9-9209-4c30-ab69-3303cf3b15e9”,
            “value”: “email@email.com”
        },
        {
            “id”: “a076a552-1d4e-4f1c-9463-6244410fdf93”,
            “value”: “215-555-1212”
        },
        {
            “id”: “0ea0c9ed-986c-4d0d-963f-b64f1ff0ad29”,
            “selected”: [{
                “id”: “d789a22a-c3f8-4666-a25f-571da11a7535"
            }]
        },
        {
            “id”: “42e40b98-d279-47ca-86fa-e4186b6ee9af”,
            “files”: [{
                “name”: “Sample Purchase Order.pdf”
            }]
        },
        {
            “id”: “e43e2f51-700a-4912-aecd-3eef6923d051”,
            “files”: [{
                “name”: “LinkSquares SoW”
            }]
        }]
    }
}

Response 

{
    “data”: {
        “id”: “33c2810a-2fc6-4657-b02a-9f577e42b062”,
        “name”: “LinkSquares NDA”,
        “kind”: “intake”,
        “created_at”: “2023-09-29T17:41:45Z”,
        “status_updated_at”: null,
        “author_id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67",
        “owner_id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67",
        “template_id”: “45629028-d4b5-4f77-ae85-efaab84330f6",
        “collaborator_ids”: [],
        “question_ids”: [“0d2af03d-e433-4100-ab5a-3e2aa1429e85”,
        “bda97b91-6d1a-439c-bb35-340430057150",
        “faa46f5d-4123-485c-a43a-286ba7e98628”,
        “85e1e77a-86c3-4b33-b687-e77bdca5c300",
        “c81cce88-82af-488c-99cd-b76e3af9032a”,
        “1316b145-f01b-41b4-aa6c-9272220b9a7b”,
        “f4e200b3-d954-49d4-9f56-1cdbb83054e6”,
        “bd2336df-11ce-421f-a1bb-062192189036",
        “e9ae642c-ee21-4c0f-b3ab-b2471f39bf45”,
        “8d209241-3406-4bf2-b925-38a8badb4c4b”,
        “514c3c85-3f0d-4cfe-81eb-fe921b90d21b”],
        “status_id”: null,
        “token_value_ids”: []
    },
    “_links”: {
        “agreement_file_upload”: {
            “href”: “https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/agreement_upload/23c2419a-2fc6-4857-b02a-9p578e42b082/agreement_file/Master%20Vendor_Agreement_2023.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2r427BSYYX2K7%2F20230929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230929T174145Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJGMEQCIHvzIz%2BpiSebyqMqcgOmrgpnCz6gOHgGFuiw85cXp7YpAiARdljFWNpNIgHYOO0ftlgfbyRbhQjQA3jbbUkztWPQQiruAwjB%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAYaeDA5NTY4NjA5MjQ3OCIMawK9B4Uca6O5j4gSKsIDtyoYNymnqLWyBSuYXT993y3tho8g2pfiiu6z%2BJ6tMxiPqRzhBi%2FuyOUzvLvcpX8IxqMSV8qyC6bibwwOi%2BhwcAussJfgRtxJzuHi0wFKqy9UhiVfAuNBhWLb23Yu6Hp2oA1D65GIhT4Ovck2dOq%2B7YaDxJh1M8UCiOubWKRGvjCovnkL6%2B%2BS3Qj5tE3EJ%2BG04KaGJok2uL89bEpdnlgP6MPw5r89gHkno%2F%2FI995DgBv90dUCbfHn9l5ohBYIjIqF%2B604Fw037bR1dG%2B9i2O6uUYllhkjq2Gl5uqR69ep4idHcWCM1fryk4k2tV%2FUt4HmI26VfYgmk7ySgu1HaBylJEn1Xk9frX%2F5LX%2FGHCtyO4Wqe5KBm%2F%2BFIn5Xa7wswtVA5yrmVld%2Fxn7kfy1dG0TLdk%2FdKbK%2BvIAa8Mg6Aq%2FLKNuVF6PJMjranKBRW3aS8ypCbtwpxZgDMXLTKtg3UMIsYpykoi%2B71TIdphGOF%2Fo5SBRvDj3yWkKFOX7oIDxM21AneMLNQ3C06H4bd9MAm9QZFWTuVPDA4udidGr%2Bblobub%2BQ27o3Pxtqva9bVtniy%2BP2ozKXaz%2FmwmRfgYiX%2BPO%2Fu2bOMOXn26gGOqYBXMjIv6JbWngxfHLhKT1uHHb7z1nQDIM7xxIiXsaLlR3Ytb8LAbfBQqgNqM%2B5xFOi07zxSurP1i9QcHxfzhy%2B6SZ%2BoDQqs2dSo%2BEHJBy6INReWQFbtebD2w3%2FN89B4CpODpHqcprI3KuTC1WQdkIySBHmCVnCwULVgRG1kov%2BjGL8l1BJuJaR%2FyAuOVb32%2FSUWKMWotvw%2BNndODo2H1X%2BD%2FAVi2NIoA%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=4c19be124cda0bd2048d30896e4e7e4e96623bd94fe6c5ec88b8cfe7efc13906”,
            “operation”: “put”,
            “file”: “Master Vendor_Agreement_2023.pdf”
        },
        “answer_file_uploads”: [{
            “href”: “https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/agreement_upload/agreements/33c2813a-2fc6-4667-b02a-9p578e42q062/answers/42e40b98-d279-47ca-86fa-e4186b6ee9af/0/Sample%20Purchase%20Order.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2V427BSYYX2K7%2F20230929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230929T174145Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJGMEQCIHwzIz%2BpiSebyqMqcgOmrgpnCz6gOHgGFuiw85cXp7YpAiARdljFWNpNIgHYOO0ftlgfbyRbhQjQA3jbbUkztWPQQiruAwjB%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAYaDDA5NTY4NjA5MjQ3vCIMawK9B4Uca6O5j4gSKsIDtyoYNymnqLWyBSuYXT993y3tho8g2pfiiu6z%2BJ6tMxiPqRzhBi%2FuyOUzvLvcpX8IxqMSV9qyC6bnbwwOi%2BhwcAussJfgRtxJzuHi0wFKqy9UhiVfAuNBhWLb23Yu6Hp2oA1D65GIhT4Ovck2dOq%2B7YaDxJh1M8UCiOubWKRGvjCovnkL6%2B%2BS3Qj5tE3EJ%2BG04KaGJok2uL89bEpdnlgP6MPw5r89gHkno%2F%2FI995DgBv90dUCbfHn9l5ohBYIjIqF%2B604Fw037bR1dG%2B9i2O6uUYllhkjq2Gl5uqR69ep4idHcWCM1fryk4k2tV%2FUt4HmI26VfYgmk7ySgu1HaBylJEn1Xk9frX%2F5LX%2FGHCtyO4Wqe5KBm%2F%2BFIn5Xa7wswtVA5yrmVld%2Fxw7kfy1dG0TLdk%2FdKbK%2BvIAa8Mg6Aq%2FLKNuVF6PJMjranKBRW3aS8ypCbtwpxZgDMXLTKtg3UMIsYpykSi%2B71TIdphGOF%2Fo5fBRvDj3yWkKFOX5oIDxM21AneMLNQ3C06H4bd9MAm9QZFWTuVPDA4udidGr%2Bblobub%2BQ27o3Pxtqua9bVtniy%2BP2ozKXaz%2FmwmRfgYiX%2BPO%2Fu2bOMOXn26gGOqYBXMjIv6JbWngxfHLhKT1uHHb7z1nQDIM7xxIiXsaLlRVYtb8LAbfBQqgNqM%2B5xFOi07zxSurP1i9QcHxfzhy%2B6SZ%2BoDQFs2dSo%2BEHJBy6INReWQjbtebD0w3%2FN89B4CpODpHqcprI3KuTC1WQdkIySBHTCVnCwULVgRG1kov%2BjGL8l1BJuJaR%2FyAuOVb32%2FSaWKMWotvw%2BNndODo2H9X%2BD%2FAVi2NIoA%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=8009328c91a38cf2adbad9aa446af03f768a70b151a3f7ff51a470448211e1c5”,
            “operation”: “put”,
            “file”: “Sample Purchase Order.pdf”
        },
        {
            “href”: “https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/agreement_upload/agreements/33c2819a-2fc6-4657-b92a-9f178e42bh62/answers/e43e2f51-700a-4912-aecd-3eef6923d051/0/3rd%20Party%20NDA_NatGeo_NDA.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2V427BSYYX2K7%2F20230929%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230929T174145Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMj%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJGMEQCIHvzIz%2BpiSebyqMqcgOmrgpnCz6gOHgGFuiw85cXp7YpAiARdljFWNpNIgHYOO0ftlgfbyRbhQjQA3jbbUkztWPQQiruAwjB%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAYaDDA5NTY4NjA5MjQ3OCIMawK9B4Uca6O5j4gSKsIDpyoYNymnqLWyBSuYXT993y3tho8g2pfiiu6z%2BJ6tMxiPqRzhBi%2FuyOUzvLvcpX8IxqMSV8qyC6bnbwwOi%2BhwcAussJfgRtxJzuHi0wFKqy9UhiVfAuNBhWLb23Yu6Hp2oA1D65GIhT4Ovck2dOq%2B7YaDxJh1M8UCiOubWKRGvjCovnkL6%2B%2BS3Qj5tE3EJ%2BG04KaGJok2uL89bEpdnlgP6MPw5r89gHkno%2F%2FI995DgBv90dUCbfHntl5ohBYIjIqF%2B604Fw037bR1dG%2B9i2O6uUYllhkjq2Gl5uqR69ep4idHcWCM1fryk4k2tV%2FUt4HmI26VfYgmk7ySgu1HaBylJEn1Xk9frX%2F5LX%2FGHCtyO4Wqe5KBm%2F%2BFIn5Xa7wswtVA5yrmVld%2Fxn7efy1dG0TLdk%2FdKbK%2BvIAa8Mg6Aq%2FLKNuVF6PJMjranKBRW3aS8ypCbtwpxZgDMXLTKtg3UMIsYpykSi%2B71TIdphGOF%2Fo5SBRvDj3yWkKFOX5oIDxM21AneMLNQ3C06H9bd9MAm9QZFWTuVPDA4udidGr%2Bblobub%2BQ27o3Pxtqva9bVtniy%2BP2ozKXaz%2FmwmRfgYiX%2BPO22Fu2bOMOXn26gGOqYBXMjIv6JbWngxfHLhKT1uHHb7z1nQDIM7xxIiXsaLlRVYtb8LAbfBQqpNqM%2B5xFOi07zxSurP1i9QcHxfzhy%2B6SZ%2BoDQFs2dSo%2BEHJBy6INReWQFbtebD2w3%2FN89B4CpODpHqcprI3KuTC1WQdkIySBHTCwnCwULVgRG1kovh2BjGL8l1BJuJaR%2FyAuOVb32%2FSUWKMWotvw%2BNndODo2H9X%2BD%2FAVi2NIoA%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=4f1783b4dcb80de97f00ed497b6b43f670d66c0dcb313792231099a475ccb6e9”,
            “operation”: “put”,
            “file”: “LinkSquares NDA”
        }],
        “agreement_uploads_complete”: {
            “href”: “https://api.linksquares.com/api/finalize/v2/agreements/32c2819a-2fc6-4657-b02w-9f578e42p062”,
            “operation”: “patch”,
            “body”: {
                “data”: {
                    “upload_complete”: true
                }
            }
        }
    }
}

Step 2: Uploading the Agreement to the Presigned URL

  • Endpoint Reference: PUT agreement_file_upload and PUT answer_file_uploads
  • If you have provided file data within the request body, the response body will return the presigned URL to which the agreement file should be uploaded (agreement_file_upload) and the presigned URL(s) to which the file(s) for file-type agreement detail fields should be uploaded (answer_file_uploads). 
  • If there are multiple presigned URLs for file-type agreement detail fields, make a separate PUT request to each URL with the file you intend to upload in response to the respective agreement detail field. 

Step 3: Completing the Agreement 

  • Endpoint Reference: PATCH agreement_uploads_complete
  • Once the agreement has been created, you can call the following endpoint to download a file that was uploaded in response to file-type agreement detail fields. 
    • GET /finalize/v2/agreements/{agreement_id}/answers/{answer_id}/attachments/{attachment_id}/file 

Note: If the second and third steps of this process are not completed while the presigned URL(s) is valid, the agreement will be abandoned and the creation of the agreement cannot be resumed. All abandoned agreements are deleted.

Retrieving Agreements 

Retrieving All Agreements 

Users can retrieve a list of all agreements within their LinkSquares instance. 

  • Endpoint Reference: GET /finalize/v2/agreements
  • Collection Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/agreements
  • Single Resource Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/agreements
  • Optionally, include any of the following query parameters in the request to filter the agreements.
    • Name: Returns only agreements with the specified name attribute. 
      • GET /api/finalize/v2/agreements/?filter[name]={name}
    • Status ID: Returns the status of the agreement.
      • GET /api/finalize/v2/agreements/?filter[status]={status}
    • Template ID: Filter agreements by a specific template ID.
      • GET /api/finalize/v2/agreements?filter[template_id][]={template_id}
    • Created at: Returns only agreements created before or after the specified date. Must be in ISO8601 format.
      • GET /api/finalize/v2/agreements?filter[[created_at][before]=2022-08-01T15:00:00
    • Status updated at: Returns only agreements with a status updated before or after the specified date. Must be in ISO8601 format.
      • GET /api/finalize/v2/agreements?filter[status_updated_at][after]=2023-08-23T15:00:00

Retrieving a Single Agreement

Using a specific agreement ID, users can retrieve information about that agreement. 

  • Endpoint Reference: GET /finalize/v2/agreements/{agreement_id}?include=embedded 
  • Collection Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}?include=embedded
  • By including the ?include=embedded query parameter, metadata about the agreement including the agreement owner, collaborators, and information about agreement detail fields and tokens will be returned. 
  • For single- and multiple-selection agreement detail fields, a unique selected_option_id that represents the response to the agreement detail field will be returned within the response code. These IDs are unique for every agreement even if the agreement detail field response selections are the same. 

Response Body 

{
    “data”: {
        “id”: “117d57c8-5531-4414-b3ef-5b7a76419274”,
        “name”: “Company MSA”,
        “kind”: “draft”,
        “analyze_agreement_id”: null,
        “created_at”: “2023-10-20T14:06:08Z”,
        “status_updated_at”: “2023-10-20T14:06:10Z”,
        “author_id”: “381af44c-6a0d-11ee-86b0-53bd688d8c0f”,
        “owner_id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67",
        “template_id”: “209a3437-3970-4f87-bc68-9db110712986",
        “collaborator_ids”: [“381af44c-6a0d-11ee-86b0-53bd688d8c0f”,
        “1d2bdffe-0152-11ed-914b-9f74296d0e67”],
        “question_ids”: [“2d90f0a9-2619-46da-80f9-3a5849fd721b”,
        “29722524-95e6-49cc-9854-6a8ff55aa76b”,
        “a5b27146-bc93-47ea-a495-76b00f276c8b”,
        “1d66c584-0bab-46e8-b387-2b38283bd792",
        “8f5438ae-330e-4402-86bb-6b77fc1a645f”],
        “status_id”: “2cc53ea5-c591-4099-9e2f-6a3ff1fac7a4”,
        “token_value_ids”: [“dab66fd4-71d2-4a9a-9572-1eb719f73bb3”,
        “c529359c-c3ae-4c34-9bf8-d39b51177742",
        “fd66a4a9-bdde-4a34-b5d5-659252a8b15a”,
        “db7ff1e1-b084-45e7-919a-8389c808c0bf”,
        “6f9186c1-0eca-48b4-95a4-8dd0994db9ce”]
    },
    “pen”: {
        “assigned_to_counterparty”: false,
        “holder_ids”: [“1d2bdffe-0152-11ed-914b-9f74296d0e67"]
    }    “_embedded”: {
        “users”: [{
            “id”: “381af44c-6a0d-11ee-86b0-53bd688d8c0f”,
            “first_name”: “name”,
            “last_name”: “name”,
            “email”: “email@email.com”
        },
        {
            “id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67”,
            “first_name”: “name”,
            “last_name”: “name”,
            “email”: “email@email.com”
        }],
        “questions”: [{
            “id”: “2d90f0a9-2619-46da-80f9-3a5849fd721b”,
            “answer_type”: “text”,
            “description”: “Please provide the agreement name”,
            “required”: true,
            “answer”: null
        },
        {
            “id”: “29722524-95e6-49cc-9854-6a8ff55aa76b”,
            “answer_type”: “text”,
            “description”: “Please enter counterparty email address”,
            “required”: false,
            “answer”: {
                “id”: “556d27f9-f0f3-4dc1-9be9-54d99e2d0ebf”,
                “value”: “email@email.com”
            }
        },
        {
            “id”: “a5b27146-bc93-47ea-a495-76b00f276c8b”,
            “answer_type”: “single_selection”,
            “description”: “Have the parties executed an NDA?“,
            “required”: true,
            “answer”: {
                “id”: “c0df9f24-eed0-435b-be3d-82371cfcba1e”,
                “selected_option_ids”: [“50d006c3-fc29-4cf7-ac46-60cbc238f03f”]
            },
            “options”: [{
                “id”: “50d006c3-fc29-4cf7-ac46-60cbc238f03f”,
                “description”: “Yes”
            },
            {
                “id”: “6566dabe-1fcd-4bf2-9789-7a0c06a77f0d”,
                “description”: “No”
            }]
        },
        {
            “id”: “1d66c584-0bab-46e8-b387-2b38283bd792”,
            “answer_type”: “text”,
            “description”: “Requestor Email”,
            “required”: true,
            “answer”: {
                “id”: “cf9cb97d-c3bf-414e-8b4f-0cc9cb28e692”,
                “value”: “email@email.com”
            }
        },
        {
            “id”: “8f5438ae-330e-4402-86bb-6b77fc1a645f”,
            “answer_type”: “file”,
            “description”: “Add Invoice or Purchase Order”,
            “required”: false,
            “attachment_ids”: [],
            “answer”: null
        }],
        “statuses”: [{
            “id”: “2cc53ea5-c591-4099-9e2f-6a3ff1fac7a4”,
            “name”: “Internal Review”,
            “description”: “This is where an agreement starts when an agreement is directly drafted from a third-party paper template,
            an our-paper template,
            or agreement is sent to Finalize.“,
            “internal_enum”: “internal_review”
        }],
        “token_values”: [{
            “id”: “dab66fd4-71d2-4a9a-9572-1eb719f73bb3”,
            “token_id”: “d5f8c9b5-1f01-42e4-b185-46ec23e2ccfc”,
            “value”: “September 20,
            2023”
        },
        {
            “id”: “c529359c-c3ae-4c34-9bf8-d39b51177742”,
            “token_id”: “04c62f21-52cc-4a76-9075-687c40729ba4”,
            “value”: “company”
        },
        {
            “id”: “fd66a4a9-bdde-4a34-b5d5-659252a8b15a”,
            “token_id”: “9a3df681-3ad8-4d9e-a7f6-15fd078e6eb9”,
            “value”: “NY”
        },
        {
            “id”: “db7ff1e1-b084-45e7-919a-8389c808c0bf”,
            “token_id”: “c48f14ab-85a9-465d-925f-bb1b2f2ff42f”,
            “value”: “address”
        },
        {
            “id”: “6f9186c1-0eca-48b4-95a4-8dd0994db9ce”,
            “token_id”: “90c8376e-8f3d-4454-8fbe-2716535a72c4”,
            “value”: “Massachusetts”,
            “selected_option_ids”: [“435b5410-a11f-4f79-b7fb-08cabef00cba”]
        }]
    }
}

Downloading Agreement Versions and Attachments

Downloading Agreement Versions

Download a specific agreement version using the version ID.

  • Endpoint Reference: GET /finalize/v2/agreements/{agreement_id}/agreement_versions/{version_id}/file
  • Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}/agreement_versions/{version_id}/file
  • Calling this endpoint will download the file contents so it can be leveraged in other systems.
  • The AWS s3 link is in the location response header 

Request Body

curl
-X 'GET' \
'https://api.linksquares.com/api/finalize/v2/agreements/25d08a28-b722-4fa0-ae52-26e3d7c6ccbf/agreement_versions/ee2b06ce-4ed2-493f-bb7c-578f6f44dbb1/file' \
-H 'accept: */*'

 

Downloading Agreement Attachments

Download a specific agreement attachment using the attachment ID.

  • Endpoint Reference: GET /finalize/v2/agreements/{agreement_id}/attachments/{attachment_id}/file
  • Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}/attachments/{attachment_id}/file
  • Calling this URL will download the attachment file contents so they can be leveraged in other systems.
  • The AWS s3 link is in the location response header

Request Body

curl
-X 'GET' \'https://api.linksquares.com/api/finalize/v2/agreements/23d2289c-158c-4e5b-8d27-3cf6d6a86a62/attachments/949ed294-84fb-49e3-9d6d-e27fbf0b4593/file' \
-H 'accept: */*'

 

Uploading Attachments to Existing Agreements

Upload an attachment to an existing agreement using the relevant agreement ID. Multiple files can be uploaded in a single request.

Step 1: Sending Attachments

Upload the attachment file(s) to the relevant agreement.

  • Endpoint Reference: POST /finalize/v2/agreements/{agreement_id}/attachments
  • Full Endpoint URL: POST https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}/attachments
  • This request will be a JSON.
  • The agreement_id should correspond to the ID of the agreement to which you want to upload the attachment.
  • The supported file types are as follows. 
DOC DOCX PDF XLS XLSX PPT PPTX
MP3 GIF JPEG HPG PNG BMP SVG
TXT MP4 MPEG MPG MOV WMV AVI

Note: Within API code, file extensions should be referenced using all lowercase letters.

Request Body 

curl
--location 'https://api.linksquares.com/api/finalize/v2/agreements/597158ed-72ea-45ab-ab7e-fc11879193f2/attachments' \--header 'x-api-key: {
    api_key
}' \--header 'Content-Type: application/json' \--data '{
    "data": {
        "attachment_file": {
            "name": "Sample Purchase Order.pdf"
        }
    }
}'

Response

{
    "data": {
        "id": "106c9acc-d637-4dfa-af8f-cfb823405843",
        "created_at": "2023-09-14T18:49:13Z",
        "file_name": null
    },
    "_links": {
        "attachment_file_upload": {
            "href": "https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/attachment_upload/agreements/597158ed-72ea-45ab-ab7e-fc11879193f2/attachments/106c9acc-d637-4dfa-af8f-cfb823405843/attachment_file/Sample%20Purchase%20Order.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2V427P3JQXPOQ%2F20230914%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230914T184913Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaCXVzLWVhc3QtMSJHMEUCIQDBs5d%2FyF5JnssRixchwqrZzDEgyb%2B5%2BKf%2FSXfxbV06EwIgMG3pst6Oe7eseGq0uJP%2Fp9pww6e3j9PSOqLfajUruFsq5QMIqxAFGgwwOTU2ODYwOTI0NzgiDAuIiadlkdTcBkjXMirCA3Gf4JNgO1bYb5Ddc9xJ35IiYwXgcOxv4PxwBbRC17M4V1v4ITayOoTYTy6uq9yuOKsgvfYeD7RgDAL9uB8F9HS1xL0Qlwzc%2Fcr%2F07q1hjeEHYqf%2FC75zaDdzHGXzCJ2rgv6YPMSDfUa%2Bkqhoc0jsjw35fBfHTYCbA6thkGmh28L%2F6c%2FmItuD8VNObFiYkiNSR5X%2F8y436B%2BKh3sG7%2FUYrv9bvA5XWiG0%2Bg6hGNuF%2FyewmNWzVGrRJLVGWTqwizhtiGv4PrUns3z5O0KpfLnt10eNy5gsKUak%2BI%2BVcEg2oKpYwQEv0trz9BIfwdmiFDYUWXFpsVew9lvxVtVQEUEXCQU1fnS7pzrq5yw569Kd7lnIe6vLtC3MM3DJvie95kpt55VZnTH8N0uQ3d7Pb7qlo3oJt%2FmH%2BaK79Z5r5sKZRdBrs2tSUSSRd4DhhwIDuV1hAXeSzO8xsVvQX2dNcHaDx2oNR%2FCN03gxOvQV%2FITiVI8mujbSQ4Pycbh6h94ftFlI5oBHqOh5lkfsZmxkVWiug5BI3CrwowDaaPAkz5jF8a%2FF5AfsO9C0jpqUn0FdsFCS4GLZr2e5UP9kAD86FxWR3V9CzDVkY2oBjqlAXdhSAqjvHHNv1fAKSJF9TNPlPyWWz3wp0Xgk%2BSyQ8LEUewabdAc4kjHKoWxJaMhfZZeqYD048pcUVlFhoLLmfEIkUykn3ChW4uqOJeeATkwDQ21A5sbYGZFyH7PFnQwMfhBhGlz%2BS8Vpr%2FWjwhf5tS7I05INPFCj%2FqU0s2FxncGwCLQ5%2Fau8nTty3Uc%2Fb3ROpNxkHazgm8CblyTfM0byBB2EHqgpg%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=c624e74b0b7d9e4f8733639218c863ccfa4bbb1504ba5f8bed7caa902352c5ca",
            "operation": "put",
            "file": "Sample Purchase Order.pdf"
        },
        "attachment_upload_complete": {
            "href": "https://api.linksquares.com/api/finalize/v2/agreements/597158ed-72qa-45ap-ab7e-fc118791p3f2/attachments/109c9acc-d237-5dfa-af8f-cfb823405843",
            "operation": "patch",
            "body": {
                "data": {
                    "upload_complete": true
                }
            }
        }
    }
}

Step 2: Uploading to the Presigned URL 

The response code from the previous step will include instructions on the next steps to take to successfully upload the attachment.

  • A presigned URL (attachment_file_upload) is included in the response of the POST call. Upload the file for the attachment using a PUT request with the file to the presigned URL.
    • This file must be a binary file (DOCX or PDF). 

Request Body 

curl
--location
--request PUT 'https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/attachment_upload/agreements/597158ed-72ea-45ab-ab7e-fc11879193f2/attachments/106c9acc-d637-4dfa-af8f-cfb823405843/attachment_file/Sample%20Purchase%20Order.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2V427P3JQXPOQ%2F20230914%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230914T184913Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEGIaCXVzLWVhc3QtMSJHMEUCIQDBs5d%2FyF5JnssRixchwqrZzDEgyb%2B5%2BKf%2FSXfxbV06EwIgMG3pst6Oe7eseGq0uJP%2Fp9pww6e3j9PSOqLfajUruFsq5QMISxAFGgwwOTU2ODYwOTI0NzgiDAuIiadlkdTcBkjXMirCA3Gf4JNgO1bYb5Ddc9xJ35IiYwXgcOxv4PxwBbRC17M4V1v4ITayOoTYTy6uq9yuOKsgvVYeD7RgDAL9uB8F9HS1xL0Qlwzc%2Fcr%2F07q1hjeEHYqf%2FC75zaDdzHGXzCJ2rgv6YPMSDfUa%2Bkqhoc0jsjw35fBfHTYCbA6thkGmh28L%2F6c%2FmItuD8VNObFzYkiNSR5X%2F8y436B%2BKh3sG7%2FUYrv9QvA5XWiG0%2Bg6hGNuF%2FyewmNWzVGrRJLVGWTqwizhtiGv4PrUns3z5O0KpfLnt1eeNy5gsKUak%2BI%2BVcEg2oKpYwQEv0trz9BIfwdmiFDYUWXFpsVew9lvxVtVQEUEXCQU1fnS7pzrq5yw569Kd7lnIe6vLtC3MM3DJvie95kpt55VZnTH8N0uQ3d7Pb7qlo3oJt%2FmH%2BaK79Z5r5sKZRdBrs2tSUSSRdxDhhwIDuV1hAXeSzO8xsVvQX2dNcHaDxnoNR%2FCN03gxOvQV%2FITiVI8mujbSQ4Pycbh6h94ftFlI5oBHqOh5lkfsZmxkVWiug5BI3CrwowDaaPAkz5jF8a%2FF5AfsO9C0jpqUn0FdsFCS4GLZr2e5UP9kAD86FxWR3V9CzDVkY2oBjqlAXdhSAqjvHHNv1fAKSJF9TNPlPyWWz3wp0Xgk%2BSyQ8LEUewabdAc4kjHKoWxJaMhfZZeqYD048pcUVMFhoLLmfEIkUykn3ChW4uqOJeeATkwDQ21A5sbYGZFyH7PFnQwMfhBhGlz%2BS8Vpr%2FWjwhf5tS7I05INPFCj%2FqUEs2FxncGwCLQ5%2Fau8nTty3Uc%2Fb3ROpNxkHazgm8CblyTfM0byBB2EHqgpg%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=c624e74b0b7d9e4f8733639218c863ccfa4bbb1504ba5f8bed7caa902352c5ca' \--header 'x-api-key: qAa445sMKYvYRSrYnKLbT7P3FOpe_z8DRONrgYx3hGD_98VJtnVkl5OWiqHT7U36' \--header 'Content-Type: application/pdf' \--data '@Sample Purchase Order.pdf'

Step 3: Confirming Successful Attachment Uploads

Complete the attachment file upload to Finalize. 

  • Endpoint Reference: PATCH {attachment_upload_complete}
  • Use the PATCH endpoint to inform Finalize that you have finished uploading the attachment files to the agreement. 

Request Body

curl
--location
--request PATCH 'https://api.linksquares.com/api/finalize/v2/agreements/597158ed-72ea-45ab-ab7e-fc11879193f2/attachments/04e3efa4-7157-4cb1-b1cc-233198ed8d47' \--header 'x-api-key: {
    api_key
} \--header 'Content-Type: application/json' \--data '{
    "data": {
        "upload_complete": true
    }
}'

Updating Agreement Statuses

Using the agreement ID, the user must first query the available next statuses for the given agreement. Then the agreement can be transitioned to the next status. It is possible to update the status of an agreement with or without a file (i.e., a new agreement version).

Step 1: Retrieving Agreement Statuses

Query valid next statuses for agreement using the agreement ID.

  • Endpoint Reference: GET /finalize/v2/statuses/{agreement_id}
  • Full Endpoint URL: GET https://api.linksquares.com/api/finalize/v2/statuses/{agreement_id}
  • This will return a list of statuses for the agreement including an ID, name, and description for each status.
  • Store the ID for the new status that you want to assign to the agreement. 
  • To learn more about agreement phases and statuses, reference our article on Agreement Phases and Statuses.
  • If you are attempting to transition an agreement with tasks to the Ready for Signature status, you must first retrieve and complete all associated tasks. After all tasks are completed, the agreement status will automatically update to Ready for Signature. If the agreement does not have any outstanding tasks, this step can be skipped. To learn more about the available functionality for retrieving and approving tasks using the Finalize API, reference the Retrieve and Approve Tasks section of this article. 

Response

{
    "data": [{
        "id": "35a57fa1-6ecc-464f-bc0e-cf94340ac112",
        "name": "Counterparty Review",
        "description": "This is where an agreement moves when it has been sent externally to review & approver.",
        "internal_enum": "counterparty_review"
    },
    {
        "id": "3bb194de-1cd3-4616-92bb-5d70508018a1",
        "name": "Done",
        "description": "This is where an agreement moves when it has been completed,
        but no signatures are required. It is the end-state for documents that are configured to skip the Signature Phase. (For example,
        pricing quotes or non-binding order forms.) Agreement that requires no signature receives all needed approvals.",
        "internal_enum": "done"
    },
    {
        "id": "ce629acd-f723-40f9-bf3e-8148f3520615",
        "name": "Fully Signed",
        "description": "This is where an agreement moves when it has been signed by all parties. This is also when an agreement should be sent over to Analyze automatically. Agreement data should be a locked state and should not be editable by users.",
        "internal_enum": "fully_signed"
    },
    {
        "id": "2cc53ea5-c591-4099-9e2f-6a3ff1fac7a4",
        "name": "Internal Review",
        "description": "This is where an agreement starts when an agreement is directly drafted from a third-party paper template,
        an our-paper template,
        or agreement is sent to Finalize.",
        "internal_enum": "internal_review"
    },
    {
        "id": "e8a9c79e-08b0-4cd7-bf01-4d3b52a4fa87",
        "name": "Out for Signature",
        "description": "This is where an agreement moves when it has been sent to all required parties for signature.",
        "internal_enum": "out_for_signature"
    },
    {
        "id": "c0a10544-7195-4fa3-a3d8-51e4e5187276",
        "name": "Partially Signed",
        "description": "This is where an agreement moves when it has been signed by some,
        but not all,
        required parties.",
        "internal_enum": "partially_signed"
    },
    {
        "id": "021b04ad-8fd0-4b54-bde7-67201226e62b",
        "name": "Paused",
        "description": "This is where an agreement moves when no additional work is foreseen (i.e. the contract has been abandoned for the time being,
        but future work will resume at some point). Outstanding tasks become “inactive” but not deleted; if an agreement is unpaused,
        those tasks are revived.",
        "internal_enum": "paused_partially_signed"
    },
    {
        "id": "3328a74b-7dee-4c48-bf30-d8bdac5796b3",
        "name": "Paused",
        "description": "This is where an agreement moves when no additional work is foreseen (i.e. the contract has been abandoned for the time being,
        but future work will resume at some point). Outstanding tasks become “inactive” but not deleted; if an agreement is unpaused,
        those tasks are revived.",
        "internal_enum": "paused_ready_for_signature"
    },
    {
        "id": "9cec8659-0073-4d20-97c1-5d36edbea497",
        "name": "Paused",
        "description": "This is where an agreement moves when no additional work is foreseen (i.e. the contract has been abandoned for the time being,
        but future work will resume at some point). Outstanding tasks become “inactive” but not deleted; if an agreement is unpaused,
        those tasks are revived.",
        "internal_enum": "paused_out_for_signature"
    },
    {
        "id": "8bc45047-fb65-4d7f-975f-92d6a0b94abe",
        "name": "Paused",
        "description": "This is where an agreement moves when no additional work is foreseen (i.e. the contract has been abandoned for the time being,
        but future work will resume at some point). Outstanding tasks become “inactive” but not deleted; if an agreement is unpaused,
        those tasks are revived.",
        "internal_enum": "paused_request_pending"
    }],
    "total_count": 14,
    "_links": {
        "next": {
            "href": "https://api.linksquares.com/api/finalize/v2/statuses?page=2"
        }
    }
}

Step 2: Updating the Agreement Status

Issue a PATCH call to update the current status of an agreement using the agreement ID. 

  • Endpoint Reference: PATCH /finalize/v2/agreements/{agreement_id}
  • Full Endpoint URL: PATCH https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}
  • This request will be a JSON. 
  • Provide the status_id key that corresponds to the status the agreement should be transitioned to. 

Request Body

{
    “data”: {
        “status_id”: “2cc53ea5-c591-4099-9e2f-6a3ff1fac7a4”
    }
}

zendeskstar.jpgUpdate Agreement Details Info Endpoint

The Finalize API Update Agreement Details endpoint enables customers to update the Agreement Details in the Info tab on a previously created Finalize agreement.

Step 1:  Issue a GET agreement call to retrieve the Question id and the Answer values or Answer id(s) (Single, Multi-Selection options)

Text, Paragraph, Date, Numbers and URL all use questions:id / answer: value

Set the answer: value for Text, Paragraph, Date, Numbers and URL

 

Single and Multiple Selection use options: id: description in the options array.

GET > https://api.linksquares.com/api/finalize/v2/agreements/{agreement id}?include=embedded

 

Answer Type Options:

  • Text: (Short text response; 80 characters maximum)
  • Paragraph:  (Long text response; 1200 characters maximum)
  • Date: (format: yyyy-mm-dd)
  • Numbers: (Numerical digits)
  • URL: (must be a valid URL)
  • Single Selection: (One option applies; value must be part of the selection answers within the template)
  • Multiple Selection: (Multiple options apply: values must be part of the selection answers within the template and all values including new selection must be included in the payload)
  • File:

Step 2: Issue PATCH call to update the Agreement Answer option(s) in the Info tab

Example: Text Type JSON Response

 

JSON Response Example snippet:

"questions": [{
    "id": "d33eba0b-69e3-4a9f-93be-ff8de52e8eaa",
    "answer_type": "text",
    "description": "Please provide the agreement name",
    "required": true,
    "answer": null
},
{
    "id": "b83f9a93-877f-4808-8829-2670018764a1",
    "answer_type": "text",
    "description": " Contact (Text)",
    "required": true,
    "answer": {
        "id": "06de950a-054c-442b-8f1c-cdea59d8bbbc",
        "value": "John Bell"
    }
}

 

Update Text in an Agreement Detail using PATCH Endpoint

Use the question:id from the GET Agreement JSON response and then add the question:id and then the new Text value.  (Maximum text characters = 80)

 

PATCH > https://api.linksquares.com/api/finalize/v2/agreements/{agreement id}

Body:

{
    "data": {
        "questions": [{
            "id": "b83f9a93-877f-4808-8829-2670018764a1",
            "answer": {
                "value": "Carrie Barlow"
            }
        }]
    }
}

Single-Selection Type JSON Response

 

JSON Response Single-Selection snippet:

{
    "id": "5100ab17-de0b-4a97-8648-d848a07d4cd3",
    "answer_type": "single_selection",
    "description": "Select Contract Type (Single Selection)",
    "required": true,
    "answer": {
        "id": "35fefb59-89a7-4013-bb36-ac0a398ce337",
        "selected_option_ids": ["23787b3a-ed21-4655-a851-56bd66079664"]
    },
    "options": [{
        "id": "23787b3a-ed21-4655-a851-56bd66079664",
        "description": "Vendor Agreement"
    },
    {
        "id": "1a8d4673-cd95-4021-a673-3a277b86be79",
        "description": "Lease Agreement"
    },
    {
        "id": "4626bb6e-2e4f-473b-9f03-065d1c6b3719",
        "description": "Non-Disclosure Agreement"
    }]
}

 

Update Single Selection in an Agreement Detail Endpoint

 

Use the question:id from the GET Agreement JSON response and then add the selected:id and the custom_description of the selection value available within the template.  Values must equal what is configured for he question within the template.

 

Include the selected:id and the description to update the selection

 

PATCH>  https://api.linksquares.com/api/finalize/v2/agreements/{agreement id} 

Body:

{
    "data": {
        "questions": [{
            "id": "5100ab17-de0b-4a97-8648-d848a07d4cd3",
             question.id         "answer": {
                "selected": [{
                    "id": "1a8d4673-cd95-4021-a673-3a277b86be79",
                    "custom_description": "Lease Agreement"
                }]
            }
        }]
    }
}

  

Multiple Selection Type JSON Response

JSON Response Example snippet:

{
    "id": "19a67269-bea4-4bd2-be95-a7e3e276b132",
    "answer_type": "multiple_selection",
    "description": "Business Locations (Multiple Selection)",
    "required": true,
    "answer": {
        "id": "2d5c1da8-8588-418f-81c1-7d968df00964",
        "selected_option_ids": ["68f91e21-497a-48a9-bae4-98c4f355e523",
        "e8f6f38b-4695-4a4e-aa02-882a474b0c31"]
    },
    "options": [{
        "id": "e8f6f38b-4695-4a4e-aa02-882a474b0c31",
        "description": "Massachusetts"
    },
    {
        "id": "68f91e21-497a-48a9-bae4-98c4f355e523",
        "description": "New Hampshire"
    },
    {
        "id": "988aa229-bbfc-4674-86f4-66741179153a",
        "description": "Maine"
    }]
}

 

Update Multiple Selection in an Agreement Detail

Use the question:id from the GET JSON response and then add the selected:id and the custom_description of the selection values available within the template.

Values must equal what is configured for the question within the template.

 

For multiple-selection updates, all previous values including the new selection must be included in the payload.

PATCH > https://api.linksquares.com/api/finalize/v2/agreements/{agreement id}

Body: 

{
    "data": {
        "questions": [{
            "id": "19a67269-bea4-4bd2-be95-a7e3e276b132",
            "answer": {
                "selected": [{
                    "id": "e8f6f38b-4695-4a4e-aa02-882a474b0c31",
                    "custom_description": "Massachusetts"
                },
                {
                    "id": "988aa229-bbfc-4674-86f4-66741179153a",
                    "custom_description": "Maine"
                }]
            }
        }]
    }

 

Uploading New Agreement Versions 

Uploading a new agreement version is accomplished by sending a file and status for the new agreement version, uploading the file to the presigned URL, and informing Finalize the upload is complete. 

Note: Users cannot send multiple new agreement versions in a row. Once an agreement version has been fully completed, another agreement version can be uploaded.

Step 1: Retrieving the Agreement Status 

  • Endpoint Reference: GET finalize/v2/agreements/{agreement_id}
  • Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}
  • Record the status_id returned in the response. 

Response 

{
    “data”: {
        “id”: “0308af9b-c3f8-479c-9714-5c5ac3962f64”,
        “name”: “Agreement Version”,
        “kind”: “draft”,
        “created_at”: “2023-08-07T15:18:36Z”,
        “status_updated_at”: “2023-08-08T13:54:52Z”,
        “author_id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67”,
        “owner_id”: null,
        “template_id”: “27b38606-f2b7-4be2-b54b-9ebf76a2e344",
        “collaborator_ids”: [“1d2bdffe-0152-11ed-914b-9f74296d0e67"],
        “question_ids”: [“21a80339-2568-4124-be7f-7d10a2b386a4",
        “3c926c8e-3563-4e2b-9d1c-2f61ca52628e”,
        “73e00b92-9707-4f9b-8841-c38c3b48dd7c”,
        “23e7a0dc-4ce2-4674-9bbd-1cda82bcaf1e”,
        “ac076afc-c550-4f94-95d3-0a9f006cba71"],
        “status_id”: “2cc53ea5-c591-4099-9e2f-6a3ff1fac7a4",
        “token_value_ids”: [“c38ad25a-51f8-474a-ba9e-4dcd9a50136d”,
        “ae0c19b3-83c5-40f9-90bd-9f2bd0f33b7f”,
        “d0f45026-95eb-4e80-ace5-b5131ee592ef”,
        “28cb16b6-b0a4-4b19-b547-c6ff6b514b3a”,
        “4a3d961e-37d6-453d-af7e-d16b8ef5891d”]
    }
}

 

Step 2: Sending the New Agreement Version

  • Endpoint Reference: POST /finalize/v2/agreements/{agreement_id}/agreement_versions
  • Full Endpoint URL: POST https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}/agreement_versions 
  • This request will be a JSON. 
  • The agreement_id should correspond to the ID of the agreement to which you want to upload the new version.
  • Users will specify the status and the file name for the new agreement version within the request body. 
  • The supported file types are as follows. 
DOC DOCX PDF XLS XLSX PPT PPTX
MP3 GIF JPEG JPG PNG BMP SVG
TXT MP4 MPEG MPG MOV WMV AVI

Note: Within API code, file extensions should be referenced using all lowercase letters.

Request Body

curl
-X 'POST' \  'https://api.linksquares.com/api/finalize/v2/agreements/fb3e7e7f-1c1e-4f89-8881-6266cefcb672/agreement_versions' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "data": {
        "status_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agreement_version_file": {
            "name": "Agreement_Version_v2.docx"
        }
    }
}’

Response 

{
    “data”: {
        “id”: “9d4efdee-9706-47fe-af33-022578ca84f5”
    },
    “_links”: {
        “agreement_version_file_upload”: {
            “href”: “https://linksquares-finalize-templates-production.s3.amazonaws.com/cache/creation/agreement_version_upload/agreements/0308af9b-c3f8-479c-9714-5c5ac3962f64/versions/9d4efdee-9706-47fe-af33-022578ca84f5/agreement_version_file/Agreement_Version_v2.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIARMR2V427GPCXSVOR%2F20230919%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230919T141818Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjENb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQC2ukgSKMJCmwYVlsSbbykxauFhGlrv0GhijZGOgHIF9gIgUOTfTHNPUeYQFUz%2FeFJ9o7iq8ykn0Hn9f8DfL6J7sfoq7gMIvv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAFGgwwOTU2ODYwOTI0NzgiDCNusnNjouoECuepZyrCAx%2B%2FQbNdn7Xr49jfiG5htqmiFvqsMHXZIuquub94ONeLWbF9TqzW3%2BWbzerYPrGrba4sLd1CCNygMpIj7PXJO1Q1kBlxVxaeNnKaorp9Vc2e%2Fbp8gSdAkm9I1Z%2Ft00UZ8RjvbROOlQDLkWTa%2FXUa9LZQCP5Cn31GPFAq5LzmO11aKlxebWb%2FYYQKsqHXL8zXqNS1OzrczaM5fzmkbA%2B8C8qLE7P4WMGu%2FKyxNFbeVpqdXLEXA9mO8YVo%2B5Fn7TckRBCaw1QUGimIU3p3Lm13EVTdbopFTogoD4ryLxNx%2FeoAxVBTQP6lerfSUyIhl%2FPZjT2XpucTxkF93RuChJn%2FlUd%2Bg9PZGcPWZtPawAbISpF%2BDZhPpuV8b9zaJhOqKnTxwS8Y5trWkf09XPD1wHnfsupSRQvsgMwKhiwepAgWoH%2B4LKpfZ8DQPAbGDVeAIl4YlCp206XPG5AUIz3OHvW%2F2VA%2F%2BzvpAcn3bwfpnkITitGDeBkLqATjCYqybXxN7Yq1FC889sUTonNR6y4J9JmvUX7gIvgft1C44VF3TfOPETazJSRVhZbD3ADWalvKp4gZIG7VVXdQwt1bLEXgRF7qZVUakDCJwKaoBjqlAc4XPLD74Jnsnbq%2BwL8SHfPAlnPw0xJOYsQecQRFnuAYOsjQL%2FPt53EJl10AiPStDlvs8NbmkTOasgoBb1MUjJp7fu7P1L34qEL5OzSycL%2Bj1p7jxhu0Ee3hg6FB%2FfVZroCadtQqZAVBlyC%2Fci7Gyzu0UfZSrzaJeCOQAajjAdkrla3Xuisgi3fsFZVgovm%2F0mDyrp0WCCgrxCxQzLfmOuAWQpxHAQ%3D%3D&X-Amz-SignedHeaders=host&X-Amz-Signature=27c4d56164d967bde468b3f0f3550d665575df97d15f7af020ecbcef74ab1c35”,
            “operation”: “put”,
            “file”: “Agreement_Version_v2.docx”
        },
        “agreement_version_upload_complete”: {
            “href”: “https://api.linksquares.com/api/finalize/v2/agreements/0308af9b-c3f8-479c-9714-5c5ac3962f64/agreement_versions/9d4efdee-9706-47fe-af33-022578ca84f5”,
            “operation”: “patch”,
            “body”: {
                “data”: {
                    “upload_complete”: true
                }
            }
        }
    }
}

Step 3: Uploading to the Presigned URL

The response code from the previous step will include a presigned URL to which the file for the new agreement version should be uploaded. 

  • Endpoint Reference: PUT {agreement_version_file_upload}
  • Upload the file for the new agreement version by issuing a PUT call with the file to the presigned URL (agreement_version_file_upload).
  • Include the binary file attachment of the new version of the document in the body. 

Step 4: Informing Finalize of the New Agreement Version

Issue a PATCH call to inform Finalize that you have finished uploading the agreement version file. 

  • Endpoint Reference: PATCH  {agreement_version_upload_complete}
  • The agreement_version_upload_complete variable can be found in the response of the POST call. 

Request Body

{
    “data”:  {
        “upload_complete”: true
    }
}

Reporting on the Status of an Agreement

The LinkSquares team recommends that any integration maintains the link between record identifiers in their third-party systems and the corresponding Finalize agreement identifiers.

This facilitates data reconciliation and synchronization. Another way to maintain a sync on an interval (e.g. daily, weekly, etc.) is to retrieve a list of all agreements filtered in descending order of when the agreement status was last updated.

Step 1: Retrieving a List of All Agreements 

Retrieve a list of all agreements.

  • Endpoint Reference: GET /finalize/v2/agreements
  • Collection Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/agreements
  • The agreements will be returned in the items array.
  • Filter the returned agreements by the selected date to view those agreements that were updated before or after the date. 
    • Status updated at - Returns only agreements with a status updated before or after the specified date. Must be in ISO8601 format.
      • GET /api/finalize/v2/agreements?filter[status_updated_at][after]=2023-08-23T15:00:00

Step 2: Updating the Record in the Third-Party System 

Iterate through the selected agreement items in the response and update records in the third-party system.

  • For the set of agreement records whose status_updated_at was more recent than the previous sync, you can use the agreement ID and status_id to reflect the latest agreement status in your third-party system.

Retrieving and Approving Tasks 

Users can retrieve information about and approve tasks associated with their LinkSquares environment.

Retrieving All Tasks

This endpoint will return a list of tasks associated with the organization’s LinkSquares environment. The returned tasks are not limited based on user permissions. 

  • Endpoint Reference: GET finalize/v2/tasks
  • Collection Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/tasks
  • Users can filter the returned tasks by:
    • Name: The name of the task.
    • Active: If the task is active or inactive.
    • Status: The status of the task. The available statuses are unreviewed, or approved.
      • Note: Some tasks may have a status of ‘rejected.’ This status has been deprecated and will only appear where it was historically applied.
    • Agreement ID: The ID for the agreement associated with the task. 
      • To filter tasks by a single agreement, call the following endpoint: https://api.linksquares.com/api/finalize/v2/tasks?filter[agreement_id][]={agreement_id}
    • Author ID: The ID for the user that created the task.
    • Assignee ID(s): The ID(s) of the assignee(s) associated with the task. 

Retrieving a Single Task 

Users can retrieve a single task using the task ID.

  • Endpoint Reference: GET finalize/v2/tasks/{task_id}
  • Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/tasks/{task_id}
  • Users can pass include=embedded within the call to retrieve information about the users associated with the given task (assignee(s), author, and resolver).

Response 

{
    “data”: {
        “id”: “c818c4b0-353f-43ff-8a01-b5f6b8ed8e4b”,
        “name”: “Approve latest version”,
        “type”: “ApprovalTask”,
        “approval_type”: “latest_version”,
        “status”: “approved”,
        “active”: false,
        “text”: “Please review the latest version and approve the agreement to complete this task.“,
        “due_date”: null,
        “position”: 1,
        “assignee_ids”: [“1d2bdffe-0152-11ed-914b-9f74296d0e67"],
        “author_id”: null,
        “resolver_id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67”,
        “agreement_id”: “5c7ec7be-d5da-4977-84e4-82ec367532be”,
        “attachment_id”: null
    },
    “_embedded”: {
        “users”: [{
            “id”: “1d2bdffe-0152-11ed-914b-9f74296d0e67",
            “first_name”: “Name”,
            “last_name”: “Name”,
            “email”: “email@email.com”
        }]
    }
}

Approving Tasks

Users can retrieve a single task and transition the task status to approved.

  • Endpoint Reference: PATCH finalize/v2/tasks/{task_id}
  • Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/tasks/{task_id}
  • Tasks can only be transitioned to the approved status. Attempting to transition a task to a status other than approved will return an error.
  • If a given task is part of an ordered list, the tasks must be approved in the outlined order. Attempting to approve tasks out of order will return an error.

Request Body 

{
    “data”: {
        “status”: “approved”
    }
}

 

Response

{
    "data": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "active": true,
        "agreement_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "approval_type": "latest_version",
        "assignee_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
        "attachment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "author_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "due_date": "2023-09-15T20:00:39Z",
        "name": "Approve Deliverable",
        "position": 1,
        "resolver_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "unreviewed",
        "text": "Please review the latest version and approve the agreement to complete this task",
        "type": "ApprovalTask"
    }
}

 

Adding Activity Comments

Users can add a single comment to an existing agreement.

  • Endpoint Reference: POST finalize/v2/agreements/{agreement_id}/comments
  • Full Endpoint URL: https://api.linksquares.com/api/finalize/v2/agreements/{agreement_id}/comments

Request Body 

{
    “data”: {
        "text": "This is my comment,
        created by the new Finalize API Activity Comments endpoint."
    }
}

Response

{
    "data": {
        "id": "16d0c854-d516-4c5d-a51c-6470f4cf2cd0",
        "author_id": "1d2bdffe-0152-11ed-914b-9f74296d0e67",
        "text": "This is my comment,
        created by the new Finalize API Activity Comments endpoint",
        "commentable_id": "4a2dcc58-c308-4b28-bad8-ed0ea333b682",
        "created_at": "2024-04-09T19:29:21Z"
    }
}

Related to

LinkSquares is here to help! Contact your Customer Success Manager or the Support team via the chat in our knowledge base or by email at support@linksquares.com.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Return to top

Related articles