USR AppsDevelopers
USR Apps API · v1

Build on USR Apps without waiting for anyone

Sign up, get sandbox keys in minutes, connect your product to leads, contacts, tickets, people and events across 40+ USR apps, and go live after automatic checks. Everything here is self-service.

Get sandbox keys5-minute quick startOpenAPI 3.1 file
REST + JSONOne API for every app
OAuth 2.0USR SSO, OpenID Connect
WebhooksSigned, retried for 24 h
SandboxFree, sample data
Create a lead
# 1. Get a token
curl -s https://auth.usrinfo.tech/realms/usr/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=$USR_CLIENT_ID -d client_secret=$USR_CLIENT_SECRET

# 2. Send a lead to USR CRM Lite
curl -s https://sandbox.api.usrinfo.tech/v1/leads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: web-48213" \
  -H "Content-Type: application/json" \
  -d '{"contact":{"name":"Priya S","email":"priya@acme.in"},
       "interest":{"apps":["crm","desk"]},
       "consent":{"contact":true,"captured_at":"2026-10-14T09:30:00Z"}}'

From sign-up to live, with no calls or meetings

Every step runs in USR Console. Your tech team can finish all of it in a day.

  1. Sign up as a partnerFill in the partner form on the website. You get a USR Console login straight away.2 minutes
  2. Get a sandboxA sandbox workspace with sample leads, tickets and employees is created for you.Instant
  3. Create API keysConsole → Developer → New client. Pick only the scopes you need.1 minute
  4. Build and testUse the samples below, and send test webhooks to your endpoint from the Console.Your pace
  5. Pass checks, go liveAutomatic checks run against your sandbox. When they pass, production keys unlock and you can list on Integrations.Automatic
Customers can use this too. A USR customer's admin can create API keys for their own workspace in USR Console → Developer, with the same API and the same samples.

Quick start

Three calls: get a token, check who you are, create a lead. Set USR_CLIENT_ID and USR_CLIENT_SECRET from USR Console first.

The lead now shows in USR CRM Lite in your sandbox, with its source, consent and any website visits linked to it.

Authentication

USR Apps uses OAuth 2.0 on USR SSO (OpenID Connect). Choose the flow that matches what you are building.

Client credentials (server to server)

Your backend syncs data with one workspace. Tokens last 60 minutes; get a new one when it expires.

Authorization code with PKCE (for users)

Your app acts for a signed-in USR user, or offers "Sign in with USR". The user and their admin approve the scopes.

ItemValue
Token URLhttps://auth.usrinfo.tech/realms/usr/protocol/openid-connect/token
Authorize URLhttps://auth.usrinfo.tech/realms/usr/protocol/openid-connect/auth
Discoveryhttps://auth.usrinfo.tech/realms/usr/.well-known/openid-configuration
API basehttps://api.usrinfo.tech/v1 · sandbox https://sandbox.api.usrinfo.tech/v1

Scopes

leads:readleads:writecontacts:readcontacts:writetickets:readtickets:writepeople:readevents:writewebhooks:manage

Ask only for what you use. Customers see the scope list before they approve your app, and fewer scopes are approved faster.

API reference

The full contract is in the OpenAPI 3.1 file. Import it into Postman, Insomnia or your code generator.

MethodPathWhat it doesScope

Lead body

The same shape the USR website and login page send, so every source looks alike in USR CRM Lite.

Conventions

Pagination

Lists return data and next_cursor. Pass ?cursor= until it is null. limit is 1–200, default 50.

Incremental sync

Use ?updated_since= with the time of your last sync (ISO 8601, UTC) to fetch only what changed.

Safe retries

Send an Idempotency-Key on every POST. A retry with the same key returns the first result for 24 hours.

Versions

The version is in the URL (/v1). New fields can appear at any time, so ignore fields you do not know. Breaking changes get a new version and 12 months' notice.

Time and money

Times are ISO 8601 in UTC. Amounts are in the smallest unit (paise, cents) with a currency code.

