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:

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

940940

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 APICurrent API
GET/pingGET/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 endpointDescription
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

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:

  1. Change the base URL.
  2. Use the contracts/create endpoint instead of agreements.
  3. 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.

  1. Specify the contract workspace_id and the template_id.
19041904

GET a contract: syntax comparison

When getting a contract by its ID, perform the following steps:

  1. Change the base URL.
  2. Use the GET /contracts/{contract_id} endpoint instead of GET/agreements/{agreement_id}.
  3. 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.

16321632

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:

  1. Change the base URL.
  2. Use the helpers/contract_create_data endpoint.
  3. Specify the x-oneflow-api-token (former X-Flow-API-Token) and user email header parameters.
17821782

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 nameCurrent nameDescription
acl_permissionsThe acl attribute is now _permissions. See more in Permissions.
datadata_fieldsThe 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.
partiespartiesThe 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_boxesproduct_groupsThe 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.
statestateThe 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_roleis_adminThe user_role attribute has been simplified to is_admin, and is now a boolean rather than a string. See more in User.
fullnamenameThe 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

19941994

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

13421342

Please read our dedicated section on how to handle errors.