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.

AttributeTypeDescription
_linksobjectContains links to endpoints associated with the parent object. See Links.
_privateobjectContains attributes that are only visible to the party of the current user. See Private.
_private_ownersideobjectContains attributes that are only visible to the owner-side party. See Private ownerside.
_permissionsobjectContains permissions of the current user for various operations possible on the contract. See Permissions.
available_optionsobjectGives information about the capabilities of the contract. See Available options.
data_fieldsarrayThe 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
idinteger(signed_integer_id)The unique ID of the contract.
lifecycle_stateobjectKeeps track of the contract status. See Lifecycle state.
lifecycle_settingsobjectContains settings available for the lifecycle. See Lifecycle settings.
linksarrayThe list of linked contracts with their link types. See Links.
partiesarrayThe list of parties in the contract, representing companies, organizations, individuals, government departments, etc. See Party.
product_groupsarrayThe list of product groups. See Product group.
published_timestring(datetime)The time the contract was published.
signing_period_expiry_timestring(datetime)The time during which a signatory can sign the contract.
statestring(enum)Indicates the status of the contract in the signing process. See State.
state_updated_timestring(datetime)Time of the last update of the contract status.
updated_timestring(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.

AttributeTypeDescription
namestringThe name of the contract.
signing_period_expirationobjectThe deadline for signing the contract. See Signing period expiration.
valueobjectThe deal size of a contract expressed in monetary value. See Value.
workspace_idintThe ID of the workspace that owns the template used to create the contract.

Signing period expiration

The signing_period_expiration object contains attributes related to the contract signing deadline.

There are three types of the signing_period_expiration setting:

  • never
  • days_after_publish
  • fixed_date.

πŸ“˜

Note:

You can specify the days_after_published type only before the contract is published, and once the contract is published, the system will convert it to fixed_date.

AttributeTypeDescriptionRequired
typestring(enum)The type of expiration.
Can be:
- never
- days_after_publish
- fixed_date.
Always.
expire_days_after_publishintThe number of days the contract is available for signing after it has been published.When type == days_after_publish.
expire_datestring(date)The final day the contract is valid for signing.When type == fixed_date.

Value

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

AttributeTypeDescription
amountamountAmount indicating the total value of the contract.
currencystring(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.

AttributeTypeDescription
created_timestring(datetime)The time the contract was created.
template_idintThe ID of the template used to create the contract.
template_type_idintThe 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.

AttributeTypeDescription
contract:deletebooleanIndicates 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.

AttributeTypeDescription
can_receive_attachmentsbooleanIndicates 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_pdfbooleanIndicates 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_productsbooleanIndicates 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_channelsarray[object]Indicates the available methods by which the contract can be delivered to its participants. See Delivery channels.
sign_methodsarray[object]Shows available methods of signing contracts. See Sign methods.
two_step_authentication_methodsarray[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.

AttributeTypeDescription
namestringThe name of the delivery channel. See Delivery channel name.
preferredbooleanIndicates which delivery channel has been set as preferred by the template designer.
required_participant_attributesarray[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 **.

MethodRequired participant attributesAllowed sign methods
emailemail*All listed here.**
none-*All listed here.**
same_devicesign_method*All listed here except standard_esign.**
smsphone_number*All listed here.**

Delivery channel name

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

ChannelDescription
emailThe counterparty will receive an email with a link to the contract.
smsThe counterparty will receive an SMS with a link to the contract.
same_deviceThe 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.
noneThe contract will not be delivered when it is published. Access tokens can be requested after publish.
unknownUsed 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.

AttributeTypeDescription
namestringThe name of the method of signing the contract. See Sign method name.
preferredbooleanIndicates 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.

MethodDescription
standard_esignThis 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.
smsE-signature with an SMS code.
swedish_bankidE-signature with a Swedish BankID.
norwegian_bankidE-signature with a Norwegian BankID.
danish_nemidE-signature with a Danish NemID.
finnish_bankidE-signature with a Finnish BankID.
unknownUsed 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.

AttributeTypeDescription
namestringThe name of the two-step authentication method. See Two-step authentication method name.
preferredbooleanIndicates the two-step authentication method that has been set as preferred by the template designer.
required_participant_attributesarray[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.

MethodRequired Participant Attributes
emailemail*
none-*
smsphone_number*

Two-step authentication method name

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

TypeDescription
emailThe security code is sent by email.
smsThe security code is sent by SMS to a phone.
noneTwo-step authentication is disabled.
unknownUsed 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.

AttributeTypeDescription
compositestring(enum)The attribute in the lifecycle that summarizes the current lifecycle state attributes. See Composite.
contract_end_timestring(datetime)The time the contract ends.
contract_start_timestring(datetime)The time the contract starts.
cancel_timestring(datetime)The time the contract was canceled. The value is null if not canceled.
has_ended_by_terminationbooleanIndicates whether the contract was manually terminated.
has_passed_notice_period_start_timebooleanIndicates 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_canceledbooleanIndicates whether the contract has been canceled.
is_recurringbooleanIndicates whether the contract gets renewed periodically.
lifecycle_statestring(enum)See Lifecycle states.
lifecycle_state_updated_timestring(datetime)The time the lifecycle state was last updated.
notice_period_start_timestring(datetime)The time the notice period starts.
Note: Notice period always behaves the same, regardless of other settings.
periodintegerThe 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_timestring(datetime)The time the current period ends.
period_start_timestring(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.

CompositeDescription
awaitingThe contract has not started yet.
awaiting-recurringThe contract is recurring and has not started yet.
activeThe contract has started and is active until it’s canceled or ended naturally.
active-recurringThe contract is recurring. It has started and is active until it’s canceled or ended naturally.
active-canceled-recurringThe contract is recurring. The contract has started, and then someone ended it by canceling the contract.
endedThe contract has ended after being canceled or ended naturally.
ended-terminatedThe contract has ended by being terminated.
ended-terminated-recurringThe contract is recurring and has ended by being terminated.
unknownUsed for future extensions.

Lifecycle states

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

LifecycleDescription
awaitingThe contract has not started yet.
activeThe contract has started and is active until it’s canceled or ends naturally.
endedThe contract has ended after being canceled or ended naturally.
unknownUsed 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.

AttributeTypeDescription
durationstring(duration)The duration of the contract period; the exact meaning depends on the type. See more in Duration types.
end_datestring(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_durationstring(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_periodstring(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_datestring(date)The contract start day.
typestring(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.

DurationDescription
no_durationno_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_periodThe contract is valid for a single period of time, after which it will end.
recurringThe recurring contract will automatically renew for new periods until canceled.
recurring_two_periodsThe 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 dateSigning timeResponse description
No start dateBefore and after signingThe "lifecycle_state" will be null and the lifecycle_settings attribute won’t be null.
With a start date in futureBefore signingThe "lifecycle_state" will be null and the lifecycle_settings attribute won’t be null.
With a start date in futureAfter signingBoth the "lifecycle_state" and the lifecycle_settings attributes won’t be null.
With a start date that passedAfter signingThe "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.

StateDescription
draftOnly the owner-side can view the contract.
pendingThe contract is under negotiation.
overdueThe contract signing period has expired, and the contract can no longer be signed. It will revert to pending if the signing period is extended.
signedAll participants signed the contract. The contract is signed.
declinedOne participant declined the contract. The contract is declined.
unknownUsed for future extensions.

Links

Related contracts can be linked to each other. The list of linked contracts with their link types will be listed under links.

πŸ“˜

Note:

You can have multiple contracts and different types of relationships linked to the same contract.

The table below displays all the attributes available for a link object.

AttributeTypeDescription
idinteger(signed_integer_id)The unique ID of the link.
linked_contractinteger(signed_integer_id)The unique ID of the linked contract.
typestring(enum)The type of the link, which describes the relationship between the two contracts.
Can be one of the followings:
amends, amended_by, sub_contract , main_contract, replaced_by, replaces, relates_to

🚧

Note:

In the API response, the link type represent the target contract relationship to the main contract. However, in Oneflow application it will represent in other way around (Main contract relationship to the target contract).

If we take the main contract as X and the target contract as Y, following table explains how the API response and Oneflow application represent the relationship between two contracts.

API responseOneflow application
Y relates_to XX relates_to Y
Y is the main_contract of XX is a sub_contract of Y
Y is a sub_contract of XX is the main_contract of Y
Y replaces XX is replaced_by Y
Y is replaced_by XX replaces Y
Y amends XX amended_by Y
Y amended_by XX amends X