Oneflow Integration Platform

Use the Oneflow API to build powerful integrations to automate your contract management.

Contract is the main working entity of Oneflow, to which all other contract content, settings, data, etc., are connected.

In addition to being the central point of connection, the contract entity itself contains quite a lot of data described further in this section.

Contract attributes

The table below contains the list of all attributes available for each contract.

Attribute

Type

Description

_links

object

Contains links to endpoints associated with the parent object. See Links.

_private

object

Contains attributes that are only visible to the party of the current user. See Private.

_private_ownerside

object

Contains attributes that are only visible to the owner-side party. See Private ownerside.

_permissions

object

Contains permissions of the current user for various operations possible on the contract. See Permissions.

available_options

object

Gives information about the capabilities of the contract. See Available options.

data_fields

array

The list of data fields that exist in the contract template type. If there are no data fields in the contract template type, the list will be empty. See Data field

id

integer(signed_integer_id)

The unique ID of the contract.

lifecycle_state

object

Keeps track of the contract status. See Lifecycle state.

lifecycle_settings

object

Contains settings available for the lifecycle. See Lifecycle settings.

parties

array

The list of parties in the contract, representing companies, organizations, individuals, government departments, etc. See Party.

product_groups

array

The list of product groups. See Product group.

published_time

string(datetime)

The time the contract was published.

signing_period_expiry_time

string(datetime)

The time during which a signatory can sign the contract.

state

string(enum)

Indicates the status of the contract in the signing process. See State.

state_updated_time

string(datetime)

Time of the last update of the contract status.

updated_time

string(datetime)

Time of the last update of the contract.

Private

Some of the contract data is classified as private and only visible to the party owning the data.

๐Ÿ“˜

Note:

Private data exists in multiple attribute values, one for each party, where each party can only see its own copy.

The _private object contains attributes that are visible only to a specific set of parties.

Attribute

Type

Description

value

object

The deal size of a contract expressed in monetary value. See Value.

name

string

The name of the contract.

workspace_id

int

The ID of the workspace that owns the template used to create the contract.

Value

The value object contains all attributes related to the contract value.

Attribute

Type

Description

amount

amount

Amount indicating the total value of the contract.

currency

string(currency)

The currency of the amount. The currency is inherited from the workspace in which the contract is located.

Private ownerside

The _private_ownerside object contains attributes that are only visible to the owner-side party. The owner-side party is the party that created the contract.

Attribute

Type

Description

created_time

string(datetime)

The time the contract was created.

template_id

int

The ID of the template used to create the contract.

template_type_id

int

The ID of the template type the template belongs to.

Permissions

The _permissions object contains permissions for various operations possible within the contract. The permission format is ''contract:'' followed by a specific operation, such as ''contract:create.'' Currently, only the delete contract permission is displayed.

๐Ÿ“˜

Note:

Permissions are always set for the current user. If the permission is set to true, the user will be able to perform the specified operation; otherwise, the operation will be disabled for the current user.

Attribute

Type

Description

contract:delete

boolean

Indicates whether the user is allowed to delete contracts.

Available options

The available_options object gives information about the capabilities of the contract, such as which delivery channels, sign methods, and two-step authentication methods are available for the contract and lists the data types the contract can receive.

Attribute

Type

Description

can_receive_attachments

boolean

Indicates if attachments can be uploaded to the contract via API.

Using API, you can only add attachments when there is only one Attachments section in the contract. In this case, the true value indicates that the contract has precisely one Attachments section, and you can attach files to it. Otherwise, the value will be false, which means that there are no Attachments sections in the contract, or there are several of them, and, therefore, attachments cannot be added to the contract.

can_receive_expanded_pdf

boolean

Indicates if a PDF document can be uploaded to the contract via API.

Using API, you can only add a PDF document when there is only one PDF document section in the contract. In this case, the true value indicates that the contract has precisely one PDF document section, and you can add a PDF document to it. Otherwise, the value will be false, which means that there are no PDF document sections in the contract, or there are several of them, and, therefore, the PDF document cannot be added to the contract.

can_receive_products

