Check-in API

Examples below show the wire-format Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE header. To compute the signature in your code, use the signedRequest helper in Authentication.

The Check-in API lets your backend read the duty presence state of your salespeople in SalesOS — did they check in today, where, on which shift, and until when it is valid. It was built for composing your own app screens (for example, a super-app home widget) before the user ever opens the SalesOS module. It is a server-to-server API: you look collaborators up by CPF or email, in batch, and SalesOS answers with today’s state computed in your company’s timezone. With the checkin:write scope it can also check a collaborator in and out.

How It Works

You get an API Key with the checkin:read scope (Admin > Integrations > API Keys)
Your backend asks for the check-in state of one or many collaborators (by CPF or email)
SalesOS answers with today’s latest check-in per collaborator — plus optional week/month engagement counts
Optionally, your backend checks people in and out with a key that also has checkin:write, relaying the GPS reading from the collaborator’s phone

Authentication

All requests require an API Key in the Authorization header:

Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE

See the Authentication page for details on creating and managing API Keys.

Property	Details
Header	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Scope required	`checkin:read` for reading and `checkin_options`; `checkin:write` for `checkin_create` and `checkin_checkout`
Rate limit	Configurable per key (default: 1000 requests/hour)
Key format	`sk_live_` (production) or `sk_test_` (testing)

Environments

Production
Staging

Base URL: https://api.play2sell.com

Base URL: https://api-staging.play2sell.com

Endpoint Reference

POST https://api.play2sell.com/functions/v1/checkin-partner-api

The endpoint accepts these actions via the action field:

Action	Scope	What it does
`checkin_status`	`checkin:read`	Today’s state, in batch
`checkin_engagement`	`checkin:read`	State plus week/month counts, in batch
`checkin_options`	`checkin:read`	What one collaborator can do right now
`checkin_create`	`checkin:write`	Check one collaborator in
`checkin_checkout`	`checkin:write`	Check one collaborator out

Each collaborator is identified by CPF (any format — digits are normalized) or email. When both are sent, CPF wins.

Action: checkin_status

Today’s latest check-in per collaborator. “Today” is computed in your company’s timezone (returned as timezone / reference_date in the response) — never UTC.

Request Schema

string

required

Must be "checkin_status"

array

required

Array of collaborator references (max 500)

string

CPF, any format (52998224725 or 529.982.247-25). Must contain exactly 11 digits.

string

Email — used only when cpf is absent

Example

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_status",
    "collaborators": [
      { "cpf": "529.982.247-25" },
      { "email": "joao@yourcompany.com" }
    ]
  }'

Response (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-07-19",
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-...",
        "name": "Maria Santos",
        "membership_status": "active",
        "checked_in_today": true,
        "on_duty_now": true,
        "latest_checkin": {
          "status": "active",
          "mode": "geo",
          "shift": "afternoon",
          "checked_in_at": "2026-07-19T16:03:21+00:00",
          "shift_expires_at": "2026-07-19T21:00:00+00:00",
          "location_id": "c81e728d-...",
          "location_name": "Plantão Morumbi",
          "location": { "lat": -23.6012, "lng": -46.7003, "accuracy": 14 }
        },
        "org_unit_id": "a87ff679-..."
      },
      {
        "email": "joao@yourcompany.com",
        "found": true,
        "user_id": "45c48cce-...",
        "name": "Joao Silva",
        "membership_status": "active",
        "checked_in_today": false,
        "on_duty_now": false
      }
    ],
    "total": 2,
    "found": 2
  },
  "meta": { "request_id": "a1b2c3d4-...", "timestamp": "2026-07-19T18:00:00.000Z" }
}

Response fields explained

boolean

Whether the CPF/email matched a collaborator in your company. An unknown collaborator is found: false — it is not an error, and the array keeps the same order as your request.

boolean

Whether the collaborator has at least one non-rejected check-in today (company timezone).

boolean

true when the latest check-in is active/approved and its shift has not expired — i.e. the collaborator is on duty right now.

object

Today’s most recent check-in. Omitted when there is none. mode is geo (in-person with GPS), home (home office) or offline. status may be active, approved, pending (awaiting leader approval), expired (shift ended normally) or checkout. location has the GPS reading stored with the check-in: lat, lng, accuracy (meters) and, for check-ins made through this API, captured_at (when the phone read the GPS). Absent when the check-in had no GPS (home office, checkout).

string

The collaborator’s membership in your company (active, inactive, …). A collaborator can be found and inactive.

Day track (`include_day`)

Send "include_day": true on checkin_status to get, beyond the current state, how the day is going shift by shift and when the button unlocks again. This is what a home screen needs to render the check-in block without opening the SalesOS module.

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_status",
    "collaborators": [{ "cpf": "52998224725" }],
    "include_day": true
  }'

Response (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-13",
    "shifts": [
      { "key": "morning",   "label": "Manha", "start": "09:00", "end": "13:59" },
      { "key": "afternoon", "label": "Tarde", "start": "14:00", "end": "18:59" }
    ],
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "day": {
          "shifts": [
            { "key": "morning",   "label": "Manha", "start": "09:00", "end": "13:59",
              "state": "completed", "checked_in_at": "2026-08-13T12:04:00.000Z" },
            { "key": "afternoon", "label": "Tarde", "start": "14:00", "end": "18:59",
              "state": "upcoming" }
          ],
          "shifts_source": "tenant_default",
          "action": { "state": "waiting", "opens_at": "2026-08-13T17:00:00.000Z" }
        }
      }
    ]
  }
}

Shifts come back once at the top, not repeated per person. On a 500-collaborator batch that is the difference between a lean response and a multi-megabyte one.

Fields

Field	Meaning
`shifts[]` (top level)	Your company’s enabled shifts, ordered by start time
`shifts[].label`	The shift name as your company configured it — render this value
`day.shifts[].state`	`completed` · `open` · `upcoming` · `missed`
`day.shifts[].checked_in_at`	When that shift’s check-in happened. Absent when there was none — test for presence, not for `null`
`day.action.state`	`available` when a shift is open without a check-in; otherwise `waiting`
`day.action.opens_at`	When the next shift opens. Absent while `state` is `available` (a shift is open now) and once the day is over
`day.shifts_source`	Which schedule was used: `location` or `tenant_default`
`day.location_id`	The unit whose schedule was used, when `shifts_source` is `location`

A unit can have its own hours, and they win. The top-level shifts array is your company’s default. When someone checks in at a unit that has its own schedule, day.shifts follows that unit and day.shifts_source says so. Read the person’s track, not the top-level array, when drawing their screen.Before the first check-in of the day there is no unit to resolve, so the company default is used.

The number of shifts belongs to your company — it is not fixed. It may be two, three, or none, with its own labels and hours. Build the screen from the array; never assume three slots or specific times.

Read opens_at together with state. With state: "available" it is absent because a shift is open right now. With state: "waiting" and no opens_at, the day is over and there is no further opening today — the screen must not show a countdown crossing midnight.

Action: checkin_engagement

Everything checkin_status returns, plus week/month engagement counts per collaborator. Batches are capped at 100.

string

required

Must be "checkin_engagement"

array

required

Array of collaborator references (max 100)

Example

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_engagement",
    "collaborators": [{ "cpf": "52998224725" }]
  }'

Each found collaborator gains an engagement object:

{
  "engagement": {
    "week":  { "checkins": 9,  "presence_days": 5 },
    "month": { "checkins": 34, "presence_days": 17 }
  }
}

checkins — check-ins in the current week/month (company timezone; expired counts — it is the normal end of a shift)
presence_days — distinct days with at least one check-in

Writing check-ins

With the checkin:write scope, your backend can check a collaborator in and out — for example from a “Check in” button on your own home screen. The effect is the same as a check-in made in the SalesOS app: the collaborator enters the lead queue, gets the shift and its end time, earns points, and the checkin.confirmed / checkin.checked_out webhooks fire.

