Developer Documentation
IntegrationsHelp CenterSign in

Create a contract with counterparties

Suggest Edits

A counterparty is a legal entity involved in a contract.

In Oneflow, you can create contracts with companies or individual counterparties. See how to create a contract with each type of counterparty in the sections that follow.
Oneflow makes a distinction between counterparties and the party that owns the contract, called the owner-side party.

Create a contract with a company

To create a contract with a company counterparty, you need to add the company’s information to the parties attribute in the request body and set the type attribute for the party added to the company. Each party must have a name and at least one participant.

Step 1. Obtain necessary information

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

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
workspace_id The unique ID of the workspace where you want to create your contract. You can find the workspace ID using the workspaces endpoint.
template_id The unique ID of the template you want to use for creating your contract. You can find the template ID using the templates endpoint.
Parties
parties The array of the contract parties object.
name The name of a contract party in the array.
type Each party in the array of parties must have its type set to company.
Participants
participants [array] The array of contract party participants (at least one.)
name The participant’s name.
delivery_channel Defines the channel that the system will use to send contract-related notifications to the participant. Select this attribute only based on the selected template’s available options. To learn more about delivery_channeltypes, please see Delivery channels.
sign_method Defines the method by which the participant can sign the contract. Select this attribute only based on the selected template’s available options. If the sign method is not provided, it will be set to its default value, standard_esign. To learn more about sign_method types, please see Sign methods.
two_step_authentication_method An optional way to increase contract security by ensuring that only the intended recipient can access the contract. Select this attribute only based on the selected template’s available options. To learn more about two_step_authentication_method types, please see, Two-step authentication methods. Requests made without a user’s email address will be authenticated and authorized as anonymous admin users’ requests.
signatory When signatory is set to true, the participant will be able to sign the contract. In that case, the contract:update permission must be true as well.
email The participant's email attribute is mandatory based on the delivery_channel and two_step_authentication_method, e.g., if the delivery channel is email, then the participant's email is required.
phone_number The participant's phone_number attribute is mandatory based on the delivery_channel and two_step_authentication_method, e.g., if the delivery channel is sms, then the participant's phone_number attribute is required.
Permissions
_permissions [object]
contract:update When set to true, the participant can make changes to the contract. Please read more about permissions here.

Step 2. Run the code

Replace the values of the parameters in the following command with the actual data from your account and run it:

curl --request POST \
  --url https://api.oneflow.com/v1/contracts/create \
  --header 'content-type: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN' \
  --header 'x-oneflow-user-email: USER_EMAIL' \
  --data-raw '{
    "workspace_id": WORKSPACE_ID,
    "template_id": TEMPLATE_ID,
    
    "parties": [
        {
            "country_code": "SE",
            "identification_number": "11223344-5566",
            "name": "Company AB",
            "type": "company",
            "participants": [
                {
                    "_permissions": {
                        "contract:update": true
                    },
                    "delivery_channel": "email",
                    "email": "[email protected]",
                    "identification_number": "10034544-0066",
                    "name": "First Last",
                    "phone_number": "+111222333444",
                    "signatory": true,
                    "sign_method": "standard_esign",
                    "two_step_authentication_method": "email"
                }
            ]
        }
    ]
}'

import requests

headers = {
    'content-type': 'application/json',
    'x-oneflow-api-token': 'API_TOKEN',
    'x-oneflow-user-email': 'USER_EMAIL',
}

data = {
  "workspace_id": WORKSPACE_ID, 
  "template_id": TEMPLATE_ID, 
  "parties": [ 
    { 
      "country_code": "SE", 
      "identification_number": "11223344-5566", 
      "name": "Company AB", 
      "type": "company", 
      "participants": [ 
        { 
          "_permissions": { 
            "contract:update": true 
          }, 
          "delivery_channel": "email", 
          "email": "[email protected]", 
          "identification_number": "10034544-0066", 
          "name": "First Last", 
          "phone_number": "+111222333444", 
          "signatory": true, 
          "sign_method": "standard_esign", 
          "two_step_authentication_method": "email" 
        } 
      ] 
    } 
  ] 
}

