Skip to content
Last updated

Create CRB Flow

Guide  ·  Intermediate  ·  ⏱ ~8 min read

This guide walks through the complete process of creating a Cannabis Related Business (CRB) record via the Green Check Access API. The flow covers authentication, fetching the POS credentials schema, collecting POS details, submitting the creation request, and handling all response outcomes.

What this guide covers

  • The six-step CRB creation process end to end
  • How to use the POS credentials schema to drive dynamic UI forms
  • What each API response code means and how to handle it

Process overview

  1. Authenticate — Obtain an access token using your service provider credentials
  2. Retrieve POS credentials schema — Fetch the schema to understand required fields per POS provider
  3. Present POS selection — Let the user choose their POS provider
  4. Collect POS details — Gather credentials and configuration for the selected provider
  5. Submit CRB creation request — Send the complete CRB payload to the API
  6. Handle response outcomes — Process success or manage errors appropriately

Flow diagram

The diagram below shows the complete CRB creation flow, including all decision points and response paths.

Create CRB Flow Diagram

💡 Tip — Full-size view

Click the diagram to open the full-size SVG in a new tab. Use your browser's zoom controls to inspect individual steps.

Step 1 — Authenticate

Obtain a valid access token from the Green Check Access API. This token is required for all subsequent requests.

POST /auth/token
{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "grant_type": "client_credentials"
}
  • Store the token securely for the duration of your session
  • Pass it as Authorization: Bearer <access_token> in every request header
  • Check expires_at and re-authenticate before the token expires

⚠️ Warning — Token expiry

Tokens have a finite lifetime. Build refresh logic into your integration from the start to avoid unexpected 401 errors. See the Integration overview for the full auth response schema.

Step 2 — Retrieve POS credentials schema

Fetch the POS credentials schema for your service provider. This schema defines the required fields and format for each supported POS provider.

GET /service-providers/{sp_id}/pos-credentials-schema
  • The response lists all supported providers (Cova, MJFreeway, Seed, GrowFlow, etc.) and their required fields
  • Use the schema to determine which fields are required vs. optional per provider
  • Drive your UI forms dynamically from this response — do not hardcode provider fields

ℹ️ Schema-driven forms

The POS credentials schema can change as new integrations are added or updated. Fetch it at runtime rather than caching it statically to ensure your forms always match the current requirements.

Step 3 — Present POS selection

Display the list of available POS providers from the schema response to the user and allow them to select one. The selection determines which credential fields you'll collect in the next step.

Step 4 — Collect POS details

Based on the selected POS provider, gather the required credentials and configuration from the user.

Provider typeRequired fields
Cova, MJFreeway, SeedAPI keys and account identifiers (as defined by the schema)
Other providersProvider-specific credentials as returned in the schema

💡 Tip — Validate before submitting

Check all inputs against the schema constraints on the client side before sending the creation request. Early validation surfaces formatting issues (wrong field lengths, missing required fields) before they result in a 422 from the API.

Step 5 — Submit CRB creation request

Send a POST request to create the CRB with the collected POS credentials and business information.

POST /service-providers/{sp_id}/crbs
{
  "org": {
    "name": "Example Dispensary",
    "state": "CO",
    "business_type": "retail"
  },
  "pos_info": {
    "pos_type": "GrowFlow",
    "pos_credentials": {
      "client_id_name": "mygrowflowclientid"
    }
  },
  "users": [],
  "options": {
    "onboarding_required": false
  }
}
FieldDescription
orgBasic business information — name, state, and business type
pos_info.pos_typeThe POS provider selected in Step 3
pos_info.pos_credentialsCredentials collected in Step 4, shaped to match the schema
usersOptional — include user objects to send an onboarding invite email
options.onboarding_requiredSet to true to require the CRB to complete a due diligence application

Step 6 — Handle response outcomes

The API returns different responses based on request validation. Handle each case appropriately.

On success (200): The CRB has been created and will begin syncing data on the nightly schedule. Display a confirmation to the user that includes the new crb_id.

On error: See the error reference table below.

Error reference

StatusMeaningCommon cause & fix
400 Bad RequestValidation failedCheck that all required fields are present and formatted correctly — location ID format, credential field names, required org fields
401 UnauthorizedInvalid or expired tokenRe-authenticate with POST /auth/token and retry
403 ForbiddenManual intervention requiredUser information is incomplete or POS credentials were entered incorrectly — confirm location ID matches the dispensary location and credentials are accurate
404 Not FoundPOS provider unavailableThe selected POS type is not available for the given location — check credential location ID against provider availability
412 Precondition FailedAlready connectedA CRB already exists with the same POS credentials — check for an existing record before submitting to prevent duplicate connections

What's next

Previous page
Next page