Call Microsoft 365 API to transfer organizational data for API-based import (Step 2 of 3) (preview)

Applies to: Microsoft 365 Global Administrator or Organizational Data Source Administrator or Human Resources Information System admin

1. Prepare and export your data on a set frequency

Export organizational data for all employees in the company and add all fields you want to import in a .csv template or an automated .csv output in an external source like Workday Report as a Service (RaaS). Learn how to structure this data file.

At the frequency you decide (such as once a month or once a week), have your custom app or external source integration export organizational data from your source system.

2. Call the API to import your data

To import your data to Microsoft 365, you can pick from one of five options:

1. Use our API to build a custom app that exports and imports your data at the frequency you choose. Learn how.

2. Run our C# solution on your console, which is based on our API. Learn how.

3. Run our PowerShell script, which is also based on our API. Learn how.

4. Use an Azure Data Factory template to send data to the API-based import. Learn how.

5. Run our Node script to retrieve OAuth tokens. Then, use those tokens to send data directly from an external source like Workday to the API-based import. Learn how.

If you're working with option 1, 2, 3, or 4, make sure you have this information:

• App (client) ID. Find this ID in the registered app information in the Microsoft Entra admin center under Application (client) ID.

• Client secret: This is a secret string that the application uses to prove its identity when requesting a token. It's also referred to as application password. This secret is only shown for the first time when the client secret is created. To create a new client secret, follow these steps.

• Certificate name. This name is configured in your registered application. After you upload the certificate, the certificate name shows up under Description in the Azure Portal. You can use the certificate name as an alternative to the client secret.

• Microsoft Entra tenant ID. You can find this ID on the app's overview page under Directory (tenant) ID.

• Scale unit: The scale unit provided to you for your tenant, such as "novaprdwus2-01."

• The .csv file and the path to the .csv file.

Or, if you're working with option 5, make sure you have this information:

• App (client) ID. Find this ID in the registered app information in the Microsoft 365 admin center under Application (client) ID.

• Client secret: This is a secret string that the application uses to prove its identity when requesting a token. It's also referred to as application password. This secret is only shown when you create the client secret. Learn how to create a new client secret.

• Microsoft Entra tenant ID. You can find this ID on the app's overview page under Directory (tenant) ID.

• Connector ID: This is the string at the end of the URL that appears when you select your API-based connector in the Microsoft 365 admin center, such as https://admin.cloud.microsoft/OrganizationalDataInM365/connection-details/[Connector ID here].

• Scale unit: The scale unit provided to you for your tenant, such as "novaprdwus2-01."

Push data

App to call Microsoft 365 API to push content

[POST] https://api.orginsights.viva.office.com/v1.0/tenants/{tenantid}/modis/connectors/HR/ingestions/fileIngestion

In case connector isn't set:

403: Forbidden

If connector is set but previous ingestion isn't complete yet:

400: Bad request: Previous ingestion is not complete.

Option 1: Use the Microsoft 365 API to build a custom import/export app

You can use the Microsoft 365 API to build a custom app that automatically exports data from your source system, and then imports it to the Microsoft 365 admin center.

Your app can take any form, like a PowerShell script, but it needs to export your source data as a .csv file at the frequency you pick, and import that file into Microsoft 365 apps and services.

Option 2: Import data through our C# solution after exporting data through your custom app

After you've exported your source data as a .csv file at the frequency you pick, you can run the DescriptiveDataUploadApp C# solution on the console. The DescriptiveDataUploadApp C# solution then brings your locally stored data into Microsoft 365. Learn more on GitHub.

To run the solution:

1. Clone this app to your machine by running the following command on the command line:

   git clone https://github.com/microsoft/orgdata_apibasedimport.git.

2. Include the following console values.

   • AppID/ClientID
   • Absolute path to the .csv file. Format the path like this: C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.csv
   • Microsoft Entra tenant ID
   • Certificate name

Option 3: Run the DescriptiveDataUpload PowerShell solution after exporting data through your custom app

Similar to option 2, after you've exported your source data as a .csv file at the frequency you pick, you can run the DescriptiveDataUpload PowerShell solution on the console. The DescriptiveDataUpload PowerShell solution then brings your locally stored data into Microsoft 365. Learn more on GitHub.

1. Clone the source code to your machine by running this command on the command line:

   git clone https://github.com/microsoft/orgdata_apibasedimport.git.

2. Open a new PowerShell window as an administrator.

3. In your PowerShell window, run the following command:

   Install-Module -Name MSAL.PS

   Or, go to this PowerShell gallery link for instructions on installation.

4. Set parameters.

   • ClientID
   • pathTocsvFile
   • TenantId
   • novaScaleUnit
   • ingressDataType: HR
   • ClientSecret or certificateName