This API writes. Unlike the read actions above, checkin_create and checkin_checkout change who receives leads. They require a key with checkin:write; a key with only checkin:read answers 403 with code: "scope_insufficient".

Write actions handle one collaborator per request, sent as collaborator (an object, not a list). In a write, “not found” is an error — there is no partial write:

Situation	HTTP	`code`
CPF/email not in your company	404	`COLLABORATOR_NOT_FOUND`
Collaborator found but inactive	409	`COLLABORATOR_INACTIVE`
More than one person matched	409	`COLLABORATOR_AMBIGUOUS`

Action: checkin_options

What your screen can offer right now, so it only shows the button that will work. Read-only — requires checkin:read.

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_options",
    "collaborator": { "cpf": "52998224725" },
    "location": { "lat": -23.6, "lng": -46.7, "accuracy": 15, "captured_at": "2026-09-21T14:03:00Z" }
  }'

location is optional. When sent, locations come back sorted by distance and duty says whether any is within reach.

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "current_shift": { "key": "afternoon", "label": "Tarde", "ends_at": "2026-09-21T20:59:00.000Z" },
    "on_duty_now": false,
    "modes": [
      { "key": "duty", "label": "Com Geolocalização", "requires_geo": true, "available": true },
      { "key": "home", "label": "Sem Geolocalização", "requires_geo": false, "available": false,
        "unavailable_reason": "HOME_SHIFT_NOT_ALLOWED" }
    ],
    "locations": [
      { "id": "c81e728d-...", "name": "Plantão Morumbi", "distance_meters": 42, "radius_meters": 100, "within_radius": true }
    ]
  }
}

unavailable_reason uses the same codes a checkin_create would return (MODE_DISABLED, TOO_FAR, HOME_OUTSIDE_SHIFT, HOME_SHIFT_NOT_ALLOWED, PRIOR_GEO_REQUIRED, LOCATION_NOT_FOUND). Mode and shift labels are your company’s configuration — render them as they come.

Action: checkin_create

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f2b8c1e-5d4a-4b7e-9f10-2a6c8d9e0f11" \
  -d '{
    "action": "checkin_create",
    "collaborator": { "cpf": "52998224725" },
    "mode": "duty",
    "location": { "lat": -23.6, "lng": -46.7, "accuracy": 15, "captured_at": "2026-09-21T14:03:00Z" },
    "location_id": "c81e728d-...",
    "client": { "app": "your-home", "version": "1.0.0" }
  }'

string

required

duty (on-site, requires location) or home (home office).

object

The device’s GPS reading, captured on the collaborator’s phone and relayed by your backend. Required for duty: lat, lng, accuracy (meters) and captured_at (ISO 8601 — when the phone read the GPS).

string

The on-site location the collaborator chose. Optional — without it, SalesOS picks the nearest location within its radius.

object

Your app and version (app, version). Stored with the check-in for audit.

Response (201):

{
  "data": {
    "checkin_id": "5f0c...",
    "status": "active",
    "mode": "duty",
    "on_duty_now": true,
    "queue_eligible": true,
    "shift": "afternoon",
    "shift_label": "Tarde",
    "shift_expires_at": "2026-09-21T20:59:00.000Z",
    "checked_in_at": "2026-09-21T14:03:05.000Z",
    "location_id": "c81e728d-...",
    "location_name": "Plantão Morumbi",
    "distance_meters": 42,
    "location": { "lat": -23.6, "lng": -46.7, "accuracy": 15, "captured_at": "2026-09-21T14:03:00Z" }
  },
  "meta": { "request_id": "a1b2c3d4-...", "timestamp": "2026-09-21T14:03:05.120Z" }
}

location echoes the GPS reading that was stored — same shape as latest_checkin.location in checkin_status. Absent when no GPS was sent. A new check-in closes the collaborator’s previous active one, exactly as in the app. It stays valid until shift_expires_at — your app does not need to keep pinging.

Location requirements

The GPS reading comes from your backend, so SalesOS checks that it is recent and precise before trusting it:

