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>. Endpoints marked write refuse a read-only personal API token with 403 INSUFFICIENT_; 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
| Header | Why |
|---|---|
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/json | Always. |
X-App-Platform, X-Client-Version | ios or android, and the app's version. Lets your Laramin refuse versions that are too old with 426 UPGRADE_REQUIRED. |
X-Locale | The language the person chose in the app. |
X-Workspace-Ref, X-Team | Optional, 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-Id | Recommended: 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-, X-Device-Model, X-OS-Version, X-App-Version | Optional. Kept with each request in your Laramin's logs, to help trace problems. |
The signed-in person
GET profile
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"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)
| Field | Rules |
|---|---|
name | Required, up to 255 characters. |
language_code | Required, 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/ 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)
| Field | Rules |
|---|---|
current_password | Required. |
password | Required, and must meet your Laramin's password rules. |
Counts against the sign-in limit of 5 a minute.
Workspaces and permissions
| Method | Path | What it returns |
|---|---|---|
| GET | /api/ | The workspaces the person may work in, with each one's time zone and office hours. |
| GET | /api/ | 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.
| Field | What it is |
|---|---|
ref | The workspace's reference. Send it as X-Workspace-Ref. |
code, name | The workspace's code and name. |
time_zone | The time zone its business rules use, such as Asia/Kolkata. |
is_default | true for your Laramin's default workspace. |
is_preferred | true for the workspace the person chose as theirs. |
office_hours | Each 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_ | A note about the hours, such as "Closed on public holidays", or null. |
The answer also has:
resolved: the workspace this request ran in.modeisspecificfor one workspace orallwhen reading across every workspace;refis its reference;bysays why:header(the app sent it),preferred,only,default,firstornone.zones:display, the time zone to show times in for this person, andsystem, your Laramin's time zone.scope:memberships, orall_activefor 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_, and a team 403 TEAM_UNAVAILABLE: show the picker again.
GET authorization
| Field | What it is |
|---|---|
permissions | The names of the permissions the person has here, sorted: their own, and those of their roles in this workspace and team. |
all | true for a super admin, who may do everything. permissions is then empty. |
roles | The person's role names, to show. Don't decide anything on them. |
context | The 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. |
subject | The person's id and is_super_admin. |
version | A 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
| Parameter | Use | Default |
|---|---|---|
types | system, push, or both separated by a comma. | Both |
unread_only | true to list unread ones only. | false |
since_days | Only the last 1 to 365 days. | All |
page, per_page | Paging. 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.
Consent
When your Laramin needs people to accept terms or other consents, the app reads and records them here.
GET consent
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)
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{ "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., cookies., cookies. and cookies.. terms_of_service and cookies. 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.
| Method | Path | What it serves |
|---|---|---|
| GET | /api/ | What has changed since the app last looked, so it fetches only that. |
| GET | /api//api/ | 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/ | Core Mobile's settings, theme, menus, onboarding and home dashboard. See How Core Mobile works. |
| GET | /api/ | The social sign-in providers the app can offer. See Social sign-in from a mobile app. |
Careful: Don't build on GET /api/. 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/ 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/ instead.
Module endpoints for apps
Modules add their own endpoints under /api/, signed in with the same token:
- Monetization's plans and features: Monetization catalogue API reference.
- Activity Log: the signed-in person's own activity, at
module/andactivitylog/ logs/ list module/.activitylog/ logs/ details - Custom Fields: an entity's field definitions, at
/api/. See Custom field types and settings.v1/ customfield/ schema/ <alias>
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.laramin.in. The online article may have changed since.