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 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:

https://api.oneflow.com/v1.

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
`GET/ping`	`GET/ping`
`GET/collections/`	`GET/workspaces`
`GET/positions/`	`GET/accounts/me`. Only returns the data that is part of the `account` attribute. `GET/users`. Only returns position-specific data. Account data is not included.

We have added a new partner-specific endpoint to streamline selecting data for contract creation.

New endpoint	Description
`GET/helpers/`	With the new `helpers` endpoint, you can retrieve important information related to contract creation. See the list of available parameters for this endpoint in the API Reference documentation.

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 of agreements.
Specify the x-oneflow-api-token (former X-Flow-API-Token) and user email header parameters.

🚧
Note:
Some header parameters, such as X-Flow-Current-Position, Cookie, and source_id, have been deprecated.

Specify the contract workspace_id and the template_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 of GET/agreements/{agreement_id}.
Specify the x-oneflow-api-token (former X-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 (former X-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 `acl` attribute is now `_permissions`. See more in Permissions.
data	data_fields	The legacy `data` attribute is used for all data in a contract, such as `data_fields`, `assets`, `text`, and `products`. In the current API, if there are `data_fields`, `product`, or `asset` (now `file`) attributes in the contract, we return each one in a separate attribute. See more in Data field, Product group, and Contract file.
parties	parties	The `parties` attribute name has not changed; however, `orgnr` is now `identification_number`, `self` is now `my_party`, and `consumer` is `type`. We now use `true` or `false` for boolean fields like `self` and `consumer` instead of `0` or `1`. See more in Party.
preprocessed_product_boxes	product_groups	The `preprocessed_product_boxes` attribute is now `product_groups`, and the `count` and the `count_type` attributes are now a `quantity` object. See more in Product group.
state	state	The name of the `state` attribute has not changed, but its value is now a `string` rather than an `integer`, as shown in this list: `0: draft`, `1: pending`, `2: overdue`, `3: signed`, `4: signed`, `5: declined`, `7: declined`, See more in State.
user_role	is_admin	The `user_role` attribute has been simplified to `is_admin`, and is now a `boolean` rather than a `string`. See more in User.
fullname	name	The `fullname` attribute has been shortened to `name`. See more in User.

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.