Getting Started

REST

Representational State Transfer (REST) is a set of best practices for designing maintainable web services. REST defines a simple and generic interface, however, we make use of a more simplified variant:

Example GET POST PUT DELETE
Listing URL
/items/v2 		Retrieve a list of all elements Create a new element Update an existing element(s) Discontinue or disable an existing element
/plants/v2 ONLY
Element URL
/plants/v2/{id} 		Retrieve a specific element Update an existing element(s) Discontinue or disable an existing element
Element Action URL
/plants/v2/{action}
/plants/v2/{id}/{action} 		Perform {action} on existing element(s) Perform idempotent {action} on existing element(s)

The PUT and DELETE methods are referred to as idempotent, meaning that the operation will produce the same result no matter how many times it is repeated. The GET method is a safe method (or nullipotent), meaning that calling it produces no side-effects. In other words, retrieving or accessing a record does not change it. POST, on the other hand, is not required to be idempotent, therefore, calling it multiple times will likely perform the same action or change each time.

Read more about REST in the Representational State Transfer Wikipedia article.

Vendor API Key

Your Vendor API Key is specific to your company and the software you develop. Vendor API keys can be created and maintained within Metrc Connect. Your Vendor API Key is to be used by every instance of your software at all times, regardless of which customer, location, or user is using it. Keep this API key safe and protected, and do not share it.

User API Key

API calls require a user API key, which your industry customer creates and provides to you. The user API key is tied directly to the user's account (not the company or facility), and everything your software does is tied to your integrator API key and the user API key. Your software will be limited by the permissions granted to the user within Metrc.

Authentication

The Metrc API requires two pieces of information to authenticate each request - the software vendor's API key and the user's API key.

Both authenticating API keys must be sent through the Authorization HTTP header using the basic access authentication method. Basic access authentication combines a username and password, encodes them using Base64, and the resulting value is then passed through via the Authorization HTTP header. For our API, the username is equivalent to the software vendor's API key and the password is equivalent to the user's API key. The Authorization HTTP header for this API is prepared as follows:

  1. Both API keys are combined into a single string in the following manner:
    software_api_key:user_api_key
    • software_api_key = Software vendor's API key
    • user_api_key = User's API key
  2. The combined string is then encoded using RFC2045-MIME Base64 without the 76 char/line limit.
  3. The HTTP header value is composed of the literal word Basic followed by a space and the encoded string:
    Basic encoded_api_keys

Please Note: Most programming frameworks already include mechanisms for generating an Authorization HTTP header using basic access authentication. The above is provided only as a rudimentary reference of the actual process. See the Basic access authentication Mozilla Developer Network article for more details.

Authorization

Authorizations and permissions are solely dependent on the validated user's permissions.

Working with the API

The API endpoints will only establish communication over the HTTP Secure (HTTPS) communication protocol.

All API endpoints make use of the JSON format for sending and receiving data. All POST and PUT requests are expected to contain JSON formatted data and are required to have a Content-Type header of application/json.

Below is a short list of sites that may be of assistance while developing using JSON:

JSON on Wikipedia
Overview of the JSON format, its history, and numerous samples.
JSON on MDN
Provides technical details of the JSON format.
JSON (.org)
Large compilation of development libraries that add support, processing, and/or parsing of JSON.
JSONLint
Provides validation and pretty-formatting (no coloring, however) of JSON data.

Please note: The above list of links, articles, and websites are provided for assistance by the Metrc developers, and are not directly or indirectly endorsed by Metrc LLC, Franwell Inc, or their subsidiaries.

Dates and Times

All date and date/time fields submited to the server are expected to be in ISO 8601 format. Likewise, all date and date/time fields returned by the server will be in ISO 8601 format.

The only ISO 8601 date format supported is YYYY-MM-DD. Even though the standard defines YYYY-DDD as valid, it is currently not supported.

Examples of valid ISO 8601 date/time formats:

Example Description
2015-08-04T22:04:50Z The above date/time format represents August 4th, 2015 10:04:50 PM (UTC) using the Z identifier. The API will assume 000 milliseconds.
2015-08-04T22:04:50+00:00 The format above represents the same August 4th, 2015 10:04:50 PM (UTC) using a numerical time zone offset of +00:00. The API will assume 000 milliseconds.
2015-10-03T16:30:40.345+00:00 The format above represents October 3rd, 2015 4:30:40.345 PM (UTC) using a numerical time zone offset of +00:00. Note the addition of the milliseconds portion of the time in this example.
2016-02-04T22:20:30.456-06:00 The format above represents February 4th, 2016 10:20:30.456 PM (MDT) using a numerical time zone offset of -06:00. Note the addition of the milliseconds portion of the time in this example.

Please note: The API will accept any time zone offset specified, and convert it to UTC for storage.

Making Calls with Timestamps

When a date/time is used in a query string, such as during a GET call, it is essential that the URL is properly encoded. In particular, when a plus sign (+) is used in a time zone offset, it must be correctly encoded as %2B. Failure to encode the plus sign correctly will cause the date/time to be misinterpreted.

For example, let's say you wish to call GET /packages/v2/active and return all active packages for license number 123-ABC that have been modified since 2023-11-01T08:00:00+02:00. If you make a call to:
GET /packages/v2/active?licenseNumber=123-ABC&lastModifiedStart=2023-11-01T08:00:00+02:00,
the call will not return the expected results. You should instead make the call to:
GET /packages/v2/active?licenseNumber=123-ABC&lastModifiedStart=2023-11-01T08:00:00%2B02:00.

Last Modified Filter Range

Metrc makes a LastModified field available on most data provided via the API. This field represents the date and time when an entity was last changed, regardless of the source (a user, an API call, etc.) and how minor of a change it was.

If the software ensures that a request is made covering every minute of the day, it will always have up-to-the-minute data. For example, let's assume the software has a 1-hour scheduled job which requests all changes made within the last 1-hour and 5-minutes (5 min buffer, because of potential clock drift between systems). This will enable the software to stay on top of all data changes that occur within Metrc. If the scheduled job is paused or falls out of sync, then simply requesting the last run time plus 5 minutes should cover all changes that occurred since the last sync.

Server Responses

200 OK Server processed the request successfully.
400 Bad Request

An error has occurred while executing your request.

Example Response
[
	{
		"row": 0,
		"message": "-- error description --"
	},
	{
		"row": 1,
		"message": "-- error description --"
	}
]
401 Unauthorized Invalid or no authentication provided.
403 Forbidden The authenticated user does not have access to the requested resource.
404 Not Found The requested resource could not be found (incorrect or invalid URI).
413 Content Too Large The request exceeds the maximum number of objects allowed. See the Object Limiting section for details.
429 Too Many Requests The limit of API calls allowed has been exceeded. Please pace the usage rate of the API more apart.
500 Internal Server Error An error has occurred while executing your request. The error message is typically included in the body of the response.

Postman

Postman is a great tool for quickly testing out requests to an API. Below you will find a collection you can import into Postman to start making requests right away.

Import the following collection:

Postman JSON


Prepare your environment:


With these changes, you should be able to make requests. The default data in the POST and PUT examples may need to be modified for a successful response.