DYI Export API

This set of endpoints provide programmatic access to the downloadable files generated by a DYI (download your information) export job. DYI export jobs are initiated on the Download Workplace Data tab within the Admin Panel on Workplace.

Each DYI export job has a unique job ID, which is used as the endpoint path on Graph API for fetching information about that job. The export job endpoint payload contains references to DYI jobs that ran as part of that export job.

There will be one Company DYI job per export, and one User DYI job per user included in that export. For each DYI job you can retrieve the status and download file URLs for that job.

Object Hierarchy

The object hierarchy for the Export Job API looks like this:

• Community

  • (1:n) DYI export job

    • (1:1) Company DYI job

      • (1:n) Files
    • (1:n) User DYI jobs

      • (1:n) Files

Permissions

The DYI Export Job API endpoints require the Read Workplace company data exports permission.

GET /community/work_dyi_jobs

Fetch a list of IDs for export jobs that exist within the current community.

GET /{work_dyi_job_id}

Fetch information about a single export job. The endpoint exposes a number of fields which you can use to inspect the progress status for the job, and edges for fetching the files generated for the export job.

Fields

Abort reason field values

The abort_reason field returns an enumerated value indicating why an export job was aborted.

The list of possible return values for this field may change, but below are some example values:

• TARGET_NOT_VISIBLE
• CANCELLED_BY_USER
• ARCHIVE_TOO_BIG

Data types field values

The data_types field returns a list of enumerated values, each of which describes a type of data included in the export.

The list of possible return values for this field may change, but below are some examples of data type values that can be returned:

• WORKPLACE_COMPANY_METADATA_GROUPS
• WORKPLACE_COMPANY_METADATA_USER_PROFILE
• WORKPLACE_COMPANY_METADATA_COMPANY_INFO
• SAVED_ITEMS_YOUR_ACTIVITY
• MESSENGER_V2
• POSTS_YOUR_ACTIVITY
• EVENTS_YOUR_ACTIVITY
• COMMENTS_REACTIONS_YOUR_ACTIVITY
• REPORTED_PROBLEMS_YOUR_ACTIVITY
• GROUPS_YOUR_ACTIVITY
• WORKPLACE_SURVEYS
• WORKPLACE_KNOWLEDGE_LIBRARY
• WORKPLACE_NOTES
• POLLS_YOUR_ACTIVITY
• PROFILE_PERSONAL_INFO
• FRIENDS_V2
• SEARCH_LOGGED_INFO
• SECURITY_AND_LOGIN_INFORMATION_V

DYI format field values

The dyi_format field returns an enumerated value from the following list of possible values:

• JSON
• HTML
• NONE
• HTML_AND_JSON
• CSV

Media quality field values

The media_quality field returns an enumerated value from the following list of possible values:

• VERY_LOW
• LOW
• MEDIUM
• HIGH
• VERY_HIGH

Edges

GET /{dyi_job_id}

Get information about the company or user job represented by dyi_job_id, as returned in the DYI job object on the company_job field or the list of DYI Job objects on the /user_dyi_jobs edge for a given export job ID.

Each DYI job object has a number of fields providing metadata about the job and a list of files that can be downloaded for that job.

Fields

Edges

GET /{dyi_job_id}/files

Get a list of files that are available for download for the current DYI job specified in dyi_job_id.

Each item in the list is an object containing the fields id, download_url and file_size. The download_url URL can be used to directly download each file,

      GET https://graph.workplace.com/{id}/files?fields=id,download_url,file_size
    

Sample code

Below is an example of traversing the DYI Export Job API endpoints using a Python script, to generate a list of all files available for download.

import requests

# Set your access token
access_token = "YOUR_ACCESS_TOKEN"

# Set the API endpoints
work_dyi_export_jobs_endpoint = f"https://graph.facebook.com/community/work_dyi_jobs?access_token={access_token}"
export_job_endpoint = lambda id: f"https://graph.facebook.com/{id}?fields=id,is_completed,company_job&access_token={access_token}"
user_dyi_jobs_endpoint = lambda id: f"https://graph.facebook.com/{id}/user_dyi_jobs?access_token={access_token}"
dyi_job_files_endpoint = lambda id: f"https://graph.facebook.com/{id}/files?access_token={access_token}"

# Fetch all DYI export jobs for the community
response = requests.get(work_dyi_export_jobs_endpoint)
work_dyi_jobs = response.json()

# Iterate through all DYI export jobs
for export_job in work_dyi_jobs["data"]:
    # Only process completed jobs
    if export_job["is_completed"] != True:
        print(f"Skipping job {export_job['id']} because it is not completed")
        continue
    
    # Fetch the job details
    response = requests.get(export_job_endpoint(export_job["id"]))
    export_job_details = response.json()

    # Fetch the company DYI job for the current export job 
    company_dyi_job = export_job_details["company_job"]

    # Fetch the files for the company DYI job
    response = requests.get(dyi_job_files_endpoint(company_dyi_job["id"]))
    files = response.json()

    # Iterate through all files
    for file in files["data"]:
        # Print the results (replace with your desired logic)
        print(f"Export ID: {export_job['id']}, Job ID: {company_dyi_job['id']}, Job Type: Company, File ID: {file['id']}, File Size: {file['file_size']}, Download URL: {file['download_url']}")

    # Fetch the user DYI jobs for the current job
    response = requests.get(user_dyi_jobs_endpoint(export_job['id']))
    user_dyi_jobs = response.json()

    # Iterate through all user DYI jobs
    for user_dyi_job in user_dyi_jobs["data"]:
        # Fetch the files for the user DYI job
        response = requests.get(dyi_job_files_endpoint(user_dyi_job["id"]))
        files = response.json()

        # Iterate through all files
        for file in files["data"]:
            # Print the results (replace with your desired logic)
            print(f"Export ID: {export_job['id']}, Job ID: {user_dyi_job['id']}, Job Type: User, File ID: {file['id']}, File Size: {file['file_size']}, Download URL: {file['download_url']}")