GIS Integration API — Developer Guide

1. Introduction

The GIS Integration API enables firm CRM and practice management systems to exchange entity data and compliance status with the Global Independence System (GIS). Rather than building bespoke connectors to each firm's systems, GIS exposes a standard REST API that firms can integrate from their side.

Integration model: Firm systems connect to GIS via REST API. GIS does not connect to firm systems.

Who this guide is for: Firm IT teams, system integrators, and CRM administrators building integrations with GIS.

1a. Which URL to share

GIS has two different addresses, and integrations fail in confusing ways if they are mixed up.

The exact backend URL for your environment, plus one-click Copy API endpoint and Copy MCP endpoint buttons and a connection URL validator, are in GIS → Settings → API Documentation. Copy from there rather than typing the URL by hand.

2. Getting Started

Requesting an API Key

API keys are generated by your firm administrator in GIS under Settings → API access. Global administrators can also generate keys for any firm. Contact your firm administrator or the HLB Executive Office to request a key.

API Key Security

• Treat your API key like a password — do not commit it to source control
• Store keys in environment variables or a secrets manager
• Rotate keys periodically by generating a new one and revoking the old

Base URL

https://<project-ref>.supabase.co/functions/v1/gis-api

All endpoints are prefixed with /v1/.

Quick Test

curl -s -H "x-api-key: gis_live_YOUR_KEY_HERE" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities?limit=1" \
  | jq .

3. Authentication

Pass your API key in the x-api-key HTTP header with every request:

x-api-key: gis_live_abc123def456...

4. Response Format

All responses are JSON. Every response includes a meta object with a unique request ID and timestamp.

Success (200)

{
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Error (4xx / 5xx)

{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "No entity found with the specified identifier."
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Pagination

List endpoints return meta.total, meta.limit, and meta.offset for pagination.

5. Error Codes Reference

6. Endpoints — Detailed Reference

6.1 Search Entities

Search the firm's entity register. Returns entities owned by the authenticated firm only.

Permission: read

curl -s -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities?q=barclays&limit=5" \
  | jq .

Example Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "client_name": "Barclays PLC",
      "jurisdiction": "United Kingdom",
      "engagement_type": "audit",
      "pie_status": "pie",
      "status": "active",
      "group_id": "GLEIF_213800",
      "parent_entity_id": null,
      "identifiers": [
        { "type": "lei", "value": "213800LBQA1Y9L22JB70", "verified": true },
        { "type": "companies_house", "value": "01026167", "verified": true }
      ],
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-03-01T14:22:00Z"
    }
  ],
  "meta": { "total": 142, "limit": 5, "offset": 0 }
}

6.2 Lookup Entity by Identifier

Find an entity by a specific identifier. Searches across all firms to support cross-firm conflict detection.

Permission: read

curl -s -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/lookup?type=lei&value=213800LBQA1Y9L22JB70" \
  | jq .

Response — Own Firm's Entity

{
  "data": {
    "id": "uuid",
    "client_name": "Barclays PLC",
    "jurisdiction": "United Kingdom",
    "engagement_type": "audit",
    "pie_status": "pie",
    "status": "active",
    "own_entity": true,
    "identifiers": [ ... ]
  }
}

Response — Another Firm's Entity

{
  "data": {
    "id": "uuid",
    "client_name": "Barclays PLC",
    "jurisdiction": "United Kingdom",
    "own_entity": false,
    "held_by_firm": "Menzies LLP"
  }
}

6.3 Create Entity

Create a new entity in the authenticated firm's register. Automatically triggers duplicate detection.

Permission: write

curl -s -X POST -H "x-api-key: gis_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Holdings Ltd",
    "jurisdiction": "United Kingdom",
    "engagement_type": "audit",
    "pie_status": "non_pie",
    "identifiers": [
      { "type": "companies_house", "value": "12345678" }
    ],
    "notes": "Imported from CRM ref: ACC-2026-001"
  }' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities" \
  | jq .

6.4 Update Entity

Update an entity owned by the authenticated firm. Only provided fields are updated.

Permission: write

Updatable fields: client_name, jurisdiction, engagement_type, pie_status, status, notes, relationship_type, parent_entity_id

