Data Portability - Onboarding Guide

This guide will walk you through the steps to onboard your platform as a destination for users to transfer their data through our Export Your Information (EYI) tool.

Process Overview

There are four primary steps to onboarding as a data transfer destination. Each step is outlined in this section, with more details below.

Step 1 – Register Your App with the Data Trust Registry

Before starting the Meta onboarding process, you must register your app at DTI Trust Registry. Meta has partnered with the DTI Trust Registry to manage the vetting process for data transfer destinations. Make sure your app is registered and vetted here before proceeding to the next steps. Note that Meta reserves the right to conduct further review before rendering a decision (see Step 2)

Step 2 - Create a Data Transfer App

You'll need an account and App registered on developers.facebook.com to configure the integration between our platforms and yours. To create the Data Transfer app, you'll need to enter the Developer Portal and complete:

• An onboarding application form - to request approval from Meta to be listed as a destination for data transfer.

Upon approval of your application, a representative from Meta's data portability engineering team will partner with you to assist with the rest of the process.

Step 3 - Development and Integration

In order to transfer data to your platform, Meta's portability infrastructure needs to call your APIs. Meta transfers data using the Data Transfer Project (DTP) transfer worker, so you'll need to integrate your platform with DTP.

As Meta's data portability infrastructure needs to call your APIs on behalf of the user requesting the transfer, Meta authenticates with your API using the OAuth 2.0 Authorization Code flow. To support this, you must complete an OAuth Configuration form on developers.facebook.com.

Step 4 - Testing and Review

Once your App on developers.facebook.com is approved and you've begun integration of your platform with DTP, we'll need to test data transfers to your platform end-to-end. This may require testing multiple revisions of your DTP Adapters, OAuth configuration, or API. Your Meta engineering partner will help you with this process.

Step 5 - Release and Maintenance

When testing is complete, and both parties are satisfied with the stability of the integration, Meta can activate your platform as a public-facing destination for data transfer. Your platform will appear in Meta's Export Your Information (EYI) tool.

Creating a Data Transfer App

To become a destination for Export Your Information (EYI), you need to create a Data Transfer App on developers.facebook.com.

Step 0 - Register your app at Data Transfer Registry

Before starting the Meta onboarding process, you must register your app at DTI Trust Registry. Meta has partnered with the DTI Trust Registry to manage the vetting process for data transfer destinations. Make sure your app is registered and vetted here before proceeding to the next steps.

• For photos, videos, posts, notes and events - Level 1 DTI Trust Registry entry is required.
• For archives - Level 2 DTI Trust Registry entry is required.

Note that Meta reserves the right to conduct further review before rendering a decision

Step 1 - Create a Business Manager Account

Before creating an App, your business must create a Facebook Business Manager account and verify the business in Business Manager.

When the Business Manager account is set up and account verification has been started, your developer account can be added to the Business Manager account with the 'Apps and integrations' permission, which will allow you to create Apps on developers.facebook.com associated with the Business Manager account.

Step 2 - Create a Developer Account

To create and manage apps, you must first create a developer account on developers.facebook.com.

As part of registration, you must agree to the Meta Platform Terms.

Step 3 - Create a Data Transfer App

Navigate to developers.facebook.com/apps and click Create App to begin the App creation process and follow the steps below:

Fill out the App name and add a contact email address.

Select Allow users to transfer their data to other apps under Other on the use case page.

Select the Business Portfolio to associate the App with.

Review the requirements and details of your app, and click Go to dashboard. By proceeding, you agree to the Data Portability Terms.

Step 4 - Complete DTI Trust Registry form

Navigate to the Data Transfer customization page from the dashboard or Use-case page on the nav bar, and fill out the DTI Trust Registry form to begin the approval process for your Data Transfer App by clicking Get started.

Enter your Data Trust Registry URL and submit the registration form.

Step 5 - Complete the Pre-Approval Form

Most of the information in the pre-approval form will be automatically filled in using your data transfer entry.

You only need to complete these two sections:

Select the data types your Data Transfer App will support. These data types correspond to Data Types supported by the Data Transfer Project. See DTP Data Types for more details.

Provide details about your security standards.

Once the form is complete, click the Submit button. Note that you can save your progress with the Save for later button. Meta will contact you on the provided email if your application is approved, or let you know if we need anything else.

Pre-approval Review at Meta

Once submitted, we will review your pre-approval form, checking that your submission meets these key criteria:

• You have a valid Level 1 or Level 2 entry (dependent on data requested) within the DTI Trust Registry.
• You have a verified Meta Business Manager Account.
• You have a publicly available privacy policy, including how users can exercise their data subject rights.
• You support OAuth 2.0.
• You meet the security standards.

Once we have fully reviewed your submission, you will receive a developer notification and email with Meta's decision.

Approved

Once your pre-approval is confirmed, you can begin development and integration for your platform (see steps below). When you have the adapters built and ready, we will work with you to enable your adapter on Facebook and launch it to the public.

