Share via

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

Important

This feature is for public preview customers only. Features in preview might not be complete and could undergo changes before becoming available in the broader release.

Applies to: Microsoft 365 Global Administrator or Organizational Data Source Administrator or HRIS Source system admin

1. Prepare and export your data on a set frequency

Import organizational data for all employees in the company and add all fields you want to import in a .csv template. 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 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 three options:

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

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

  • Run our PowerShell script, which is also based on our API. [Links to Option 3 below.]

Note

Our C# and PowerShell solutions only import data to Organizational Data in Microsoft 365. They don't export data from your source system.

Before working with any of the options below, 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.

Push data

1P/3P survey 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

[Body] file content as multipart/form-data

Type: Zip archive

Content to be archived:

Metadata.json

Data.csv

[Request Body]

Body: 

{ 

   "$content-type": "multipart/form-data", 

   "$multipart":  

    [ 

        { 

            "headers":  

                { 

                    "Content-Disposition": "form-data; name=\"file\"; filename=info" 

                   }, 

            "body": @{body('Get_blob_content_(V2)')} 

         } 

    ] 

}

[Response Body]

200:  
{ 

  "FriendlyName": "Data ingress", 

  "Id": "<ingestion Id>", 

  "ConnectorId": "<connector Id>", 

  "Submitter": "System", 

  "StartDate": "2023-05-08T19:07:07.4994043Z", 

  "Status": "NotStarted", 

  "ErrorDetail": null, 

  "EndDate": null, 

  "Type": "FileIngestion" 

}

In case connector is not set:

403: Forbidden

If connector is set but previous ingestion is not complete yet:

400: Bad request: Previous ingestion is not complete.

Poll status

API to poll status for the ingestion, as the ingestion of data is a long-running operation.

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

[Response]

200: 
{ 

            "FriendlyName": "Data ingress", 

            "Id": "<ingestion Id>", 

            "ConnectorId": "<connector Id>", 

            "Submitter": "System", 

            "StartDate": "2023-05-08T19:05:44.2171692Z", 

            		  "Status": "NotStarted/ExtractionComplete/ValidationFailed 

/Completed/", 

            "ErrorDetail": null, 

            "EndDate": "2023-05-08T20:09:18.7301504Z", 

            "Type": "FileIngestion" 

},

Download error stream if validation fails (issue in data)

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

[Response]

200: File stream with errors, if any.

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

Make changes to the connection or data

  • Last updated on