Migration checklist for developers
To start with migrating your current API to our new public API, we suggest you follow these steps:
Step 1. Change the base URL.
Step 2. Update your API calls.
Step 3. Update your attributes.
Step 4. Update your error format.
Step 1. Change the base URL
We have updated the base URL in our new API; thus, make sure to change your current base URL as follows:


Step 2. Update your API calls
Endpoints mapping
Find out which endpoints your integration uses and find the equivalents in the new public API using our mapping tables further in this section, and test drive calls with your data.
Utility endpoints mapping
Legacy API | Current API |
---|---|
| |
| |
|
|
We have added a new partner-specific endpoint to streamline selecting data for contract creation.
New endpoint | Description |
---|---|
With the new |
Contracts and templates mappings
- The new contract create endpoint now combines creating contracts with adding products.
- We now have separate endpoints for events.
- It is now possible to add files using a single endpoint.
Legacy API | Current API |
POST/agreements/
POST/api/agreements/{contract_id}/products/ |
POST/contracts/create |
GET/agreements/{contract_id} |
GET/contracts/{contract_id} |
Events are part of the agreement entity. | GET/contracts/{contract_id}/events |
Events are part of the agreement entity. | GET/contracts/{contract_id}/events/
{event_id} |
POST/agreements/{contract_id}/attachments/
POST/agreements/{contract_id}/pdfs/ |
POST/contracts/{contract_id}/files |
POST/agreements/{contract_id}/participants/
{participant_id}/tokens |
POST/contracts/{contract_id}/
participants/{participant_id}/
access_link |
GET/templates/ |
GET/templates |
Template types and data fields mapping
Legacy API | Current API |
PUT/data_field_sets/{data_field_set_id}/
fields/ |
PUT/template_types/{template_type_id}/
data_fields |
GET/data_field_sets/{data_field_set_id}
/fields/ |
GET/helpers/template_types/
{template_type_id}/data_fields |
GET/ext/templategroups/{template_type_id} |
GET/template_types/{template_type_id} |
Update your code
Update your app code by replacing your current API calls with the new public API calls.
In the examples below, we will consider the most commonly used endpoints:
Please, check out the Tutorials section to learn about the most common scenarios of using the new Oneflow endpoints and test drive your API calls using the Postman collection.
Create a contract: syntax comparison
When you create a contract, make the following changes in your code:
- Change the base URL.
- Use the
contracts/create
endpoint instead ofagreements
. - Specify the
x-oneflow-api-token
(formerX-Flow-API-Token)
and user email header parameters.
Note:
Some header parameters, such as
X-Flow-Current-Position
,Cookie
, andsource_id
, have been deprecated.
- Specify the contract
workspace_id
and thetemplate_id
.


GET a contract: syntax comparison
When getting a contract by its ID, perform the following steps:
- Change the base URL.
- Use the
GET /contracts/{contract_id}
endpoint instead ofGET/agreements/{agreement_id}
. - Specify the
x-oneflow-api-token
(formerX-Flow-API-Token)
and user email header parameters.
Note:
Some header parameters, such as
X-Flow-Current-Position
, have been deprecated.


Helpers endpoint: syntax comparison
You can now get all the information related to a contract using a single endpoint. For example, if you need to get the data required to create a contract, such as workspace
(formerly collection
) and template
, you no longer need to call two endpoints to get them, instead use the helpers/contract_create_data
endpoint:
- Change the base URL.
- Use the
helpers/contract_create_data
endpoint. - Specify the
x-oneflow-api-token
(formerX-Flow-API-Token)
and user email header parameters.


Step 3. Update your attributes
Find out which attributes your integration uses and find the equivalents in the new public API using our mapping table. Then, update your app code by replacing your current attributes with the new ones.
Attribute mapping
Find out which attributes your integration uses and find the equivalents in the new public API using our mapping tables below, and test drive calls with your data.
Legacy name | Current name | Description |
---|---|---|
acl | _permissions | The |
data | data_fields | The legacy |
parties | parties | The |
preprocessed_product_boxes | product_groups | The |
state | state | The name of the |
user_role | is_admin | The |
fullname | name | The |
Updating your code
Update your app code by replacing your current API attributes with the new attributes.
In the example below, we will consider the GET a contract API call response.
GET a contract API call response: syntax comparison


Step 4. Update your error format
We have updated our error responses to provide you with all the details you need to make your integration as reliable and user-friendly as possible.
Update the error responses in your application to use the public API errors.
Error responses format: syntax comparison


Please read our dedicated section on how to handle errors.
Updated 3 months ago