response = requests.post('https://api.oneflow.com/v1/contracts/create', 
                         headers=headers, json=data)

print(response.json())

Expected response

This request will output details about the contract with a company counterparty you created in the JSON format:

{
...
   "parties": [
       {
           "_private_ownerside": {
               "created_time": "2021-03-17T11:06:42+00:00",
               "updated_time": null
           },
           "country_code": "SE",
           "id": 300266,
           "identification_number": "5569032989",
           "my_party": true,
           "name": "Owner Party Company",
           "participants": [
               {
                   "_permissions": {
                       "contract:update": true
                   },
                   "_private_ownerside": {
                       "created_time": "2021-03-17T11:06:42+00:00",
                       "first_visited_time": "2021-03-17T11:06:42+00:00",
                       "last_visited_time": "2021-03-17T11:06:42+00:00",
                       "updated_time": "2021-03-17T11:06:42+00:00",
                       "visits": 1
                   },
                   "delivery_channel": "email",
                   "delivery_status": "success",
                   "email": "[email protected]",
                   "id": 123456,
                   "identification_number": "",
                   "my_participant": true,
                   "name": "Owner Party",
                   "organizer": false,
                   "phone_number": "",
                   "sign_method": "standard_esign",
                   "sign_state": "undecided",
                   "sign_state_updated_time": "2021-03-17T11:06:42+00:00",
                   "signatory": true,
                   "title": "CEO",
                   "two_step_authentication_method": "none"
               }
           ],
           "type": "company"
       },
   ],
...
}

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

Create a contract with an individual

To create a contract with an individual counterparty, you need to add the individual’s information to the parties attribute in the request body and set the type attribute to individual. The individual type counterparty can have only one participant.

Step 1. Obtain necessary information

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

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.
Body
workspace_id The unique ID of the workspace where you want to create your contract. You can find the workspace ID using the workspaces endpoint.
template_id The unique ID of the template you want to use for creating your contract. You can find the template ID using the templates endpoint.
name The contract name.
Parties
parties [array] The contract party.
type The contract party type must be set to individual.
Participant
participant [object] The contract party participant (precisely one).
name The name of the participant.
delivery_channel Defines the channel that the system will use to send contract-related notifications to the participant. Select this attribute only based on the selected template’s available options. To learn more about delivery_channel alternatives, please see Delivery channels.
sign_method Defines the method by which the participant can sign the contract. Select this attribute only based on the selected template’s available options. If the sign method is not provided, it will be set to its default value, standard_esign. To learn more about sign_method alternatives, please see Sign methods.
two_step_authentication_method An optional way to increase contract security by ensuring that only the intended recipient can access the contract. Select this attribute only based on the selected template’s available options. To learn more about two_step_authentication_method alternatives, please see, Two-step authentication methods. Requests made without a user’s email address will be authenticated and authorized as anonymous admin users’ requests.
signatory When set to true, the participant will be able to sign the contract. In that case, the contract:update permission must be true as well.
email The participant's email attribute is mandatory based on the delivery_channel and two_step_authentication_method, e.g., if the delivery channel is email, then the participant's email is required.
phone_number The participant's phone_number attribute is mandatory based on the delivery_channel and two_step_authentication_method, e.g., if the delivery channel is sms, then the participant's phone_number attribute is required.
Permissions
_permissions Defines what actions the user is allowed to perform against the contract.
contract:update When set to true, the participant can make changes to the contract. Please read more about permissions here.

Step 2. Run the code

Replace the values of the parameters in the following command with the actual data from your account and run it:

curl --request POST \
  --url https://api.oneflow.com/v1/contracts/create \
  --header 'content-type: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN' \
  --header 'x-oneflow-user-email: USER_EMAIL' \
  --data-raw '{
    "workspace_id": 130406,
    "template_id": 756510,
    "parties": [
        {
            "country_code": "SE",
            "type": "individual",
            "participant": {
                "_permissions": {
                	"contract:update": true
                },
                "delivery_channel": "email",
                "email": "[email protected]",
                "identification_number": "10034544-1166",
                "name": "First Last",
                "phone_number": "+111222333666",
                "signatory": true,
                "sign_method": "standard_esign",
                "two_step_authentication_method": "email"
            }
        }
    ]
}'

