Grometrics

Identify API

Merge a Grometrics browser visitor with an application user from your backend.

Last updated June 3, 2026

Use POST /api/v1/identify when signup or login is handled by a form POST, server action, or backend endpoint. Read the first-party Grometrics visitor cookie from the incoming customer request, then forward that opaque visitor ID with your application user ID.

Workspace-scoped authentication

Send a workspace API key as a Bearer token and include `websiteId`. Grometrics verifies that the site or tracked app belongs to that workspace before accepting the request.

Replace YOUR_SITE_ID with your site ID from Settings > Tracking.

POST /api/v1/identify

1curl https://usegrometrics.com/api/v1/identify \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "websiteId": "YOUR_SITE_ID",6    "visitorId": "OPAQUE_GROMETRICS_VISITOR_ID",7    "userId": "user_123"8  }'

Options / Configuration

FieldMeaningRequired
websiteIdThe Grometrics site or tracked app ID owned by the API-key workspace✓
visitorIdOpaque Grometrics ID read from the site-specific cookie✓
userIdStable application user ID; never used as Visitor.id✓

200 response

1{2  "visitorId": "CANONICAL_GROMETRICS_VISITOR_ID",3  "previousVisitorId": "OPAQUE_GROMETRICS_VISITOR_ID",4  "mergedSources": ["OPAQUE_GROMETRICS_VISITOR_ID"],5  "mergeCount": 16}

Python / Flask

1key = f'gm_cross_visitor_id_{WEBSITE_ID}'2visitor_id = request.cookies.get(key) or request.cookies.get(f'gm_visitor_id_{WEBSITE_ID}')3requests.post(GROMETRICS_URL, headers={'Authorization': f'Bearer {API_KEY}'}, json={'websiteId': WEBSITE_ID, 'visitorId': visitor_id, 'userId': user.id})

Browser and mobile SDKs use the deliberately public /api/track/identify endpoint with recent-session validation and rate limits. Backend integrations use this authenticated route. Both call the same merge service and produce the same canonical visitor.

Server-side sign-out reset

There is no reset endpoint. Generate a fresh unique anonymous ID and replace gm_cross_visitor_id_<websiteId> in the sign-out response. The trusted events API creates internal Grometrics sessions itself.

Was this page helpful?