Rule	Limit	Refusal
Freshness	`captured_at` at most 60 s old (and at most 10 s in the future, for phone clock drift)	`400 STALE_LOCATION`
Precision	`accuracy` no larger than the chosen location’s radius (your company can set its own limit)	`422 LOW_ACCURACY`
Distance	Inside the radius of the chosen location — or of some location, when `location_id` is omitted	`422 TOO_FAR`

Read the GPS when the user taps the button, not when the screen opens. A reading taken on screen load is often stale by the time it arrives, and an indoor reading is often imprecise — both are refused, and asking the user to step outside and try again fixes them.

A refused check-in writes nothing: the collaborator stays exactly as before.

Action: checkin_checkout

Ends the active check-in before the shift ends. The collaborator leaves the lead queue immediately and checkin.checked_out fires.

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7a1c2e3f-0b4d-4e5f-8a6b-9c0d1e2f3a4b" \
  -d '{
    "action": "checkin_checkout",
    "collaborator": { "cpf": "52998224725" },
    "reason": "user_requested",
    "client": { "app": "your-home", "version": "1.0.0" }
  }'

Response (200):

{
  "data": {
    "status": "checkout",
    "on_duty_now": false,
    "already_checked_out": false,
    "checked_out_at": "2026-09-21T17:10:00.000Z",
    "previous_checkin_id": "5f0c..."
  }
}

With no active check-in, the answer is still 200 with "already_checked_out": true and nothing is written — a double tap never breaks your screen.

Retries and `Idempotency-Key`

Send an Idempotency-Key header (8–128 characters; a UUID works) on checkin_create and checkin_checkout. Repeating the request with the same key within 24 hours:

returns the same response, with the header Idempotency-Replayed: true, and creates nothing new;
with a different body, answers 409 IDEMPOTENCY_KEY_REUSED;
while the first request is still running, answers 409 IDEMPOTENCY_IN_PROGRESS — retry in a few seconds.

A refused request (4xx) does not consume the key: after fixing the cause (a fresh GPS reading, for example) you can retry with the same key.

The signature timestamp is valid for 30 seconds, so a retry must be signed again — the Idempotency-Key is what ties the attempts together.

Messages for the collaborator

Write errors carry a message in Brazilian Portuguese, written to be shown directly to the collaborator (for example: “Você está a 180 m de Plantão Morumbi. Chegue a até 100 m para fazer o check-in.”). Branch your logic on code, never on the text.

HTTP	`code`	When
400	`VALIDATION_ERROR`	Invalid body; `details` names the field
400	`GEO_REQUIRED`	`duty` without `location`
400	`STALE_LOCATION`	GPS reading older than 60 s
404	`COLLABORATOR_NOT_FOUND`	CPF/email not in your company
404	`LOCATION_NOT_FOUND`	`location_id` unknown or inactive, or no active location
409	`COLLABORATOR_INACTIVE` / `COLLABORATOR_AMBIGUOUS`	See above
409	`IDEMPOTENCY_KEY_REUSED` / `IDEMPOTENCY_IN_PROGRESS`	See retries
422	`TOO_FAR`	Outside the radius; `details` has distance, radius and location
422	`LOW_ACCURACY`	GPS too imprecise; `details` has both values
422	`MODE_DISABLED`	The mode is turned off in your company
422	`HOME_OUTSIDE_SHIFT` / `HOME_SHIFT_NOT_ALLOWED`	Home office outside the shifts your company allows
422	`PRIOR_GEO_REQUIRED`	Your company requires an on-site check-in earlier the same day before home office
429	`RATE_LIMITED`	More than 10 writes for the same collaborator in 10 minutes; see `Retry-After`
503	`PRIOR_GEO_CHECK_UNAVAILABLE`	Temporary failure checking the rule above — retry

Self mode (SSO user token)

If your app already holds the token of a user who signed in through SSO, the same endpoint answers for the token’s own user, with no API key:

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "action": "checkin_status" }'

