Updating contract metadata

Use the API to edit contract metadata.

  1. Review contract metadata
  2. Update contract status
  3. Update contract's boolean fields
  4. Update contract's date attributes

1. Review metadata

Fetch the contract object from the API. In case your contract has a PDF file attached to it, you'll notice how it has some values filled in:

import requests

ZEFORT_APIKEY = "ySLE1mhh6lfRsYa..."
CONTRACT_ID = 'doc_1Jp1kwQmgS8oFr24Bk'

response = requests.get(f'https://sandbox.zefort.com/api/contracts/{CONTRACT_ID}/', 
                        auth=(ZEFORT_APIKEY,''))
print(response.json())

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X GET "https://sandbox.zefort.com/api/contracts/$CONTRACT_ID/" \
     -u $ZEFORT_APIKEY:

Response:

{
    "attributes": {
        "title": "NON-DISCLOSURE AGREEMENT",
        "end_date": null,
        "effective_date": "2017-06-01",
        "signed_date": "2017-06-01",
        "main_language": "en"
    },
    "cover_document": {
        "id": "doc_1Jq361GT0IIKsx354Vo",
        "content_type": "application/pdf",
        "role": "contract",
        "status": "complete",
        "num_pages": 1,
        "filename": "Sample_NDA.pdf",
        "receive_time": "2021-10-13T07:16:56.521828Z",
        ...
    },
    "id": "ct_1JrjJQNzE6TVlyVHls",
    "incomplete": false,
    "num_emails": 0,
    "num_files": 1,
    "num_users": 1,
    "owner": {
        "id": "user_1KjGppHeBNKdZaUACX",
        "email": "demo@example.com",
        "name": "Demo User"
    },
    "parties": [
        {
            "id": "pty_1L34559HrKSNNDWeQPtm",
            "name": "Aivan Innovations Ltd",
            "org_id": "",
            ...
        }
    ],
    "status": "review",
    ...
}

Zefort analyzed the PDF automatically and filled in a number of metadata fields based on the information in the document.

Note how the status field has changed from queued to review. Here, review means that the automatically produced suggestions for metadata are ready to be reviewed by a human.

2. Update contract status

Let's accept the suggestions and update the status to done. Use the PATCH /api/contracts/<id>/ endpoint to update a contract:

import requests

ZEFORT_APIKEY = "ySLE1mhh6lfRsYa..."
CONTRACT_ID = "ct_1JrjJRTzEMlHVHls"

response = requests.patch(f'https://sandbox.zefort.com/api/contracts/{CONTRACT_ID}/', 
                          auth=(ZEFORT_APIKEY, ''), 
                          json={"status": "done"})

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X PATCH "https://sandbox.zefort.com/api/contracts/$CONTRACT_ID/" \
     -u $ZEFORT_APIKEY: \
     -H "Content-Type: application/json" \
     -d '{"status": "done"}'

Refresh the user interface, and you'll see the contract card now shows as "Reviewed".

3. Update contract boolean fields

While the API digests most of the values in payload json as strings, boolean values should be given as real bools so they would work correctly.

Example:

import requests

ZEFORT_APIKEY = "ySLE1mhh6lfRsYa..."
CONTRACT_ID = 'ct_1KOu7f5gX1NVTd9SIO'
payload = {
    "status": "done",
    "allow_emails": True,
    "attributes": {
        "main_language": 'en',
        ...
    }
    ...
}

response = requests.patch(f'https://sandbox.zefort.com/api/contracts/{CONTRACT_ID}/', 
                          auth=(ZEFORT_APIKEY,''), 
                          json=payload)

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X PATCH "https://sandbox.zefort.com/api/contracts/$CONTRACT_ID/" \
     -u $ZEFORT_APIKEY: \
     -H "Content-Type: application/json" \
     -d '{"allow_emails": true, "status": "done", "attributes": {"main_language": "en"}}'

Refreshing the user interface again let's you see the effects of your operation, and printing response.json() let's you see the changes immediately:

Response.json():

{
    "attributes": {
        "title": "NON-DISCLOSURE AGREEMENT",
        "end_date": null,
        "effective_date": "2017-06-01",
        "signed_date": "2017-06-01",
        "main_language": "en"
    },
    "cover_document": {
        "id": "doc_1Jq361GT0IIKsx354Vo",
        "content_type": "application/pdf",
        "role": "contract",
        "status": "complete",
        "num_pages": 1,
        "filename": "Sample_NDA.pdf",
        "receive_time": "2021-10-13T07:16:56.521828Z",
        ...
    },
    "id": "ct_1JrjJQNzE6TVlyVHls",
    "incomplete": false,
    "num_emails": 0,
    "num_files": 1,
    "num_users": 1,
    "allow_emails": true,
    "owner": {
        "id": "user_1KjGppHeBNKdZaUACX",
        "email": "demo@example.com",
        "name": "Demo User"
    },
    "parties": [
        {
            "id": "pty_1L34559HrKSNNDWeQPtm",
            "name": "Aivan Innovations Ltd",
            "org_id": "",
            ...
        }
    ],
    "status": "done",
    ...
}

4. Update contract's date attributes

In addition to regular strings and boolean values, you might need to update date fields. Date field wants it's information as a string and properly formatted.

Here is an example of setting a contracts end_date to 28th of February in 2023:

import requests

ZEFORT_APIKEY = "ySLE1mhh6lfRsYa..."
CONTRACT_ID = 'ct_1KOu7f5gX1NVTd9SIO'
payload = {
    "attributes": {
        "end_date": "2023-02-28"
    }
}

response = requests.patch(f'https://sandbox.zefort.com/api/contracts/{CONTRACT_ID}/', 
                          auth=(ZEFORT_APIKEY, ''), 
                          json=payload)

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."
CONTRACT_ID="ct_1KOu7f5gX1NVTd9SIO"

curl -X PATCH "https://sandbox.zefort.com/api/contracts/$CONTRACT_ID/" \
     -u $ZEFORT_APIKEY: \
     -H "Content-Type: application/json" \
     -d '{"attributes": {"end_date": "2023-02-28"}}'

Check your contracts updated end_date from user interface, or printing response.json().

Next steps

In our next topic, we will discuss about deleting documents and contracts.