m3terDocumentation

On this page

File Upload Service API

You can use the m3ter file upload service API to upload a usage data measurements data file to the platform in preparation for measurements ingest:

  • You can upload measurements files in JSON or CSV text formats or upload zipped files and you must specify the file content type when you request an upload URL.

  • An upload job ID is returned with the upload URL and you can use this upload job ID for other file upload service calls to follow up and troubleshoot any issues that arise with a file upload.

This section explains how to use the file upload service API to upload a usage data measurements file and API calls you can use to troubleshoot and issues you encounter:

Uploading a Measurements Data File

This is a two-stage process:

1. First, obtain an upload URL from the m3ter platform by making a POST request to this endpoint:

https://api.m3ter.com/organizations/{{orgId}}/fileuploads/measurements/generateUploadUrl

The request body for this call should have the following structure:

1
{
2
  "fileName": "measurements_2022_02_14.json",
3
  "contentType": "text/json",
4
  "contentLength": 209
5
}

The fileName and contentLength parameter values you use will be specific to the file you intend to upload. In the response, the call will return:

  • An upload URL, which is time limited - it is valid for one minute.

  • An upload job ID.

Note: Authentication with Platform. To make the POST generateUploadUrl API call, you'll have to use a Bearer Token you've obtained for authentication with the platform. For more details, see Service Authentication.

More Details? See the API Reference documentation for the Generate an upload URL API call.

2. Second, when you have received the response to your request for an upload URL, you can upload the data in your file using a PUT request to the returned upload URL. The binary data from the file should form the request body and the file should contain an array of measurements data. For example:

1
[
2
  {
3
     "uid": "xxxxxxxx-62f7-45ea-a916-xxxxxxxxxxxx",
4
     "meter": "api_request",
5
     "account": "acme_corp",
6
     "ts": "2022-02-14T11:30:51.897Z",
7
     "measure": {
8
         "quantity": 1.0
9
     }
10
  },
11


12
  .
13


14
  .
15


16
  .
17


18
]
19

Troubleshooting Measurement File Uploads

If any issues occur with your measurements data file upload, file upload service API calls are available to help you follow up and troubleshoot:

More Details? For more details on how to make the API calls referred to in this section, see the Measurements section of our API Reference documentation.

Downloading Previously Uploaded Measurements File

You can retrieve a measurements file that you've previously uploaded to the file upload service:

Follow a two-step process:

  • Use this call with the file upload job id to obtain a download URL. A download URL is returned together with a download job id.

  • You can then use a GET using the returned download URL as the endpoint to retrieve the previously uploaded file.

Obtaining File Upload Job Details

You can use two calls to obtain details of file upload jobs:

  • List File Upload Jobs - use this call to return a list of the file upload jobs.

  • Get File Upload Job Response - use this call to get the file upload job response using the file upload job id. This returns useful information about the specific upload job, including it's status - "notUploaded", "running", "failed", or "succeeded".

Next: Submitting Test Usage Data


Additional Support

Login to the Support portal for additional help and to send questions to our Support team.