Get data to create a contract
In many cases, when building an integration with Oneflow, hardcoding the workspace and template works just fine, as we already described in the tutorials for creating contracts.
However, mostly this solution is not optimal. For instance, it could hardly be possible to build a CRM integration with only one workspace and one template available. What if a CRM user doesn’t have access to that workspace? Or if the template is changed to no longer have the template type required by the integration?
To solve these issues, you can fetch relevant options dynamically by querying the workspaces and templates endpoints. Together, these endpoints return all workspaces and templates available to a specific user within an integration.
These endpoints allow you to retrieve:
Workspaces: All workspaces where the user has permission to create contracts.Templates: All active templates optionally filtered by template type.
For more information about the template type extension, please see Building a partner system integration.
Step 1. Obtain necessary information
To run requests for these endpoints, you’ll need the following header 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. |
Query Parameters by Endpoint
| Parameter | Type | Details | Description |
|---|---|---|---|
filter[id] | String | Length <= 200 | Retrieve specific workspaces by providing a comms-seperated list of workspace IDs. |
filter[name] | String | Length <= 30 | Filter workspaces by name. |
filter[workspace_admin] | String(enum) | Option: true, false | Filter workspaces based on workspace admin privilege. When set to true and the user has workspace admin privileges, all workspaces within the account are returned; otherwise, only workspaces accessible to the user are returned. |
limit | Integer | Default: 100 | Number of items per page. |
offset | Integer | Default: 0 | Page offset for pagination. |
sort | String | A comma-sperated list of columns by which results are sorted. |
| Parameter | Type | Details | Description |
|---|---|---|---|
extension_type | String | Length: 1 to 100 Patern: ^[a-zA-Z0-9_]+$ | Template type subtype used by partner system integration. See Building a partner system integration for details. |
filter[active] | String(enum) | Option: true, false | Filter templates whether they are active or inactive. |
filter[blueprint_ids] | String | Length <= 100 | Filter templates with blueprints that are in the specified comma-separated list of blueprint IDs. |
filter[playbook_ids] | String | Length <= 100 | Filter templates with playbooks that are in the specified comma-separated list of playbook IDs. |
filter[workspace_ids] | String | Length <= 100 | Filter templates from workspaces that are in the specified comma-separated list of workspace IDs. |
limit | Integer | Default | Number of items per page. |
offset | Integer | Default: 0 | Page offset for pagination. |
sort | String | A comma-separated list of columns by which results are sorted. | |
template_type_id | Integer | None | The unique ID of a template type. You can find template type ID using the GET/templates endpoint. |
Step 2. Run the code
1. Workspaces Endpoint
Example request:
curl --request GET \
--url 'https://api.oneflow.com/v1/workspaces?offset=0&limit=100' \
--header 'Accept: application/json' \
--header 'x-oneflow-api-token: API_TOKEN' \
--header 'x-oneflow-user-email: USER_EMAIL'import requests
headers = {
'Accept': "application/json",
'x-oneflow-api-token': API_TOKEN,
'x-oneflow-user-email': USER_EMAIL
}
response = requests.get('https://api.oneflow.com/v1/workspaces?offset=0&limit=100',
headers=headers)
print(response.json())Expected response:
The above call will result in output similar to the following:
{
"_links": {
"next": {
"href": null
},
"previous": {
"href": null
},
"self": {
"href": "https://api.oneflow.com/v1/workspaces?offset=0&limit=100"
}
},
"count": 2,
"data": [
{
"_integration_permissions": [],
"_links": {
"self": {
"href": "https://api.oneflow.com/v1/workspaces/130001"
}
},
"_permissions": {
"contract:create": true
},
"company_name": "My Company AB",
"country_code": "SE",
"created_time": "2019-05-16T10:11:48+00:00",
"date_format": "YYYY-MM-DD",
"description": "A workspace for holding HR templates.",
"id": 130001,
"name": "Best Workspace",
"registration_number": "11223344-0000",
"type": "Sales",
"updated_time": "2021-07-22T11:59:11+00:00"
},
{
"_integration_permissions": [],
"_links": {
"self": {
"href": "https://api.oneflow.com/v1/workspaces/130002"
}
},
"_permissions": {
"contract:create": true
},
"company_name": "",
"country_code": "",
"created_time": "2020-01-05T10:44:42+00:00",
"date_format": "",
"description": "A workspace for holding sales templates.",
"id": 130002,
"name": "Sales Workspace",
"registration_number": "",
"type": "Legal",
"updated_time": "2020-02-12T13:44:42+00:00"
}
]
}Response codes:
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Returns the list of workspaces. |
| 400 | Bad Request | Invalid format or content of the request. |
| 401 | Unauthorized | The API token or the user email is invalid. |
| 403 | Forbidden | The request is not authorized by the server. |
2. Templates Endpoint
Example request:
curl --request GET \
--url 'https://api.oneflow.com/v1/templates?offset=0&limit=100' \
--header 'Accept: application/json' \
--header 'x-oneflow-api-token: API_TOKEN' \
--header 'x-oneflow-user-email: USER_EMAIL'import requests
headers = {
'Accept': "application/json",
'x-oneflow-api-token': API_TOKEN,
'x-oneflow-user-email': USER_EMAIL
}
response = requests.get('https://api.oneflow.com/v1/templates?offset=0&limit=100',
headers=headers)
print(response.json())Expected response:
The above call will result in output similar to the following:
{
"_links": {
"next": {
"href": null
},
"previous": {
"href": null
},
"self": {
"href": "https://api.oneflow.com/v1/templates?limit=100&offset=0"
}
},
"count": 2,
"data": [
{
"_links": {
"self": {
"href": "https://api.oneflow.com/v1/templates/170001"
},
"template_type": {
"href": "https://api.oneflow.com/v1/template_types/220001"
}
},
"_private": {
"date_format": "YYYY-MM-DD,",
"language": "en,",
"name": "Sales Proposal template,",
"signing_period_expiration": {
"expire_days_after_publish": "14,",
"type": "days_after_publish"
},
"workspace_id": 130001
},
"available_options": {
"can_receive_attachments": false,
"can_receive_expanded_pdf": false,
"can_receive_products": true,
"delivery_channels": [
{
"name": "email",
"preferred": true,
"required_participant_attributes": [
"email"
]
},
{
"name": "none",
"preferred": false,
"required_participant_attributes": []
},
{
"name": "same_device",
"preferred": false,
"required_participant_attributes": [
"sign_method"
]
},
{
"name": "sms",
"preferred": false,
"required_participant_attributes": [
"phone_number"
]
}
],
"sign_methods": [
{
"name": "sms",
"preferred": false
},
{
"name": "standard_esign",
"preferred": true
}
],
"two_step_authentication_methods": [
{
"name": "email",
"preferred": false,
"required_participant_attributes": [
"email"
]
},
{
"name": "none",
"preferred": true,
"required_participant_attributes": []
},
{
"name": "sms",
"preferred": false,
"required_participant_attributes": [
"phone_number"
]
}
]
},
"configuration": {
"default_counterparty_type": "company",
"default_creator_roles": {
"_permissions": {
"contract:update": true
},
"organizer": false,
"signatory": true
}
},
"created_time": "2023-04-20T11:49:44+00:00",
"draft_approval_workflow": null,
"pending_approval_workflow": null,
"id": 170001,
"name": "Sales Proposal template",
"tags": [],
"template_active": true,
"template_type": {
"created_time": "2021-07-05T07:28:26+00:00",
"description": "Hubspot data fields",
"extension_type": "hubspot",
"id": 220001,
"name": "Hubspot Template",
"updated_time": "2023-04-03T12:41:41+00:00"
},
"playbook": {
"id": 180001,
"name": "Hubspot Integration Template"
},
"blueprints": [
{
"id": 180101,
"name": "Hubspot Integration Template"
},
{
"id": 180102,
"name": "Teamtailor Integration Template"
}
],
"updated_time": "2023-04-20T11:50:20+00:00",
"workspaces": [
{
"id": 130001,
"name": "Best Workspace"
},
{
"id": 130002,
"name": "Sales Workspace"
}
]
},
{
"_links": {
"self": {
"href": "https://api.oneflow.com/v1/templates/170002"
},
"template_type": {
"href": null
},
"_private": {
"date_format": "YYYY-MM-DD,",
"language": "en,",
"name": "Test template,",
"signing_period_expiration": {
"expire_days_after_publish": "14,",
"type": "days_after_publish"
},
"workspace_id": 130001
}
},
"available_options": {
"can_receive_attachments": false,
"can_receive_expanded_pdf": false,
"can_receive_products": false,
"delivery_channels": [
{
"name": "email",
"preferred": true,
"required_participant_attributes": [
"email"
]
},
{
"name": "none",
"preferred": false,
"required_participant_attributes": []
},
{
"name": "same_device",
"preferred": false,
"required_participant_attributes": [
"sign_method"
]
},
{
"name": "sms",
"preferred": false,
"required_participant_attributes": [
"phone_number"
]
}
],
"sign_methods": [
{
"name": "sms",
"preferred": false
},
{
"name": "standard_esign",
"preferred": true
}
],
"two_step_authentication_methods": [
{
"name": "email",
"preferred": false,
"required_participant_attributes": [
"email"
]
},
{
"name": "none",
"preferred": true,
"required_participant_attributes": []
},
{
"name": "sms",
"preferred": false,
"required_participant_attributes": [
"phone_number"
]
}
]
},
"configuration": {
"default_counterparty_type": "individual",
"default_creator_roles": {
"_permissions": {
"contract:update": true
},
"organizer": true,
"signatory": false
}
},
"created_time": "2023-04-26T06:50:39+00:00",
"draft_approval_workflow": null,
"id": 170002,
"name": "Test template",
"pending_approval_workflow": null,
"tags": [
{
"id": 380001,
"name": "tag one"
}
],
"template_active": true,
"template_type": null,
"updated_time": "2023-04-26T06:52:30+00:00",
"workspaces": [
{
"id": 130001,
"name": "Best Workspace"
}
]
}
]
}Response codes:
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Returns the list of templates. |
| 400 | Bad Request | Invalid format or content of the request. |
Updated 13 days ago
Did this page help you?