Where data lives

Production data is hosted in India. Your workspace region is returned by GET /me.

Errors and rate limits

Errors use the standard problem format (RFC 9457) with a request_id. Include it when you raise a ticket.

StatusMeaningWhat to do
400The body failed validationFix the fields listed in errors
401Token missing, expired, or a scope is missingGet a new token; check the scopes on your client
404Not found in this workspaceCheck the id and the workspace your token belongs to
409Same Idempotency-Key, different bodyUse a new key for a new request
429Too many requestsWait for the seconds in Retry-After, then retry
5xxSomething failed on our sideRetry with backoff (1 s, 2 s, 4 s…) using the same Idempotency-Key

Limits: 600 requests a minute per client in production, 120 in the sandbox. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Webhooks

Subscribe once and USR calls your endpoint when something happens. Create subscriptions in USR Console or with POST /webhooks.

What you receive

Check the signature

Every call has X-USR-Signature: t=<unix time>,v1=<hex>. Compute HMAC-SHA256 of t + "." + raw body with your signing secret, compare in constant time, and reject anything older than 5 minutes.

Reply fast. Return a 2xx within 10 seconds and do the work in the background. Failed calls are retried with backoff for 24 hours, then the subscription is marked failing and your Console shows the errors. Events can arrive more than once or out of order, so use id to skip duplicates and occurred_at to order them.

Website kit

Two snippets connect any website to USR CRM Lite and USR Sales Assistant: visitor journeys and lead forms. Both use a publishable site key (pk_…) that can only create leads and send events, and only from the website addresses you allow in USR Console.

1. Visitor tracking (after cookie consent)

2. Lead form

Privacy built in. The tracker sends nothing until the visitor allows analytics cookies, respects Global Privacy Control, and never collects names, emails or form contents. Only the form submission, with consent, creates a lead.

Sign in with USR

Let USR customers open your app with their USR login. Use any OpenID Connect library with the discovery URL above, the authorization code flow and PKCE. You receive sub, email, name and workspace_id in the ID token.

Recipes

Sync new leads from your system into USR every 10 minutes

Raise a USR Desk ticket from your app

Keep your user list in step with USR HRIS

Security and data protection

USR is certified to ISO/IEC 27001 and ISO/IEC 42001 and is DPDP ready. Partners who connect to customer data follow the same rules:

  • Keep client secrets and signing secrets in a secrets manager, never in code, browsers or mobile apps.
  • Use HTTPS (TLS 1.2 or later) for every webhook endpoint.
  • Ask for the fewest scopes, and keep only the data your feature needs.
  • Send consent with every lead: consent.contact, captured_at and the exact text shown.
  • Delete a person's data within 30 days when USR sends a contact.updated event with erased: true.
  • Report a suspected security issue within 24 hours to security@usrinfo.tech.

Certification and go-live

When you click Request production access in USR Console, these checks run automatically against your sandbox. You see the result in minutes.

CheckPasses when
Token handlingTokens are reused until they expire, not fetched for every call
IdempotencyEvery POST in the last 7 days carried an Idempotency-Key
Rate limitsYour client backed off after a 429 and never exceeded the limit for long
WebhooksYour endpoint verified the test signature, rejected a bad one and answered within 10 seconds
ConsentEvery lead created carried consent fields
ScopesEvery scope you hold was used at least once
ListingName, logo, description, support email, privacy policy and terms are filled in
After go-live your integration can be listed on the USR Integrations page and in the in-app store. Customers install it themselves, and leads you refer are tracked to your partner account.

Help and status

Raise a developer ticket

Open a ticket in USR Desk with your request_id. Most answers arrive automatically from the knowledge base. Raise a ticket →

Ask USR Assist

Ask how-to questions about the API in plain words on the website or inside any USR app. About USR Assist →

Changelog

New fields and endpoints are listed in USR Console → Developer → Changelog, and sent to your developer email.

Email

support@usrinfo.tech for anything the ticket desk cannot answer.