Other important changes

Naming

While creating the new API, we renamed some of the terms used in the Oneflow application. Please, see the table below to learn what's changed:

Participant type

We have introduced a more flexible solution instead of participant types. Participant objects now have the following attributes: the signatory and the organizer flags and the _permissions attribute containing the contract_update flag (see more in the Participant data model.)

Here is the mapping for migrating your implementation and its role in the Oneflow application:

Template

The template for creating a contract should now belong to the same workspace where the contract is created.

📘

Note:

The template is now a required component of every contract. When creating a contract in a workspace, ensure that the contract template belongs to the same workspace; otherwise, share the template with that workspace.

See more in the Template data model.

Webhook API

We have improved the format of our webhooks. Check out the Webhook API section for details.

🚧

Note:

You can still use the legacy webhook format to automate your existing workflows. However, if you decide to switch to the new format, additional configuration will be required on our part. Therefore, please get in touch with your customer success manager for further information.

Attachments and PDFs

You can now use the Files endpoint to upload a single expanded PDF or multiple attachments.

The new endpoint can be used the same way as the previous endpoints, except that you now need to include the upload_as variable to indicate whether you want to upload your content as an attachment or an expanded PDF.

Create a contract with attachments: syntax comparison

Please see the Create a contract with a PDF tutorial for more information.

Data fields

We've made some changes to the data fields format and structure and the way you access them. First, we have revised the idea of data field sets. Data fields are now contained in an array called data_fields and retrieved per template type (see more in the Data field data model.)

You can now list or update data fields using the following endpoints:

• GET /helpers/template_types/{template_type_id}/data_fields
• PUT /template_types/{template_type_id}/data_fields.

Data field format: syntax comparison

Here is an example of the changes in the format of an individual data field:

🚧

Note:

We have changed external_key to custom_id, and the type attribute is no longer included. Since the type of all data fields is a string, we have removed this attribute.

Contract privacy

We have placed certain contract attributes inside a new _private_ownerside object to help clarify what information is private to the owner-side party in a contract. Owner-side refers to the party that created the contract. See more in the Private-ownerside chapter.

The following endpoints were affected by this change:

• GET/contracts
• POST/contracts/create.

📘

Note:

Only the output of these endpoints is affected.

We have made the following attributes private to the owner-side. Containing objects are in bold, and the attributes we moved inside _private_ownerside are listed below.

Contract

• created_time

Party

• created_time
• updated_time

Participant

• created_time
• first_visited_time
• last_visited_time
• updated_time
• visits

Product

• created_time
• updated_time

Product groups

• created_time
• updated_time

The example below shows the format of the participants object in the response of the GET/contracts/{contract_id} request:

"participants": [
    {
      "_permissions": {
        "contract:update": true
      },
      "_private_ownerside": {
        "created_time": "2021-03-17T11:49:02+00:00",
        "first_visited_time": "2021-03-17T11:49:02+00:00",
        "last_visited_time": "2021-03-17T11:49:02+00:00",
        "updated_time": "2021-03-17T11:49:02+00:00",
        "visits": 1
      },
      "delivery_channel": "email",
      "delivery_status": "not_sent",
      "email": "[email protected]",
      "id": 123456,
      "identification_number": "",
      "my_participant": true,
      "name": "Oneflow User",
      "organizer": false,
      "phone_number": "",
      "sign_method": "standard_esign",
      "sign_state": "undecided",
      "sign_state_updated_time": "2021-03-17T11:49:02+00:00",
      "signatory": true,
      "title": "CEO",
      "two_step_authentication_method": "none"
    }
]