Failure To Meet Criteria

If you fail to meet one or more requirements, you will be notified directly that your request to onboard doesn’t meet one or more of the requirements alongside the reasons why. You will then have the opportunity to resubmit your application, which will trigger a further Meta internal review. Once the issue(s) that caused your app to be rejected have been resolved, you can resubmit.

Appeals Process

If you cannot meet the requirements after multiple attempts, Meta may formally deny your request. In this case, you may trigger the appeals process with your Meta point of contact.

Development and Integration

To become a destination for data transfers from Meta's platforms, you must integrate with the Data Transfer Project and complete OAuth Configuration to set up authentication and authorization between your platform and ours.

When you have completed the pre-approval form for your Data Transfer App on developers.facebook.com and your application has been approved, you should independently work through the integration steps below. Once you have completed these steps (or if you get stuck), contact a Meta engineer who will be able to assist you with the remainder of theis process. This section of the onboarding guide describes technical details required to complete the integration.

Data Transfer Project Integration

Meta's data portability infrastructure is built on the open-source Data Transfer Project (DTP). You can read more about DTP in the DTP Documentation, but a key concept is that DTP operates on a push model; users initiate a data transfer on Meta's platform, and Meta's infrastructure calls your platform's APIs to transfer the requested data.

DTP exports data from Meta using Export Adapters, which convert Meta's data to DTP's internal representation. DTP then imports data into your platform using an Import Adapter, which converts from DTP's internal representation to API calls to your platform.

DTP Data Types

The Data Transfer Project supports multiple data types organized into verticals, which are comprised of:

• A data model internal to DTP
• Export Adapters which export data from a platform and convert it to the DTP data model
• Import Adapters which convert from the DTP data model and import the data to a platform by calling that platform's APIs

DTP facilitates the transfer of data between platforms by combining Adapters of the same data type.

Core Data Types

Meta platforms support the following data types:

Archive Data Type

The archive data type contains many data types that don't map directly to a DTP data type as they can't be easily generalized between platforms or have limited value on non-Meta surfaces. This archive can be downloaded by the user, or transferred to another platform as file-based data using the Archives (Blobs in the DTP codebase) data type.

If your platform supports file-based data, such as for backup services, or you want to allow users to transfer data that is currently only available through an archive, your platform can support the Archive data type. Users initiate these transfers through the Export Your Information (EYI) tool.

Integration Options

There are two routes for integrating with DTP - building a Custom Adapter or using pre-built Universal Adapters.

Custom Adapters

If you have an existing API that could support the transfer of user data to your platform, and you are comfortable writing Java and contributing to the open-source DTP codebase, you can develop a custom adapter. A custom adapter gives you full control over how your API is called and allows tight integration between DTP and your platform.

Universal Adapters

If you don't have an existing API or don't have experience writing Java, you can opt to use DTP's Universal Adapters (also called Generic Adapters) and implement an HTTP API conforming to the Generic Importers API specification in the language of your choosing. The Universal Importer Adapter can then be configured to call your API endpoints.

Using Universal Adapters gives less control over the integration between your platform and DTP, but is much faster to implement and cheaper to build than a custom integration. Universal Adapters support all DTP data types exported by Meta, which are listed in DTP Data Types.

Integration Configuration

Once you have decided on an integration option, configure the integration on the developer portal under Data import adapters.

For Universal Adapters, specify your adapter endpoint.

For Custom Adapters, specify the GAV coordinates of your library containing your transfer extension.

OAuth Authentication

When users initiate a data transfer from Meta's platform to yours, Meta's infrastructure calls your APIs on behalf of the user. To do this, Meta obtains an access token with the OAuth 2.0 Authorization Code flow:

1. Users initiate a data transfer from one of Meta's platforms, and selects your platform as a destination for their data
2. Meta redirects the user to your platform to request authorization
3. Your platform displays the access request to the user, who can authorize Meta to interact with your platform on their behalf
4. Your platform redirects the user to Meta's platform along with an authorization code
5. Meta stores the authorization code and the user starts the transfer
6. Meta's infrastructure uses the authorization code to obtain an access token, and optionally a refresh token

For more information about the Authorization Code flow, see the OAuth documentation and related resources.

If you have an existing API, it may already be using OAuth for authentication and authorization. If you don't already have an API or you aren't using OAuth, it's unlikely that you'll want to implement the OAuth spec by yourself. OAuth 2.0 is a common standard and there is likely a package that supports your preferred API framework and implementation language. There are also multiple third-party OAuth providers that support the Authorization Code flow.

OAuth Configuration

When setting up your Data Transfer App on developers.facebook.com, you'll need to complete an OAuth Configuration form that provides Meta with the information required to complete the OAuth Authorization Code flow described above.

The key fields are:

