Contract
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. |
| attachment_file_groups | array | Contains the list of attachments in the contract. See Attachment file groups. |
| 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. |
| links | array | The list of linked contracts with their link types. See Links. |
| parties | array | The list of parties in the contract, representing companies, organizations, individuals, government departments, etc. See Party. |
| pdf_file_groups | array | Contains the list of PDFs in the contract. See PDF file groups. |
| 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 |
|---|---|---|
| name | string | The name of the contract. |
| signing_period_expiration | object | The deadline for signing the contract. See Signing period expiration. |
| value | object | The deal size of a contract expressed in monetary value. See Value. |
| workspace_id | int | The 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_publishedtype only before the contract is published, and once the contract is published, the system will convert it tofixed_date.
| Attribute | Type | Description | Required |
|---|---|---|---|
| type | string(enum) | The type of expiration. Can be: - never- days_after_publish- fixed_date. | Always. |
| expire_days_after_publish | int | The number of days the contract is available for signing after it has been published. | When type == days_after_publish. |
| expire_date | string(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.
| 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.
Attachment file groups
The attachment_file_groups contain the list of files uploaded to the contract as attachments.
Attachment file groups attributes
The table below contains the list of all the attributes available for a Attachment file groups within a contract.
| Attribute | Type | Description |
|---|---|---|
| _private_ownerside | object | The attachment file group attributes that are visible only to the owner-side party. See Private owner-side attachment file groups. |
| files | array | The list of attachments in the contract. |
| id | integer(signed_integer_id) | The ID of the attachment file group. |
| type | string(enum) | The file uploaded to the contract as an attachment. |
Private owner-side attachment file groups
| Attribute | Type | Description |
|---|---|---|
| created_time | string(datetime) | The date and time when the attachment file group was created. |
| updated_time | string(datetime) | The date and time when the attachment file group was last updated. |
Files
| Attribute | Type | Description |
|---|---|---|
| _private_ownerside | object | The attachment file group attributes that are visible only to the owner-side party. See Private owner-side attachment file groups. |
| extension | string(enum) | Indicates the attached file extension (see Attachments). See also, Contract file extensions. |
| id | integer(signed_integer_id) | The ID of the attachment file. |
| name | string | If the file name contains only non-US-ASCII characters, the default filename will be generated as type_id.extension. For example, a file named *-+%&.png will be changed to attachment_123.png, where 123 is the value of the id attribute. |
| size | integer | The size of the attachment. |
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 the 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 the API, you can add products when there are one or more Product table sections in the contract. In this case, the true value indicates that the contract contains one or more Product table sections, 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, 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 **.
Note:
For a free plan account, you can select only
noneasdelivery_channelmethod and onlystandard_esignassign_methodwhen adding a counterparty participant.
Delivery channel name
The table below displays all methods available for the delivery_channels object name attribute.
| Channel | Description |
|---|---|
| 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. |
| email_and_sms | The counterparty will receive an email and 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_mitid | E-signature with a Danish MitID. (This was previously known as Danish NemID.) |
| finnish_bankid | E-signature with a Finnish BankID. |
| handwritten_signature | Drawing of handwritten signature. |
| eid_sign | E-signature with any other electronic ID. |
| 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* | |
| none | -* |
| sms | phone_number* |
| personal_identification | identification_number* |
Two-step authentication method name
The table below shows all methods available for the two_step_authentication_methods object name attribute.
| Type | Description |
|---|---|
| The security code is sent by email. | |
| sms | The security code is sent by SMS to a phone. |
| personal_identification | A unique identification for a person such as date of birth, social security number, personal number, etc. |
| 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_durationand 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. |
PDF file groups
PDF file groups contain the list of files uploaded as expanded_pdf to the contract (see Create a contract with a PDF).
PDF file groups attributes
The table below contains the list of all the attributes available for a PDF file groups within a contract.
| Attribute | Type | Description |
|---|---|---|
| _private_ownerside | object | The PDF file group attributes that are visible only to the owner-side party. See Private owner-side pdf file groups. |
| files | array | The list of PDFs in the contract. |
| id | integer(signed_integer_id) | The ID of the PDF file group. |
| type | string(enum) | The file uploaded to the contract as an expanded PDF |
Private owner-side pdf file groups
| Attribute | Type | Description |
|---|---|---|
| created_time | string(datetime) | The date and time when the pdf file group was created. |
| updated_time | string(datetime) | The date and time when the pdf file group was last updated. |
Files
| Attribute | Type | Description |
|---|---|---|
| _private_ownerside | object | The pdf file group attributes that are visible only to the owner-side party. See Private owner-side pdf file groups. |
| extension | string(enum) | Indicates the file extension (see PDF Document). |
| id | integer(signed_integer_id) | The ID of the pdf file. |
| name | string | If the file name contains only non-US-ASCII characters, the default filename will be generated as type_id.extension. For example, a file named *-+%&.png will be changed to pdf_123.pdf, where 123 is the value of the id attribute. |
| size | integer | The size of the pdf. |
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. |
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.
| Attribute | Type | Description |
|---|---|---|
| id | integer(signed_integer_id) | The unique ID of the link. |
| linked_contract | integer(signed_integer_id) | The unique ID of the linked contract. This is not available for links with the type external. |
| type | string(enum) | The type of the link, which describes the relationship between the two contracts. Can be one of the following: amends, amended_by, sub_contract, main_contract, replaced_by, replaces, relates_to, external |
| external_link | string | The URL that links the contract to an external entity (i.e. a website). This is only used with links with the type external. |
| external_title | string | The name of the external_link. This is only used with links with the type external. |
Note:
In the API response, the link type represents the target contract relationship to the main contract. However, in the Oneflow application, this is represented the other way around (i.e. Main contract relationship to the target contract). There is no difference for links with the type
external.
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 response | Oneflow application |
|---|---|
| Y relates_to X | X relates_to Y |
| Y is the main_contract of X | X is a sub_contract of Y |
| Y is a sub_contract of X | X is the main_contract of Y |
| Y replaces X | X is replaced_by Y |
| Y is replaced_by X | X replaces Y |
| Y amends X | X amended_by Y |
| Y amended_by X | X amends Y |
Updated 1 day ago