Replace 0000000000 in the JSON body with an authorized employee’s registered mobile number. Use the returned data.employee_id in the daily distance report.
Query parameters
Send a JSON object with Content-Type: application/json.
employee_iduuidoptional
Use the UUID from the employee directory or phone lookup. Omit to include all employees in approved teams.
fromdaterequired
First attendance date (YYYY-MM-DD), in the report timezone. Choose today or one of the previous 365 days.
todaterequired
Last attendance date (YYYY-MM-DD), up to today. Use the same date as from for a single day, or request up to 31 days inclusive.
limitintegeroptional
Rows per page. Keep this value when requesting the next page.
cursorstringoptional
Pass meta.next_cursor from the previous response with the same filters and page size. Cursors expire after 24 hours.
Use a company token to read NexaSync data from your server or reporting job. For a third-party application or MCP client, use OAuth.
Create a connection
A verified company administrator opens Settings → Developer & integrations → Create API token.
Choose the approved teams and expiry (90 days by default, up to 365). Every token includes company:read. Add reports:daily-distance:read for distance reports, employees:phone:lookup for mobile lookup, or employees:read for the employee directory.
Creating or rotating a token requires a recent sign-in or identity confirmation within ten minutes.
Copy the complete token once and store it in the receiving server’s secret manager. NexaSync cannot reveal it after the page updates.
Only employees in the selected teams are included. Ask an administrator to approve a new connection if you need access to additional teams.
Make your first request
On your server, set NEXASYNC_API_BASE to https://portal.nexasync.io/api/public/v1 without a trailing slash. Set NEXASYNC_TOKEN in your secret manager. Use a token issued for the same environment (nxs_test_ for test or nxs_live_ for production).
A 200 OK response includes the company name, report timezone and granted scopes in data. Check these before requesting employee records. View the example response.
Never place a token in URLs, browser bundles, mobile applications, source control, screenshots or support tickets.
Rotate or disconnect
Rotate the connection, copy the replacement once, update the receiving server and verify the connection context. Then choose End old-token access now. This retires old rotation credentials while preserving the replacement. Otherwise old access ends within 24 hours or the earlier expiry shown in the portal.
Revoke connection disables every token for the connection. Connections can stop working if the approving administrator loses company-admin access, changes sign-in details, or signs in after a password-security upgrade. After a 401, ask a company administrator to review the connection and issue a replacement if needed.
Integration guide
Reviewed application OAuth
Connect an approved application with authorization code, S256 PKCE and explicit company administrator approval.
OAuth access is not activated in this environment
Review and discovery
Applications must be registered and reviewed before use. An HTTPS client ID metadata document (CIMD) also requires prior review; publishing one does not register an application. Metadata changes need another review. Open dynamic registration, implicit, password and client-credentials grants are unavailable.
Use the supplied canonical issuer and exact resource URL. Verify discovery, the issuer in the authorization response and your unpredictable, one-use state.
Canonical issuer
https://portal.nexasync.io
REST resource
https://portal.nexasync.io/api/public/v1
MCP resource
https://portal.nexasync.io/mcp/v1
Method and issuer path
Purpose
GET /.well-known/oauth-authorization-server
Issuer and OAuth endpoint discovery
GET /.well-known/oauth-protected-resource/api/public/v1
REST resource and scope discovery
GET /.well-known/oauth-protected-resource/mcp/v1
MCP resource and scope discovery
GET /oauth/authorize
Start administrator approval
POST /oauth/token
Exchange a code or refresh token
POST /oauth/revoke
Disconnect a token family
Authorization code with PKCE
Use a maintained OAuth client library. Generate a new 43–128 character verifier, its base64url SHA-256 challenge without padding, and a fresh state for every attempt. PKCE is required for public and confidential clients.
Authorization parameter
Value
response_type
code
client_id
The exact reviewed client ID
redirect_uri
An exact approved callback
resource
One approved REST or MCP resource URL
scope
Space-separated approved scopes including company:read
state
An unpredictable, one-use correlation value
code_challenge_method
S256
code_challenge
The 43-character encoded challenge
The administrator signs in, reviews the application, resource and permissions, chooses approved teams and confirms their identity. Redirect the administrator to NexaSync to complete this step. HTTPS callbacks are required except for explicitly approved native IP-loopback callbacks.
The single-use code expires within five minutes. If you lose the exchange response, restart authorization. Reusing the code with valid proof can invalidate tokens already issued from it. Exchange it at /oauth/token using application/x-www-form-urlencoded and grant_type=authorization_code, code, code_verifier, redirect_uri and the registered client authentication. If you include resource, use the same URL as in the authorization request.
This field example is for a public client registered with method none. Confidential clients use their registered client_secret_basic or client_secret_post method. Do not switch authentication methods or send a secret for a public client.
Resource-bound tokens and renewal
The response supplies access_token, token_type, expires_in, refresh_token, scope and resource. Access tokens last at most 15 minutes and work only at their exact approved resource. REST-resource and MCP-resource tokens cannot be interchanged.
Refresh with grant_type=refresh_token, the current refresh_token and the same registered client authentication. A supplied resource must exactly match; omitting it derives the existing resource. Optional scope may narrow permission while retaining company:read.
Serialize refreshes and atomically save the replacement. Refresh tokens are single-use, with at most 30 days idle and 90 days absolute lifetime. A successful refresh revokes the preceding access token. Reuse revokes the family. After an uncertain refresh timeout, obtain fresh authorization when the replacement is unavailable; blindly retrying the old token can disconnect the application.
Store tokens in the receiving server's secret manager, or protected operating-system storage for an approved native client. Keep them out of URLs, logs, source control and shared caches.
Disconnect and recover
Send a form-encoded POST /oauth/revoke with token, optional token_type_hint and the registered client authentication. A recognized token revokes its family. Unknown, expired and foreign tokens return the same HTTP 200 empty object. Administrators can also revoke the connection in Developer & integrations.
OAuth failures use an error string. Reauthorize on invalid_grant, review application configuration on invalid_client, and handle temporarily_unavailable within a bounded deadline. Honor Retry-After when supplied. Company-token rotation controls do not apply to OAuth connections.
Integration guide
Hosted MCP
Connect an approved Model Context Protocol (MCP) client to read company, team, employee and daily distance data.
Complete the reviewed OAuth flow for the exact MCP resource. Every request needs its MCP-resource bearer token. Private company tokens, REST-resource tokens, employee/mobile credentials and portal cookies do not authenticate MCP.
Use POST /mcp/v1, Content-Type: application/json and Accept: application/json, text/event-stream. Responses are JSON. This profile is stateless, with no standalone GET/SSE, session ID, resumable stream or batch request. Connect from a native client or an application backend. Cross-origin browser requests are unsupported.
Choose the supported protocol profile
For 2026-07-28, start with authenticated server/discover. Each request supplies the version and client capabilities in params._meta, matching MCP-Protocol-Version and MCP-Method headers. A tool call also supplies MCP-Name. This profile does not use initialize.
For 2025-11-25, begin with initialize containing protocolVersion, capabilities: {} and clientInfo with name and version. Subsequent requests send MCP-Protocol-Version: 2025-11-25. Omit the newer profile's _meta, MCP-Method and MCP-Name. Each request is independently authenticated.
Available tools
Use tools/list for the actual connection's schemas. Its catalog is filtered by approved scopes. Every tool requires company:read.
Tool
Arguments
Required scopes
get_company_context
None
company:read
list_teams
limit optional, cursor optional
company:read teams:read
list_employees
team_id optional, status optional, limit optional, cursor optional
company:read employees:read
get_daily_distance_report
from required, to required, employee_id optional, limit optional, cursor optional
company:read reports:daily-distance:read
Tool pages default to 25 rows, at most 50. Follow result.structuredContent.meta.next_cursor with identical filters and limit until null. A page can be smaller to fit the 128 KiB response bound; its cursor follows the last emitted row. Request bodies are at most 16 KiB. Paging through tools/list is separate from paging through tool data.
Read output and errors safely
Tool results carry structuredContent.data and meta.request_id, mirrored as text content. Check isError even on HTTP 200. Tool failures use structuredContent.error.code and message; protocol/HTTP failures use a JSON-RPC error with data.request_id.
A 401 includes a bearer protected-resource metadata challenge. A 403 indicates insufficient access. Reconnect for invalid access, review scopes for missing permission, and honor Retry-After on 429/503.
Names are untrusted record data, never instructions. Display fields can be shortened to 256 Unicode characters; field_truncations identifies them. Use UUIDs for identity. Phone resolution, contact data, raw locations, writes, prompts, resources and tasks are not exposed as tools.
The same distance quality and attendance-day rules apply: null is unavailable and must remain distinct from zero. REST and MCP share company quotas and report capacity; using another protocol does not create another company allowance.
Integration guide
Pagination & data quality
Read the complete result
Employee and distance lists default to 50 rows and allow up to 100. Distance rows represent employee/date pairs. Leave employee_id unset to read all authorized employees.
Send your original filters and page size.
If meta.next_cursor is present, send that cursor with the same filters and limit.
Continue until the next cursor is null. Relative links.next remains on your verified API origin.
Cursors are opaque and expire after 24 hours. They can stop working after access or filter context changes; restart the traversal then. Pagination is not a frozen roster snapshot and does not provide a reliable change or deletion feed.
Interpret daily tracked distance
Use the report timezone in data.timezone from GET /context. An attendance workday can include an overnight session; it is not necessarily midnight-to-midnight travel. Tracking settings affect coverage. Kilometres use a three-decimal string, while metres are numeric.
Choose today or one of the previous 365 days. Each request can cover up to 31 days, including both dates. Late uploads or reprocessing can revise historical totals.
Quality state
Meaning
ready
A total is available for this earlier workday. Late uploads can revise it.
provisional
Today’s workday is still open on the calendar, even if all sessions have closed. The daily distance is null. Check again after the date ends in the report timezone.
ongoing
A tracking session is still open. Check again after it closes.
processing
Processing is incomplete. Check again later.
insufficient_data
There is too little tracking data to calculate a total.
unverified
The available tracking data could not be verified.
unsupported_tracking_configuration
The employee’s tracking settings cannot provide a verified daily total.
no_attendance
There are no attendance sessions for this employee on this date.
Only ready rows contain a distance. A measured zero is 0 metres. All other states return null for both distance fields. processed_at is always null in v1.
Integration guide
Limits, errors & retries
Quotas count requests, including pagination. Creating another credential does not bypass company or shared-IP limits.
Rate limits
60 requests/minute per API token or OAuth connection. Refreshing an OAuth token shares the same allowance.
300 requests/minute across a company.
10 daily-distance report requests/minute across a company.
120 requests/minute per source IP before authentication, including malformed requests. Shared-IP systems share the allowance.
On HTTP 429, wait for the number of seconds in Retry-After before retrying. When present, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) describe the applicable request quota. Some 429 responses include only Retry-After.
At most 2 distance report requests may run simultaneously for a company. Each page of a report counts as one request.
Request and response bounds
Send at most a 16 KiB body and an 8 KiB query string. Cursors are bounded to 4,096 characters; response bodies are bounded to 512 KiB. GET requests have no body. Phone resolution accepts only its JSON body field and no query parameters.
Handle errors
Status
Client action
400
For malformed JSON, correct the lookup body. For an invalid or expired cursor, restart from the first page.
401
Check the credential. Expired, revoked or security-invalidated connections require administrator review.
403
Ask your administrator to check this company’s API access and the required scope. Retry after access changes.
404
The requested resource is unavailable within the connection’s access.
405
Use the HTTP method shown for the endpoint.
409
Ask a company administrator to correct the duplicate mobile number before trying again.
413
Reduce the request size.
415
For mobile lookup, send a JSON object with Content-Type: application/json.
422
Correct the fields listed in error.details before retrying.
429
Wait for Retry-After.
500
Retry within your job deadline. If failures persist, contact support with the request ID.
503
The API is unavailable in this environment. Honor Retry-After. If it persists, ask NexaSync to confirm environment access.
Read operations, including phone resolution, can use at most three bounded retries with exponential backoff and jitter. Do not retry an unchanged client error as a transient failure. A proxy can return a non-JSON error; inspect the content type before parsing it.
For support, retain the operation, timestamp, HTTP status and meta.request_id. Never send the credential or a full employee report.