curl -s -X PATCH -H "x-api-key: gis_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "engagement_type": "review", "pie_status": "pie" }' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/550e8400-..." \
  | jq .

6.5 Get Compliance Status

Returns a compliance summary for an entity with per-module traffic light statuses.

Permission: read

curl -s -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/550e8400-.../compliance" \
  | jq .

Example Response

{
  "data": {
    "entity_id": "uuid",
    "client_name": "Barclays PLC",
    "pie_status": "pie",
    "overall_status": "attention_required",
    "modules": {
      "conflict_checks": { "status": "clear", "active_checks": 0 },
      "acceptance": { "status": "approved", "approved_at": "2026-01-20T14:30:00Z" },
      "nas_evaluations": { "status": "clear", "active_count": 0, "prohibited_count": 0 },
      "fee_dependency": { "status": "warning", "dependency_percentage": 18.5 },
      "rotation": {
        "status": "attention_required",
        "roles_nearing_rotation": [
          { "role": "engagement_partner", "due_date": "2026-09-30" }
        ]
      },
      "breaches": { "status": "clear", "open_count": 0 },
      "declarations": { "status": "clear", "pending_count": 0, "overdue_count": 0 }
    }
  }
}

The overall_status is derived: if any module is attention_required or in breach, the overall is attention_required. If all are clear or approved, the overall is clear.

6.6 Get Group Structure

Returns the group structure for an entity — parent, subsidiaries, and group metadata. Cross-firm entities show firm name but not engagement details.

Permission: read

curl -s -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/550e8400-.../group" \
  | jq .

6.7 Initiate Conflict Check

Initiate a conflict check for an entity. Broadcasts to all other firms in the network.

Permission: write

curl -s -X POST -H "x-api-key: gis_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "iesba_path": "audit_review_4a",
    "notes": "Pre-engagement check from CRM"
  }' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/conflict-checks" \
  | jq .

6.8 Get Conflict Check Status

Returns the status of a previously initiated conflict check with response summary.

Permission: read

curl -s -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/conflict-checks/550e8400-..." \
  | jq .

Example Response

{
  "data": {
    "id": "uuid",
    "entity_name": "Acme Holdings Ltd",
    "status": "complete",
    "issued_at": "2026-03-08T10:00:00Z",
    "responses": {
      "total": 5,
      "received": 5,
      "no_conflict": 4,
      "potential_conflict": 1,
      "conflict_identified": 0
    },
    "resolution": "approved",
    "resolved_at": "2026-03-08T16:30:00Z"
  }
}

6.9 Identifiers — Add, Verify, Delete

Manage entity identifiers (LEI, Companies House, RCS, VAT, ACRA UEN, etc.). Duplicate identifier values within the firm return 409 CONFLICT.

Body fields: type, value and jurisdiction are all required; source is optional.

Permission: write

curl -X POST -H "x-api-key: gis_live_abc123" -H "Content-Type: application/json" \
  -d '{"type":"lei","value":"529900T8BM49AURSDO55","jurisdiction":"United Kingdom","source":"crm-sync"}' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/{id}/identifiers"

6.10 Set Entity Parent (Group Structure)

Sets or clears the parent of an entity. Cross-firm parents are only allowed when both entities belong to the same group (enforced by the set_entity_parent RPC).

Permission: write

curl -X PATCH -H "x-api-key: gis_live_abc123" -H "Content-Type: application/json" \
  -d '{"parent_entity_id":"550e8400-..."}' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities/{id}/parent"

6.11 Notifications (Per-User)

Notifications are per-user. The user_id query parameter is required and must belong to the firm that owns the API key. Optional unread_only=true filter.

Permission: read (list), write (mark read)

curl -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/notifications?user_id={uuid}&unread_only=true"

6.12 Compliance — Read

Reads compliance records for a module. Supports entity_id and status filters plus standard pagination.

Modules: acceptance, nas, fee, declarations, rotation, conflict-register, gifts, breach, tcwg, disclosure

Permission: read

curl -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/compliance/breach?status=open&limit=25"

6.13 Compliance — Write (Draft Only)

Creates or updates compliance records for five modules: acceptance, nas, breach, gifts, conflict-register.

