Skip to content
Last updated

Integration Overview

Guide  ·  Beginner  ·  ⏱ ~10 min read

Green Check Access is Green Check's public API suite. It lets service providers — financial institutions, payroll companies, CRMs, and other platforms serving the cannabis industry — programmatically manage CRB onboarding, due diligence, and ongoing data synchronization. This guide covers the domain model, authentication, and the four core workflows you'll use in any integration.

What this guide covers

  • Key entities in the Green Check domain model (SP, CRB, templates, statuses)
  • How to authenticate and manage bearer tokens
  • The four core integration workflows
  • Available operational data endpoints for ongoing sync

Key concepts

Before diving into endpoints, it helps to understand how Green Check's domain model works.

Service Provider (SP): Your organization. Every API call is scoped to your service provider ID (sp_id), which you receive during onboarding with Green Check.

CRB (Cannabis Related Business): The businesses your platform serves — dispensaries, cultivators, wholesalers, etc. CRBs are the entities you invite, onboard, and pull data from via the API.

Onboarding template: A configurable application form that determines what information and documents a CRB must provide during onboarding. You can maintain multiple templates (e.g., one for retail dispensaries, another for wholesale operations). Each template includes document requirements (business licenses, insurance certificates, financial statements, etc.) and custom fields (freeform questions you define). You create and manage templates in the Green Check web application, then reference them by template_id when inviting CRBs via the API.

Due diligence status: Each CRB's application moves through a lifecycle tracked by its status field:

StatusMeaning
gcv_pendingCRB has been invited but hasn't started the application
gcv_in_progressCRB is actively completing the application
bank_awaiting_reviewCRB submitted — documents and data are ready for your review
bank_review_in_progressYour team is actively reviewing the application
bank_approvedApplication approved

POS (Point of Sale): Green Check integrates with many cannabis POS systems (Dutchie, Flowhub, Treez, Blaze, etc.). If a CRB connects their POS, Green Check ingests their sales, customer, product, and inventory data — all of which you can access through the API.

Authentication

All API requests require a Bearer token. Obtain one by exchanging your client credentials:

curl --location 'https://sandbox-api.greencheckverified.com/auth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials"
}'

Example response

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "scope": ["ServiceProviderRead", "ServiceProviderWrite"],
  "expires_at": 1700000000,
  "issued_at": 1699996400,
  "client_id": "your-client-id"
}

Include the token in all subsequent requests as Authorization: Bearer <access_token>.

⚠️ Warning — Token expiry

Tokens expire. Check the expires_at field (Unix timestamp) and re-authenticate before making requests after expiry. Build token refresh logic into your integration from the start to avoid unexpected 401 errors in production.

Core workflows

There are four primary integration patterns. Most integrators use some combination of all four.

1. Inviting CRBs to onboard

Use this when your platform is the starting point — for example, a CRM workflow that triggers an invite for a new cannabis client to complete their Green Check application.

Step 1: Fetch your onboarding templates.

GET /service-providers/{sp_id}/onboarding-templates

This returns all templates you've configured. Note the template_id of the one you want the CRB to complete.

Step 2: Create the CRB and send the invite.

POST /service-providers/{sp_id}/crbs
{
  "org": {
    "name": "Example Dispensary",
    "state": "CO",
    "business_type": "retail",
    "template_id": "0dac3862-07e1-49a4-9025-6c01862d0c79"
  },
  "users": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example-dispensary.com"
    }
  ],
  "options": {
    "onboarding_required": true
  }
}

Setting onboarding_required: true means the CRB won't be auto-approved — they'll receive an invite link and must complete the application in Green Check before proceeding. If you already have the CRB's POS credentials, you can include pos_info instead of (or in addition to) users to connect their POS up front.

2. Syncing CRBs that sign up via Green Check

CRBs can also discover and connect with your organization through the Green Check marketplace — meaning they initiate the relationship. To detect these new connections, poll the CRBs endpoint:

GET /service-providers/{sp_id}/crbs

This returns all CRBs associated with your organization. Green Check also sends email notifications when new CRBs connect, but polling this endpoint and checking for new IDs is the programmatic approach for keeping your external system in sync.

3. Monitoring application completion

Once a CRB has been invited, use the same endpoint to track when they've finished their application:

GET /service-providers/{sp_id}/crbs

Filter for CRBs where status is bank_awaiting_review — this indicates the CRB has submitted and their documents are ready for review.

ℹ️ Email notifications

Green Check sends email notifications when applications are completed, but these should be treated as a convenience — not a trigger for automated workflows. Use status polling as the reliable signal in any production integration.

4. Fetching application data and documents

Once a CRB's application is complete, pull their submitted information into your system.

Step 1: Get the completed onboarding template.

GET /service-providers/{sp_id}/crbs/{crb_id}/onboarding-template

The response includes two key sections:

  • custom_requirements — the CRB's responses to your custom form fields (text answers, selections, etc.)
  • standard_requirements — document requirements, each containing an array of documents with metadata and IDs

Step 2: Download documents.

Walk through the standard_requirements array and use each document id to download:

GET /service-providers/{sp_id}/crbs/{crb_id}/documents/{doc_id}/download

This returns the document as a base64-encoded blob.

Operational data endpoints

Beyond onboarding, Green Check Access provides read access to a CRB's operational data sourced from their connected POS. These endpoints are useful for ongoing monitoring and compliance sync.

EndpointDescription
GET /service-providers/{sp_id}/crbs/{crb_id}/salesSales transactions with line items, taxes, and compliance status. Supports date range filtering and pagination.
GET /service-providers/{sp_id}/crbs/{crb_id}/customersCustomer records (PII is hashed). Supports pagination and search.
GET /service-providers/{sp_id}/crbs/{crb_id}/productsProduct catalog with category, THC/CBD content, and pricing.
GET /service-providers/{sp_id}/crbs/{crb_id}/inventoryCurrent inventory levels by product and location.
GET /service-providers/{sp_id}/crbs/{crb_id}/inventory-locationsPhysical locations associated with a CRB's POS.

All operational data endpoints support pagination via limit and offset query parameters.

💡 Tip — See it in action

The API integration workflow tutorial walks through authenticating, fetching sales data, and handling pagination with a complete Python example.

Additional endpoints

License search — Validate a CRB's licensing against the cannabis license database before or during onboarding:

GET /service-providers/{sp_id}/licenses-search?name=Example+Dispensary&state=CO

POS credentials schema — If you're collecting POS credentials within your own UI, this endpoint tells you what fields each POS type requires:

GET /service-providers/{sp_id}/pos-credentials-schema

Upload documents — Upload documents to a CRB's onboarding template requirements on their behalf:

PUT /service-providers/{sp_id}/crbs/{crb_id}/onboarding-template/requirements/{requirement_id}/documents

Integration lifecycle at a glance

  1. Authenticate — POST /auth/token to get a bearer token
  2. Fetch templates — GET .../onboarding-templates to identify the right application form
  3. Create/invite CRBs — POST .../crbs with template ID and user contact info
  4. Monitor status — Poll GET .../crbs and filter by status: bank_awaiting_review
  5. Pull application data — GET .../crbs/{crb_id}/onboarding-template for form responses and document metadata
  6. Download documents — GET .../crbs/{crb_id}/documents/{doc_id}/download for each document
  7. Sync operational data — Use the sales, customers, products, and inventory endpoints for ongoing sync

What's next