• OAuth URL - The URL on your platform that Meta will redirect users to as part of the Authorization Code flow.
• Access Token URL - The URL Meta will use to request an access token using the authorization code.
• Access Token Revocation URL - An optional URL Meta can use to revoke an access code. See the Access Token Revocation section.
• Client ID - A unique identifier for Meta's platform. Included as a query parameter when Meta redirects a user to your platform as part of the Authorization Code flow. This lets your platform know where the authorization request originated from.
• Client Secret - A secret Meta will pass alongside the Client ID when requesting to create an access token from an authorization token. This validates that the request comes from Meta.
• API Scopes - The OAuth scopes required to complete a data transfer using your API. See the OAuth Scopes section.

OAuth Scopes

The OAuth standard allows you to add granular authorization controls to your API using OAuth scopes.

Endpoints or features available through your API can be associated with different scopes, such as photos.read protecting the /photos GET endpoint, or albums.write protecting one endpoint that adds photos to an album and another that changes an album's name.

Authorization codes (and the refresh tokens and access tokens created from a given authorization code) are also associated with a subset of all available OAuth scopes, which allows a user to grant access to only a part of your API. When authorizing Meta to access your API on their behalf, users should be informed of the OAuth scopes Meta is being granted.

You must set the OAuth scopes required to transfer data to your platform in the OAuth Configuration Form.

Redirect URLs

When redirecting users to your platform as part of the Authorization Code flow, Meta includes a Client ID and a Redirect URL as query parameters. The Client ID is set in the OAuth configuration of your App on developers.facebook.com and uniquely identifies Meta in your OAuth configuration. The Redirect URL specifies where your platform should redirect users when a user has approved the authorization request.

As a security measure, you should only allow pre-approved Client ID and Redirect URL combinations. This is part of the OAuth standard and will be enforced by any OAuth frameworks. To support this, you must add our list of Redirect URLs to your OAuth configuration. You can find an up-to-date list of our Redirect URLs during App setup on developers.facebook.com.

Refresh Tokens

When Meta requests an access token during the Authorization Code flow, your platform can optionally provide a refresh token alongside the access token. See the OAuth documentation for more details.

Generally, refresh tokens are long-lived (as long as months) and access tokens are short-lived (as short as minutes). This allows your platform to have short lifetimes for access tokens while allowing new access tokens to be created without user involvement. Meta uses this feature to enable recurring transfers, such as daily or monthly transfers, without the user having to re-authenticate with destination platforms for every transfer.

If an access token expires during a transfer and a refresh token has been provided, the DTP transfer worker will attempt to create a new access token using the refresh token. If a user has an active recurring transfer, Meta may also occasionally create an access token from the refresh token between transfers in order to keep the refresh token active.

If an access token expires during a transfer or in between recurring transfers and your platform did not provide a refresh token, or if an attempt to create a new access token from a refresh token fails, any active transfers will be paused and the user will be prompted to re-authorize the transfer by completing the Authorization Code flow again.

Access Token Revocation

When all one-time and recurring transfers created by a user to transfer data to your platform have completed, Meta will revoke access tokens for that user if you have provided an Access Token Revocation URL in your OAuth configuration. See the OAuth Documentation for more information.

Testing and Review

With an adapter and your API implemented and configured correctly, contact your engineer at Meta who will then test the integration to ensure it is possible to successfully complete a transfer, and will update our configuration to enable the destination for Meta internal users and users in your Business Account.

You will receive a developer notification when your platform is enabled and you can start reviewing and validating the transfer.

Reviewing and Validating Transfers

Step 1 - Create a Transfer

Navigate to Export Your Information (EYI) in Accounts Center on a Meta platform, for example Facebook EYI.

Follow the steps to initiate a transfer to your platform.

If your platform does not appear in the list, validate that:

• You are a member of the Data Transfer App's associated Business Account
• You have selected the correct data type - for example, if your platform accepts Calendar Event transfers it will not appear if you have selected a Photos transfer

Step 2 - Review Details

Review the display name and icon of your platform on the Export Your Information (EYI) tool.

These can be configured on developers.facebook.com in the Data Transfer App's basic settings. Changes to these settings can take a few days to take effect.

Step 3 - Test

For each data type you support, run a number of test transfers and validate that the expected data has been transferred to your platform.

Release and Maintenance

With integration and testing complete, you can initiate the release of your platform as a data transfer destination on Meta's platforms.

Request Release

To request the release of your platform to users, reach out to your Meta engineering partner or send an email to dataportability@meta.com and provide the following:

• Your App ID - you can find this on developers.facebook.com
• Your destination display name
• A point of contact for coordinating the launch

Meta will then configure your destination to be visible to users in the Export Your Information (EYI) tool.

Service Level Agreements

At Meta, we aim to provide robust services to our users, and expect data transfer destinations to do the same. While there isn't currently a formal SLA for data transfer destinations, Meta monitors the availability and success rates of destination APIs. If these metrics fall below acceptable levels, we'll work with you to improve them or remove your platform as a destination until the issue is resolved. This is rare and is done solely to maintain a high quality of service for both Meta users and your users.