Creating an acceptance record against an entity whose pie_status is unresolved returns 409 PIE_UNRESOLVED; resolve the entity's PIE status first. A pie_status supplied in the body must be the enum pie | non_pie | unresolved — booleans return 400 INVALID_PIE_STATUS.

Permission: write

Server-derived fields: firm_id and the actor column (initiated_by, reported_by, created_by, etc.) are set from the API key — do not pass them.

curl -X POST -H "x-api-key: gis_live_abc123" -H "Content-Type: application/json" \
  -d '{"entity_id":"...","breach_type":"independence","description":"…","occurred_on":"2026-04-20"}' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/compliance/breach"

6.14 Reports — Async Job Pattern

Reports are generated asynchronously by the report-worker background job (runs every minute, plus a best-effort kick on enqueue).

1. POST a report request — returns 202 Accepted with a job id and status: "queued".
2. GET the job by id every 5–10 seconds. Status transitions: queued → running → completed (or failed after 3 retries).
3. When status = "completed", the response includes a download_url — a 1-hour signed URL to the report file in the report-exports bucket.

Body: report_type (required), format (pdf | csv | xlsx | json, default json) and filters (optional object, persisted on the job and passed to the generator).

Report types: conflict_check_summary, network_response, entity_register, audit_activity, declaration_completion, rotation_status, fee_dependency, breach_summary

Permission: read

# 1. Enqueue
curl -X POST -H "x-api-key: gis_live_abc123" -H "Content-Type: application/json" \
  -d '{"report_type":"breach_summary","format":"csv","filters":{"from":"2026-01-01","to":"2026-04-30"}}' \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/reports"

# 2. Poll
curl -H "x-api-key: gis_live_abc123" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/reports/{job_id}"
# → { "data": { "status": "completed", "download_url": "https://…signed…" } }

7. Integration Patterns

7.1 CRM Entity Sync (Push)

# On new client created in CRM:
1. POST /v1/entities (create in GIS)
2. Store returned entity_id in CRM as foreign key
3. Check duplicate_warnings — flag for review if matches found

# On client updated in CRM:
1. PATCH /v1/entities/{id} (update in GIS)

# Nightly sync:
1. GET /v1/entities?limit=100&offset=0 (paginate through all)
2. Compare with CRM records, reconcile differences

7.2 Pre-Engagement Independence Check

# When engagement is proposed in CRM:
1. GET /v1/entities/lookup?type=companies_house&value={number}
2. If entity exists:
   a. GET /v1/entities/{id}/compliance → check traffic light
   b. If clear → proceed
   c. If attention_required → flag for manual review
3. If entity not found:
   a. POST /v1/entities (create)
   b. POST /v1/conflict-checks (initiate check)
   c. Poll GET /v1/conflict-checks/{id} until complete
   d. Proceed or escalate based on result

7.3 Dashboard Widget (Read-Only)

# For each audit client displayed in CRM dashboard:
1. GET /v1/entities/{id}/compliance
2. Display overall_status as traffic light (green/amber/red)
3. Link "View in GIS" to the GIS application

7a. Request Examples (curl and Postman)

All examples use the backend URL. Substitute <project-ref> with the value shown in GIS → Settings → API Documentation, where the exact URLs can also be copied with one click.

curl — REST API

# 1. Confirm the key, firm binding and rate limit
curl -s -H "x-api-key: gis_live_YOUR_KEY_HERE" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/health" | jq .

# 2. Search the firm's entity register
curl -s -H "x-api-key: gis_live_YOUR_KEY_HERE" \
  "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities?q=acme&limit=5" | jq .

# 3. Create an entity
curl -s -X POST "https://<project-ref>.supabase.co/functions/v1/gis-api/v1/entities" \
  -H "x-api-key: gis_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
        "client_name": "Acme Holdings Ltd",
        "jurisdiction": "United Kingdom",
        "engagement_type": "audit",
        "pie_status": "non_pie"
      }' | jq .

curl — MCP server

MCP is JSON-RPC over Streamable HTTP: always POST, and always send Accept: application/json, text/event-stream — omitting it returns 406 Not Acceptable. curl is for diagnostics; day-to-day use goes through an MCP client that performs the OAuth 2.1 flow for you.

