Freshservice public APIs are primarily intended for integration purposes, and not recommended for large-volume API transactions (see Freshservice API documentation).
Due to the complexities in differentiating normal API transactions vs. migrations, data migration partners experience the following challenges.
When rate limits per minute are not sufficient, it results in longer migration duration.
When high level of data is transferred, the Agents (whose API keys are used for migration) are blocked.
When tickets are migrated, a large number of notifications and emails are triggered.
Public APIs are not flexible in supporting all the migration requirements.
This article describes the process to migrate data via public APIs for Freshservice’s data migration partners.
Submit the data migration request
As part of the migration process, Freshservice data migration partners are required to submit a request.
To submit a data migration request:
Login to your Freshservice account.
Go to https://fsdevops.Freshservice.com/support/catalog/items/142.
Enter the data migration partner name in the Partner Name field.
Select the relevant region from the Region dropdown. For example, EU.
Enter your account ID details in the Account ID and Confirm Account ID fields.
Enter the approximate number of tickets that are expected to be migrated in the Approximate Number of Tickets field.
Select the relevant migration initiation date from the Planned Start Date option.
Select the relevant migration completion date from the Planned End Date option.
Note: Ensure that the planned start and end dates are selected for a future time-period (not current/present).
Select the relevant option from the Increased API Limit required? dropdown.
Select Yes, if the migration requires a higher API limit (700 per minute) as compared to the current API rate limit (per minute) for your account. See Submit additional items for more information.
Select No, if the standard limit is sufficient.
Click Place Request.
Submit additional items
For increasing the minute-level API limit or evaluating API pack add-ons, you need to provide additional details, and then submit the data migration request.
Expand the Additional items section on the form request page.
Select the Api Minute Level Limit Setter checkbox.
Note: Review the limits under Migration Purpose and API Packs (Pack 1 and Pack 2).
Enter your account ID details in the Account ID field.
Select the relevant request type from the Request type dropdown.
If you’ve selected the Migration limit increase request type, select the relevant option from the Migration Duration dropdown.
If you’ve selected the Choose Addon pack request type, select the relevant option from the Choose Addon pack dropdown.
Enter a relevant reason in the Reason field.
Enter the relevant URL in the Support Ticket URL field.
Submit the request.
After you submit the data migration request, it is sent for approval to the Freshservice team.
After the request is approved:
A token is generated and added as a note in your Service Request ticket (as highlighted in the following figure).
The rate limit is increased to 700 per minute for the required duration.
Important:
The generated token is a unique token, which works as a combination only for the data migration partner and the associated customer account.
This token can be used only for the defined duration against the associated customer account.
Add token details to your API Platform
After the token is generated, you need to add the token details to the API Platform you use for managing APIs (for example, Postman).
On the Postman app, go to the collection where Freshservice Public APIs are stored, such as Tickets, Changes, or Service Items.
In the Headers section of the Public API used for migration, add the token in the following key-value pair format:
Key: X-FW-Partner-Migration.
Value: The token generated after approval.
For example, for the Tickets API, the Header would be similar to the key-value pair highlighted in the following figure:
(Only for the duration of the migration) Passing this Header along with the usual API payload will result in the following:
Agents will be whitelisted from spamwatcher (not blocked).
The following sub-module limits will apply.
Future enhancements to API Data Migration
The following enhancements related to API Data Migration are planned to be included, as part of the future roadmap:
Notifications will not be sent out for tickets which are migrated.
Separate limits will be allocated for migration, which will be different from non-migration activity limits.
Sub-limits for migration will be removed (in which case the Header token can be used to identify migration vs. non-migration activity).
Migration-specific functionality (based on Header token) will be extended to other modules.
