Table of contents
Part 1 - Usage Guide for Bulk APIs
Step by step details on how to use the Bulk API end point:
How to prepare & format their data
General guidelines for using Bulk APIs - Number of records which can be processed as part of Bulk API, using normal APIs for non-bulk use cases
Pre-requisites for using Bulk APIs ( Attachments to be stored in Public Url etc)
Specific call outs (FYIs oh what they can expect in terms of behavior of the Bulk APIs) - Notification disabling for Bulk APIs, etc
Any other Bulk API specific technical detail which hasn't been captured above
Part 2/3/4 - For each of the Bulk APIs, to cover the following
-- Bulk API endpoint detail
-- Payload request details
-- Payload response details
-- Error handling
-- Rate limits applicable per min for a Bulk API
-- Any other endpoint specific technical detail which hasn't been captured above
----------------------------------------------
Usage Guide for Bulk APIs
Pre-requisites
A Migration Token must be generated and included in the request headers to authenticate calls to the migration APIs.
Attachments must be publicly accessible via a URL for the migration APIs to process them correctly.
Bulk Migration APIs can be used to import Tickets and Notes along with their attachments.
For all other entities, please use the standard public APIs available at: https://api.freshservice.com/
Ensure that dependent entities (e.g., workspaces, users) are created before importing entities that rely on them.
When importing Notes, make sure the corresponding Ticket is created first. The ticket's ID should then be referenced as "ticket_id" in the body of the note request.
Behaviour of the product during the migration
Notifications (Email - only ticket assigned, cc_emails and associations) will not be triggered or sent to end users during the migration.
Slack, Teams, Business Rules, Workflows - Will not be muted. Hence the recommendation is to mute them before initiating migration.
Search and Analytics functionality will not update in real time during the migration. There may be a delay in indexing and visibility of migrated data.
A maximum of 50 tickets or notes can be imported in a single request. The account-level rate limit is 10 requests per minute.
The maximum allowed attachment size per entity is 40 MB.
For entities with multiple attachments, only those with a cumulative size less than 40 MB will be successfully uploaded. Any additional attachments beyond this limit will fail (partial failure).
If a single attachment exceeds 40 MB, the entire attachment will be rejected. However, the parent entity (e.g., ticket or note) will still be created successfully.
Workflows and other configured automations will continue to operate during the migration. Currently, there is no option to disable these automations specifically for migration purposes.
Generating the migration token
Generating the migration token will follow the same steps as below.
https://docs.google.com/document/d/1Ac10DED1iMNTkk-ls2r0lq-wmBdu1eARgIr_0MwF3qE/edit?tab=t.0
Tickets
Endpoint
/api/v2/tickets/bulk
Method
POST
Description
Perform bulk create of entity type "tickets".
Request Schema
Headers
X-API-Key: {api_key}
X-FW-Partner-Migration: {migration_token}
Content-type: application/json
Request body
This request contains a list of ticket entities. Per request currently 50 ticket entities are allowed for bulk processing.
For the exact payload and fields that are supported refer to the Create ticket payload available in the public api documentation → https://api.freshservice.com/#create_ticket [todo: check if anything else in this payload needs to be called out like attachments]
Note: For attachments alone we need to pass a list of publicly accessible URLs and not the way shown in the documentation mentioned above.
Response Schema
Request queued for processing
API Response code: 202
Notes
Endpoint
/api/v2/notes/bulk
Method
POST
Description
Perform bulk create of entity type "notes".
Request Schema
Headers
X-API-Key: {api_key}
X-FW-Partner-Migration: {migration_token}
Content-type: application/json
Request body
This request contains a list of notes entities. Per request currently 50 notes entities are allowed for bulk processing.
For the exact payload and fields that are supported refer to the Create Note payload available in the public api documentation → https://api.freshservice.com/#create_a_note
Note: For attachments alone we need to pass a list of publicly accessible URLs and not the way shown in the documentation mentioned above.
Response Schema
Request queued for processing
API Response code: 202
Job Status
Endpoint
GET /api/v2/<entity_type>/bulk/{job_id}
Method
GET
Description
Retrieves the current status and detailed results of a bulk import job.
Request Schema
Headers
X-API-Key: {api_key}
Path Parameters
Path Parameters
Response Schema
Processing
API Response Code: 202
This response is thrown when the job is still in processing state
Success
API Response Code: 202
This response is thrown when all the records are successfully processed
Success_with_failures
API Response Code: 202
This response is thrown when there are both success and failure records
Failure
API Response Code: 202
This response is thrown when no records are processed and all have failed.
Error Response - Job not found
API Response Code: 404
This response is thrown when the corresponding job-id is not found/does not exist in our backend database. This generally happens when no job with this job-id is created.
Error Codes and Handling
Below are the errors that we can see when the response code is 200 and the job has been submitted, but there was some issue in processing the records.
The system examines the error response and:
1. Checks for parent entity errors first - if any core entity creation failed, assigns code 2001
2. Then checks for child entity errors - if only secondary entities failed, assigns code 2002
3. Falls back to generic response error (2000) if the error pattern doesn't match known types
All the above errors cannot be retried automatically. In the event of occurrence either it needs to be handled via code change(bug) or customer should change the payload to pass the validation.
Retrying failed entities
To retry failed entities, please resolve the errors specified in the response, then create and submit a new bulk API request. If the issue requires a code fix, kindly raise a support ticket with Freshservice Support or Engineering.
Rate Limits
Account level rate limits are listed below for each endpoint. [To be confirmed post load testing]
