In this section · 3 articles

Mobile API endpoints

What Core 12.8's mobile API lets a signed-in app do (profile, photo, password, notifications, consent, the person's workspaces and what they may do) and what it serves before sign-in, with each endpoint's fields, the headers mobile apps should send, and which module endpoints build on it.

Applies to
Core 12.8 and later
Who can do this
Developer
On this page

Every path below is under https://<your Laramin>/api/v1/mobile/. Endpoints marked write refuse a read-only personal API token with 403 INSUFFICIENT_SCOPE; an app's own sign-in token may write. For signing in, see Sign people in from a mobile app.

Headers a mobile app should send

HeaderWhy
Authorization: Bearer <access token>Once someone is signed in.
X-Api-Key: <app key>Before anyone is signed in. Signing in, the two-factor step and refresh don't need it.
Accept: application/jsonAlways.
X-App-Platform, X-Client-Versionios or android, and the app's version. Lets your Laramin refuse versions that are too old with 426 UPGRADE_REQUIRED.
X-LocaleThe language the person chose in the app.
X-Workspace-Ref, X-TeamOptional, once someone is signed in: the workspace, and the team in it, the request acts in. Take the workspace from GET workspaces. Leave them out to use the person's usual workspace.
X-Device-IdRecommended: an id that stays the same for each installed app. Requests made before sign-in are counted per device for the rate limits, so phones on one network don't share a limit. Also kept in your Laramin's logs.
X-Device-Platform, X-Device-Model, X-OS-Version, X-App-VersionOptional. Kept with each request in your Laramin's logs, to help trace problems.

The signed-in person

GET profile

JSON
{
  "success": true,
  "message": "Profile retrieved successfully.",
  "data": {
    "user": {
      "id": 42,
      "name": "Example User",
      "email": "user@example.com",
      "language_code": "en",
      "avatar_url": "https://crm.example.com/storage/avatars/42.webp",
      "is_super_admin": false
    }
  },
  "meta": { "request_id": "6f1d0c2e-…", "locale": "en" }
}

Replace the highlighted values with your own.

Those six fields are all data.user has. It doesn't include the person's roles.

POST profile (write)

FieldRules
nameRequired, up to 255 characters.
language_codeRequired, one of the languages your Laramin has turned on, such as en.

POST profile/avatar (write), DELETE profile/avatar (write)

Upload the photo as multipart/form-data in a field named avatar. The file types and size allowed are your Laramin's profile photo rules. A failed upload never changes the name or language.

POST password (write)

FieldRules
current_passwordRequired.
passwordRequired, and must meet your Laramin's password rules.

Counts against the sign-in limit of 5 a minute.

Workspaces and permissions

MethodPathWhat it returns
GET
/api/v1/mobile/workspaces
The workspaces the person may work in, with each one's time zone and office hours.
GET
/api/v1/mobile/authorization
What the person may do in the workspace and team the request runs in.

Both answer for the signed-in person only, need no permission, and send an ETag: send it back in If-None-Match to get 304 when nothing has changed. Their answers depend on X-Workspace-Ref and X-Team.

GET workspaces

data.workspaces lists the workspaces, by name. They're exactly the ones X-Workspace-Ref accepts from this person.

FieldWhat it is
refThe workspace's reference. Send it as X-Workspace-Ref.
code, nameThe workspace's code and name.
time_zoneThe time zone its business rules use, such as Asia/Kolkata.
is_defaulttrue for your Laramin's default workspace.
is_preferredtrue for the workspace the person chose as theirs.
office_hoursEach day, mon to sun, with open, from and to as HH:MM in the workspace's time zone. The workspace's own hours, or your Laramin's when it has none. null when neither is set.
office_hours_noteA note about the hours, such as "Closed on public holidays", or null.

The answer also has:

  • resolved: the workspace this request ran in. mode is specific for one workspace or all when reading across every workspace; ref is its reference; by says why: header (the app sent it), preferred, only, default, first or none.
  • zones: display, the time zone to show times in for this person, and system, your Laramin's time zone.
  • scope: memberships, or all_active for a super admin, who may enter every active workspace.

There's no endpoint to switch workspace. Keep the person's choice in the app and send it as X-Workspace-Ref on each request. A workspace they can't enter answers 403 WORKSPACE_UNAVAILABLE, and a team 403 TEAM_UNAVAILABLE: show the picker again.

GET authorization

FieldWhat it is
permissionsThe names of the permissions the person has here, sorted: their own, and those of their roles in this workspace and team.
alltrue for a super admin, who may do everything. permissions is then empty.
rolesThe person's role names, to show. Don't decide anything on them.
contextThe workspace (mode, ref, name) and team (id, name, or null) the answer is for. When reading across all workspaces, only permissions that aren't tied to a workspace count.
subjectThe person's id and is_super_admin.
versionA short id of this answer, to note in your logs.

Use it to decide what to show, such as hiding a button the person can't use. Your Laramin still checks every request, and a record-level decision, such as whether they may edit one particular record, comes from that record's own endpoint. Ask again after changing X-Workspace-Ref or X-Team.

Notifications

In-app and push notifications only. Email, SMS and WhatsApp messages aren't listed.

GET notifications

ParameterUseDefault
typessystem, push, or both separated by a comma.Both
unread_onlytrue to list unread ones only.false
since_daysOnly the last 1 to 365 days.All
page, per_pagePaging. per_page is 1 to 50.1, 20

POST notifications/{id}/read (write), POST notifications/read-all (write)

Mark one or all as read. Both answer with unread, the number still unread. An id that belongs to someone else answers 404.

When your Laramin needs people to accept terms or other consents, the app reads and records them here.

data.purposes lists each consent with purpose, label, required_version, required, refusable, current_outcome, accepted_version and outstanding. data.outstanding lists the purposes the person still owes.

POST consent (write)

JSON
{ "decisions": [ { "purpose": "terms_of_service", "outcome": "granted" } ] }

Send 1 to 32 decisions. outcome is granted, refused or withdrawn. A consent that can't be refused accepts only granted. The answer lists what's still outstanding. A purpose your Laramin doesn't offer answers 422.

Laramin itself offers these purposes: terms_of_service, privacy_policy, cookies.necessary, cookies.functional, cookies.analytical and cookies.marketing. terms_of_service and cookies.necessary can't be refused. Read GET consent for the ones your Laramin asks for, and which are required.

Before sign-in

These need the app's key and nobody signed in. Some also accept a signed-in token and then answer for that person.

MethodPathWhat it serves
GET
/api/v1/mobile/sync/manifest
What has changed since the app last looked, so it fetches only that.
GET
/api/v1/mobile/assets
/api/v1/mobile/assets/{key}
Images and files the app uses, such as logos, each with a key. The list answer has a version that changes when any asset does.
GET
/api/v1/mobile/module/coremobile/…
Core Mobile's settings, theme, menus, onboarding and home dashboard. See How Core Mobile works.
GET
/api/v1/mobile/module/sociallogin/providers
The social sign-in providers the app can offer. See Social sign-in from a mobile app.

Careful: Don't build on GET /api/v1/mobile/get_setting. It's kept for older apps and will be removed in a future major version. It returns only Core's public settings, the ones GET /api/v1/public/settings serves, as rows of id, module, name, value, created_at and updated_at. It never returns passwords or keys. Read public settings from GET /api/v1/public/settings instead.

Module endpoints for apps

Modules add their own endpoints under /api/v1/mobile/module/<module>/, signed in with the same token: