Last updated: 2025-11-24

Source: https://support.freshservice.com/support/solutions/articles/50000011768-how-to-migrate-into-freshservice-via-bulk-apis-for-freshservice-data-migration-partners-

How to migrate into Freshservice via Bulk APIs? \[For Freshservice Data Migration Partners\]

``` Table of contentsUsage Guide for Bulk APIs Pre-requisites Behaviour of the product during the migration

Generating the migration token TicketsEndpoint Method Description Request Schema Headers Request body

Response Schema Request queued for processing

NotesEndpoint Method Description Request SchemaHeaders Request body

Response Schema Request queued for processing

Job StatusEndpoint Method Description Request SchemaHeaders Path Parameters Path Parameters

Response Schema Processing Success Success_with_failures Failure Error Response - Job not found

Error Codes and HandlingRetrying failed entities

Rate Limits ```

Part 1 - Usage Guide for Bulk APIs

Step by step details on how to use the Bulk API end point:

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

1. A Migration Token must be generated and included in the request headers to authenticate calls to the migration APIs.

2. Attachments must be publicly accessible via a URL for the migration APIs to process them correctly.

3. Bulk Migration APIs can be used to import Tickets and Notes along with their attachments.

4. For all other entities, please use the standard public APIs available at: https://api.freshservice.com/

5. Ensure that dependent entities (e.g., workspaces, users) are created before importing entities that rely on them.

6. 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

1. 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. 2. 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.

3. A maximum of 50 tickets or notes can be imported in a single request. The account-level rate limit is 10 requests per minute.

4. 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. 5. 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\]