# Nyota Imara

## Docs

- [GET & DELETE /v1/accounts/devices — Session Management](https://handbook.nyotaimara.com/api/accounts/devices.md): List active sessions and sign-in history for the authenticated user. Revoke any session remotely with DELETE /v1/accounts/devices/:sessionId.
- [GET & PATCH /v1/accounts/me — Your Account Profile](https://handbook.nyotaimara.com/api/accounts/profile.md): Retrieve or update your account profile. GET returns name, email, phone, dob, avatarUrl, and kycStatus. PATCH updates any writable field you include.
- [GET /v1/auth/check-email — Check If Email Is Taken](https://handbook.nyotaimara.com/api/auth/check-email.md): Check whether an email is already registered on Nyota Imara. Returns exists: true or false. Use before sign-up to prevent duplicate account errors.
- [POST /v1/auth/log — Record a Security Sign-in Event](https://handbook.nyotaimara.com/api/auth/log-event.md): Record a login or signup security event for the authenticated user. Adds IP geolocation and device info. Sends a security alert email when event is login.
- [POST /v1/auth/avatar — Upload a Profile Avatar Image](https://handbook.nyotaimara.com/api/auth/upload-avatar.md): Upload a profile photo before account creation using multipart/form-data. The server returns a public CDN URL to include in your registration payload.
- [POST /v1/billing/cancel — Cancel Your Subscription](https://handbook.nyotaimara.com/api/billing/cancel.md): Cancel the active mail subscription for an organization. Mailboxes stay active until the current billing period ends — there is no immediate loss of access.
- [POST /v1/billing/pay — Start a Card or M-Pesa Payment](https://handbook.nyotaimara.com/api/billing/initiate-payment.md): Initiate a Paystack card checkout, send an M-Pesa STK push, charge a saved payment method, or purchase a mail subscription plan — all through one endpoint.
- [GET /v1/billing/methods — List Saved Payment Methods](https://handbook.nyotaimara.com/api/billing/payment-methods.md): Retrieve all payment methods saved to the active organization. Returns masked card details (last 4 digits, expiry) and registered M-Pesa phone numbers.
- [Preview and Execute Your Mail Subscription Upgrade](https://handbook.nyotaimara.com/api/billing/upgrade.md): Preview the prorated cost with GET /v1/billing/upgrade/preview, then apply the change with POST /v1/billing/upgrade using a saved bank card.
- [Create B2B Commerce Orders, Disputes, and Product Reviews](https://handbook.nyotaimara.com/api/commerce/orders.md): Place a new customer order with automatic inventory validation, open a dispute against a fulfilled order, or submit a product review for a completed purchase.
- [Multi-Vendor Marketplace API: List and Add Sellers](https://handbook.nyotaimara.com/api/commerce/vendors.md): List vendors in your multi-vendor marketplace or add a new seller by email. Pro plan required. Vendors must have an existing Nyota Imara user account.
- [Retrieve Your Organization's KYB Verification Record](https://handbook.nyotaimara.com/api/kyb/get.md): Fetch an organization's KYB record: business type, registration number, and verification status. Document URLs are time-limited signed links.
- [POST /v1/organizations/:id/kyb — Submit Business Docs](https://handbook.nyotaimara.com/api/kyb/submit.md): Upload business registration details and supporting documents to start KYB verification for your organization. Requires the X-Organization-Id header.
- [Retrieve a User's KYC Verification Status and Docs](https://handbook.nyotaimara.com/api/kyc/get.md): Fetch a user's KYC record: verification status, submitted ID number, and time-limited signed document URLs. Pass me as userId for your own record.
- [Submit Your Identity Documents for KYC Verification](https://handbook.nyotaimara.com/api/kyc/submit.md): Upload a government ID (front and back) and passport photo to start KYC verification. Documents are stored privately; kycStatus moves to pending.
- [POST /v1/logistics/estimate — Get a Delivery Quote](https://handbook.nyotaimara.com/api/logistics/estimate.md): Request a live delivery fee and ETA for a pickup and dropoff location pair. The fee is sourced from Uber Direct and returned in KES as the lowest denomination.
- [GET /v1/notifications — Fetch In-App Notifications](https://handbook.nyotaimara.com/api/notifications/list.md): Retrieve the authenticated user's 50 most recent in-app notifications ordered newest first, plus an unreadCount integer for badge display in your UI.
- [Mark In-App Notifications as Read: One or Bulk All](https://handbook.nyotaimara.com/api/notifications/mark-read.md): PATCH /v1/notifications/:id/read marks a specific notification read. PATCH /v1/notifications/read-all clears all unread notifications in one request.
- [POST /v1/organizations — Create a New Organization](https://handbook.nyotaimara.com/api/organizations/create.md): Register a new B2B organization on Nyota Imara. Provide a name and a unique slug. The authenticated user is automatically assigned the owner role.
- [Send and Accept Organization Membership Invitations](https://handbook.nyotaimara.com/api/organizations/invites.md): Send a team invitation by email with a role assignment, or exchange an invite token to accept membership. Invitation links expire after 7 days.
- [GET /v1/organizations — List All Your Organizations](https://handbook.nyotaimara.com/api/organizations/list.md): Retrieve every organization the authenticated user belongs to, including name, slug, logo URL, and KYB verification status. No org context header required.
- [Manage organization members, roles, and permissions](https://handbook.nyotaimara.com/api/organizations/members.md): List members and pending invites, retrieve available roles and permissions, and create, update, or delete custom roles for your organization.
- [PATCH /v1/organizations/:id — Update Your Organization](https://handbook.nyotaimara.com/api/organizations/update.md): Update your organization's name, logo, KRA PIN, billing email, or address. All body fields are optional. Requires the org:organization:update permission.
- [GET /v1/users/me — Get the Authenticated User Profile](https://handbook.nyotaimara.com/api/users/get-me.md): Fetch the full profile of the authenticated user, including id, email, name, avatarUrl, kycStatus, and account status. Requires a Bearer token.
- [Authorization](https://handbook.nyotaimara.com/authorization.md)
- [Identity Verification: KYC for Users, KYB for Orgs](https://handbook.nyotaimara.com/concepts/identity-verification.md): Understand how Nyota Imara verifies individual users with KYC and organizations with KYB, including required documents, statuses, and secure file access.
- [Organizations: How B2B Workspaces Work on Nyota Imara](https://handbook.nyotaimara.com/concepts/organizations.md): Learn how Nyota Imara organizations work — roles, membership, KYB verification, and switching context with the X-Organization-Id header.
- [Permissions and Roles: How PBAC Works on Nyota Imara](https://handbook.nyotaimara.com/concepts/permissions.md): Learn how Nyota Imara enforces permissions using PBAC policies in namespace:resource:action format, built-in org roles, and custom role creation.
- [Creating Account](https://handbook.nyotaimara.com/create-account.md): How to create your Pay Hero account
- [Billing and Payments: Cards, M-Pesa, and Subscriptions](https://handbook.nyotaimara.com/guides/billing-and-payments.md): Accept Paystack card payments, M-Pesa STK pushes, or charges to saved methods, and manage mail subscriptions with volume-based seat pricing.
- [Commerce and Orders: Creating Orders and Managing Vendors](https://handbook.nyotaimara.com/guides/commerce-and-orders.md): Create inventory-checked orders for your customers, open disputes, submit reviews, and manage a multi-vendor marketplace on Pro plans.
- [Create and Configure Your Nyota Imara Organization](https://handbook.nyotaimara.com/guides/creating-an-organization.md): Set up a Nyota Imara organization, configure your business details, and learn how to use the X-Organization-Id header for scoped API requests.
- [Delivery Estimates: Get Live Quotes from Uber Direct](https://handbook.nyotaimara.com/guides/delivery-estimates.md): Request real-time delivery fee quotes and ETAs from Uber Direct by providing pickup and dropoff coordinates for your Nairobi routes.
- [Notifications: Fetch, Read, and Track In-App Alerts](https://handbook.nyotaimara.com/guides/notifications.md): Retrieve your last 50 notifications with unread counts, mark individual items or all notifications as read, and learn what events trigger them.
- [Team Management: Invites, Members, and Custom Roles](https://handbook.nyotaimara.com/guides/team-management.md): Invite teammates by email and assign roles, accept organization invitations by token, and create custom roles with fine-grained permission sets.
- [Nyota Pay Developer](https://handbook.nyotaimara.com/introduction.md): Build seamless payment experiences with our powerful, easy-to-use APIs. Comprehensive guides, references, and tools to get you started.

## OpenAPI Specs

- [openapi](https://handbook.nyotaimara.com/api-reference/openapi.json)