import requests

headers = {
    'content-type': 'application/json',
    'x-oneflow-api-token': 'API_TOKEN',
    'x-oneflow-user-email': 'USER_EMAIL',
}

data = '{ "workspace_id": 130406, "template_id": 756510, "parties": [ { "country_code": "SE", "type": "individual", "participant": { "_permissions": { "contract:update": true }, "delivery_channel": "email", "email": "[email protected]", "identification_number": "10034544-1166", "name": "First Last", "phone_number": "+111222333666", "signatory": true, "sign_method": "standard_esign", "two_step_authentication_method": "email" } } ] }'

response = requests.post('https://api.oneflow.com/v1/contracts/create', headers=headers, data=data)

Expected response

This request will return output details about the contract with an individual counterparty you created in the JSON format:

{
...
   "parties": [
       {
           "_private_ownerside": {
               "created_time": "2021-03-17T11:02:32+00:00",
               "updated_time": null
           },
           "country_code": "SE",
           "id": 234567,
           "identification_number": "10034544-1166",
           "my_party": false,
           "name": "First Last",
           "participant": {
               "_permissions": {
                   "contract:update": true
               },
               "_private_ownerside": {
                   "created_time": "2021-03-17T11:02:32+00:00",
                   "first_visited_time": null,
                   "last_visited_time": null,
                   "updated_time": "2021-03-17T11:02:32+00:00",
                   "visits": 0
               },
               "delivery_channel": "email",
               "delivery_status": "success",
               "email": "[email protected]",
               "id": 150233,
               "identification_number": "10034544-1166",
               "my_participant": false,
               "name": "First Last",
               "organizer": false,
               "phone_number": "+111222333666",
               "sign_method": "standard_esign",
               "sign_state": "undecided",
               "sign_state_updated_time": "2021-03-17T11:02:32+00:00",
               "signatory": true,
               "title": "",
               "two_step_authentication_method": "email"
           },
           "type": "individual"
       }
   ],
...
}

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

Getting default values from the template

You can get the default sign method and two-step authentication method for counterparty participants from the template in Oneflow when creating the contracts.

Step 1: Set default values in the template from the Oneflow application

Open the Oneflow template, click on the Settings tab, and select the default signing method and two-factor authentication method.

Step 2: Create the contract

You can now get the default sign method or two-step authentication method from the template when you create the contract through the Public API by sending the contract creation request without including sign_method and two_step_authentication_method in the company or individual party's participant details.

curl --request POST \
  --url https://api.oneflow.com/v1/contracts/create \
  --header 'content-type: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN' \
  --header 'x-oneflow-user-email: USER_EMAIL' \
  --data-raw '{
    "workspace_id": WORKSPACE_ID,
    "template_id": TEMPLATE_ID,
    "parties": [
        {
            "country_code": "SE",
            "identification_number": "11223344-5566",
            "name": "Company AB",
            "type": "company",
            "participants": [
                {
                    "_permissions": {
                        "contract:update": true
                    },
                    "delivery_channel": "email",
                    "email": "[email protected]",
                    "identification_number": "10034544-0066",
                    "name": "First Last",
                    "phone_number": "+111222333444",
                    "signatory": true,
                    "title": "CEO",
                }
            ]
        },
        {
            "country_code": "SE",
            "type": "individual",
            "participant": {
                "_permissions": {
                	"contract:update": true
                },
                "delivery_channel": "email",
                "email": "[email protected]",
                "identification_number": "10034544-1166",
                "name": "First Last",
                "phone_number": "+111222333666",
                "signatory": true
            }
        }
    ]
}'

import requests

headers = {
    'content-type': 'application/json',
    'x-oneflow-api-token': 'API_TOKEN',
    'x-oneflow-user-email': 'USER_EMAIL',
}

