Developer Documentation
IntegrationsHelp CenterSign in

Update a data field value

Suggest Edits

Using the PUT /contracts/{contract_id}/data_fields/{data_field_id} endpoint, you can update the value of an existing data field in a contract.

You can also update values of multiple data fields, using the PUT /contracts/{contract_id}/data_fields endpoint. Since most of the details are the same for this endpoint, we will only add information that needs your attention.

Currently, you will need the following data field attributes in the PUT request body to update a data field value:

  • _private_ownerside
  • id
  • value.

❗️

Note:

Single data field value: None of the above attributes are required paramters. However, if you run the PUT request with an id or a_private_ownerside.custom_id in the request body that doesn't match the data_field_id in the path parameter, an error will occur.

Multiple data field values: If you run the request with no id and _private_ownerside.custom_id in the request body, an error will occur.

🚧

Note:

Single data field value: The id and the _private_ownerside.custom_id parameters are not mandatory for this PUT request.

Multiple data field values: Include either or both the id or _private_ownerside.custom_id parameters in the PUT request for each data field that you want to update.

📘

Note:

Single data field value: A PUT request with novalue parameter will leave the value attribute unchanged for the data field. A PUT request that includes "value": "" or "value": null will remove the value from the data field and will assign "" to the value.

Multiple data field values: Same as updating a single data fied value for each value in each data field object.

Step 1. Obtain necessary information

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.
x-oneflow-user-email Your Oneflow user account email.
Path parameters
CONTRACT_ID The unique ID of the contract where you want to add a new participant. You can find the contract ID using the contracts endpoint.
DATA_FIELD_ID The unique ID of the data field that you want to update. It can be an id or a custom_id. If it is a custom_id, you should add c:: before the data_field_id in the path: /contracts/10015/data_fields/c::participant_last_name.
This path parameter is used only with the Update a contract data field value endpoint.
Body
data_fields [list] The list of data field objects to be updated. This parameter is used only with the Update contract data field values endpoint.
_private_ownerside [object]
custom_id The custom_id is a required parameter within the _private_ownerside object. You can use this as a reference to the data field besides the id. Each custom_id must be unique within the same contract.
id The unique identifier of the data field.
value The desired value of the data field that you want to update. This is the only data field attribute you can update with this PUT request.

Step 2. Run the code

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

Update a contract data field value

curl --request PUT \
     --url https://api.oneflow.com/v1/contracts/10015/data_fields/123456 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]' \
     --data '
{
          "_private_ownerside": {
               "custom_id": "participant_last_name"
          },
          "id": 123456,
          "value": "Smith"
}'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/data_fields/123456"

payload = {
          "_private_ownerside": {
               "custom_id": "participant_last_name"
          },
          "id": 123456,
          "value": "Smith"
}
headers = {
    "Accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]",
    "Content-Type": "application/json"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)

Update contract data field values

curl --request PUT \
     --url https://api.oneflow.com/v1/contracts/10015/data_fields \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-oneflow-api-token: 9841f1ee533681c3ea6a438560f2bb6c73b76675' \
     --header 'x-oneflow-user-email: [email protected]' \
     --data '
{
     "data_fields": [
          {
               "_private_ownerside": {
                    "custom_id": "participant_last_name"
               },
               "id": 123456,
               "value": "Smith"
          },
          {
               "_private_ownerside": {
                    "custom_id": "company_address"
               },
               "value": "1234 Main Street"
          },
          {
               "id": 2345678,
               "value": "Participant'\''s position in company."
          }
     ]
}'

import requests

url = "https://api.oneflow.com/v1/contracts/10015/data_fields"

payload = {"data_fields": [
        {
            "_private_ownerside": {"custom_id": "participant_last_name"},
            "id": 123456,
            "value": "Smith"
        },
        {
            "_private_ownerside": {"custom_id": "company_address"},
            "value": "1234 Main Street"
        },
        {
            "id": 2345678,
            "value": "Participant's position in company."
        }
    ]}
headers = {
    "Accept": "application/json",
    "x-oneflow-api-token": "9841f1ee533681c3ea6a438560f2bb6c73b76675",
    "x-oneflow-user-email": "[email protected]",
    "Content-Type": "application/json"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)

Expected response

This request will output details about the updated data field in JSON format.

📘

Note:

Since the responses from the Update a contract data field value and the Update contract data field values endpoints differ, we show them in separate tabs below.

Please see the Data field section in the Data model category for more information about the output.

{
  "_links": {
    "contract": {
      "href": "https://api.oneflow.com/v1/contracts/10015"
    },
    "self": {
      "href": "https://api.oneflow.com/v1/contracts/10015/data_fields/123456"
    }
  },
  "_private_ownerside": {
    "created_time": "2021-06-03T15:00:00+00:00",
    "custom_id": "participant_last_name",
    "updated_time": "2021-06-10T16:00:00+00:00"
  },
  "description": "lastname of the user",
  "id": 123456,
  "name": "lastname",
  "placeholder": "",
  "value": "Smith"
}

{
  "_links": {
    "next": {
      "href": null
    },
    "previous": {
      "href": null
    },
    "self": {
      "href": "https://api.oneflow.com/v1/contracts/10015/data_fields?limit=100&offset=0"
    }
  },
  "count": 12,
  "data": [
    {
      "_links": {
        "contract": {
          "href": "https://api.oneflow.com/v1/contracts/10015"
        },
        "self": {
          "href": "https://api.oneflow.com/v1/contracts/10015/data_fields/123456"
        }
      },
      "_private_ownerside": {
        "created_time": "2021-06-03T15:00:00+00:00",
        "custom_id": "participant_last_name",
        "updated_time": "2021-06-08T16:00:00+00:00"
      },
      "description": "lastname of the user",
      "id": 123456,
      "name": "Participant 1 last name",
      "placeholder": "lastname placeholder",
      "value": "Smith"
    },
    {
      "_links": {
        "contract": {
          "href": "https://api.oneflow.com/v1/contracts/10015"
        },
        "self": {
          "href": "https://api.oneflow.com/v1/contracts/10015/data_fields/123457"
        }
      },
      "_private_ownerside": {
        "created_time": "2021-06-03T15:00:00+00:00",
        "custom_id": "company_address",
        "updated_time": "2021-06-08T16:00:00+00:00"
      },
      "description": "address of the company",
      "id": 123457,
      "name": "Company address",
      "placeholder": "address placeholder",
      "value": "1234 Main Street"
    },
    {
      "_links": {
        "contract": {
          "href": "https://api.oneflow.com/v1/contracts/10015"
        },
        "self": {
          "href": "https://api.oneflow.com/v1/contracts/10015/data_fields/2345678"
        }
      },
      "_private_ownerside": {
        "created_time": "2021-06-03T15:00:00+00:00",
        "custom_id": "position_company",
        "updated_time": "2021-06-08T16:00:00+00:00"
      },
      "description": "position in the company",
      "id": 2345678,
      "name": "Position",
      "placeholder": "position",
      "value": "Participant's position in company."
    },
    ...
  ]
}

Response codes

StatusMeaningDescription
200OKReturns the updated data field with data field details.
400Bad RequestInvalid format or content of the request.
401UnauthorizedThe API token or the user email is invalid.
403ForbiddenThe request is not authorized by the server.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource.

Updated over 2 years ago