# 1. Unauthenticated call — expected: 401 with a WWW-Authenticate pointer
curl -i -X POST "https://<project-ref>.supabase.co/functions/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Protected-resource document (no auth required)
curl -s "https://<project-ref>.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource" | jq .

# 3. List tools with an OAuth access token
curl -s -X POST "https://<project-ref>.supabase.co/functions/v1/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 4. Call a tool
curl -s -X POST "https://<project-ref>.supabase.co/functions/v1/mcp" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"whoami","arguments":{}}}'

Postman

1. In GIS, open Settings → API Documentation and use Copy Postman collection; the backend URL for your environment is already filled in.
2. In Postman choose Import → Raw text and paste the collection.
3. Set the collection variables: apiKey (your firm API key) and, for MCP requests, accessToken (an OAuth 2.1 access token).
4. Postman does not perform Dynamic Client Registration; obtain the MCP token from an MCP client, or configure Postman's OAuth 2.0 helper using the discovery document above.

Request headers at a glance:

8. Data Model Reference

Entity Fields

Identifier Types

Engagement Types

IESBA Path Values

9. MCP Server (AI Assistant Integration)

GIS exposes a Model Context Protocol server so AI assistants and agentic clients (Claude, ChatGPT, Cursor, n8n, custom workflows) can work with GIS as MCP tools — same firm scoping and the same audit trail as the REST API.

Endpoint

https://<project-ref>.supabase.co/functions/v1/mcp

Copy the exact URL for your environment from GIS → Settings → API access. Requests without a valid bearer token return 401 with a WWW-Authenticate header pointing at the OAuth discovery document — MCP clients follow that automatically, so in practice you only ever paste the URL above.

Connecting a client

1. In your AI client, add a new MCP server of type HTTP / Streamable HTTP (Claude: Settings → Connectors → Add custom connector; Cursor: Settings → MCP → Add new server; n8n: MCP Client node).
2. Paste the endpoint URL. Do not add any x-api-key or other auth header.
3. The client opens a GIS sign-in page. Sign in with your normal GIS account (including MFA if enabled).
4. Approve the connection on the consent screen. The client stores the token and refreshes it automatically.
5. You should now see the GIS tools listed in the client. Test with: "Use the GIS tools to tell me who I am and list five of my firm's entities."

Tools

All tools operate on your own firm only — the federated data model prevents cross-firm access, including for global administrators.

Permissions and auditing

• Tools run under your role. A firm user sees only what a firm user can see in the interface; compliance-module tools return nothing for roles without compliance access.
• Every tool invocation is logged (tool name, status, latency, client) for compliance review.
• Access follows your account: disabling the account, or revoking the connection in your AI client, immediately ends the integration. There is no long-lived key to leak.

Example AI Workflow — Pre-engagement Independence Check

Agent prompt:
  "We're considering a new audit engagement with Acme Holdings Ltd in the UK.
   Check if we already have them, list any open compliance items, and start
   a conflict check if we don't already have an active one."

The agent will autonomously:
  1. whoami
  2. search_entities  { query: "Acme Holdings" }
  3. get_entity       { entity_id: <match> }                     # if found
  4. list_compliance  { module: "breach", entity_id, status: "open" }
  5. start_conflict_check { entity_name: "Acme Holdings Ltd",
                            jurisdiction: "United Kingdom",
                            engagement_type: "audit_review",
                            notes: "..." }                          # if needed

10. Security Best Practices

• Store API keys securely — use environment variables or a secrets manager. Never store keys in source code or version control.
• Use read-only keys unless your integration needs to create or update entities.
• Set expiry dates on keys used for temporary integrations or third-party access.
• Monitor usage via the API access tab in GIS Settings — review request counts and last-used timestamps.
• Rotate keys periodically — generate a new key, update your integration, then revoke the old key.
• Use HTTPS only — the API does not accept unencrypted HTTP connections.
• Implement error handling — handle 429 rate limit errors with exponential backoff.

11. Support & Troubleshooting

Common connection errors

Checking Request History

Review recent API requests in GIS → Settings → API access. The usage section shows requests per day and per week for each key.

Common Issues

Contact

• API key issues: Contact your firm administrator
• API bugs or feature requests: Contact the GIS product owner at the HLB Executive Office

© 2026 HLB International Limited. This document is confidential and intended for HLB member firm use only.