---
title: "Translate v2 Nylas ID into v3 Provider ID"
method: POST
path: "/v3/migration-tools/translate"
tags: ["Data migration"]
---

# Translate v2 Nylas ID into v3 Provider ID

`POST /v3/migration-tools/translate`

Use the connected account ID and a resource type, with an optional list of specific Nylas IDs, to get a response that contains a list of of Nylas IDs and their v3 Provider ID equivalents. Use this API as a one-time operation to translate v2 IDs into v3 Provider IDs. Do not use this API in your code logic as it very data intensive.

To use this endpoint, your v2 Nylas application needs to be linked to the equivalent v3 Nylas application. This endpoint does not work for objects in v2 accounts that have the provider set to `Outlook`.

By default, the API returns up to 3000 records for the requested resource type related to the v2 connected account, sorted by `created_at` date. If you specify a list of v2 Nylas IDs, the API returns the v3 Provider IDs for those specific IDs only.

Results are paginated, with a page size of 3000 results. If the response includes a `next_page_number` field, you can use that number in a request to get the next set of results. 

Also, there is a possibility to search results created only after certain Unix timestamp, in Nylas v2 database. To use this, add to body payload `start_from_timestamp` valid Unix timestamp.

The API is rate limited to 20 requests per second per Nylas application ID.

### IMAP folder resource ID

When you make a Translate ID request for an IMAP folder (`resource_type: folders`), Nylas returns its name in the `v3_resource_id` field. To get the resource ID for a specific folder, Base64 encode the folder name using the following format: `v0:<NYLAS_GRANT_ID>:<FOLDER_NAME>`.

## Request body

- object
  - `resource_type` 'messages' | 'drafts' | 'threads' | 'contacts' | 'contactgroups' | 'events' | 'calendars' | 'folders', required — The resourece(s) to get translations for.
  - `v2_account_id` string, required — The v2 connected account ID to get translations for.
  - `nylas_ids` string[] — (Optional) The list of v2 IDs to translate. If omitted, Nylas returns up to 3000 IDs for the requested resource types related to that v2 connected account. Results are returned sorted by creation date, ascending.
  - `start_from_timestamp` integer — (Optional) The Unix timestamp to search for results created after that timestamp.
  - `next_page_number` integer — (Optional) The page number for the next set of results. This appears in the response only if there are more results available.

## Response `200`

Returns a JSON list of translated objects, with mapped v2 and translated v3 ids.

- object
  - `request_id` string — The request ID.
  - `data` TranslateV2v3Id
    - `v2_application_id` string, required — The ID of the v2 Nylas application the connected account belongs to.
    - `v2_account_id` string, required — The ID of v2 connected account you are requesting translations for.
    - `resource_type` 'messages' | 'drafts' | 'threads' | 'contacts' | 'contactgroups' | 'events' | 'calendars' | 'folders', required — The names of the v2 resources you're requesting translations for. To request Gmail's "labels", include `folders`. (Nylas v3 consolidates folders and labels into one resource.)
    - `translations` object[] — A list of v2 Nylas IDs and their v3 Provider ID counterparts, according to the requested resource type and v2 connected account.
      - `v2_resource_id` string — The v2 Nylas ID.
      - `v3_resource_id` string — The v3 Provider ID.
    - `next_page_number` integer — A page number for next set of results, if more results are available. This field does not appear if there are no more results.

## Other responses

- `400` — Bad Request
- `401` — Not Authenticated

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)