# 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:

| Status | Meaning |
|  --- | --- |
| `gcv_pending` | CRB has been invited but hasn't started the application |
| `gcv_in_progress` | CRB is actively completing the application |
| `bank_awaiting_review` | CRB submitted — documents and data are ready for your review |
| `bank_review_in_progress` | Your team is actively reviewing the application |
| `bank_approved` | Application 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:


```bash
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


```json
{
  "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.**


```bash
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.**


```bash
POST /service-providers/{sp_id}/crbs
```


```json
{
  "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:


```bash
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:


```bash
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.**


```bash
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:


```bash
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.

| Endpoint | Description |
|  --- | --- |
| `GET /service-providers/{sp_id}/crbs/{crb_id}/sales` | Sales transactions with line items, taxes, and compliance status. Supports date range filtering and pagination. |
| `GET /service-providers/{sp_id}/crbs/{crb_id}/customers` | Customer records (PII is hashed). Supports pagination and search. |
| `GET /service-providers/{sp_id}/crbs/{crb_id}/products` | Product catalog with category, THC/CBD content, and pricing. |
| `GET /service-providers/{sp_id}/crbs/{crb_id}/inventory` | Current inventory levels by product and location. |
| `GET /service-providers/{sp_id}/crbs/{crb_id}/inventory-locations` | Physical 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](/tutorials/api-integration-workflow) 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:


```bash
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:


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

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


```bash
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

- [Choosing your CRB onboarding path](/guides/next-steps) — Compare the three onboarding methods and decide which fits your workflow
- [Retrieving CRB onboarding templates](/tutorials/crb-onboarding-template) — Step-by-step tutorial for pulling application data and documents
- [API integration workflow](/tutorials/api-integration-workflow) — Step-by-step tutorial for fetching and paginating sales data
- [API reference](/apis/swagger) — Full schema and endpoint documentation