Identity comes only from the verified token — do not send collaborators. A request with that field is rejected with SELF_MODE_NO_COLLABORATORS: user-level tokens can never look other people up.
The company scope comes from the session; the response has the exact same shape, with a single item in collaborators.
checkin_engagement works the same way ({ "action": "checkin_engagement" }).
Write actions and checkin_options are partner-only: with a user token they answer 400 SELF_MODE_NOT_SUPPORTED. Inside the SalesOS app, check-in is done by the app itself.

Use self mode for screens rendered inside the authenticated app; use the API key (S2S) when your backend composes screens before the user has a SalesOS session — like a super-app home widget.

Error Handling

All errors follow the shared structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": []
  }
}

Two shapes, not one. The block above is the endpoint error. Failures in the authentication layer answer before the endpoint runs, with error as a string:

{ "error": "Missing Authorization header", "code": "header_missing" }

Code that assumes error.code reads undefined on every auth failure. Branch on the type — see API Conventions.

400 — VALIDATION_ERROR

Invalid body, batch over the limit, CPF without 11 digits, or an item with neither cpf nor email. The details array points to the item index.

401 — authentication layer

API key missing, unknown or expired, or the signature does not match. Answered with error as a string and codes such as header_missing, api_key_not_found, signature_invalid, timestamp_too_old.

403 — scope_insufficient

API key is valid but lacks the scope the action needs (checkin:read, or checkin:write for writes). Answered by the authentication layer: { "error": "...", "code": "scope_insufficient", "missing_scopes": ["checkin:write"] }.

405 — METHOD_NOT_ALLOWED

Only POST is accepted.

429 — RATE_LIMITED

Too many writes for the same collaborator (10 in 10 minutes). Wait the Retry-After seconds, then retry. Write actions have their own error table in Writing check-ins.

500 — SERVER_ERROR

Internal server error. Retry with exponential backoff (2s, 4s, 8s).

An unknown collaborator is not an error. The request succeeds with found: false for that item, so one bad CPF never breaks a whole home-screen render.

Rate Limits

Limit	Value
Default requests per hour	1000
Max collaborators per `checkin_status`	500
Max collaborators per `checkin_engagement`	100
Writes per collaborator (`checkin_create` + `checkin_checkout`)	10 every 10 minutes

Security

Reading needs checkin:read; creating or ending check-ins needs checkin:write — issue write keys only to the backend that owns the button
Every check-in created through the API is stored with its origin, the key that created it, your client and the raw GPS reading, for audit
Each key is scoped to a single company — a CPF from another company answers found: false
Requests are HMAC-signed (P2S-SIGN-V1) and logged for audit; documents are never written to logs

Never expose your API key in client-side code. This API must only be called from your backend server.

Overview

Integrations

Check-in API

Check-in API

How It Works

Authentication

Environments

Endpoint Reference

Action: checkin_status

Request Schema

Example

Response fields explained

Day track (`include_day`)

Fields

Action: checkin_engagement

Example

Writing check-ins

Action: checkin_options

Action: checkin_create

Location requirements

Action: checkin_checkout

Retries and `Idempotency-Key`

Messages for the collaborator

Self mode (SSO user token)

Error Handling

Rate Limits

Security

Next Steps

Authentication

Support

​Check-in API

​How It Works

​Authentication

​Environments

​Endpoint Reference

​Action: checkin_status

​Request Schema

​Example

​Response fields explained

​Day track (include_day)

​Fields

​Action: checkin_engagement

​Example

​Writing check-ins

​Action: checkin_options

​Action: checkin_create

​Location requirements

​Action: checkin_checkout

​Retries and Idempotency-Key

​Messages for the collaborator

​Self mode (SSO user token)

​Error Handling

​Rate Limits

​Security

​Next Steps

Authentication

Support

Check-in API

How It Works

Authentication

Environments

Endpoint Reference

Action: checkin_status

Request Schema

Example

Response fields explained

Day track (`include_day`)

Fields

Action: checkin_engagement

Example

Writing check-ins

Action: checkin_options

Action: checkin_create

Location requirements

Action: checkin_checkout

Retries and `Idempotency-Key`

Messages for the collaborator

Self mode (SSO user token)

Error Handling

Rate Limits

Security

Next Steps