data = {
  "workspace_id": WORKSPACE_ID, 
  "template_id": TEMPLATE_ID, 
  "parties": [ 
    { 
      "country_code": "SE", 
      "identification_number": "11223344-5566", 
      "name": "Company AB", 
      "type": "company", 
      "participants": [ 
        { 
          "_permissions": { 
            "contract:update": true 
          }, 
          "delivery_channel": "email", 
          "email": "[email protected]", 
          "identification_number": "10034544-0066", 
          "name": "First Last", 
          "phone_number": "+111222333444", 
          "signatory": true, 
          "sign_method": "standard_esign", 
          "two_step_authentication_method": "email" 
        } 
      ] 
    } 
  ] 
}

response = requests.post('https://api.oneflow.com/v1/contracts/create', 
                         headers=headers, json=data)

print(response.json())

Expected response

This request will return output details about the contract with counterparty details obtained from the template for both company and individual counterparties in JSON format:

{
...
   "parties": [
       {
           "_private_ownerside": {
               "created_time": "2024-07-17T11:02:32+00:00",
               "updated_time": null
           },
           "country_code": "SE",
           "id": 300266,
           "identification_number": "11223344-5566",
           "my_party": false,
           "name": "Company AB",
           "participants": [
               {
                   "_permissions": {
                       "contract:update": true
                   },
                   "_private_ownerside": {
                       "created_time": "2024-07-17T11:02:32+00:00",
                       "first_visited_time": null,
                       "last_visited_time": null,
                       "updated_time": null,
                       "visits": 0
                   },
                   "delivery_channel": "email",
                   "delivery_status": "success",
                   "email": "[email protected]",
                   "id": 123456,
                   "identification_number": "10034544-0066",
                   "my_participant": true,
                   "name": "First Last",
                   "organizer": false,
                   "phone_number": "+111222333444",
                   "sign_method": "standard_esign",
                   "sign_state": "undecided",
                   "sign_state_updated_time": "2024-07-17T11:02:32+00:00",
                   "signatory": true,
                   "title": "CEO",
                   "two_step_authentication_method": "email"
               }
           ],
           "type": "company"
       },
       {
           "_private_ownerside": {
             "created_time": "2024-07-17T11:02:32+00:00",
             "updated_time": null
           },
           "country_code": "SE",
           "id": 234567,
           "identification_number": "",
           "my_party": false,
           "name": "First Last",
           "participant": {
             "_permissions": {
               "contract:update": true
             },
             "_private_ownerside": {
               "created_time": "2024-07-17T11:02:32+00:00",
               "first_visited_time": null,
               "last_visited_time": null,
               "updated_time": null,
               "visits": 0
             },
             "delivery_channel": "email",
             "delivery_status": "success",
             "email": "[email protected]",
             "id": 150233,
             "identification_number": "10034544-1166",
             "my_participant": false,
             "name": "First Last",
             "organizer": false,
             "phone_number": "+111222333666",
             "sign_method": "standard_esign",
             "sign_state": "undecided",
             "sign_state_updated_time": "2024-07-17T11:02:32+00:00",
             "signatory": true,
             "title": "",
             "two_step_authentication_method": "email"
           },
           "type": "individual"
         }
   ],
...
}

🚧

Note:

There are required attributes to get the default two step authentication method from the template.

Eg:

  • Participant email is required to get the default two_step_authentication_method of emailfor a particular counterparty participant from the template.
  • Participant phone_number is required to get the default two_step_authentication_method of sms for a particular counterparty participant from the template.

Please refer Delivery channels for more details.

🚧

Note:

  • If the delivery_channel of a particular counterparty participant is same_device, then the two_step_authentication_method would be none.
  • If the delivery_channel of a particular counterparty participant is same_device, then the sign_method cannot be standard_esign.

Response codes

StatusMeaningDescription
200OKReturns the created contract.
400Bad RequestInvalid format or content of the request.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource.

Updated 1 day ago