Download a contract file

To keep all contract-related documents together, you can upload and download files to contracts using any Attachment endpoint. Thus, each contract can contain several files: the contract itself (always), the contract verification file (if all participants have already signed the contract), and other attachments (optional).

In this tutorial, you will learn how to list files available for the contract and download the contract file from Oneflow using the public API.

Step 1. Get the list of files available for the contract

To run the script described in this step, you’ll need the following data:

Headers
x-oneflow-api-token You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find out more in the Authentication section.
Path parameter
CONTRACT_ID The unique ID of the contract you want to get. You can find the contract ID using the contracts endpoint.

Run the following code:

curl --request GET \
  --url https://api.oneflow.com/v1/contracts/CONTRACT_ID/files/ \
  --header 'Accept: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN'
import requests

headers = {
    'Accept': 'application/json',
    'x-oneflow-api-token': 'API_TOKEN'
}

response = requests.get('https://api.oneflow.com/v1/contracts/CONTRACT_ID/files/',
                        headers=headers)

print(response.json())

Expected response

This operation will display the list of all files available for the specified contract ID.

The response can contain several files with the following types:

  • Contract - the contract file includes all attachment and signature files connected to the contract. This file is always available for download.
  • Verification - if all participants have signed the contract, there will be a verification file that you can download as a separate file.
  • Attachment - if there are attachments in the contract, you can download them as separate files.
  • PDF - if the contract contains an expanded PDF file in the PDF section, you can download it as a separate file.

📘

Note:

The file type will help you understand the file's nature and thus choose the correct ID to download the file (please check out Contract file data model). For example, the actual contract PDF file type is contract, and its id is always 1. If all parties have signed the contract, there will also be a contract verification file with the verification type; its id is always 2. The IDs of other types are generated automatically and are not constant. For more information, please see the Help Center article.

{
  "_links": {
    "next": {
      "href": "https://api.oneflow.com/v1/contracts/CONTRACT_ID/files?offset=4&limit=2"
    },
    "previous": {
      "href": "https://api.oneflow.com/v1/contracts/CONTRACT_ID/files?offset=0&limit=2"
    },
    "self": {
      "href": "https://api.oneflow.com/v1/contracts/CONTRACT_ID/files?offset=2&limit=2"
    }
  },
  "count": 5,
  "data": [
    {
      "extension": "pdf",
      "id": 1,
      "name": "Contract",
      "type": "contract"
    },
    {
      "extension": "pdf",
      "id": 2,
      "name": "Verification",
      "type": "verification"
    },
    {
      "extension": "pdf",
      "id": 140245,
      "name": "Meetingnotes",
      "type": "pdf"
    },
    {
      "extension": "pdf",
      "id": 140246,
      "name": "Proposal",
      "type": "pdf"
    },
    {
      "extension": "pdf",
      "id": 140247,
      "name": "Terms and conditions",
      "type": "attachment"
    }
  ]
}

Response codes

StatusMeaningDescription
200OKReturns the requested contract files.
400Bad RequestInvalid format or content of the request.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource.

Step 2. Download a contract file

Now that you have the list of all files available for the specified contract ID, you can run the script that downloads these files.

🚧

Note:

You can download contract files only one at a time. When a file is downloaded, the file name will be converted to US-ASCII. You can always get the original file name in the UTF-8 format from the response described in step 1 of this tutorial. Please, read more about the contract file name attribute in the Contract file data model.

To run the code described in this step, you’ll need the following data:

Headers
x-oneflow-api-token You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find out more in the Authentication section.
Path parameter
CONTRACT_ID The unique ID of the contract you want to download. You can find the contract ID using the contracts endpoint.
FILE_ID The unique identifier of the file available for the contract. See the example of the contract id value in Step 1, Expected response in this tutorial.

Step 3. Run the code

Replace the values of the parameters in the following command with the actual data from your account and run it:

curl --request GET \
  --url https://api.oneflow.com/v1/contracts/CONTRACT_ID/files/FILE_ID?download=true \
  --header 'x-oneflow-api-token: API_TOKEN' \
import requests

url = "https://api.oneflow.com/v1/contracts/CONTRACT_ID/files/FILE_ID?download=true"

querystring = {"download":"true"}

headers = {'x-oneflow-api-token': 'API_TOKEN'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Expected response

📘

Note:

In the code example above, the query parameter download=true, which will redirect you to the file to download. However, the default query parameter is download=false. In this case, only the metadata about the specified file will display.

Response codes

StatusMeaningDescription
200OKReturns metadata for a specific file inside a contract.
302RedirectRedirects you to the file to be downloaded.
400Bad RequestInvalid format or content of the request.
401UnauthorizedThe API token or the user email is invalid.
404Not FoundThe referenced contract or the file is missing.

Did this page help you?