boolean

Indicates if products can be added to the contract via API.

Using API, you can only add attachments when there is only one Product table section in the contract. In this case, the true value indicates that the contract has precisely one Product table section, and you can add products to it. Otherwise, the value will be false, which means that there are no Product table sections in the contract, or there are several of them, and, therefore, products cannot be added to the contract.

delivery_channels

array[object]

Indicates the available methods by which the contract can be delivered to its participants. See Delivery channels.

sign_methods

array[object]

Shows available methods of signing contracts. See Sign methods.

two_step_authentication_methods

array[object]

Shows available two-step authentication methods. See Two-step authentication methods.

Delivery channels

The delivery_channels array of objects indicates the available methods by which the contract can be delivered to its participants.

Attribute

Type

Description

name

string

The name of the delivery channel. See Delivery channel name.

preferred

boolean

Indicates which delivery channel has been set as preferred by the template designer.

required_participant_attributes

array[string]

Indicates the attributes required by any participant depending on the selected delivery channel. For example, the SMS delivery channel requires that the participant must have a phone number. All listed attributes are required.

The table below shows what attributes and the contract signing methods are required for a participant, depending on the selected delivery channel method.
All attributes marked with * are required.
It is required to use one of the available methods marked with **.

Method

Required participant attributes

Allowed sign methods

email

email*

All listed here.**

none

-*

All listed here.**

same_device

sign_method*

All listed here except standard_esign.**

sms

phone_number*

All listed here.**

Delivery channel name

The table below displays all methods available for the delivery_channels object name attribute.

Channel

Description

email

The counterparty will receive an email with a link to the contract.

sms

The counterparty will receive an SMS with a link to the contract.

same_device

The counterparty views and signs the contract on the same device (computer, tablet, phone, etc.) used by the owner-side party to create the contract. This may be the case for door-to-door sellers or similar. Please, contact your customer success manager for more details on how to set up this feature.

none

The contract will not be delivered when it is published. Access tokens can be requested after publish.

unknown

Used for future extensions. It can never be input when creating or updating contracts.

Sign methods

The sign_methods array of objects shows available methods of signing contracts.

Attribute

Type

Description

name

string

The name of the method of signing the contract. See Sign method name.

preferred

boolean

Indicates the method of signing the contract that has been set as preferred by the template designer.

Sign method name

The table below shows all methods available for the sign_methods array of objects name attribute.

๐Ÿ“˜

Note:

To be able to use SMS-signing, you first need to activate the SMS extension. The same goes for all eIDs.

Method

Description

standard_esign

This is the default setting for the Oneflow verification and signing. Your counterparty receives notification (email or SMS) with a unique and secure link to the contract. Now they can sign the contract in the Oneflow application using the green Sign button.

sms

E-signature with an SMS code.

swedish_bankid

E-signature with a Swedish BankID.

norwegian_bankid

E-signature with a Norwegian BankID.

danish_nemid

E-signature with a Danish NemID.

finnish_bankid

E-signature with a Finnish BankID.

unknown

Used for future extensions. It can never be input when creating or updating contracts.

Two-step authentication methods

The two-step authentication is an optional way to increase your contract security by ensuring that only the intended recipient can access the contract.

The two_step_authentication_methods array of objects shows the available two-step authentication methods.

Attribute

Type

Description

name

string

The name of the two-step authentication method. See Two-step authentication method name.

preferred

boolean

Indicates the two-step authentication method that has been set as preferred by the template designer.

required_participant_attributes

array[string]

Indicates the attributes required for all participants, depending on the available two-step authentication methods. For example, if the SMS two-step authentication method is available, the participant must have a phone number. All of the listed attributes are required.

The table below shows what participant-related attributes are required, depending on the two-step authentication method.
All attributes marked with * are required.

Method

Required Participant Attributes

email

email*

none

-*

sms

phone_number*

Two-step authentication method name

The table below shows all methods available for the two_step_authentication_methods object name attribute.

Type

Description

email

The security code is sent by email.

sms

The security code is sent by SMS to a phone.

none

Two-step authentication is disabled.

