IntegrationsHelp CenterSign in

Migration checklist for developers

Suggest Edits

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.

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

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.

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.

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.

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.

Updated 3 months ago

Did this page help you?