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 |
|---|---|
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/createendpoint 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_idand 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_dataendpoint. - 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 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 almost 2 years ago