unknown

Used for future extensions. It can never be input when creating or updating contracts.

Lifecycle

The lifecycle of a contract, also called the contract duration, is the status of the contract after it has been signed.

๐Ÿ“˜

Note:

Lifecycle applies only to signed contracts.

The lifecycle of a contract tells you when a contract starts and ends, whether it's active, ended, or canceled, when a recurring contract enters a new period, etc.

The contract lifecycle consists of:

Lifecycle state

When a participant signs the contract, the contract gets a secondary lifecycle state.

The lifecycle state keeps track of the contract status, which can be awaiting, active, or ended. There are also composite states (see also Composite), or substates, for canceled (for active), and terminated (for ended).

Awaiting

Contracts that have a duration normally become active as soon as they are signed.
However, a contract may have a start date in the future. Those contracts enter the awaiting lifecycle state upon being signed and remain so until the start date comes. Then they transition to active.

๐Ÿ‘

Example:

An example is renting a cabin for one week in June. When the contract is signed in March, the contract does not become active immediately but rather is awaiting until that week in June, when it becomes active.

Active

Active contracts are contracts with a duration where the start date has passed (or was not set), the end date has not yet come, and the contract has not been terminated.

๐Ÿ‘

Example:

Continuing with the cabin example: the contract is only active for that one week in June (before it was awaiting and after the active state, it will be ended.)

Canceled

A contract of a recurring type can be canceled. If canceled before the end of the notice period, the contract will end at the end of the current period. If canceled after the end of the notice period, the contract will end at the end of the next period.
A canceled contract will remain active until the end of the contract period (set by the period attribute, see the table below).

๐Ÿ‘

Example:

Let's take a recurring contract with a one-year duration that starts at the beginning of the year. If you have a one-month notice period and cancel the contract before December, the contract ends at the end of the year. Otherwise, it will be in effect until the end of next year.

Ended

A contract with a duration that has ended gets the ended state. A contract can end naturally (not canceled or manually terminated) or terminated (substate or ended).

Terminated

A contract can be terminated in two ways:

  • The contract is canceled and passed the end date.
  • The contract is terminated manually.
    Terminating a contract manually will make it end immediately.

Lifecycle state attributes

In addition to the awaiting, active, or ended states, known in the contract table as lifecycle, the lifecycle state also refers to a set of values that make up the entire lifecycle state of the contract. The table below displays all attributes available for the lifecycle_state object.

Attribute

Type

Description

composite

string(enum)

The attribute in the lifecycle that summarizes the current lifecycle state attributes. See Composite.

contract_end_time

string(datetime)

The time the contract ends.

contract_start_time

string(datetime)

The time the contract starts.

cancel_time

string(datetime)

The time the contract was canceled. The value is null if not canceled.

has_ended_by_termination

boolean

Indicates whether the contract was manually terminated.

has_passed_notice_period_start_time

boolean

Indicates whether the notice period start time has passed. If you cancel the contract before the expiration of the notice period, the contract will remain in effect until the next period.

is_canceled

boolean

Indicates whether the contract has been canceled.

is_recurring

boolean

Indicates whether the contract gets renewed periodically.

lifecycle_state

string(enum)

See Lifecycle states.

lifecycle_state_updated_time

string(datetime)

The time the lifecycle state was last updated.

notice_period_start_time

string(datetime)

The time the notice period starts.
Note: Notice period always behaves the same, regardless of other settings.

period

integer

The count of the current period starting from 1.

For the 1st period:

  • If you cancel the contract before notice_period_start_time, the contract will end after the 1st period.
  • If you cancel the contract after notice_period_start_time, the contract will be extended to the 2nd period.

For the 2nd period:

  • If you cancel the contract during the 2nd period, the contract will remain active for a time equal to the notice period, after which the contract will end.

period_end_time

string(datetime)

The time the current period ends.

period_start_time

string(datetime)

The time the next period starts.

Composite

The lifecycle composite attribute summarizes the attributes of the current lifecycle state. It is more detailed than the lifecycle_state attribute and is meant to be used to distinguish between all possible contract states of a contract in your code without having to look at other lifecycle attributes.

