Developer Documentation
IntegrationsHelp CenterSign in

Manage template type data fields

Suggest Edits

You can create, update, or remove data fields in a template type via the API or the Oneflow application.

🚧

Note:

  • Only admin users can manage data fields.
  • Text values in a data field are limited 1024 characters.

When you set data fields for a template type using the PUT endpoint, the existing set of data fields is overwritten according to the following rules:

Data field is in requestData field is in template typeResult
✅✅The data will be updated.
✅❌The data will be created in the template type.
❌✅The data will be removed from the template type.

❗️

Warning:

Be careful when performing operations with template type data fields. When you delete data fields from a template type, these data fields will be also removed from all the templates that use this template type.

However, changing a data field's value in a template type will not affect the data field's value already present in a template. If you also want that change reflected in the template, you must manually change the template's value.

Please see [Building a partner system integration] for additional considerations when managing data fields. For partner system integrations, please see Building a partner system integration.

Step 1. Obtain necessary information

To run the script described in this tutorial, you'll need the following data:

Path and body parameters
TEMPLATE_TYPE_ID To list all of the data fields that belong to a template type, you will first need to get the template type ID. You can find a unique template type ID using the GET/templates endpoint.
data_fields The list of data fields that belong to the given template type.
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. You can find all user-related information using the users endpoint.
Body
data_fields All data fields of the given template type you want to create, update or remove.

Step 2. Run the code

curl --request PUT \
  --url https://api.oneflow.com/v1/template_types/TEMPLATE_TYPE_ID/data_fields \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN' \
  --header 'x-oneflow-user-email: USER_EMAIL' \
  --data '{"data_fields":[{"custom_id":"participant_last_name","description":"The last name of a participant in a contract.","name":"Participant Last Name","placeholder":"Last Name","value":"Smith"},{"custom_id":"company_address","name":"Company address","value":"1234 Main Street"},{"custom_id":"participant_position","name":"Participant'\''s position in company."}]}'

import requests

headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'x-oneflow-api-token': API_TOKEN,
    'x-oneflow-user-email': USER_EMAIL,
}

payload = {
    'data_fields': [
        {
            'custom_id': 'participant_last_name',
            'description': 'The last name of a participant in a contract.',
            'name': 'Participant Last Name',
            'placeholder': 'Last Name',
            'value': 'Smith',
        },
        {
          'custom_id': 'company_address', 
          'name': 'Company address', 
          'value': '1234 Main Street'
        },
        {
          'custom_id': 'participant_position', 
          'name': 'Participant\'s position in company.'
        },
    ]
}

response = requests.put('https://api.oneflow.com/v1/template_types/TEMPLATE_TYPE_ID/data_fields', 
                        json=payload, headers=headers)

print(response.json())

Expected response

The above call will result in output similar to the following:

{
  "data_fields": [
    {
      "_links": {
        "template_type": {
          "href": "https://api.oneflow.com/v1/template_types/1"
        }
      },
      "active": true,
      "custom_id": "first_name",
      "description": "First name of the customer.",
      "id": 1,
      "name": "Customer First Name",
      "placeholder": "firstname",
      "source": "user",
      "value": "Bob"
    },
    {
      "_links": {
        "template_type": {
          "href": "https://api.oneflow.com/v1/template_types/1"
        }
      },
      "active": false,
      "custom_id": "last_name",
      "description": "Last name of the customer.",
      "id": 2,
      "name": "Customer Last Name",
      "placeholder": "lastname",
      "source": "system",
      "value": "Ross"
    }
  ]
}

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

Response codes

StatusMeaningDescription
200OKReturns the created data field information.
400Bad RequestInvalid format or content of the request.
401UnauthorizedThe API token or the user email is invalid.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource.

Updated 12 months ago