In addition to the lifecycle_state attribute, the composite attribute indicates whether the contract is recurring, which means that it can be renewed over a set of periods (see the lifecycle_state object Duration types.) It also shows if the recurring contract was canceled. Finally, it shows whether the contract was terminated manually.

Composite

Description

awaiting

The contract has not started yet.

awaiting-recurring

The contract is recurring and has not started yet.

active

The contract has started and is active until itโ€™s canceled or ended naturally.

active-recurring

The contract is recurring. It has started and is active until itโ€™s canceled or ended naturally.

active-canceled-recurring

The contract is recurring. The contract has started, and then someone ended it by canceling the contract.

ended

The contract has ended after being canceled or ended naturally.

ended-terminated

The contract has ended by being terminated.

ended-terminated-recurring

The contract is recurring and has ended by being terminated.

unknown

Used for future extensions.

Lifecycle states

The table below displays all possible values of the lifecycle_state attribute.

Lifecycle

Description

awaiting

The contract has not started yet.

active

The contract has started and is active until itโ€™s canceled or ends naturally.

ended

The contract has ended after being canceled or ended naturally.

unknown

Used for future extensions.

Lifecycle settings

The lifecycle settings determine which lifecycle the contract will go through after it is signed. Will it have a duration? What is the duration? Is it recurring? When can it be canceled? When will it start? Etc.
The table below displays all the attributes available for the lifecycle_settings object.

Attribute

Type

Description

duration

string(duration)

The duration of the contract period; the exact meaning depends on the type. See more in Duration types.

end_date

string(datetime)

The end date of the contract or period; the exact meaning depends on the type. See more in Duraton types.
Note: end_date cannot be combined with initial_duration.

initial_duration

string(duration)

The initial duration of the first period of the contract only works for recurring types.
Note: initial_duration cannot be combined with end_date.

notice_period

string(duration)

The time before the start of a new contract period. During this time, one more period is added when the contract is canceled.

start_date

string(date)

The contract start day.

type

string(enum)

The list of duration types. See Duration types.

Duration types

The table below shows the types of contract duration available for the lifecycle_settings object type attribute.

Duration

Description

no_duration

no_duration is used when there is no contract duration, but you still want to set a fixed start date for the contract. See more in the No duration type explained section.

single_period

The contract is valid for a single period of time, after which it will end.

recurring

The recurring contract will automatically renew for new periods until canceled.

recurring_two_periods

The recurring contract has an initial period of finite duration and renews until the second period of infinite duration (unless canceled).

No duration type explained

The no_duration lifecycle setting is used for a lifecycle with no period, for example, a permanent employment contract.

๐Ÿ“˜

Note:

A contract that does not have a duration section is the same as setting type = no_duration and clearing all other parameters. Please, read our Help Center article about Contract duration and lifecycle settings for more information.

The table below shows different outputs for contracts with the no_duration type depending on the contract start date and signing status:

Start date

Signing time

Response description

No start date

Before and after signing

The "lifecycle_state" will be null and the lifecycle_settings attribute wonโ€™t be null.

With a start date in future

Before signing

The "lifecycle_state" will be null and the lifecycle_settings attribute wonโ€™t be null.

With a start date in future

After signing

Both the "lifecycle_state" and the lifecycle_settings attributes wonโ€™t be null.

With a start date that passed

After signing

The "lifecycle_state" will be null and the lifecycle_settings attribute wonโ€™t be null.

State

The contract state indicates where the contract is in the signing process.

๐Ÿšง

Note:

You cannot change contracts that have been signed or declined.
After a participant has signed the contract, changing the contract will reset their signature, and they will need to sign again.

State

Description

draft

Only the owner-side can view the contract.

pending

The contract is under negotiation.

overdue

The contract signing period has expired, and the contract can no longer be signed. It will revert to pending if the signing period is extended.

signed

All participants signed the contract. The contract is signed.

declined

One participant declined the contract. The contract is declined.

unknown

Used for future extensions.

Updated 16 days ago


Contract


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.